Bourse.OptionProposal (bourse v0.1.0)

Mechanical option-proposal preflight and spot/perp hedge sizing.

An AI supplies explicit option legs, risk targets, hard limits, hedge candidates and a venue policy. This module projects post-trade exposure, sizes a correctly rounded hedge toward the caller's target delta, and returns either one non-mutating approval or a stable list of actionable violations.

Strategy decisions stay with the caller: the library never chooses which option to trade or submits orders. Its optimizer only allocates quantities among caller-approved instruments and objectives. Cross-venue plans keep collateral pools separate and never claim portfolio-margin netting.

Summary

Types

proposal()

venue_policy()

Functions

calculate_hedge(current_delta, target_delta, candidates, venue_policy, option_venues)

Sizes a spot/perp hedge toward target_delta under venue_policy.

compare_margin_impact(problem)

Compares provider-reported margin impact within venue-local collateral domains.

optimize(problem)

Optimizes a finite set of caller-approved instruments into a v1-shaped plan.

preflight(proposal, opts \\ [])

Validates a caller-built option proposal without mutation.

project(legs, baseline_contributions \\ [])

Projects option-leg exposure without portfolio checks or hedge sizing.

Types

proposal()

@type proposal() :: %{
  :legs => [map()],
  :hedge_candidates => [map()],
  :risk_targets => map(),
  :hard_limits => map(),
  :venue_policy => venue_policy(),
  optional(:valuation_assumptions) => map(),
  optional(:freshness_assumptions) => map(),
  optional(:basis_risk) => map(),
  optional(:counterparty_risk) => map(),
  optional(:strategy) => map(),
  optional(:snapshot) => Bourse.PortfolioRisk.Snapshot.t(),
  optional(:scopes) => [Bourse.PortfolioRisk.scope()],
  optional(:expected_positions) => [map()]
}

venue_policy()

@type venue_policy() :: Bourse.OptionProposal.Hedge.venue_policy()

Functions

calculate_hedge(current_delta, target_delta, candidates, venue_policy, option_venues)

@spec calculate_hedge(number(), number(), [map()], venue_policy(), [String.t()]) ::
  {:ok, map()} | {:error, atom() | {atom(), term()}}

Sizes a spot/perp hedge toward target_delta under venue_policy.

compare_margin_impact(problem)

@spec compare_margin_impact(Bourse.OptionProposal.MarginImpact.problem()) ::
  {:ok, Bourse.OptionProposal.MarginImpact.result()}
  | {:error, Bourse.Error.t()}

Compares provider-reported margin impact within venue-local collateral domains.

optimize(problem)

@spec optimize(Bourse.OptionProposal.Optimizer.problem()) ::
  {:ok, map()} | {:error, term()}

Optimizes a finite set of caller-approved instruments into a v1-shaped plan.

preflight(proposal, opts \\ [])

@spec preflight(
  proposal(),
  keyword()
) :: {:ok, Bourse.OptionProposal.Result.t()} | {:error, Bourse.Error.t()}

Validates a caller-built option proposal without mutation.

Options:

:observed_at — local observation timestamp for caller-supplied data; self-fetched Greeks and derived quotes use fetch-completion time
:timeout — forwarded to portfolio snapshot when scopes are supplied
:max_age_ms — freshness gate for Greeks / portfolio when reading live
:request_opts — default HTTP opts used when enriching legs and hedge candidates

Returns {:ok, %Result{}} for both approved and rejected outcomes. Structural input errors return {:error, %Error{}}.

project(legs, baseline_contributions \\ [])

@spec project([map()], [map()]) :: {:ok, map()} | {:error, atom() | {atom(), term()}}

Projects option-leg exposure without portfolio checks or hedge sizing.