Saltar al contenido principal

Glossary

Project-specific jargon used across AlphaSwarm, with a definition and a pointer to the canonical file. New contributors and AI agents should treat this as the single source of truth for terminology — if you find a mismatch between this glossary and the code, file an issue.

See also: What is AlphaSwarm? for a non-technical overview and the documentation index for the full doc map.

Plain-English basics​

Start here if you are new to trading platforms. These are general concepts, defined the way AlphaSwarm uses them.

  • Strategy — A precise, repeatable rule for deciding what to buy or sell and when. Precise enough that a computer can follow it.
  • Backtest — Replaying a strategy against historical market data to estimate how it would have performed. Necessary but never sufficient: history is easy to overfit (see overfitting).
  • Paper trading — Running a strategy against live market data with pretend money. Catches real-world problems a backtest cannot (data delays, broker behaviour) with zero financial risk.
  • Live trading — The strategy trades real money through a broker.
  • Promotion — AlphaSwarm's formal, gated crossing from research to live trading. Requires statistical evidence, risk checks, and human approval. See Promotion evidence.
  • Alpha — Return beyond what the overall market delivered; the "skill" component of performance. Also used loosely for a signal or strategy intended to produce it.
  • Sharpe ratio — The standard "return per unit of risk" score. A higher Sharpe means steadier gains. The deflated Sharpe ratio (DSR) additionally discounts for how many experiments were run to find the result.
  • Overfitting — When a strategy has memorized historical coincidences instead of learning something real; it looks great in backtests and fails live. PBO (probability of backtest overfitting) estimates the risk of exactly this.
  • Drawdown — The peak-to-trough drop in account value along the way. A strategy that ends up +20% but fell 40% mid-way had a 40% drawdown — often the more important number.
  • Slippage — The difference between the price a strategy expected and the price it actually got. Grows with order size and market speed.
  • Order / fill — An order is an instruction to a broker to buy or sell; a fill is the broker's confirmation that (some of) it executed, at what price.
  • Bot — AlphaSwarm's smallest deployable unit: one strategy bundled with its data sources, risk limits, and deployment target. See Bots.
  • Agent — An AI worker (backed by a large language model) that performs research, analysis, or monitoring tasks inside the platform's guardrails. Agents cannot touch real money directly.
  • HITL (human-in-the-loop) — A design where specific consequential actions pause and wait for explicit human approval. See Approval queues.
  • Four-eyes — The rule that the person approving an action must be different from the person who requested it; privileged control actions need two distinct approvers.
  • Kill switch — The always-available emergency stop that halts all trading immediately.
  • Feature flag — A configuration switch that turns a platform behaviour on or off per environment. On AlphaSwarm new behaviour ships default-off, so operators decide when to enable it.
  • Research plane vs money plane — The hard separation between the world where ideas are generated/tested (research, LLM agents) and the world that can move real money. The promotion gate is the only crossing.

Core domain​

  • vt_symbol — Composite symbol id with the shape {TICKER}.{EXCHANGE} (vnpy convention), e.g. AAPL.NASDAQ, BTCUSDT.BINANCE, ESM4.CME. Always created via Symbol.parse(...) / Symbol.format(...) in alphaswarm/core/types.py; never hand-split.
  • Symbol — Immutable dataclass that bundles ticker, exchange, asset_class, security_type, optional contract spec. The atom flowing through every data feed, strategy, and broker. Defined in alphaswarm/core/types.py.
  • AssetClass vs SecurityType — AssetClass is the broad category (equity, crypto, fx, future, option, index, commodity, bond). SecurityType is the Lean-style finer-grained enum (equity, option, future_option, crypto_future, index_option, …). The _polymorphic_identity_for helper in alphaswarm/data/catalog/versions.py maps SecurityType to a joined-table subclass of Instrument.
  • Resolution — Lean-style bar cadence (Tick, Second, Minute, Hour, Daily); see alphaswarm/core/types.py.
  • Interval — Short-code bar cadence (vnpy style, 1m, 5m, 1h, 1d). Same idea as Resolution, kept for vnpy back-compat.
  • SubscriptionDataConfig — The data-plane routing key. Combines Symbol + Resolution + TickType + DataNormalizationMode. See alphaswarm_docs/core-types.md.

