Inalpha 🦊

Quant agents that evolve under audit.

An oracle that keeps a ledger.

Factor timing · Multi-perspective research · Factor lab · Risk engine · Strategy evolution · Machine-approved orders · Omikuji

English | 中文

Every factor proposed, every strategy mutated, every order routed — logged, versioned, reviewable. Agents pick the currently-effective factors to time entries, write the strategies, and evolve them; the LLM writes the code, and the engineering harness signs every decision.

Inalpha is a professional quant agent framework — an open-source system where LLM agents research (with a panel of investing legends), pick the factors that work now, write and evolve strategy code, and route every order through machine approval, all under an audit-grade engineering harness. A unified kernel (one strategy codebase — swap only the Clock and Gateway), multi-market routing (crypto, US equities, A-shares, global indices, macro), and a Claude Code-style hooks/permissions/plan-exec layer back it — built for teams that demand every decision be provable and every order path be unreachable by the LLM directly.

Hosted console · Request trial access
_{Apply for an account. After approval, an activation link is sent by email.}

--- ## Overview Inalpha is a **professional quant agent framework, governed by engineering discipline**. It treats LLM agents not as black-box signal generators, but as code-writing collaborators bounded by hooks, permissions, plan-then-execute approval, and a one-shot signature on every order path. **Agents pick the factors that work *now*.** Instead of a hard-coded indicator set, they rank factors by time-series Rank IC and surface the ones currently effective (`factor.timing`), then use that to back research and timing. Data itself is source-attributed by default — `as_of`-stamped and freshness-checked — so agents don't quietly reason on stale data. Several capability lines sit on top of that harness: - **Factor lab + factor timing** — agents formalize, compute, IC-test, multiple-testing-check, and register factors, and rank them by time-series Rank IC to time entries; every hypothesis is logged with author, timestamp, and the economic-story gate decision. - **Multi-perspective research** — a deep dive convenes technical / fundamental / sentiment analysts, plus an optional panel of investing legends (Buffett / Lynch / Wood / Burry / Druckenmiller / Marks) for opposing views that feed a synthesis. - **Risk engine** — declarative rules (notional caps, price deviation, drawdown veto) enforced at the HTTP boundary, not in prompts. - **Strategy evolution** — LLMs mutate full Python source through auditable unified diffs; AST audit, restricted loading, subprocess execution, and the `Strategy` protocol contract precede evaluation; multi-objective fitness (Sharpe + Calmar − turnover − drawdown) keeps one metric from dominating. - **Machine-approved orders (no direct LLM path)** — order intents go `trade.create_plan → approve → execute_plan` with a single-use, TTL-bound `approval_token`; the LLM has no direct path to placing an order, and every step is logged into the audit trail. - **Inari Omikuji — a shrine fortune draw (playful easter egg)** — undecided on direction? Cast a hexagram or draw a tarot card for a vantage outside the data; **hard-walled from decisions**, it can't touch risk, orders, or factors (see Core Capabilities §7). The name combines **Ina**ri (the Japanese fox deity of prosperity) with **alpha** (the quant term for excess return) — a companion that reads your direction and keeps every step on the record. > **Status:** Inalpha is in **alpha** — 79 factors with lineage & decay watch, restricted-DSL factor discovery, a three-party research debate, multi-market paper trading, and E1/E2 strategy evolution. Feature-flagged E2 adds point-in-time event snapshots, deterministic hypothesis DSL compilation, five-generation campaigns, Forward evidence, and one-shot sealed holdout. Evolution never auto-promotes, starts, or trades a candidate. Read the code, weigh in on design — **do not run this against real money** (real-money trading is out of scope). --- > Code checked on **2026-09-30**: owner-scoped EvolutionLoop reuse, durable dispatch with > leases/checkpoints, atomic stage handoffs, and bounded loop authorization/cost accounting > are implemented. Automated tests cover recovery and gate behavior; complete real-environment > runs and restart validation still need recorded evidence. Final adoption remains manual and > experimental candidates remain Runner-ineligible. See the [current state and next steps](docs/04-current-state.md#未完成--下一步). > E2 update (2026-10-10): explicit experiment preparation and frozen cost approval are implemented; the central checklist tracks deployment and normal-owner acceptance. E1 owner execution and E2 insufficient-input rejection have production evidence; the positive champion/Forward/holdout path remains unverified. See the [current-state checklist](docs/04-current-state.md#未完成--下一步). ## The Operator Console The **Operator Console** (`apps/dashboard`) is the home base — a runtime dashboard that surfaces everything you'd otherwise have to ask the agent for, with a docked agent chat on the right. The shots below are the live console, running locally.

Portfolio Overview

_{Portfolio Overview — accounts, positions, live runners, recent orders, and the strategy pool at a glance, with a KPI strip (return · max drawdown · Sharpe · win rate).}

