Scorpio-Analyst

Your personal Multi-Agent portfolio manager and financial analyst team

Scorpio-Analyst is a Rust-native reimplementation of the TradingAgents framework, inspired by the paper TradingAgents: Multi-Agents LLM Financial Trading Framework. It simulates a sophisticated trading firm by employing a society of specialized AI agents that collaborate to make autonomous, explainable financial trading decisions.

The project's primary goal is to overcome the limitations of traditional algorithmic trading and monolithic AI systems by leveraging a structured, multi-agent approach. This allows for the integration of qualitative data, enhances explainability, and achieves superior risk-adjusted returns.

The evidence discipline and provenance-reporting patterns in this project are additionally inspired by Anthropic's financial-services-plugins architecture, which demonstrates rigorous grounding of LLM outputs in authoritative runtime evidence.

The current implementation track uses a free-tier data stack: Finnhub, yfinance, and FRED. This stack is highly capable and supports strict DCF, EV/EBITDA, Options flow, Consensus Estimates, thesis memory, and macro/news/technical analysis. However, it still lacks ETF-native valuation metrics and Earnings Call Transcripts.

Within that active track, yfinance-rs is used extensively for OHLCV data, Options Chains, full Financial Statements, Analyst Estimates, Institutional/Insider ownership, and Corporate Calendar.

In practice, this means the current setup can analyze corporate equities deeply with deterministic valuation, while ETF runs will often surface valuation as not assessed rather than producing a corporate-equity-style deterministic valuation.

The system is built on two core principles from the original TradingAgents paradigm:

1. Organizational Modeling: Instead of a single AI trying to do everything, the system decomposes the trading lifecycle into highly specialized roles (Analysts, Researchers, a Trader, Risk Managers, and a Fund Manager). This mirrors the structure of a real-world trading firm, preventing cognitive overload and improving decision quality.

2. Structured Communication: To combat the "telephone effect" where data degrades in unstructured conversations, agents communicate through strictly-typed, structured data reports. This ensures that critical information is passed with perfect fidelity throughout the execution pipeline.

The system operates as a stateful workflow, orchestrating the collaboration between different agent teams in a 5-phase execution pipeline.

graph TD
    Start((Trade Trigger)) --> Preflight

    subgraph Phase_0 [Phase 0: Preflight]
        Preflight[PreflightTask\nValidate & canonicalize symbol\nDerive provider capabilities\nSeed enrichment cache keys]
    end

    Preflight --> FanOutAnalysts

    subgraph Analyst_Team [Phase 1: Analyst Team]
        FanOutAnalysts[ ]
        FanOutAnalysts --> Fund[Fundamental Analyst]
        FanOutAnalysts --> Sent[Sentiment Analyst]
        FanOutAnalysts --> News[News Analyst]
        FanOutAnalysts --> Tech[Technical Analyst]
    end

    Fund --> SyncAnalysts
    Sent --> SyncAnalysts
    News --> SyncAnalysts
    Tech --> SyncAnalysts

    SyncAnalysts[AnalystSyncTask\nDual-write evidence fields\nCompute DataCoverageReport\nCompute ProvenanceSummary]

    subgraph Researcher_Team [Phase 2: Research Debate]
        SyncAnalysts --> Bull[Bullish Researcher]
        SyncAnalysts --> Bear[Bearish Researcher]
        Bear --> Moderator{Debate Moderator}
        Bull --> Moderator
        Moderator -- Max Rounds Not Reached --> Moderator
    end

    subgraph Synthesis_Execution [Phase 3: Trade Synthesis]
        Moderator -- Max Rounds Reached --> Trader[Trader]
    end

    subgraph Risk_Team [Phase 4: Risk Discussion]
        Trader --> RiskSeeking[Aggressive Risk]
        Trader --> RiskConservative[Conservative Risk]
        Trader --> RiskNeutral[Neutral Risk]
        RiskSeeking --> RiskModerator{Risk Moderator}
        RiskConservative --> RiskModerator
        RiskNeutral --> RiskModerator
        RiskModerator -- Max Rounds Not Reached --> RiskModerator
    end

    subgraph Final_Decision [Phase 5: Managerial Arbitration]
        RiskModerator -- Max Rounds Reached --> Manager{Fund Manager}
        Manager -- Approve --> Execute((Execute Trade))
        Manager -- Reject --> Abort((Terminate))
    end

    Execute --> Report[Final Report\nData Quality and Coverage\nEvidence Provenance]
    Abort --> Report

Scorpio-Analyst is designed with a phased user interface approach to provide both power and ease of use:

• Phase 1 (MVP): A comprehensive Command-Line Interface (CLI) built with clap, supporting both structured subcommands and natural language queries.
• Phase 2: An interactive Terminal User Interface (TUI) for a rich, conversational experience.
• Phase 3: A high-performance, GPU-accelerated native desktop application.