Persistence + data plane​

  • Execution Ledger — The Postgres tables under alphaswarm/persistence/models.py + alphaswarm/persistence/ledger.py that record every signal, order, fill, agent decision, and backtest run. Authoritative for "what did the system actually do?".
  • LedgerWriter — Façade over the ledger tables. Always go through it instead of writing to ORM models directly so audit messages get emitted. alphaswarm/persistence/ledger.py.
  • Instrument joined-table inheritance — instruments is the parent table; each subclass (InstrumentEquity, InstrumentOption, …) lives in its own joined-table row keyed on instruments.id. The instrument_class discriminator selects the subclass at load time. See alphaswarm_docs/erd.md and alphaswarm/persistence/models_instruments.py.
  • polymorphic_identity — SQLAlchemy mapper arg that ties a subclass to a discriminator value (e.g. InstrumentEquity.__mapper_args__ = {"polymorphic_identity": "spot"}). When you add a new instrument subclass you must also extend the mapping dict in _polymorphic_identity_for.
  • DatasetCatalog — Parent row describing a logical dataset (HMDA LAR, FDA device events, etc.) with provider/domain/tags.
  • DatasetVersion — Per-materialisation row beneath DatasetCatalog. Captures row count, dataset hash, schema snapshot, Iceberg identifier.
  • DataLink — Edge between a DatasetVersion and an entity (Instrument, Issuer, EconomicSeries). Use this for "which symbols does this dataset cover?" queries.
  • DataSource — Logical provider record (Yahoo, Alpha Vantage, IBKR, openFDA). Datasets and data-links reference a DataSource.
  • IcebergCatalog (the wrapper) — PyIceberg handle from alphaswarm/data/iceberg_catalog.py. Always go through append_arrow, read_arrow, iceberg_to_duckdb_view; never call PyIceberg's Catalog.create_table directly.
  • aqp_<source> namespace — Iceberg namespace convention for the regulatory ingest: alphaswarm_cfpb, alphaswarm_uspto, alphaswarm_fda, alphaswarm_sec. New corpora pick a new aqp_<source> slug.
  • Persistent host warehouse — ${ALPHASWARM_WAREHOUSE_ROOT} (default ~/.alphaswarm/warehouse), bind-mounted into the alphaswarm-api and alphaswarm-worker containers at /warehouse by alphaswarm_platform/compose/docker-compose.yml. Holds the PyIceberg SQL catalog (catalog.db), Parquet data files, staging dir, and ingest audit logs.
  • legacy profile — Docker Compose profile that bundles the older REST + MinIO catalog topology (off by default). Bring it up with docker compose --profile legacy up -d.

Strategies + backtest​

  • BaseStrategy — Abstract strategy contract under alphaswarm/strategies/. Subclasses implement on_bar, on_signal, etc. See alphaswarm_docs/backtest-engines.md.
  • DeployedModelAlpha / MLSelectorAlpha — Strategies that wrap an ML model (deployed via ModelDeployment) and emit signals. DeployedModelAlpha is defined in alphaswarm/strategies/ml_alphas.py.
  • EnsembleAlpha — Weighted combination of multiple alphas. alphaswarm/strategies/ml_alphas.py.
  • IBrokerage / IDataQueueHandler — Lean-style interfaces consumed by backtest, paper, and live engines without modification (the same strategy code runs against all three). See alphaswarm_docs/paper-trading.md.
  • BacktestRun — Postgres row describing one backtest invocation (Sharpe, Sortino, drawdown, MLflow run id, dataset hash). The backtest UI's history view is just a query against this table.
  • MLflow run id — Foreign id stored on BacktestRun.mlflow_run_id pointing at the MLflow tracking server. Click-through from the UI opens the MLflow UI in a new tab.
  • dataset_hash — Deterministic SHA-256 of the input bars used in a backtest. Lets the UI flag "two backtests with the same hash = identical inputs".

