DeltaCalc.Safety (DeltaCalc v0.3.0)

Position safety scoring and before/after DCA safety comparisons.

API Functions

Function	Arity	Description	Param Kinds
`compare_dca_safety`	8	Compare safety metrics before and after adding a DCA leg.	`single_leg: value`, `dca_leg: value`, `current_price: value`, `initial_equity: value`, `mmr: value`, `side: value`, `swan_pct: value`, `safety_cfg: value`
`safety`	5	Evaluate position safety and compute risk metrics.	`liq: value`, `entry: value`, `swan_pct: value`, `side: value`, `cfg: value`

Summary

Types

safety_result()

Functions

compare_dca_safety(single_leg, dca_leg, current_price, initial_equity, mmr, side, swan_pct, safety_cfg \\ %{})

Compare safety metrics before and after adding a DCA leg.

safety(liq, entry, swan_pct, side, cfg \\ %{})

Evaluate position safety and compute risk metrics.

Types

safety_result()

@type safety_result() :: map() | {:error, :non_positive_entry}

Functions

compare_dca_safety(single_leg, dca_leg, current_price, initial_equity, mmr, side, swan_pct, safety_cfg \\ %{})

@spec compare_dca_safety(
  map(),
  map(),
  Decimal.t(),
  Decimal.t(),
  Decimal.t(),
  :long | :short,
  Decimal.t(),
  map()
) :: map() | {:error, atom()}

Compare safety metrics before and after adding a DCA leg.

Parameters

single_leg - Initial leg with :entry and :notional as canonical decimal strings; native Elixir callers may also pass Decimal or integer. (value)
dca_leg - DCA leg with :entry and :notional as canonical decimal strings; native Elixir callers may also pass Decimal or integer. (value)
current_price - Market price when adding DCA leg as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
initial_equity - Starting subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
mmr - Minimum margin requirement as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
side - Position side (:long or :short) (value)
swan_pct - Black swan threshold percentage as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
safety_cfg - Optional safety configuration whose multiplier fields use canonical decimal strings; native Elixir callers may also pass Decimal or integer. (default: %{}, value)

Returns

Map with pre_dca, post_dca, leverage_change, liquidation_change (map)

# descripex:contract
%{
  params: %{
    side: %{
      description: "Position side (:long or :short)",
      kind: :value,
      schema: %{"enum" => ["long", "short"], "type" => "string"}
    },
    current_price: %{
      description: "Market price when adding DCA leg as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    initial_equity: %{
      description: "Starting subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    swan_pct: %{
      description: "Black swan threshold percentage as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    single_leg: %{
      description: "Initial leg with :entry and :notional as canonical decimal strings; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{
        "additionalProperties" => false,
        "properties" => %{
          "entry" => %{"type" => "string"},
          "notional" => %{"type" => "string"}
        },
        "required" => ["entry", "notional"],
        "type" => "object"
      }
    },
    dca_leg: %{
      description: "DCA leg with :entry and :notional as canonical decimal strings; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{
        "additionalProperties" => false,
        "properties" => %{
          "entry" => %{"type" => "string"},
          "notional" => %{"type" => "string"}
        },
        "required" => ["entry", "notional"],
        "type" => "object"
      }
    },
    mmr: %{
      description: "Minimum margin requirement as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    safety_cfg: %{
      default: %{},
      description: "Optional safety configuration whose multiplier fields use canonical decimal strings; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{
        "additionalProperties" => false,
        "properties" => %{
          "safe_multiplier" => %{"type" => "string"},
          "threshold_multiplier" => %{"type" => "string"}
        },
        "type" => "object"
      }
    }
  },
  returns: %{
    type: :map,
    description: "Map with pre_dca, post_dca, leverage_change, liquidation_change"
  }
}

safety(liq, entry, swan_pct, side, cfg \\ %{})

@spec safety(Decimal.t(), Decimal.t(), Decimal.t(), :long | :short, map()) ::
  safety_result()

Evaluate position safety and compute risk metrics.

Parameters

liq - Liquidation price as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
entry - Entry price (> 0) as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
swan_pct - Black swan threshold percentage as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
side - Position side (:long or :short) (value)
cfg - Safety config with :threshold_multiplier and :safe_multiplier as canonical decimal strings; native Elixir callers may also pass Decimal or integer. (default: %{}, value)

Returns

Map with verdict, distance metrics, and composite_score, or {:error, :non_positive_entry} (map)

# descripex:contract
%{
  params: %{
    entry: %{
      description: "Entry price (> 0) as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    side: %{
      description: "Position side (:long or :short)",
      kind: :value,
      schema: %{"enum" => ["long", "short"], "type" => "string"}
    },
    liq: %{
      description: "Liquidation price as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    swan_pct: %{
      description: "Black swan threshold percentage as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    cfg: %{
      default: %{},
      description: "Safety config with :threshold_multiplier and :safe_multiplier as canonical decimal strings; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{
        "additionalProperties" => false,
        "properties" => %{
          "safe_multiplier" => %{"type" => "string"},
          "threshold_multiplier" => %{"type" => "string"}
        },
        "type" => "object"
      }
    }
  },
  returns: %{
    type: :map,
    description: "Map with verdict, distance metrics, and composite_score, or {:error, :non_positive_entry}"
  }
}