inalpha

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; three sandbox gates (AST audit, subprocess isolation, Strategy protocol contract) precede any candidate run; multi-objective fitness (Sharpe + Calmar − turnover − drawdown) so no metric can be gamed alone.
• 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 §6).

The name combines Inari (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 (Phase D-11 — multi-market paper trading: cross-currency cash + a live runner that auto-runs promoted strategies on live bars, on top of D-10 multi-market data and D-9 LLM-authored strategies + risk engine). Read the code, weigh in on design — do not run this against real money (real-money trading is out of scope).

Design Principles

System Architecture

Four layers, top to bottom:

• L1 · User entry. The Operator Console (apps/dashboard, with a docked agent chat) is the home base; the mastra dev playground is there for live trace, and direct CLI tool calls still work.
• L2 · packages/orchestration (Mastra · TypeScript). Where agents, tools, hook/permission middleware, the in-memory plan store, conversation memory, and telemetry live side by side. This is the only layer LLMs run in.
• L3 · Python kernel services (FastAPI). Each service is an independent, stateful process. Today: services/data (market data ingest + web search + financial fundamentals across A-shares / HK / US / global), services/paper (event-driven kernel running backtest and paper on the same code), services/research (initial multi-agent scaffolding; analysts pull fundamentals + web intel with fallback; the full bull/bear debate loop is slated for Phase E+), and services/factor (factor library — pandas-ta / Alpha101 / qlib — with IC effectiveness screening and current-effective factor timing; signals only, no execution). The asynchronous Strategy Evolution loop runs alongside.
• L4 · Persistence & external. Postgres + TimescaleDB stores all time-series and business state. External venues span crypto, US equities, A-shares, Hong Kong, major Asian and European markets, global indices, and FRED macro data — routed automatically by the orchestrator based on market classification.

Strategy Evolution loop (Phase E+)

The evolution loop runs asynchronously alongside the agent runtime, with winners promoted back into services/paper for backtest evaluation. Details — sandbox gates, fitness function, and the E1 → E4 ramp — live in Core Capabilities §3 below.

Both diagrams are rendered from D2 sources at assets/architecture.d2 and assets/strategy-evolution.d2. See 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.
• 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.

Conversational tools live at L0; a fixed validation workflow at L1; a multi-agent research crew at L2; weekly automated scans at L3. 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 constra