version: "1.0.2" name: ai-hedge-fund description: AI Hedge Fund Investment Analysis and Multi-Round Committee Debate API. Provides full-stack equity research from 14 legend investor personas (Buffett, Munger, Wood, Burry, Lynch, Ackman, Graham, Fisher, Pelosi, WSB, Technicals, Fundamentals, Sentiment, Valuation) and multi-round round table debates with dynamic portfolio allocation.

🤖 AI Hedge Fund API - Agent Skill Guide

This document is designed for AI Agents and LLMs to understand and interact with the AI Hedge Fund API.

• Server Base URL: http://localhost:6000 (or http://dns.glsoft.ai:6000)
• API Documentation: http://localhost:6000/docs
• Health Check: http://localhost:6000/api/health
• Swagger JSON: http://localhost:6000/static/swagger.json
• Default LLM Engine: Groq (openai/gpt-oss-20b) managed automatically by backend with resilient Gemini failover.

📌 Available Endpoints

1. 📊 Run Stock Analysis (POST /api/analysis)

Execute deep investment analysis across selected AI investor personas with optional multi-round round table committee debate.

• Endpoint: POST /api/analysis
• Headers: Content-Type: application/json
• Minimal Request Body (JSON):

{
  "tickers": "TSLA,NVDA",
  "enableRoundTable": true,
  "roundTableRounds": 2
}

• Full Request Body Example (JSON):

{
  "tickers": "TSLA,NVDA",
  "selectedAnalysts": [
    "warren_buffett",
    "cathie_wood",
    "michael_burry",
    "wsb",
    "technical_analyst"
  ],
  "enableRoundTable": true,
  "roundTableRounds": 2,
  "initialCash": 100000,
  "startDate": "2024-09-01",
  "endDate": "2024-12-01"
}

Request Parameters:

portfolio requires as_of (YYYY-MM-DD), non-negative cash, currency (ISO 4217), and positions (array; empty means flat). Each position requires ticker, signed quantity (positive long, negative short), non-negative average_entry_price, and trading currency. A snapshot must not be after endDate or more than 7 calendar days old. Cross-currency positions use a historical Yahoo Finance FX close no later than as_of; the request is rejected when no suitable rate is available. Omit portfolio to preserve legacy initialCash behavior.

Strict point-in-time mode uses verified publication/availability time, not report period or event date. News without a publication timestamp and financial data without filing-level availability metadata are excluded with source-specific reasons. The SEC EDGAR adapter uses filing acceptance time plus a conservative dissemination buffer for eligible US issuers and requires SEC_USER_AGENT; this filing metadata does not make Yahoo financial values point-in-time verified. Current-only security registries are reported as survivorship-biased. Daily price inputs use unadjusted OHLC; future splits are reversed, and dividend cash flows are not modeled in this analysis endpoint.

Resumable backtest grid

• POST /api/backtest/grid: accepts runId, tickers, startDate, endDate; optional portfolio, initialCash, cutoffTimeUtc (shared UTC cutoff), selectedAnalysts (array of keys from the analyst registry; unknown keys and non-array values return HTTP 400), dailyRebalancePolicy (daily or none), transactionFeeRate (default 0.001), and slippageRate (default 0.0005).
• GET /api/backtest/runs/<run_id>: reads the persisted manifest and result.
• Reusing a runId resumes the original immutable data snapshots only when the configuration fingerprint matches. SQLite defaults to instance/backtest_runs.sqlite3; Docker Compose mounts ./instance to /app/instance and sets BACKTEST_RUN_DB=/app/instance/backtest_runs.sqlite3 so checkpoints survive container replacement.
• Grid results disclose source coverage, excluded unknown timestamps, benchmark mapping/version, fees, slippage, current-universe survivorship bias, and that dividends are not modeled.

Example: {"runId":"trial-1","tickers":["AAPL","2330.TW"],"startDate":"2026-01-05","endDate":"2026-01-30","cutoffTimeUtc":"23:59:59Z","selectedAnalysts":["technical_analyst"],"initialCash":100000}

Response Format (JSON):

{
  "decisions": {
    "TSLA": {
      "action": "buy | sell | short | hold",
      "quantity": 50,
      "confidence": 85.0,
      "reasoning": "Detailed committee execution rationale..."
    }
  },
  "analyst_signals": {
    "warren_buffett_agent": {
      "TSLA": {
        "signal": "bearish",
        "confidence": 90.0,
        "reasoning": "DCF valuation indicates -80% margin of safety..."
      }
    }
  },
  "round_table": {
    "TSLA": {
      "signal": "bearish",
      "confidence": 65.0,
      "discussion_summary": "Warren Buffett and Michael Burry clashed with Cathie Wood on valuation vs innovation...",
      "consensus_view": "Valuation and debt risks outweigh short-term growth prospects.",
      "dissenting_opinions": "Cathie Wood argued for exponential AI/robotics S-curve adoption.",
      "conversation_transcript": "[Warren Buffett]: Intrinsic value doesn't hold up...\n[Cathie Wood]: Look at the innovation engine..."
    }
  }
}