_{Strategy Lab — LLM-authored candidates ranked by multi-objective fitness, filterable by status; click into source + audit log.}	_{Live Runners — promoted strategies auto-run on live bars; every bar's decision is logged and replayable.}
_{Risk Panel — declarative rules enforced before any trade; active locks and event history in real time.}	_{Factor Library — 79 factors (pandas-ta / Alpha101 / qlib + FRED macro) ranked by current-effectiveness IC.}

_{Runner Detail — Chart — drill into a paper runner: cumulative PnL (with %), win rate, decisions count, and risk-blocked tally, with every entry/exit plotted on live bars.}

_{Runner Detail — Positions & Decisions — open positions, a per-bar decision timeline (side · qty · fill · closed PnL), and the instrument's effective factors ranked by current IC.}

> See [Quick Start](#quick-start) to bring the console up locally (`pnpm dev` → ). --- ## Design Principles | Principle | Substance | |---|---| | **Discipline over vibes** | Hooks, permissions, plan-exec separation, and a one-shot approval token are declared in config — not in prompts. A failing guardrail has a single point of debug. | | **Structured roles, not a chat wrapper** | Research convenes a panel of analysts and an opposing-stance bull / bear / risk debate; every decision routes through hooks, permissions, and plan-exec. The structure lives in code, not in one mega-prompt. | | **Transparency over precision** | Prefer an agent that says "I don't know" over one that sounds certain but cannot show its evidence. | | **Unified kernel** | One strategy codebase across backtest and paper — swap the Clock and Gateway, not the logic. When behavior diverges, the cause is physical (slippage, latency, data precision), not two code paths. (Real-money live is intentionally out of scope.) | | **Long-horizon compounding** | Solid infrastructure before flashy features. Surviving long matters more than running fast. | --- ## System Architecture Three software layers over one data layer. A request flows down; results flow back up. **L1 · User entry.** The Operator Console (`apps/dashboard`) is the home base, with a docked agent chat. The `mastra dev` playground is there for live trace; direct CLI tool calls still work. **L2 · Orchestration** — `packages/orchestration` (Mastra · TypeScript). The one layer LLMs run in: a single orchestrator agent wrapped in tools, hook/permission middleware, DB-backed plan/approval state, conversation memory, and telemetry. **L3 · Kernel services** — Python · FastAPI. Five independent services, each owning one job: | Service | Owns | |---|---| | `services/data` | Market data, web search, and financial fundamentals (A-shares / HK / US / global). | | `services/paper` | The event-driven kernel — backtest + paper on the **same code** — plus the LLM-authored-strategy sandbox and the live runner. | | `services/research` | Multi-agent deep dive: 6 analysts in parallel, then a bull / bear / risk debate (triggered only when they disagree, with a soft early-stop and the decision chain persisted for replay). | | `services/factor` | The factor library (pandas-ta / Alpha101 / qlib + FRED macro): IC screening, current-effective factor timing, lineage & decay watch, DSL factor discovery. **Signals only — never places an order.** | | `services/evolver` | Owner-scoped E1/E2 evolution: unified-diff mutation, event-hypothesis campaigns, frozen-data evaluation, lineage, cost accounting, Forward/holdout gates, and explicit final adoption. **Never auto-promotes, starts, or trades a candidate.** | **L4 · Persistence & external.** Postgres + TimescaleDB holds all time-series and business state. External venues span crypto, US / A-share / HK and other Asian & European single-name equities, global indices, and FRED macro — the orchestrator routes each venue automatically by market type. The strategy-evolution loop runs asynchronously alongside the runtime. It persists and ranks candidates inside `services/evolver`; moving a selected candidate into the Paper strategy lifecycle remains a separate, explicitly approved action — there is no automatic promotion (sandbox gates, fitness function, and the E1 → E4 ramp are in [Core Capabilities §3](#3-strategy-evolution--let-strategies-write-better-versions-of-themselves)). See [`docs/04-current-state.md`](docs/04-current-state.md) for the live module inventory and what's still in flight. --- ## Core Capabilities Each capability below is built so the work it produces is auditable from day one — not retrofitted later. ### 1. Factor Lab — propose, validate, and version every alpha hypothesis An *alpha hypothesis* is a guess about what predicts returns ("stocks with low volatility outperform"; "options skew steepens before drawdowns"). Traditional factor research is bottlenecked by the manual loop — a single researcher can usually validate 5–10 such guesses a day. Inalpha lets agents do that work without taking shortcuts. - **Talk it through.** Drop a hypothesis in plain language; agents formalize it, compute the values, and run the standard statistical checks in seconds. - **Not just a registry — timing too.** Rather than a hard-coded indicator set, agents rank factors by time-series Rank IC to surface the ones effective *right now* (`factor.timing`), backing research and entry timing — when the market rotates, the chosen factors rotate with it. - **Cross-section, not only timing.** The same factors also rank *across a basket* — `factor.panel_score` scores a universe by cross-sectional Rank IC each period (who's strongest now, who to rotate into), orthogonal to single-name timing. Alpha101 cross-sectional factors are computed natively on the panel. - **An economic story gate.** A factor without a "why" never enters the library. The gate is a required step, not a recommendation. - **Guardrails for the classic mistakes.** Looking ahead in time, surviving-only universes, over-parameterized search, too few samples, normalization leaks — five middleware checks intercept each one before it pollutes a result. - **No silent promotion.** Registering a factor to the library is permanently human-only. Rejected factors are kept on file for postmortems, not silently dropped. > Shipped today: conversational tools (L0), a fixed validation workflow (L1), and factor discovery — a restricted-DSL candidate pool with multiple-testing correction and a null-IC benchmark, plus lineage & decay watch on the factors a strategy depends on. A multi-agent factor crew (L2) and weekly automated scans (L3) are planned. Design notes in `docs/03-kernel-design.md`. ### 2. Risk & Audit — no LLM reaches the order path unsupervised Letting an LLM call `submit_order` directly is how you lose money fast. Telling it "don't exceed 10% of capital" in a prompt is a suggestion, not a constraint — a sufficiently confident model will override it. So Inalpha moves risk out of prompts and into the middleware. - **Three-step orders.** Every trade idea travels *propose → approve → execute*. Approval (by a risk agent, by a human, or by an automated rule) mints a single-use, short-lived signing token. Execution consumes the token; the token is revoked the moment it is spent. - **Hard rules at the service boundary.** Notional caps, price-deviation guards, drawdown veto, per-instrument-class limits — enforced before any state change. A violating order is rejected with its reason logged against the originating proposal. - **A complete audit trail.** Every proposal, approval, and execution is persisted with who, why, when, and the token's full lifecycle. The same record drives postmortems and feeds back into the strategy-evolution loop. - **A framework-level disaster stop.** Independent of any strategy, a Position Guard enforces a catastrophe stop-loss (default −20% hard stop) across both backtest and live — it doesn't ask the LLM, and a prompt can't talk it out of firing. ### 3. Strategy Evolution — let strategies write better versions of themselves Human-written strategies hit a velocity ceiling, and parameter tuning can only adjust dials — it cannot discover a structural change like "add an RSI filter to the SMA cross." Inalpha lets an LLM rewrite the strategy's Python source, then puts every candidate through hard gates before it ever touches a backtest. - **Full source with auditable mutations.** The run starts from a vetted built-in or owner-owned promoted strategy, asks the LLM for a unified diff, applies it with bounded fuzz, and persists both the parent snapshot and diff. - **Layered execution gates.** A static AST audit, restricted loader, subprocess evaluation, and final `Strategy` contract check reject malformed candidates. The subprocess boundary keeps CPU work away from the API loop; it is not presented as a hardened container or VM sandbox. - **Balanced fitness, baseline-checked.** Candidates are scored on a balanced fitness (return + risk-adjusted return − turnover − drawdown veto), and each is auto-raced against a buy-and-hold baseline — a high score has to beat just holding, not a single Sharpe number. MAP-Elites-style diversity control is deferred until after the narrower E2 loop and only if real runs justify it. - **Cross-validated, not a single lucky split.** A candidate can run time-series cross-validation — WalkForward / Purged K-Fold / Combinatorial Purged CV with a Deflated Sharpe — so an edge has to hold across many out-of-sample paths instead of one window, with the test fold always reaching the latest bar. - **Reproducible end to end.** One run freezes `as_of`, the closed-bar dataset manifest/hash, seed source, baseline, candidate source/diff, evaluation snapshots, and non-secret LLM/provider/pricing metadata. The user's encrypted API key is resolved only for that owner and never stored in the run. - **Explicitly authorized and non-promoting.** Starting a run requires a trusted approval bound to the owner, operation ID, request, estimated cost, and frozen LLM snapshot. Completion never promotes, starts, or routes a candidate into the order path. > E1 and feature-flagged E2 run in the separate `services/evolver` service on port 8005. E2 uses fixed 8×3 generations, novelty-aware inheritance, one locked Forward champion, and a single-use sealed holdout; MAP-Elites and Island Model wait for real run data to justify the complexity. ### 4. Swarm — run dozens of backtests in parallel Real quant research is concurrent by nature: 5 symbols × 3 factor families × 4 time windows = 60 backtests. Running them one at a time inside the agent runtime is a dead end. Inalpha splits *scheduling* from *compute*. The agent runtime fans out the grid and aggregates results; a Python worker pool inside `services/paper` actually runs the backtests in parallel processes with resource limits. "Run momentum / mean-reversion / breakout across BTC, ETH, SOL, BNB, AVAX for 2024" becomes one workflow call that returns a Pareto frontier. > Current implementation (S1): single-host process pool, concurrency 4, grid capped at 20 backtests per call. ### 5. Research — a panel of investing legends A deep dive doesn't hand you one "correct answer." Beyond the usual technical, fundamental, and sentiment analysts, you can convene a panel of master personas — Buffett (value / moats), Lynch (GARP growth), Wood (disruptive innovation), Burry (contrarian / bubbles), Druckenmiller (macro trends), Marks (cycles / risk): each argues in their own style, naturally forming opposing views that feed a synthesized judgment. - **Opt-in, cost-controlled.** A plain deep dive costs the same as before; you only pay for the masters you actually convene. - **Views grounded in data.** Each persona reads technicals / fundamentals / web intel with `as_of` pinned to *now* — no passing a stale forecast off as the present. Fundamentals are read point-in-time, filtered by report period and release lag so a backtest never sees a number before it was public (Baostock today; yfinance v1 not yet PIT, flagged in place). - **Structured bull / bear / risk debate — now live.** Beyond the parallel analysts, opposing-stance bull and bear researchers argue across rounds while a risk researcher stress-tests both — triggered only when the analysts genuinely disagree, with a soft early-stop when arguments stop changing and the full decision chain (why it debated, why it stopped, how it was synthesized) persisted for replay. ### 6. Skills — absorb outside research playbooks A good investing method is often a *procedure*, not a model — "trace a hot theme down its supply chain to the bottleneck," say. Inalpha can load those as **skills**: auto-discovered markdown playbooks the orchestrator pulls into context on demand. - **Progressive disclosure.** On startup it scans the skills folder and surfaces a one-line menu; a skill's full text loads only when a task actually needs it — no prompt bloat, zero cost when none apply. - **Fail-open and trust-bounded.** A broken skill is skipped with a warning, never blocking the agent. Skills are read-only markdown (no bundled scripts are vendored or executed), and every "look up data" step is mapped onto the existing `web.* / data.* / factor.* / research.*` tools under the same freshness discipline. - **Bundled today.** `cn-equity-research` (A-share systematic research), `serenity` (supply-chain-bottleneck investing), `earnings-analysis` (earnings recap), `thesis-tracker` (falsifiable-thesis tracking) — each rewritten to be market-agnostic and source-grounded, with any trade action routed back through the approval chain. ### 7. Inari Omikuji — undecided? draw a slip for direction Real money invites real hesitation. When you're stuck, let the Inari priestess — α kit on her shoulder — draw you an *omikuji* (a shrine fortune slip): cast an I Ching hexagram or pull a tarot card for **a vantage outside the data**. A different angle, a breath, maybe a small unexpected nudge from Inari. - **A whisper, not an order.** The hexagram or card **never** touches risk, approval, order placement, or factor scoring — it can't read or sway a single real decision. Which quietly makes the point: if even Inari's omen can't reach the decision path, the machine-approval boundary is real. - **The trade still answers to data.** Once the slip is drawn, the call still belongs to research, factors, and backtests; the omikuji only helps unknot your brow. --- ## Guarding against overfitting The hardest adversary in quant research isn't the market — it's *multiple-testing bias*. Pick the best of many trials and you'll find a Sharpe of 2.0 in pure noise. So Inalpha never leans on one clever backtest; every stage where a "best" gets selected carries its own statistical correction. | Stage | Defenses | What it prevents | |---|---|---| | **Backtest validation** | Combinatorial Purged CV (purge + embargo) · Deflated Sharpe (corrects for N trials) · bootstrap Sharpe 95% CI · parameter-neighborhood sensitivity — `POST /backtest/cv`, `POST /backtest/sensitivity` | A lucky window, or a fragile parameter peak, passing as a real edge | | **Factor screening** | null-IC selection benchmark · Benjamini–Hochberg FDR correction · economic-story gate · ρ < 0.85 de-correlation | A data-mined ghost factor reaching the library | | **Strategy evolution** | multi-objective fitness (return − turnover − drawdown veto) · buy-and-hold baseline race | A candidate gaming a single metric to look good | | **Look-ahead defense** | point-in-time fundamentals · FRED release-lag table · bars truncated to `as_of` · CV test fold ends on the latest bar | A backtest seeing data that wasn't public yet | > DSR and the bootstrap Sharpe CI are surfaced in the CV / backtest reports today; PBO (Probability of Backtest Overfitting, CSCV) lives in `services/paper/.../engine/robustness.py`, ready for swarm-grid comparison. --- ## Roadmap Where each capability stands today. Live module inventory and the end-to-end decision sequence diagram live in [`docs/04-current-state.md`](docs/04-current-state.md). | Status | Capability | Phase | Highlight | |---|---|---|---| | ✅ Shipped | Plan/Exec audit trail + Hooks + Permission Engine | D-8a | three-step orders · one-shot signing token · 5 lifecycle hook events · allow / ask / deny tri-state | | ✅ Shipped | Research → strategy → backtest lineage | D-8c | `deep_dive → compose_strategy → run_backtest` with `research_id` / `backtest_id` threaded through | | ✅ Shipped | LLM-authored strategies — E1 MVP | D-9 | three sandbox gates (AST · subprocess · `Strategy` contract) + multi-objective fitness + baseline auto-run | | ✅ Shipped | Strategy evolution — E1 production loop | E1 | `services/evolver:8005` · explicit cost-bearing approval · unified-diff mutation · frozen dataset/hash · seed/baseline/candidates evaluated on the same bars · owner-scoped async run/slot state | | ✅ Shipped | Frozen LLM approval snapshot | E1 closure | Dashboard approve/deny · owner/operation/model/pricing binding · Ed25519 replay-safe credential grant · per-slot token/cost accounting, including rejected mutations | | ✅ Feature flag | Event-driven automatic evolution | E2 | bitemporal event snapshots · HypothesisSpec DSL · five 8×3 generations · Forward + one-shot sealed holdout · human experimental adoption only, never Runner eligible | | ✅ Shipped | Risk engine at the HTTP boundary | D-9 | declarative `risk_rules.toml` · pre-trade `enforce` · `risk_locks` table with independent commit | | ✅ Shipped | Bull / bear researcher debate | D-9 | opposing-stance researchers under `services/research` | | ✅ Shipped | Scheduler / cron agent mode | D-9 | `scheduler_jobs` + advisory lock + `/api/scheduler/*` management plane | | ✅ Shipped | RiskGuard per-account isolation | D-9.1a | `RiskGuardFactory` removes cross-account state bleed | | ✅ Shipped | Multi-market data sources — web search + financial fundamentals | D-10 | zero-key DDGS web search · `baostock` is the logical A-share venue: Tencent HTTPS bars/ticker + Baostock fundamentals/calendar/constituents; yfinance covers global markets including HK · analyst integration + fallback · per-market lookbackDays | | ✅ Shipped | Unified multi-market financial news | D-12 | `GET /news` + `data.get_news` · Eastmoney / SEC / HKEX / Crypto feeds · current-snapshot `as_of` filtering with explicit incomplete-history coverage · observable provider failures · explicit index/ETF proxy labels for market-level stock news | | ✅ Shipped | Risk engine — all 5 rules live in HTTP path | D-9 closed | `closed_trades` writes from HTTP order flow; `RoutingCalendar` for US equity + crypto; all trade-based rules trigger on real data | | ✅ Shipped | `askUserChoice` — `ask` permission path | D-11 (issue #2) | pending-permission flow resolves the `ask` state (no longer a workaround) | | ✅ Shipped | `permissions.yaml` configuration | D-11 (issue #4) | `config/permissions.default.yaml` + `yaml_loader.ts` replace the hard-coded `defaults.ts` | | ✅ Shipped | Multi-market paper trading — live runner + multi-currency cash | D-11 | closed-bar `on_bar` → guarded plan/exec · per-currency cash buckets + FX-converted equity · D-11.1 trust-boundary hardening (candidate ownership check · per-account run cap · retryable-error split) | | ✅ Shipped | Factor library + IC effectiveness | D-11 | `services/factor` (pandas-ta / Alpha101 / qlib) · `factor.timing` / `.score` / `.catalog` · signals only, no execution | | ✅ Shipped | Live runner ops hardening | D-11.2 | net PnL (fees deducted) · runtime TTL auto-stop · build-phase backoff + error classification | | ✅ Shipped | Skills as procedural memory | D-11 | auto-discovered markdown skills (progressive disclosure · fail-open · read-only trust boundary) | | ✅ Shipped | Research debate — three-party + contested trigger | D-12 | 6 analysts + bull / bear / risk researcher · contested-only trigger · Jaccard soft early-stop · decision chain persisted | | ✅ Shipped | Factor lineage & decay watch | D-12 | `factor_snapshot` + `factor_baseline` · independent decay patrol · `factor_decay` warning (alert-only, no auto-trim) | | ✅ Shipped | Monthly FRED macro factors | D-12 | CPI / core CPI / unemployment / payrolls / M2 (62 → 70 factors) · per-series release-lag table | | ✅ Shipped | FRED macro factors — Phase 3 | D-12 | credit spreads (HY / IG OAS) · curve front-end (10Y–3M) · real economy (PPI / industrial production / retail) · sentiment (70 → 79 factors) | | ✅ Shipped | Factor discovery — L1 | D-12 | restricted qlib-style DSL (zero eval/exec) · `factor_candidates` pool · multiple-testing correction + null-IC benchmark · discovery workflow → propose; register is dashboard-only | | ✅ Shipped | Cross-sectional factor scoring | D-12 | `factor.panel_score` · `POST /panel/score` · cross-sectional Rank IC (rank the pool each period vs forward cross-sectional return) · native Alpha101 a1/a3 · orthogonal to single-name timing | | ✅ Shipped | Time-series cross-validation — anti-overfitting | D-12 | WalkForward / PurgedKFold / Combinatorial Purged CV + Deflated Sharpe · `POST /backtest/cv` · test fold always includes the latest bar · auto-fallback to walk-forward when samples are short | | ✅ Shipped | Point-in-time fundamentals | D-12 | Baostock financials filtered by actual publication date · `GET /fundamentals?as_of=` · prevents look-ahead (yfinance v1 not yet PIT, explicitly flagged) | | 🗓️ Planned | Factor discovery — L2 / L3 | L2 / L3 | multi-agent factor crew (L2) + weekly automated scans (L3), on top of the L1 DSL pipeline already shipped | | 🗓️ Planned | Automated decay handling | TBD | reflection-driven backtest + auto-trim of decaying factors — today the decay patrol only alerts, never moves the book | | 🔬 Exploring | Alpha Zoo cold start | E1+ | seed factor library with public alphas (Qlib / Kakushadze / GTJA) | | 🔬 Exploring | E4 `evolve_strategy` MCP tool | E4 | evolution loop exposed to the orchestrator as one MCP tool | | 🔬 Exploring | Point-in-time fundamentals — deeper coverage | TBD | bars-table PIT metadata + adjustment handling, beyond the report-lag filter shipped today | | 🔬 Exploring | Analog backtesting | TBD | similarity-window-driven backtest range selection (STUMPY) | > **Legend** — ✅ Shipped: behavior already lives in `main` · ⏭️ In Flight: actively in this phase · 🗓️ Planned: scoped for an upcoming phase, not started · 🔬 Exploring: research recorded, no commit date. --- ## For whom | Audience | Value | |---|---| | Quant researchers and students | LLM agents accelerate research; one tech stack for backtest and live | | Trading system engineers | A reference integration of modern agents with traditional kernels, cross-referenced against Nautilus / qlib / vnpy | | AI agent developers | Real-world financial deployment of multi-agent + hooks + permissions | | Individual traders (research-oriented) | A research companion you can talk to, plus an engineered home for your strategies | --- ## Quick Start ### Docker self-hosting (recommended) This is the supported Docker path for a personal server or local machine. It builds the complete stack locally: PostgreSQL/TimescaleDB, Redis, migrations, data, paper, research, factor, evolver, Mastra, and the Operator Console. Prerequisites: Docker Engine with Docker Compose v2, Git, and OpenSSL. Clone the repository, then initialize the local-only environment file and start the stack: ```bash git clone https://github.com/mirror29/inalpha.git cd inalpha bash scripts/selfhost.sh init bash scripts/selfhost.sh up ``` The console is available only on the host at . Wait until `bash scripts/selfhost.sh status` shows the application services healthy, then create the first login account. The prompt reads the password without echoing it or placing it in shell history: ```bash bash scripts/selfhost.sh create-user --email you@example.com ``` For a public deployment, create the review account with the `admin` role (use your existing owner subject if it must keep the current account data): ```bash bash scripts/selfhost.sh create-user --email admin@inalpha.dev --roles admin --subject console:dev ``` Visitors can then choose **Request a trial** on the sign-in page. Registration creates a `pending` account without accepting a password. Approval in **Trial Waitlist** generates a one-time activation link: send it to the applicant's stated email address to verify mailbox ownership. The applicant sets a password from the link and only then becomes active. Links expire after 48 hours and can be regenerated; rejected applications remain blocked. Because the application endpoint is public, keep a persistent per-IP rate limit or challenge enabled at the reverse proxy / CDN layer; the in-process limits are only a second line of defence. Sign in at , open **LLM Settings**, and add your provider, model, and personal API key. The Dashboard encrypts it with `LLM_CONFIG_ENCRYPTION_KEY`; the orchestrator and Evolver resolve that owner-scoped credential. The standalone Research service still uses the deployment-level `LLM_PROVIDER` / `LLM_MODEL` and matching provider key in `infra/.env.selfhost`, so configure that block if you need deep dives and treat it as a shared-credential boundary until per-owner propagation lands. Useful operations: ```bash bash scripts/selfhost.sh logs [service] bash scripts/selfhost.sh status bash scripts/selfhost.sh down ``` #### Public deployment The self-host Compose file intentionally exposes only `127.0.0.1:3001`. For remote access, place your own TLS-terminating Caddy, Nginx, or Cloudflare Tunnel in front of the Dashboard and proxy only that address. Never publish PostgreSQL, Redis, Mastra, or the Python service ports, and do not expose the login or API-key settings page over bare HTTP. ### Local development ### 1 · Install dependencies ```bash cd packages/orchestration && pnpm i && cd ../.. for service in data paper research factor evolver; do (cd "services/$service" && uv sync) done ``` ### 2 · Configure your LLM key (required) A single `.env` at the repo root is read by Mastra (TS) **and** all Python services. Copy the template and fill in the LLM provider you want to use: ```bash cp .env.example .env ``` Inside `.env`, set `LLM_PROVIDER` to one of `deepseek | anthropic | openai | gemini | kimi | zhipu | ollama` and fill in the matching key. Defaults pick each vendor's preferred Inalpha model as of 2026-09. Override with `LLM_MODEL=...` if you want a reasoning / flagship variant. | Provider | env var | Default model (2026-09) | Get a key | |---|---|---|---| | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-flash` | [platform.deepseek.com](https://platform.deepseek.com) | | `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-4-8` | [console.anthropic.com](https://console.anthropic.com) | | `openai` | `OPENAI_API_KEY` | `gpt-5.5` | [platform.openai.com](https://platform.openai.com) | | `gemini` | `GEMINI_API_KEY` | `gemini-3-pro` | [aistudio.google.com](https://aistudio.google.com) | | `kimi` | `KIMI_API_KEY` | `kimi-k2.6` | [platform.moonshot.ai](https://platform.moonshot.ai) | | `zhipu` | `ZHIPU_API_KEY` | `glm-5.2` | [open.bigmodel.cn](https://open.bigmodel.cn) | | `ollama` | — (local) | `llama4` | `ollama pull llama4` | Override the default model by setting `LLM_MODEL=...` in the same file. Mastra and `services/research` both read this one file — no per-service config to juggle. If you want to run Evolver, also generate its Ed25519 credential-grant keypair and place the DER base64 values in `EVOLUTION_CREDENTIAL_PRIVATE_KEY_B64` / `EVOLUTION_CREDENTIAL_PUBLIC_KEY_B64`. The exact commands are in [`services/evolver/README.md`](services/evolver/README.md). Evolution is fail-closed without these keys and currently accepts only the priced default model for each of DeepSeek, OpenAI, Kimi, and Zhipu; ordinary chat can still use other models or custom proxies. > Already have keys in `services/*/.env` or `packages/orchestration/.env` from earlier? Those still work as cwd-level overrides while you migrate. Once you copy them up into the root `.env`, the per-service files can be deleted. **Optional · FRED key for macro factors.** The factor library's macro factors (`macro.*` — rates, term & credit spreads, CPI, payrolls, real-economy, sentiment) read FRED data via `venue=fred`. Set `FRED_API_KEY` in `.env` to enable them — it's [free and instant](https://fred.stlouisfed.org/docs/api/api_key.html). Without a key the connector simply isn't registered and macro factors degrade gracefully (price/volume factors are unaffected). Note: macro factors are computed **only at `timeframe=1d/1wk`** — they're filtered out on intraday bars (monthly series would be a step function), so request `1d` to see them. ### 3 · Start PostgreSQL / Redis and migrate ```bash cp infra/.env.example infra/.env (cd infra && docker compose up -d) (cd infra/migrations && uv sync && uv run alembic upgrade head) ``` The local defaults in `infra/.env.example` and the repository-root `.env.example` are intentionally identical. If you change the database password or port, update both files before starting services. ### 4 · Start all services ```bash bash scripts/dev.sh # one shot — data (8001) + paper (8002) + research (8003) + factor (8004) + evolver (8005) + mastra (4111) bash scripts/dev.sh logs # follow service logs bash scripts/dev.sh stop # stop everything ``` ### 5 · Open the Operator Console — your home base The **Operator Console** is the recommended way to use Inalpha — your home base. A runtime dashboard surfaces everything you'd otherwise have to ask the agent for, at a glance: portfolio & positions, live runners with bar-by-bar decisions, the cross-module agent activity timeline, the strategy lab, the system factor library, the risk panel, and the Inari Omikuji. **A docked agent chat sits on the right** — talk to the orchestrator directly: pull quotes, run backtests, tune factors, draw a hexagram, all in one place. ```bash cd apps/dashboard pnpm i # first time only pnpm dev # → http://localhost:3001 ``` No per-app config — the console reads the repo-root `.env` directly (backend URLs + `JWT_SECRET` are inherited), so as long as the services from step 4 are up, it just connects. It ships with **dark / light themes** (a terminal "Vermilion" aesthetic — see [`apps/dashboard/design.md`](apps/dashboard/design.md)) and an `en / 中` switcher in the sidebar. > The console is the single front door: data, research, backtests, live runners, and the > conversation with the orchestrator now all live in one place. **Try automatic event evolution locally.** Set `EVENT_EVOLUTION_ENABLED=true` in the repository `.env`, and either import historical event facts or also enable the archive/extraction workers with `EVENT_ARCHIVE_ENABLED=true` and `EVENT_EXTRACTION_ENABLED=true`. Restart the services, then open a strategy, paper-run, or E1-result detail page and choose **Start evolution**. You can also type “start evolution” in the docked agent chat. Repeated requests reuse the same active owner-and-target loop. E2 runs its generations without per-generation approval, but a result still needs manual adoption and remains research-only (`runner_eligible=false`). A target with no point-in-time event facts fails before spending LLM budget with `EVENT_SNAPSHOT_EMPTY`. > The orchestrator and an explicitly approved `services/evolver` run can consume your owner-scoped > LLM key; `services/research` currently uses the deployment-level provider/key, and > `services/paper` never calls an LLM directly. Evolver resolves the encrypted credential just in > time through an owner/operation-bound credential grant. A lost response permits one exact-scope > retry within two minutes; the queued grant is cleared after a successful exchange, and only the frozen > non-secret config/pricing snapshot remains. > Prefer the manual multi-terminal flow, or want the low-level live > trace (the `mastra dev` playground at )? See [`AGENTS.md §4`](AGENTS.md). ### 6 · Try asking With the console up, talk to the orchestrator in the docked chat on the right — it replies in the language of your message. Each prompt below shows off a different part of the system: - `Which factors are working for NVDA right now, and how strong is each?` — **factor timing**: ranks the currently-effective factors by time-series Rank IC, with decay state. - `Research NVDA: latest price + fundamentals, run a bull / bear / risk debate, and synthesize a rating.` — **multi-perspective research**: six analysts in parallel plus a three-party debate, triggered only when they disagree, with the decision chain persisted. - `Research TSLA with a Buffett and a Cathie Wood take.` — **investing-legends panel**: opt-in master personas argue in their own styles. - `Trace the AI-compute supply chain to its tightest bottleneck and surface the names worth researching first.` — **research-methodology skills**: auto-loads an external playbook (e.g. `serenity` supply-chain bottleneck, or `cn-equity-research` for A-shares). - `Design a mean-reversion strategy for ETH, backtest the last 6 months, and show its fitness vs buy-and-hold.` — **LLM-authored strategy**: the model writes the full source, it clears three sandbox gates, then auto-races a baseline. - `Evolve my promoted BTC strategy with one candidate and stop after this run.` — **E1 evolution**: shows the frozen model and estimated cost for approval, evaluates seed/baseline/candidate on one dataset hash, and leaves promotion as a separate human decision. - `Backtest momentum / mean-reversion / breakout across BTC, ETH, SOL for the last year and give me the Pareto frontier.` — **swarm**: dozens of backtests fanned out in parallel. - `Open a small NVDA position.` — **machine-approved orders**: watch it route through propose → approve → execute; the LLM has no direct path to placing an order. > Examples only, not a fixed menu — ask about any ticker or market (crypto · US · A-shares · HK · global indices · commodities · FRED macro) in any language; the orchestrator picks the venue and answers in kind. --- ## AI Collaboration Inalpha is **tool-neutral and local-first**. Strategies, data, and decision records live in your repository — LLM calls go to external providers, but structured outputs and cache control are owned by the codebase, so the harness is observable, auditable, and provider-swappable. The hard constraints (naming, untouchable directories, commit conventions, three-part tool-description style) are declared once and read by every AI coding tool: - [`CLAUDE.md`](CLAUDE.md) — Claude Code project-level memory - [`AGENTS.md`](AGENTS.md) — common entry point for Cursor / OpenAI Codex / Aider / Continue / Cline - `scripts/check-consistency.sh` — mechanical cross-file consistency checks --- ## Acknowledgments Inalpha is built on top of other people's good ideas. What we borrowed is named here so it's clear we're standing on their shoulders, not starting from zero. **Trading system designs** - [Nautilus Trader](https://github.com/nautechsystems/nautilus_trader) — the same-code invariant across backtest / paper / live, and the event-driven kernel - [vnpy](https://github.com/vnpy/vnpy) — the Gateway abstraction and multi-market access mindset - [Microsoft qlib](https://github.com/microsoft/qlib) — factor expression DSL and point-in-time universe handling - [Hummingbot](https://github.com/hummingbot/hummingbot) · [Freqtrade](https://github.com/freqtrade/freqtrade) — what open-source crypto tooling can be **Agent and LLM engineering** - [TradingAgents](https://github.com/TauricResearch/TradingAgents) — multi-agent opposing-stance debate for research - [Anthropic](https://anthropic.com) and the [Claude Code](https://claude.com/claude-code) team — hooks, permissions, plan/exec, MCP, and subagents as borrowable engineering primitives - [Mastra](https://mastra.ai) — the TypeScript agent orchestration scaffolding - [Model Context Protocol](https://modelcontextprotocol.io) — the open protocol that lets tools plug in without hand-rolled glue **Infrastructure** - [PostgreSQL](https://postgresql.org) · [TimescaleDB](https://timescale.com) · [FastAPI](https://fastapi.tiangolo.com) · [CCXT](https://github.com/ccxt/ccxt) · [Next.js](https://nextjs.org) · [CopilotKit](https://copilotkit.ai) · [uv](https://github.com/astral-sh/uv) · [pnpm](https://pnpm.io) And to every quant researcher who refuses to accept opaque "AI signals" — this project is written for you. We hope to give back, in time. --- ## License **[GNU AGPL-3.0](LICENSE)** — free software with a strong network copyleft. - Allowed: any use (personal research, academic, commercial in-house, integration into AGPL-compatible projects) - Required: if you modify Inalpha and offer it as a network service, you must release the complete corresponding source under AGPL-3.0 - Commercial licensing (proprietary / closed-source / hosted SaaS without source release): please open an issue to discuss a dual license ---

_{💬 Discussions · 📬 Subscribe on Substack · 📕 知乎专栏 — engineering notes, ADRs, post-mortems}

_{Inalpha · Where Inari meets alpha · 2026}