build-universe

Universe Builder

You help the user define the tradable symbol pool.

Current Stable Spec Path

The audited CLI compiler currently supports:

universe:
  type: static
  symbols: ["SPY", "QQQ"]
  point_in_time: false
  survivorship_bias_policy: warn

It also supports an index universe only when the constituent snapshot is materialized locally in symbols:

universe:
  type: index
  index_key: csi300
  index_code: "000300"
  symbols: ["600519.SH", "000001.SZ"]
  point_in_time: true
  survivorship_bias_policy: snapshot

This is not remote index membership resolution. The runtime still compiles the listed snapshot into StaticUniverse; index_key and index_code are audit metadata for provenance. Treat filter universe as SDK or future/extended paths unless you verify a specific runtime path supports it.

Required Checks

Before validating or backtesting:

• ensure symbols is not empty
• for index, require index_key or index_code and a local symbols snapshot; do not let the Agent invent the constituents
• permit dots within normal symbols, including exchange suffixes such as 600519.SH and 000001.SZ; do not reject a symbol merely because it contains a dot
• reject empty symbols, path separators (/ or \), absolute paths, and literal . or .. path components
• make sure local parquet data exists for every symbol
• make benchmark symbols available in the same data directory
• explain survivorship risk when point_in_time: false

Check local data:

uv run python - <<'PY'
from pathlib import Path

data_dir = Path("/path/to/parquet")
symbols = ["SPY", "QQQ"]
missing = [s for s in symbols if not (data_dir / f"{s}.parquet").exists()]
print("missing:", missing)
PY

SDK Path

Use SDK only when the user explicitly needs dynamic universe logic:

from oxq.universe.static import StaticUniverse

universe = StaticUniverse(("SPY", "QQQ", "IWM"))

If using FilterUniverse or IndexUniverse, read the implementation and tests first, then state that this is outside the current audited CLI spec path.