Every BUY / SELL recommendation runs through a 5-phase pipeline — collect → analyze → consensus → certify → track. Each decision records its market context and per-agent reasoning, then auto-scores against actual outcomes after 30 / 60 / 90 days. Agent weights drift ±30% based on hit rate.

• 🧠 Evidence-first — every recommendation includes per-agent reasoning, gate certification trail, and 30 / 60 / 90 d outcome tracking. No black-box scores.
• 🔁 Self-correcting — agent weights adjust based on actual prediction accuracy, not hand-tuning.
• 🛡️ 3-D certification — gates apply per Account × Asset Class × Market. One error-grade fail → REJECTED, no manual override.
• 🔓 Open data flow — phases coupled only via SQLite tables. Re-run any phase, downstream consumers refresh automatically.
• ✅ Tested rigorously — 5,892 backend tests, 100% statement coverage (CI verified, 2026-05-06).

# Prerequisites: Python 3.12, uv, ta-lib, Node 22
brew install uv ta-lib fnm && fnm install 22

git clone https://github.com/researcherhojin/nuri-quant.git && cd nuri-quant
make setup                                              # backend deps + DB init + git hooks
cd frontend && npm ci && cd ..                          # frontend
cp .env.example .env                                    # API keys (all optional)
cp config/portfolio.example.yaml config/portfolio.yaml  # your holdings (gitignored)

make start          # API on :8001 + Dashboard on :3000

Visit :3000 for the Action-First dashboard or :8001/docs for OpenAPI.

flowchart TB
    CFG[/"config/*.yaml<br/>policies"/]:::source

    subgraph Pipeline["5-phase decision pipeline (DB-only coupling)"]
        direction TB
        A(["① Collect<br/>26 data collectors"]):::pipe
        B(["② Analyze<br/>22 signals · 10 regimes · factors"]):::pipe
        C(["③ Consensus<br/>10-agent weighted vote"]):::pipe
        D(["④ Certify<br/>Certification (3-D gates)"]):::pipe
        E(["⑤ Track<br/>30 / 60 / 90 d outcomes"]):::pipe

        A --> B --> C --> D --> E
        E -. "agent weight drift (±30%)" .-> C
    end

    DB[("SQLite WAL · 51 tables<br/>audit · evidence · pipeline events")]:::sink

    CFG -. policies .-> Pipeline
    Pipeline -. persist .-> DB

    classDef source fill:#1e293b,stroke:#64748b,color:#e2e8f0
    classDef pipe   fill:#0f3057,stroke:#3b82f6,color:#dbeafe
    classDef sink   fill:#0f172a,stroke:#334155,color:#cbd5e1

Phases never import each other — communication is via SQLite tables / CSV only. Detail: docs/ARCHITECTURE.md. Certification spec: docs/CERTIFICATION_SPEC.md.

The dashboard at :3000/ answers "what should I do today?" — Action-First design that surfaces actionable intelligence ahead of raw data. Pension / IRP holdings filtered (monthly rebalance ≠ daily decision).

Korean tickers display as names (삼성전자) instead of codes (005930.KS). 17 routes total.

Rules live in config/rules.yaml (loaded via nuri/core/rules.py) — code never hardcodes them. Sources: O'Neil (CAN SLIM), Minervini (SEPA), Shefrin & Statman (1985, 처분효과 / disposition effect).

Take-profit ladders (growth: +20% / +40% / -15% trailing; value: +15% / +30% / -15%) and hard gates (VIX > 30 blocks new buys; Certification rejects any error-grade fail) apply on top. Full thresholds & rationale: docs/STRATEGY.md §3.4-§3.5, §6.

LLM integrations are wired but inactive unless you set the corresponding env var. The system runs without any LLM and falls back to regex / rule-based logic. Egress policy: docs/STRATEGY.md §4.4.3.

The egress policy is enforced by nuri/llm/openai_client.py: a single wrapper logs every external call to the external_llm_calls table (timestamp / model / tokens, no content); NURI_DISABLE_EXTERNAL_LLM=1 raises immediately.

Backend

Frontend

Quant

CI/CD

make full-scan      # 5-phase pipeline end-to-end
make consensus      # 10-agent analysis + decision recording
make certify        # Certification (3-D gates)
make scan           # Daily scan (us_core, 85 tickers)
make scan-extended  # Weekly scan (S&P 500, 543 tickers)

make test           # full test suite
make test-fast      # backend, slow tests excluded (~24s, PR CI)
make ci-cov         # CI artifact combine — Codecov ground-truth coverage

make help           # full target list with categories

The reference operator setup runs across two Apple Silicon Macs (MBP dev → Mac mini 24/7 receiver) with make deploy-mini 1-command sync.

• docs/STRATEGY.md — project philosophy, architectural decisions, investment rules
• docs/ARCHITECTURE.md — detailed code / DB layout, schema, env vars, CI/CD
• docs/CERTIFICATION_SPEC.md — 3-D certification spec
• docs/KIS_INTEGRATION.md — KIS (Korea Investment & Securities) Open API
• CONTRIBUTING.md — development workflow, PR discipline
• SECURITY.md — security policy, LLM egress rules
• CLAUDE.md / AGENTS.md — agent guides (Claude Code / Cursor / Copilot)

Academic foundations: O'Neil CAN SLIM, Minervini SEPA, Shefrin & Statman 1985 (disposition effect), Markowitz, Damodaran, Bernstein.

AGPL-3.0