2. 🏛️ Standalone Round Table Debate (POST /api/round_table)

Run an investment committee debate with pre-computed analyst signals.

• Endpoint: POST /api/round_table
• Headers: Content-Type: application/json
• Request Body (JSON):

{
  "tickers": "NVDA",
  "analystSignals": {
    "cathie_wood": {
      "NVDA": {"signal": "bullish", "confidence": 90, "reasoning": "Exponential AI infrastructure demand"}
    },
    "michael_burry": {
      "NVDA": {"signal": "bearish", "confidence": 75, "reasoning": "Hyperscaler capex peak and concentration risk"}
    }
  },
  "numRounds": 2
}

Response Format (JSON):

{
  "round_table": {
    "NVDA": {
      "signal": "neutral",
      "confidence": 65.0,
      "discussion_summary": "Cathie Wood debated Michael Burry on AI capex sustainability...",
      "consensus_view": "Strong long-term positioning balanced against near-term concentration risk.",
      "dissenting_opinions": "Michael Burry warned of margin compression if hyperscaler spending cools.",
      "conversation_transcript": "[Cathie Wood]: AI transformation is just beginning...\n[Michael Burry]: Don't ignore the customer concentration risk..."
    }
  }
}

3. 💓 Health Check (GET /api/health)

• Endpoint: GET /api/health
• Response: {"status": "healthy", "version": "2.0.0", "timestamp": "2026-08-26T07:35:04Z"}

👥 14 Analyst Personas Reference Table

💡 Agent Usage Tips

1. For General Stock Analysis:

• Send POST /api/analysis with enableRoundTable: true to get both individual analyst metrics and a synthesized committee decision.

1. For High-Growth / Tech Stocks:

• Select ["cathie_wood", "michael_burry", "wsb", "valuation_analyst"] to get balanced bull/bear debate on growth vs valuation.

1. For Value / Defensive Stocks:

• Select ["warren_buffett", "ben_graham", "charlie_munger", "fundamentals_analyst"].

1. For Non-US Stocks (e.g. Taiwan 2330.TW, Hong Kong 0001.HK):

• The system automatically normalizes ticker suffixes and leverages 2md search for global news and sentiment.

1. Bilingual Support (English & Traditional Chinese / 雙語輸出):

• All reasoning, discussion_summary, consensus_view, dissenting_opinions, and conversation_transcript automatically provide comprehensive bilingual explanations in English and Traditional Chinese (【繁體中文解析】).

🔌 Model Context Protocol (MCP) Server Integration

This repository ships with a built-in standard MCP Server (`mcp_server.py`) compatible with Cursor, Claude Desktop, Windsurf, and Antigravity.

Available MCP Tools:

1. analyze_stock_with_committee: Run full 14-persona hedge fund analysis and round table debate.
2. get_stock_quant_audit: Instant quantitative audit returning 95%/99% VaR, CVaR, Realized Volatility Regimes, 5×5 DCF Sensitivity Matrix, Altman Z-Score (bankruptcy risk), Piotroski F-Score (0-9 financial health), Amihud Illiquidity Ratio, and ATR Dynamic Trailing Stops.

Claude Desktop / Cursor Configuration:

{
  "mcpServers": {
    "ai-hedge-fund": {
      "command": "python3",
      "args": ["/absolute/path/to/ai-hedge-fund-API/mcp_server.py"],
      "env": {
        "GROQ_API_KEY": "your_groq_key_here"
      }
    }
  }
}

🛡️ JSON Compliance & Strict Parsing Guarantees (RFC 8259)

• Zero `NaN` / `Infinity` Guarantee: All numerical metrics across all 14 analysts (e.g. momentum_6m, historical_volatility, volatility_z_score, z_score, atr_ratio, dcf_value, etc.) are strictly sanitized to standard JSON floats or null.
• Node.js & TypeScript 100% Safe: Never triggers SyntaxError: Unexpected token 'N' (NaN is not valid JSON) when executing JSON.parse() in Node.js, Next.js API routes (route.ts), Python, Go, or browser clients.
• Graceful Insufficient Data Handling: When historical price days are shorter than rolling indicator windows (e.g. calculating 6-month momentum on a 3-month timeframe), indicators automatically use min_periods=1 and fallback to valid numbers or null.