• Rust 1.93+ (rustup update stable)
• API keys for at least one LLM provider
• Register a free account and get the financial data APIs key :
  • Finnhub for market data and news
  • FRED for economic indicators
  • yfinance is used through the bundled Rust client and does not require an API key

Copy .env.example to .env and fill in your keys:

cp .env.example .env

# Pick the provider(s) you intend to use in config.toml
SCORPIO_OPENAI_API_KEY=sk-your-key-here
SCORPIO_ANTHROPIC_API_KEY=sk-ant-your-key-here
SCORPIO_GEMINI_API_KEY=your-gemini-key-here
SCORPIO_OPENROUTER_API_KEY=your-openrouter-key-here

# Financial data APIs
SCORPIO_FINNHUB_API_KEY=your-finnhub-key-here
SCORPIO_FRED_API_KEY=your-fred-api-key-here

Only the keys for providers referenced in config.toml are required at runtime.

The defaults in config.toml use OpenRouter free models and analyze NVDA. Adjust as needed:

[llm]
quick_thinking_provider = "openrouter"   # openai | anthropic | gemini | openrouter
quick_thinking_model    = "openrouter/free"
deep_thinking_provider  = "openrouter"
deep_thinking_model     = "qwen/qwen3.6-plus-preview:free"

[trading]
asset_symbol = "NVDA"   # ticker to analyze

Note: GitHub Copilot does not yet support tool calling — use OpenAI, Anthropic, or Gemini for the quick_thinking_provider. See Known Limitations for details.

cargo run

The pipeline executes all five phases and prints a structured report to the terminal. Configuration can be overridden at runtime with environment variables (prefix SCORPIO__, e.g. SCORPIO__TRADING__ASSET_SYMBOL=AAPL).

Full CLI usage and a TUI interface are planned for subsequent phases.

This project is in the early stages of development. The architecture and core components are being actively built.

Current financial-data roadmap is intentionally scoped to free-tier provider reality

The active roadmap assumes only free-tier Finnhub, yfinance, and FRED. As a result:

• thesis memory is in-scope
• deterministic valuation is fully capable for corporate equities (DCF, EV/EBITDA)
• ETF-style runs are supported, but they may legitimately produce valuation not assessed rather than a corporate-equity valuation result
• event/news enrichment is in-scope
• consensus estimates are supported via yfinance
• options flow and implied volatility are supported via yfinance
• transcript enrichment is deferred from the current implementation track
• ETF-native valuation inputs are deferred

See the active roadmap summary at docs/superpowers/roadmaps/2026-04-07-financial-services-plugins-architecture-roadmap-summary.md and the optional deferred follow-on plan at docs/plans/2026-04-07-006-optional-premium-data-follow-ons-plan.md.

GitHub Copilot provider does not yet support tool calling (Phase 1 analysts non-functional with Copilot)

The current Copilot provider communicates over ACP (Agent Client Protocol) via a single shared subprocess. The ACP session/new call hardcodes an empty mcp_servers list and the prompt-building path silently drops any tools passed to it — meaning all four Phase 1 analyst agents (Fundamental, Sentiment, News, Technical) fail to invoke their data-fetching tools when Copilot is configured as the provider.

The fix requires routing analyst tools through a per-session MCP helper server, splitting the Copilot monolith into focused modules, and adding a worker pool to eliminate the shared-subprocess bottleneck. The full implementation plan is at docs/superpowers/plans/2026-03-27-copilot-phase1-mcp-tool-calling.md.

Until that work is complete, use OpenAI, Anthropic, or Gemini as the quick_thinking_provider for Phase 1 analysts.

This repository includes matching OpenCode commands and GitHub Copilot prompt files to simplify the OpenSpec workflow for planned changes.

These shortcuts only work when all the following are true:

• OpenSpec is already set up in the repository
• openspec/AGENTS.md exists
• PRD.md exists
• docs/architect-plan.md exists

The following custom commands are available through .opencode/command/:

• /spec-writer <spec-name>
• /spec-reviewer <spec-name>
• /spec-code-developer <spec-name>
• /spec-code-reviewer <spec-name>

Matching Copilot prompt files are available in .github/prompts/:

• spec-writer.prompt.md
• spec-reviewer.prompt.md
• spec-code-developer.prompt.md
• spec-code-reviewer.prompt.md

In CLI or in chat:

/spec-writer add-sentiment-data

• spec-writer: create a new OpenSpec proposal from the plan
• spec-reviewer: review and improve the proposal docs
• spec-code-developer: implement the approved OpenSpec change
• spec-code-reviewer: review the implementation across requirements, security, performance, code quality, and tests

For a deep dive into the system's architecture, agent roles, and technical specifications, please see the Product Requirements Document (PRD.md).

Contributions are welcome!