ML + agents​

  • Tier (deep / quick) — Two LLM tiers in the agentic crews. deep = high-capability (Nemotron 70B / GPT-4-class) for analysis; quick = small/fast (Llama 3.2 / Mini) for control-flow decisions. Provider per tier is in settings.llm_provider_deep / _quick; model per tier in llm_deep_model / llm_quick_model.
  • router_complete — One-shot LLM completion through LiteLLM exposed by alphaswarm/llm/providers/router.py. All AlphaSwarm code goes through this — never call litellm.completion or the Ollama client directly.
  • Director — Nemotron-driven planner + verifier in alphaswarm/data/pipelines/director.py. Sits between discovery and materialisation in generic file ingestion.
  • IngestionPlan / PlannedDataset — Director output dataclass. One PlannedDataset per discovered family with target namespace, table name, expected_min_rows, domain hint, and skip list.
  • VerifierVerdict — Director's post-materialise judgement (accept or retry with adjusted knobs).
  • __assets__ family — Synthetic DiscoveredDataset carrying the non-tabular inventory (PDFs, XML, images) found during discovery. Never materialised; surfaced under IngestionReport.extras for visibility.
  • AgentDecision / DebateTurn — Agent crew audit trail rows.
  • CrewRun — One full agentic crew invocation (planner → research → execution sub-agents).
  • Alpha158 — Microsoft Qlib's 158-feature factor zoo, ported to AlphaSwarm under alphaswarm/data/indicators_zoo.py.
  • FeatureSet / FeatureSetVersion — Composable feature spec (list of IndicatorZoo expressions + transformations) versioned in Postgres, materialised on demand.
  • ModelDeployment / MLDeployment — A trained ML model that has been registered for inference (rows in alphaswarm/persistence/models.py).

Bots​

  • Bot — Smallest self-contained, deployable unit on AlphaSwarm. Aggregates a universe + data pipeline + strategy + backtest engine + optional ML deployments + optional agent specs + RAG plan + metrics
    • risk caps + deployment target. Lives under a Project and is uniquely identified by (project_id, slug). See alphaswarm_docs/bots.md.
  • BotSpec — Pydantic blueprint for a bot. Hashed via snapshot_hash() to drive immutable bot_versions snapshots. Defined in alphaswarm/bots/spec.py.
  • TradingBot / ResearchBot — Bot subclasses selected by BotSpec.kind. TradingBot does backtest / paper / deploy; ResearchBot does chat (and optional backtest if a strategy block is set).
  • BotRuntime — Single sanctioned execution entry point for any bot lifecycle action. Snapshots specs into bot_versions, opens bot_deployments rows, and emits progress through alphaswarm/tasks/_progress.py.
  • bot_versions — Immutable, hash-locked spec snapshots (mirrors agent_spec_versions). Never mutated in place.
  • bot_deployments — Ledger of every backtest / paper / chat / k8s invocation for a bot. References the BotVersion that produced it so a run can be replayed.
  • Deployment target (paper_session / kubernetes / backtest_only) — Selected via BotSpec.deployment.target. Backed by alphaswarm/bots/deploy.py::DeploymentDispatcher.

Provider catalog​

  • LLMProvider — Lightweight handle around a LiteLLM provider spec. Registered in alphaswarm/llm/providers/catalog.py::PROVIDERS.
  • ProviderSpec — Static config for a provider slug (LiteLLM prefix, env-var name, default models).
  • vllm provider — OpenAI-compatible vLLM endpoint behind LiteLLM's openai/ adapter. Empty ALPHASWARM_VLLM_BASE_URL disables.
  • nemotron-3-nano:30b — Default Director model on Ollama (NVIDIA Nemotron Nano v3, 31.6B params). Pull with ollama pull nemotron-3-nano:30b. Configurable via ALPHASWARM_LLM_DIRECTOR_MODEL.

Streaming + live​

  • KafkaDataFeed — In-process Kafka consumer that hands bars/quotes to the IDataQueueHandler interface.
  • features.indicators.v1, market.bar.v1, … — Versioned Kafka topics. Naming pattern is <domain>.<entity>.v<n>.
  • StreamingIngester — alphaswarm-stream-ingest CLI that publishes to Kafka topics from Alpaca / IBKR.
  • Heartbeat / kill-switch — Periodic Redis publish from the paper- trading session; absence triggers the runner to halt. ALPHASWARM_RISK_KILL_SWITCH_KEY (default alphaswarm:kill_switch).

