pi-stock-analysis

A self-contained, modular equity-research pipeline for the Pi coding agent, built on a composable control-flow node algebra (branch / parallel / loop / retry / gate / map / choose / wait). It re-implements the stock-analysis Claude Code plugin's orchestration as a TypeScript workflow — the same port pattern used for pi-super-dev ↔ super-dev-plugin.

Runs 5 modes × 19 stages — screen GICS sub-industries → deep-dive companies → scoring → adversarial verify → judge panel → 3-horizon reports → best picks — by spawning 22 specialist pi subagents directly. No dependency on any external workflow engine.

Install

pi package add pi-stock-analysis
# or, from a local checkout:
pi -e /path/to/pi-stock-analysis

Prerequisites

• Node ≥ 22.19
• uv on PATH (the deterministic Python scripts run via uv run)
• Python ≥ 3.11 (handled automatically by uv against the bundled pyproject.toml + uv.lock)

Use

# From the pi TUI:
/stock-analysis --mode pipeline --universe US
/stock-analysis --mode screen --top-industry 40
/stock-analysis --mode analyze AAPL MSFT
/stock-analysis --mode compare NVDA,AMD,INTC
/stock-analysis --mode walk "humanoid robotics"

# Or directly via the tool call:
stock_analysis({ mode: "analyze", tickers: ["AAPL"], universe: "US" })

Tool options: mode, tickers, theme, topIndustry, totalCompany, topPrice, minHeadroom, days, universe, model, maxAgents.

Modes

The --mode <name> flag is authoritative. The positional arguments that follow it depend on the mode (tickers for analyze, a comma-list for compare, a quoted theme for walk). Omit --mode to infer it from the request phrasing.

| Mode | What it does | Positional args after --mode | Example | |---|---|---|---| | pipeline (default) | Screen sectors and deep-dive the top companies end-to-end (Stage 0→19) | — (uses filters) | /stock-analysis --mode pipeline --universe US --total-company 15 | | screen | Screen GICS sub-industries + companies only (no per-company deep-dive) | — (uses filters) | /stock-analysis --mode screen --top-industry 40 --days 5 | | analyze | Deep-dive one or more tickers (full 5→15 analyst waves + scoring + reports) | whitespace-separated tickers | /stock-analysis --mode analyze AAPL MSFT | | compare | Compare 2–5 tickers with identical valuation methodology | comma-separated tickers | /stock-analysis --mode compare NVDA,AMD,INTC | | walk | Bottleneck walk: trace a theme's supply chain → score chokepoint candidates → deep-dive the top 3–5 | quoted multi-word theme | /stock-analysis --mode walk "humanoid robotics" |

Trigger-phrase fallback (when --mode is omitted — the parser infers mode from the request):

| Phrase pattern | Inferred mode | |---|---| | "find best stocks", "top picks", "全面筛选" | pipeline | | "screen sectors", "筛选行业", "best industries" | screen | | "analyze TICKER", "deep dive X", "valuation of X", "DCF X" | analyze (+ extracted ticker) | | "X vs Y", "compare X,Y", "which is better" | compare (+ extracted tickers) | | "walk the chain for X", "chokepoint analysis X", "瓶颈分析 X" | walk (+ theme) |

A-share tickers: bare 6-digit codes auto-suffixed (600519 → 600519.SH, 000001 → 000001.SZ); Chinese names (e.g. 贵州茅台) are flagged for akshare resolution at Stage 1.

JSON escape hatch: /stock-analysis also accepts a raw JSON object, e.g. /stock-analysis {"mode":"analyze","tickers":["AAPL"]}.

Options reference

| Flag | Tool param | Default | Notes | |---|---|---|---| | --top-industry N | topIndustry | 8 pipeline / 40 screen / 7 walk | top sub-industries (or walk candidates) | | --total-company M | totalCompany | 15 | pipeline only, cap 50 | | --top-price N | topPrice | 200 | max price filter; 0 disables | | --min-headroom N | minHeadroom | 5 | Growth-Headroom floor 1–10 | | --days N | days | 1 | hot-sector window 1–20 (1=today, 5=week) | | --universe US\|CN\|ALL | universe | US | listing-exchange filter | | --model <id> | model | — | override specialist model | | --max-agents N | maxAgents | 200 | cap specialist spawns |

The Python decision (keep, do not rewrite)

