StrategySpec - Ithaca

A StrategySpec is a declarative, JSON-serializable description of a trading strategy. Agents author specs; the Ithaca backtest engine executes them. No agent-authored code is ever run — the spec is matched against a frozen, closed schema and dispatched to trusted numpy kernels.

Design principles

The schema is closed: additionalProperties: false on every object. Unknown fields are rejected at validation time, not silently dropped. This prevents agents from smuggling arbitrary keys into the engine.

Declarative, not imperative. The agent describes what to trade, not how to compute it.
Closed schema. Every field is enumerated. No extension points, no freeform blobs.
Server-stamped identity. id, version, and tenant_id are assigned by the server. If an agent supplies them, they are ignored.
Deterministic. A seed field makes every backtest reproducible to the bit.

Top-level fields

Field	Type	Required	Description
`spec_version`	string	yes	Always `"1.0"`. Bumped only on breaking schema changes.
`name`	string	yes	Human-readable strategy name.
`universe`	object	yes	Tradable universe definition.
`strategy`	object	yes	Signal logic selector + parameters.
`construction`	object	yes	Portfolio construction scheme.
`risk`	object	yes	Risk guardrails.
`execution`	object	yes	Execution assumptions.
`resources`	object	yes	Compute tier reservation.
`seed`	integer	no	RNG seed. Defaults to `42`.

Server-stamped fields (ignored if supplied)

These fields are never accepted from the agent. The server assigns them on persist:

Field	Source	Notes
`id`	server (UUID)	Ignored if present in the request body.
`version`	server (monotonic int)	Increments per tenant + name.
`tenant_id`	server (from auth)	Derived from the caller’s principal.

If an agent sends "id": "..." or "tenant_id": "...", the server silently discards them. This prevents an agent from impersonating another tenant or overwriting an existing strategy.

`universe`

Field	Type	Required	Description
`symbols`	string[]	yes	Ticker list, e.g. `["NVDA","AMD","INTC"]`.
`source`	string	yes	Price panel source. Currently `"polygon"`.

`strategy`

Field	Type	Required	Description
`id`	enum	yes	One of `momentum`, `ma_cross`, `mean_reversion`, `rank_returns`.
`params`	object	yes	Strategy-specific parameters (see below).

Strategy `id` reference

momentum

Rolling-window momentum. params: lookback (days, int), skip (days, int, default 0).

ma_cross

Moving-average crossover. params: fast (days), slow (days).

mean_reversion

Z-score reversion to rolling mean. params: lookback (days), entry_z (float), exit_z (float).

rank_returns

Cross-sectional return ranking. params: lookback (days), top_n (int).

`construction`

Field	Type	Required	Description
`scheme`	enum	yes	`equal_weight`, `rank_weight`, or `vol_weight`.
`long_only`	boolean	yes	If `true`, weights are clipped at 0 (no shorts).
`gross`	float	yes	Target gross exposure, e.g. `1.0` for fully invested.

`risk`

Field	Type	Required	Description
`max_gross`	float	yes	Maximum gross exposure.
`max_net`	float	yes	Maximum net exposure.
`max_name_pct`	float	yes	Maximum per-name weight (e.g. `0.10` = 10%).

`execution`

Field	Type	Required	Description
`cost_bps`	float	yes	Round-trip cost in basis points.
`algo`	enum	yes	Fill model. Currently `"twap"`.
`rebalance`	enum	yes	Rebalance frequency: `daily`, `weekly`, or `monthly`.

`resources`

Field	Type	Required	Description
`tier`	enum	yes	Compute tier: `"dev"` or `"prod"`.

Validation flow

Parse

The request body is parsed as JSON. Malformed JSON is rejected with 400.

Schema validate

The JSON is validated against the frozen StrategySpec schema. Unknown fields, type mismatches, and missing required fields return 422 with a field-level error list.

Strip server fields

id, version, and tenant_id are removed from the payload if present.

Semantic validate

Cross-field rules are checked (e.g. fast < slow for ma_cross, max_name_pct <= max_gross).

Stamp + persist

The server assigns id, version, tenant_id and writes the immutable spec row.

Complete example

{
  "spec_version": "1.0",
  "name": "Semis momentum 60/20",
  "universe": {
    "symbols": ["NVDA", "AMD", "INTC", "TSM", "QCOM"],
    "source": "polygon"
  },
  "strategy": {
    "id": "momentum",
    "params": { "lookback": 60, "skip": 5 }
  },
  "construction": {
    "scheme": "vol_weight",
    "long_only": true,
    "gross": 1.0
  },
  "risk": {
    "max_gross": 1.05,
    "max_net": 1.0,
    "max_name_pct": 0.25
  },
  "execution": {
    "cost_bps": 5.0,
    "algo": "twap",
    "rebalance": "weekly"
  },
  "resources": { "tier": "prod" },
  "seed": 42
}

The seed field is what makes a backtest reproducible. The same spec + the same price panel + the same seed always produces the same result hash. Change the seed and you get a different Monte Carlo path (where applicable).

Backtest system — how a spec becomes an equity curve
Artifacts — the 8-file bundle produced by every run
Approval workflow — promoting a backtest to paper trading
Strategy endpoints — the REST API for proposing specs

​Design principles

​Top-level fields

​Server-stamped fields (ignored if supplied)

​universe

​strategy

​Strategy id reference

​construction

​risk

​execution

​resources

​Validation flow

​Complete example

​Related

Design principles

Top-level fields

Server-stamped fields (ignored if supplied)

`universe`

`strategy`

Strategy `id` reference

`construction`

`risk`

`execution`

`resources`

Validation flow

Complete example

Related