Observability​

  • OTEL endpoint — ALPHASWARM_OTEL_ENDPOINT (default empty disables). When set, every Celery task and HTTP request emits OpenTelemetry spans via alphaswarm/observability/.
  • Progress bus — Redis pub/sub channel alphaswarm:task:<task_id> carrying {stage, message, timestamp, **extra} payloads. UIs subscribe via the WebSocket relay at /chat/stream/{task_id}. See alphaswarm/ws/broker.py and alphaswarm/tasks/_progress.py.

Configuration​

  • settings — Cached Settings instance re-exported from alphaswarm/config/settings.py, a backward-compatible shim over alphaswarm_config.engine.settings (the setting implementation moved to the alphaswarm_config sibling package). Always import as from alphaswarm.config import settings and never construct Settings() directly.
  • ALPHASWARM_* env namespace — Every settable knob takes the ALPHASWARM_ prefix. Bools accept true/false/1/0. Paths are resolved by _coerce_path.
  • host-downloads — /host-downloads:ro bind mount in alphaswarm_platform/compose/docker-compose.yml exposing the user's local Downloads/ directory for CLI ingest jobs.

Inspiration rehydration (Phase 2026-04-29)​

  • Microprice — (P_ask * Q_bid + P_bid * Q_ask) / (Q_bid + Q_ask). Volume-weighted refinement of mid-price; converges to the deeper side of the book. Implemented in alphaswarm/data/microstructure.py.
  • OBI (Order Book Imbalance) — (Q_bid - Q_ask) / (Q_bid + Q_ask), range [-1, +1]. Positive = bid-side pressure. Used as a quote skew signal in the LOB market-making strategies under alphaswarm/strategies/hft/.
  • VPIN — Volume-synchronized probability of informed trading (Easley/López/O'Hara). Re-buckets trade flow by equal-volume buckets; rolling mean of |buy-sell|/|buy+sell|. See alphaswarm/data/microstructure.py.
  • Sample-aware Sharpe — Annualised Sharpe ratio that uses the actual sample frequency of a returns series instead of the assumed 252 trading days. Required for HFT strategies with sub-daily bars. See alphaswarm/backtest/hft_metrics.py.
  • Walk-forward — Training scheme where the model is re-fit on a rolling (or anchored) window and tested on the immediately following slice. Implemented in alphaswarm/backtest/walk_forward.py.
  • Bachelier (Normal) model — Options pricing model assuming the underlying follows arithmetic Brownian motion (dF = sigma dW). Appropriate for low-priced or near-zero underlyings (rates, basis spreads). See alphaswarm/options/normal_model.py.
  • Inverse option — Option settled in the underlying asset (e.g. BTC) rather than quote currency (USD). Common on crypto venues like Deribit. See alphaswarm/options/inverse_options.py.
  • Regime classifier — Lightweight classifier that labels each bar as trending vs ranging using ADX threshold (default 25) or as bull/bear/neutral via multi-MA slope vote. See alphaswarm/data/regime.py.
  • Factor expression — Tiny Polars-based DSL covering Alpha101 primitives (Ts_Mean, Ts_Std, Rank, Decay_Linear, Delta, Ts_Corr). See alphaswarm/data/factor_expression.py.
  • Engle-Granger cointegration — Two-step test for cointegrated pairs: OLS hedge ratio + ADF test on the residual. See alphaswarm/data/cointegration.py.
  • Triple-barrier label — Lopez de Prado labeling: look forward horizon bars, label +1 if upper barrier hit first, -1 if lower, 0 if horizon reached. See alphaswarm/data/labels.py.
  • Yang-Zhang volatility — OHLC vol estimator combining overnight, open-to-close, and Rogers-Satchell components. The most efficient of the OHLC family. See alphaswarm/data/realised_volatility.py.
  • LobStrategy — ABC for limit-order-book strategies; subclasses emit OrderIntent lists in response to LobState updates. Engine integration is deferred — see alphaswarm_snippets/extractions/_FUTURE_PROMPTS/lob_adapter_prompt.md.
  • Dataset preset — Curated declarative spec for a one-click ingestion (e.g. intraday_momentum_etf, crypto_majors_intraday). See alphaswarm/data/dataset_presets.py.
  • Inspiration source — One of seven external repos under alphaswarm_snippets/inspiration/ from which strategies / models / agents were rehydrated. Tracked via the source kwarg on alphaswarm.core.registry.register and surfaced as the source:* tag.

Testing​

  • tests/data/test_pipelines_smoke.py — Reference test for the Iceberg ingestion path. New ingest features should add a test in this directory.
  • director_enabled=False — Pass when constructing IngestionPipeline in tests so the real LLM is bypassed in favour of the deterministic identity plan.

Platform terms added 2026-07/08​

New vocabulary from the July–August 2026 development window (see the 2026-08-13 changelog for the full story).

  • TrialLedger — Postgres ledger (trial_families / trial_attempts) recording every research trial so DSR/PBO statistics use an honest trial count N. See Promotion evidence.
  • EvidenceBundle — The lab-produced package of DSR, PBO, and trial counts that the PromotionGateChain verifies before a strategy can be promoted; crosses the plane boundary via a registered probe port, never a direct lab import.
  • ApprovedPromotion token — Proof-of-approval that paper/live execution demands before running a promoted artifact.
  • Approval TTL / expiry — Time-to-live stamped on every queued HITL approval; overdue requests flip to expired (sweeper) or return HTTP 410 at decide time. See Approval queues.
  • Six clocks — The six named latency checkpoints along the order path (md.event_lag, strategy.dispatch_wait, strategy.decide, oms.gate, oms.persist, broker.submit_ack, ams.apply_fill) exported as OTel histograms. See Six-clock latency.
  • Vendor home — The single sanctioned module per market-data vendor (under alphaswarm/streaming/vendors/) where that vendor's SDK clients may be constructed; enforced by a CI import guard. See Market-data vendors.
  • BYOK ("Rule 55") — Bring-your-own-key: vendor/broker credentials resolve through the CredentialResolver chain before any settings fallback, so keys stay out of process env.
  • Confluent wire framing — Kafka payload framing (magic byte + schema id) with a dual-read decoder; unknown schema ids fail closed. See Streaming governance.
  • Feed URN — Catalog-governed stream address resolved by KafkaDataFeed.from_feed_urn, replacing hard-coded topic names.
  • Semantic layer — The committed-YAML metrics catalog + local compiler exposing named business metrics via data.dbt.* tools. See dbt semantic layer.
  • First-class module facade — The opt-in alphaswarm/facade/ re-export + Protocol layer from ADRs 033–039 that defines the stable public kernel surface. See the transformation plan.
  • ExecutionProfile translator — Default-off converter between orchestration-shaped and worker-shaped execution profiles (part of the facade program).
  • Schema readiness — The /health + /readyz subsystem that distinguishes "migrations pending" from "database down".
  • Supervisor lease — agent_run_lease row (partial unique index) providing mutual exclusion for supervised agent runs, swept by a guarded beat task.
  • Tenancy strategy defaults — resolve_tenancy_strategy picks shared-RLS (b2c), schema-per-tenant (b2b), or database-per-enterprise (enterprise); explicit strategy always wins.
  • RebacAuthorizationPort — Bridge adapting relationship-based access control (ReBAC) onto the core AuthorizationPort for document/bot sharing, fail-closed.
  • LLM gateway repoint — Flag-gated (llm_gateway_route_enabled) reroute of LLM calls to the in-cluster LiteLLM proxy; accounting keeps original model ids, faults fail open to the direct path.
  • Fleet analyst perception tools — Default-off, read-only market perception MCP tools (data.market.assess_macro, data.market.assess_vix, data.market.crypto_momentum, data.feature.news_sentiment) for fleet analyst personas; payloads are descriptive only.

Cross-repo​

  • agentic_assistants — Sibling repo providing the cross-system lineage API (ALPHASWARM_AGENTIC_ASSISTANTS_API).
  • rpi_kubernetes — Sibling repo with the k8s deployment manifests under alphaswarm_platform/deploy/k8s/.