The 76 deterministic financial scripts under scripts/*.py are kept verbatim. This is deliberate, not a stop-gap:

• akshare + baostock provide China A-share market data with no Node.js equivalent. Rewriting would be a real capability loss, not just effort.
• scipy, statsmodels, arch (GARCH), pandas-ta, polars are Python-only scientific/financial stacks.
• The source skill already mandates uv run python ${EXTENSION_ROOT}/scripts/<name>.py; this package preserves that contract.

This is the same boundary pi-super-dev drew: re-implement the orchestration in TypeScript; keep deterministic analysis code + domain knowledge verbatim. The TS layer orchestrates + spawns agents; agents invoke the Python via the thin src/scripts.ts bridge.

Architecture

extension.ts  ──►  registers  stock_analysis tool + /stock-analysis command
      │                       (arg parser: --mode flag > trigger phrase > default)
      ▼
workflow.ts  ──►  runs a tree of Nodes (ctx.agent / ctx.helper / ctx.script)
      │
      ▼
stages/index.ts  ──►  choose(state.mode) → per-mode stage sequence
      │
      ├─ nodes.ts        the control-flow algebra (task/sequence/branch/choose/
      │                   parallel/loop/retry/gate/map/wait/tryCatch/noop)
      ├─ helpers.ts      A-share ticker normalize, mode-aware defaults, gates
      ├─ prompts.ts      per-stage prompt builders (inject EXTENSION_ROOT)
      ├─ agents.ts       loads agents/<name>.md (22 specialists)
      ├─ pi-spawn.ts     spawns `pi` subprocesses (default backend)
      ├─ session-agent.ts  in-process backend (STOCK_ANALYSIS_BACKEND=session)
      ├─ scripts.ts      runScript → `uv run python` bridge to verbatim Python
      ├─ control.ts      tolerant <control> JSON extractor
      └─ args.ts         /stock-analysis arg parser (pure, unit-tested)

Control-flow node algebra (src/nodes.ts)

| Node | Purpose | |---|---| | task(stage) | Leaf — runs a Stage, stores return value at state[stage.id] | | sequence([...], {tolerant?}) | Ordered composition — fail-fast or tolerant-continue | | branch(pred, {yes, no?}) | Binary conditional | | choose([{when, run}, ...]) | Multi-way switch — ROOT mode dispatch | | parallel([...], {concurrency?}) | Fork-join with a concurrency cap | | loop({while?, until?, times?}) | Iterate a body until a condition holds | | retry({attempts, backoff?}) | Re-run on failure (retry-on-null 10×) | | gate({validate, attempts}) | Write → validate → re-write (quality-gate loop) | | map({over, as, concurrency?}) | Fan out over a collection (per-company DAG) | | wait(ms) / waitForEvent(name) | Time or event synchronization | | tryCatch(body, {catch, finally}) | Error boundary | | noop() | Identity |

Grounded in AWS Step Functions ASL, the Workflow Control Patterns taxonomy (van der Aalst), Temporal workflows, and LangGraph.

The pipeline (src/stages/index.ts)

The root is choose(state.mode) dispatching to one of five tolerant sequences:

pipeline: 0→1→[gate 1.5]→2→3→4→[gate 4.5]→[map 5-15 waves]→16→[gate 16.5]
          →16.6→16.7→17→[map 17.4 critic]→[gate 17.5]→18→[gate 18.5]→19
screen:   0→1→[gate 1.5]→2→3→4→[gate 4.5]→17→[map 17.4]→[gate 17.5]→18→[gate 18.5]→19
analyze:  0→1→[gate 1.5]→[map 5-15 waves]→16→[gate 16.5]→16.6→16.7→17→…→19
compare:  (structurally analyze; max 5 tickers, identical valuation methodology)
walk:     0→1→[gate 1.5]→walk(roadmap-walker)→[map 5-15 top 3-5]→16→…→19

The per-company DAG (Stages 5–15) is map({over: companies, concurrency: 4}) around 4 dependency-ordered waves of parallel analysts, each wrapped in retry({attempts: 10}). Stage 15 (A-share) is gated by branch(company.isAsh).

How agents invoke scripts

Agents receive ${EXTENSION_ROOT} and call deterministic calculations via:

uv run python ${EXTENSION_ROOT}/scripts/compute_scores.py --metrics ./reports/<RUN_ID>/metrics.json ...

src/scripts.ts wraps this with path-safety (script names validated against ^[A-Za-z0-9_-]+$), a 10-minute timeout, structured-JSON parsing, and never-throws semantics so tolerant stages continue on a script failure.

Backends

The default subprocess backend spawns isolated pi child processes (robust for 30-min+ multi-company runs). Set STOCK_ANALYSIS_BACKEND=session for the faster in-process backend via the pi SDK.

Testing

npm run typecheck   # tsc --noEmit
npm test            # vitest — hermetic, no pi spawns, no network, no uv

The suite covers: package structure, control-flow algebra semantics, mode dispatch, arg parser, runScript wrapper (mocked spawn), A-share ticker normalization, control-JSON extraction, and workflow composition.

License

MIT