QuantCoderFS v2.0.2 Technical Documentation

Complete reference for quantitative research and algorithm development platform

What is QuantCoderFS?

QuantCoderFS is a unified quantitative research platform that combines two distinct modules:

1. Market Intelligence Module

• Purpose: Multi-agent equity research inspired by MarketSense AI (Fatouros et al., 2024)
• Input: Stock tickers (e.g., AAPL.US, TSLA.US)
• Output: BUY/HOLD/SELL trading signals with conviction scores (1-10)
• Technology: Custom multi-agent system with 4 specialized agents + 1 orchestrator

2. Strategy Generator Module

• Purpose: Automated trading algorithm generation from academic research papers
• Input: PDF research papers
• Output: Production-ready QuantConnect algorithm code (Python)
• Technology: CrewAI multi-agent workflow with PDF extraction and code generation

Core Technology Stack

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js 15)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Stocks     │  │  Strategies  │  │   Settings   │     │
│  │ (Research)   │  │ (Code Gen)   │  │              │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP/REST API
┌──────────────────────────┴──────────────────────────────────┐
│                Backend (FastAPI + Python)                    │
│  ┌─────────────────────┐    ┌─────────────────────┐        │
│  │ Market Intelligence │    │ Strategy Generator  │        │
│  │ • Stock Handler     │    │ • PDF Extraction    │        │
│  │ • Signal Agents     │    │ • Code Generation   │        │
│  │ • Data Aggregation  │    │ • QC Integration    │        │
│  └─────────────────────┘    └─────────────────────┘        │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              SQLite/PostgreSQL Database              │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼─────┐    ┌──────▼──────┐   ┌──────▼──────────┐
   │ EODHD    │    │  OpenAI/    │   │  QuantConnect  │
   │   API    │    │  Anthropic  │   │   REST API     │
   └──────────┘    └─────────────┘   └────────────────┘

Module Structure

Backend Directory Structure:

backend/
├── market_intelligence/          # Market Intelligence Module
│   ├── agents/                   # Multi-agent system (5 agents)
│   ├── api/routers/              # REST API endpoints
│   ├── core/                     # Business logic
│   └── db/                       # Database models & migrations
├── strategy_generator/           # Strategy Generator Module
│   ├── agents/                   # CrewAI agents
│   ├── routers/                  # REST API endpoints
│   └── tools/                    # CrewAI tools
├── shared/                       # Shared utilities
└── main.py                       # FastAPI app entry point

Dependencies & Third-Party Services

Backend Dependencies

Required Third-Party Services

1. EODHD API (Market Data Provider)

• Purpose: Stock EOD prices, fundamentals, financial news
• Endpoint: https://eodhd.com/api/
• Authentication: API key
• Free Tier: 20 API calls/day, 1 year historical data, 500 welcome bonus calls
• Paid Plans: From €19.99/month (100,000 calls/day, 30+ years historical data)
• Usage: Market Intelligence module

2. OpenAI API (Primary LLM Provider)

• Purpose: AI-powered signal generation and code generation
• Models Used: GPT-4, GPT-3.5-turbo
• Authentication: API key (sk-...)
• Cost: ~$0.03 per 1K tokens (GPT-4)
• Usage: Both modules (signals + strategy generation)

Optional Third-Party Services

3. Anthropic Claude API (Alternative LLM)

• Purpose: Alternative LLM provider
• Models: Claude 3 Opus, Claude 3 Sonnet
• Usage: Signal generation (user selectable)
• Cost: ~$0.015 per 1K tokens

4. Ollama (Local LLM) - PLANNED

• Status: Not yet implemented
• Purpose: Local LLM inference (no API costs)
• Models: llama2, mixtral, etc.
• Authentication: None (local)
• Cost: Free (requires local GPU)
• Planned Usage: Market Intelligence signals only (user selectable)

5. Tavily API (Web Search)

• Purpose: Macro environment research
• Usage: Macro agent in Market Intelligence
• Cost: Free tier available

6. QuantConnect API (Trading Platform)

• Purpose: Deploy algorithms for backtesting/live trading
• Endpoint: https://www.quantconnect.com/api/v2/
• Authentication: User ID + API Token
• Cost: Free tier available, paid for live trading

Price Normalization

Understanding adjusted vs. raw prices for accurate analysis

The Problem: Corporate Events Create Data Discontinuities

Stock splits and dividends create discontinuities in historical price data that make charts and calculations misleading without proper adjustment.

Example: NVDA 10-for-1 Stock Split (June 10, 2024)

Without Normalization (Raw Prices):

June 7, 2024:  Close = $1,208.88
June 10, 2024: Close = $121.79  ← Appears as -90% crash!

With Normalization (Adjusted Prices):

June 7, 2024:  Adjusted Close = $120.84
June 10, 2024: Adjusted Close = $121.74  ← Smooth transition (+0.7%)

The split was not a loss of value - shareholders received 10 shares for every 1 share they owned. But raw price data shows a misleading 90% drop.

How Price Normalization Works

QuantCoderFS uses EODHD API, which provides two price fields:

• close - Raw closing price as actually traded
• adjusted_close - Price adjusted backward for all corporate events

EODHD adjusts historical prices backward from the present:

Before Split (historical):
  Raw price: $1,208.88
  Adjusted:  $120.84  (divided by split ratio 10:1)

After Split (current):
  Raw price: $121.79
  Adjusted:  $121.74  (minimal difference)

This creates a continuous, meaningful price series for analysis.

Setting the Normalization Mode

Navigate to Parameters → Price Normalization section.

Parameters page showing Price Normalization settings with detailed explanations for Adjusted vs Raw prices

Options:

Impact Across the Platform

The normalization setting is global and affects every feature that uses price data:

• Portfolio Analysis: Equal-weight, MVO, Min Variance, Black-Litterman optimization, all equity curves
• Risk Analysis: Monte Carlo simulations (all 1000+ paths), VaR/CVaR calculations, volatility measurements
• Pair Trading: Price series for both stocks, spread calculations, z-score analysis, backtest results
• Peer Comparison: Normalized performance charts, relative performance metrics, correlation analysis

When to Use Each Mode

Read the complete Price Normalization Guide

Corporate Events Display

Visual markers for stock splits and dividends on charts

Overview

When using adjusted prices, QuantCoderFS automatically displays corporate events (stock splits, reverse splits) as visual markers on all charts.

Visual Representation

• Vertical dashed lines in orange (#d29922) mark the exact date of corporate events
• Labels show format: TICKER: SPLIT_RATIO (e.g., "NVDA: 10/1")
• Labels positioned at the top of the line for clarity
• Works on all chart types: Portfolio Analysis (Chart.js) and Peer Comparison (Recharts)

NVDA stock chart using adjusted prices showing continuous normalized curve without gaps despite the 10-for-1 split on June 10, 2024

Portfolio equity curve visualization showing optimized portfolio performance over time

Peer comparison showing normalized performance across sector competitors

Supported Events

Where Events Appear

• Portfolio Analysis: Equal-weight, MVO, Min Variance, Black-Litterman equity curves
• Risk Analysis: Monte Carlo simulation charts (all scenarios)
• Peer Comparison: Normalized performance charts with sector peers

Recent Notable Splits

Events tracked by QuantCoderFS (last 5 years):

• NVDA: 2024-06-10 (10:1 split)
• TSLA: 2022-08-25 (3:1 split)
• GOOGL: 2022-07-18 (20:1 split)
• AAPL: 2020-08-31 (4:1 split)
• AMZN: 2022-06-06 (20:1 split)

Technical Implementation

Data Source: EODHD Splits API

GET https://eodhd.com/api/splits/{ticker}
Parameters:
  - api_token: Your EODHD API key
  - from: Start date (YYYY-MM-DD)
  - to: End date (YYYY-MM-DD)
  - fmt: json

Response: CSV format
Date,"Stock Splits"
2024-06-10,10.000000/1.000000

Backend Module: market_intelligence/core/corporate_events.py

Frontend Integration:

• Chart.js: Uses chartjs-plugin-annotation for vertical line annotations
• Recharts: Uses <ReferenceLine> component with custom labels

API Overview

Core Functionality

QuantCoderFS provides a RESTful API for two main workflows:

Module 1: Market Intelligence API

Automated equity research and signal generation using EODHD market data.

API Endpoints Overview

Module 2: Strategy Generator API

Automated QuantConnect algorithm generation from academic papers.

Snapshot Architecture

QuantCoderFS v2.0 introduced a snapshot-based architecture for stock data management:

Key Concepts

• Snapshot ID: Timestamp in format YYYYMMDD_HHMMSS (e.g., 20251016_143022)
• Multiple Snapshots: Each ticker can have multiple snapshots taken at different times
• Immutable Data: Once created, snapshot data doesn't change (refresh creates new snapshot)
• File Storage: All data stored in /stocks/{ticker}/{snapshot_id}/ directory
• Independent Analysis: Each snapshot has its own signals and research reports

Benefits

• Track how market conditions evolve over time
• Compare signals generated on different dates
• Reproducible analysis - same snapshot always yields same signal
• Easy cleanup - delete old snapshots without affecting recent data

See the Stocks API documentation for detailed snapshot management endpoints.

Detailed API Documentation

• Stocks API - Complete reference for stock data management
• Signals API - Complete reference for signal generation
• Settings API - Manage API keys and credentials
• Research API - Generate comprehensive research reports
• Strategies API - Algorithm generation endpoints
• Backtest API - QuantConnect deployment

Market Intelligence Module

Purpose

Multi-agent equity research system inspired by MarketSense AI paper (Fatouros et al., 2024).

Screenshots

Stock Analysis with Benchmarks

Stock data view with price chart, fundamentals, and benchmark comparison (SPY, QQQ, DIA, IWM). This is the first view you see when analyzing a stock - FinViz-like visualization with comprehensive market data.

Return Distribution Analysis

Statistical analysis of historical return distributions with interactive histogram visualization (daily/weekly/monthly returns, Sharpe ratio, win rate).

Peer Comparison

Peer comparison: normalized performance across sector competitors with correlation and beta metrics.

Portfolio Optimization

Portfolio optimization: equal-weight vs. max Sharpe with equity curves and composition breakdown.

Onboarding Wizard

Onboarding wizard: 6-step setup for license, API keys, and QuantConnect integration.

API Keys Setup

API keys setup: EODHD, OpenAI (required), Tavily (optional for deep research).

QuantConnect Integration

QuantConnect integration: User ID, API Token, Organization ID for strategy deployment.

Credentials Management

Credentials page: License activation, API credentials, and AI model configuration.

Benchmark Tab - Market Comparison

Compare stock performance against market benchmarks (SPY, QQQ, DIA, IWM) with Alpha, Beta, correlation metrics, and Up/Down capture ratios.

Benchmark Comparison Methodology

Key Metrics Calculated:

• Alpha (Annualized): Excess return compared to benchmark
  Alpha = Mean(Stock Return - Benchmark Return) × 252
  Positive alpha indicates outperformance; negative indicates underperformance.
• Beta: Systematic risk relative to benchmark
  Beta = Cov(Stock, Benchmark) / Var(Benchmark)
  Beta > 1: More volatile; Beta < 1: Less volatile; Beta ≈ 1: Similar volatility
• Correlation: Degree of linear relationship with benchmark
  Correlation = Pearson(Stock Returns, Benchmark Returns)
  Range: -1 to +1. High correlation (>0.8): Moves with market; Low correlation (<0.5): Independent behavior
• Tracking Error (Annualized): Deviation from benchmark
  Tracking Error = StdDev(Excess Returns) × √252
  Higher tracking error indicates more independent performance from benchmark.
• Information Ratio: Risk-adjusted alpha
  IR = Alpha / Tracking Error
  IR > 0.5: Good risk-adjusted outperformance; IR < 0: Underperformance
• Up Capture Ratio: Performance on benchmark's up days
  Up Capture = [Mean(Stock Returns | Benchmark > 0) / Mean(Benchmark Returns | Benchmark > 0)] × 100
  Up Capture > 100%: Outperforms on up days; <100%: Underperforms on up days
• Down Capture Ratio: Performance on benchmark's down days
  Down Capture = [Mean(Stock Returns | Benchmark < 0) / Mean(Benchmark Returns | Benchmark < 0)] × 100
  Down Capture < 100%: Protects on down days (good); >100%: Amplifies losses (bad)
• Sharpe Ratios: Risk-adjusted returns for both stock and benchmark
  Sharpe = (Mean Return / StdDev) × √252
  Compare Sharpe ratios to see which asset has better risk-adjusted returns.

Normalized Performance Chart:

Both stock and benchmark prices are normalized to start at 100 to visualize relative performance over time. The stock line is solid, the benchmark line is dashed.

Example Interpretation:

Stock: AAPL | Benchmark: SPY | Period: 12 months

• ✓ Alpha = +5.2% (outperformed S&P 500 by 5.2% annualized)
• ✓ Beta = 1.15 (15% more volatile than market)
• ✓ Correlation = 0.82 (high correlation - moves with market)
• ✓ Information Ratio = 0.68 (good risk-adjusted outperformance)
• ✓ Up Capture = 112% (captures 12% more gains on up days)
• ✓ Down Capture = 95% (protects 5% better on down days)
• ✓ Tracking Error = 7.6% (moderate deviation from benchmark)
• ✓ Sharpe (AAPL) = 1.2 vs Sharpe (SPY) = 0.9 (better risk-adjusted returns)

Peers Tab - Sector Comparison

Select up to 5 peer companies and compare normalized performance with metrics including return, volatility, beta, and correlation. Chart shows relative performance over selectable time periods (1M, 3M, 6M, 1Y, 3Y, 5Y).

Agent Architecture

The system uses 5 specialized agents working in orchestration:

1. Fundamentals Summarizer Agent (30% weight)

• Input: Quarterly financial statements, company highlights
• Processing: Financial health score, revenue growth, profit margins
• Output: Summary (100-200 words) + Score (0-100)

2. Progressive News Summarizer Agent (25% weight)

• Input: 60-day rolling news articles
• Processing: Sentiment aggregation, narrative themes
• Output: Summary + Sentiment score (0-100)

3. Stock-Price Dynamics Summarizer Agent (25% weight)

• Input: OHLCV price data (1 year), S&P 500 benchmark
• Processing: Technical analysis (MA, RSI, MACD), volatility
• Output: Summary + Technical score (0-100)

4. Macroeconomic Environment Summarizer Agent (20% weight)

• Input: Sector information, web search results (via Tavily)
• Processing: Sector analysis, economic cycle assessment
• Output: Summary + Macro score (0-100)

5. Signal Generation Agent (Master Orchestrator)

• Input: Outputs from all 4 summarizer agents
• Processing: Chain-of-Thought reasoning, weighted consensus
• Output: Final BUY/HOLD/SELL signal with conviction (1-10) and confidence (0.0-1.0)

Signal Calculation Formula

weighted_score = (
    fundamentals_score * 0.30 +
    news_score * 0.25 +
    price_dynamics_score * 0.25 +
    macro_score * 0.20
)

if weighted_score >= 70:
    signal = "BUY"
elif weighted_score <= 40:
    signal = "SELL"
else:
    signal = "HOLD"

Data Flow

1. User creates stock project (POST /api/stocks/create)
2. System fetches data from EODHD API (EOD prices, fundamentals, news)
3. Data stored in file system: user_workdir/stocks/{ticker}_{timestamp}/
4. User generates signal (POST /api/signals/generate/{project_id})
5. Signal Orchestrator runs agents in sequence (60-90 seconds)
6. Results saved to database + file system
7. Frontend displays signal with agent breakdowns

Agent Console

Purpose

Real-time WebSocket-based logging console for transparent AI agent execution monitoring.

Screenshot

Agent Console: real-time WebSocket logging showing AI agent execution with color-coded status indicators.

Features

• Real-Time Logging: WebSocket connection displays agent activities as they execute
• Color-Coded Status: Visual indicators for info (blue), progress (yellow), success (green), error (red)
• Agent Filtering: Filter logs by agent type (All, Fundamentals, News, Price, Macro)
• Export Capability: Download complete log history as text file for auditability
• Auto-Scroll: Automatically scrolls to latest logs with minimize/expand controls

WebSocket Endpoint

ws://localhost:8000/ws/agent-logs

Message Format

{
  "agent": "Fundamentals Agent",
  "action": "Starting analysis",
  "details": "Ticker: AAPL",
  "status": "progress",
  "timestamp": "2025-10-17T12:00:00.000Z"
}

Agent Execution Flow Example

1. MarketSense Orchestrator → Starting multi-agent analysis (info)
2. Fundamentals Agent → Fetching fundamentals (progress)
3. Fundamentals Agent → Analysis complete - Score: 75/100 (success)
4. News Agent → Analyzing sentiment (progress)
5. News Agent → Analysis complete - Score: 80/100 (success)
6. Price Dynamics Agent → Analyzing momentum (progress)
7. Price Dynamics Agent → Analysis complete - Score: 70/100 (success)
8. Macro Agent → Analyzing market environment (progress)
9. Macro Agent → Analysis complete - Score: 65/100 (success)
10. Signal Agent → Integrating agent outputs (progress)
11. Signal Agent → Signal generated - BUY (Conviction: 80, Confidence: 84) (success)

Portfolio Optimization

Purpose

Multi-stock portfolio construction with Modern Portfolio Theory optimization algorithms and comprehensive risk analysis.

Screenshot

Risk analysis: Monte Carlo simulation (1,000 scenarios) and Value at Risk (VaR) metrics for portfolio management.

Optimization Algorithms

• Mean-Variance Optimization (MVO): Maximizes Sharpe ratio for optimal risk-adjusted returns
• Black-Litterman Model: Bayesian approach incorporating investor views with market equilibrium
• Minimum Variance Portfolio: Minimizes portfolio volatility for conservative risk management

Risk Analysis Tools

• Monte Carlo Simulation: 1,000-10,000 scenarios over configurable time horizon (252 trading days default)
• Value at Risk (VaR): Historical and Parametric VaR at 95% confidence level
• Conditional VaR (CVaR): Expected loss beyond VaR threshold
• Stress Testing: Portfolio performance under extreme market conditions

Monte Carlo Output Metrics

• Mean Final Value
• Median (50th percentile)
• Standard Deviation
• Min/Max scenarios
• 5th and 95th Percentile ranges

Workflow

1. Create empty portfolio with drag-and-drop interface
2. Add stocks from Stocks section
3. Select optimization algorithm (MVO, Black-Litterman, Min Variance)
4. System calculates optimal weights based on historical returns and covariance
5. View allocation pie chart, expected return, volatility, Sharpe ratio
6. Run Monte Carlo simulation for risk analysis
7. Calculate VaR and CVaR for downside risk assessment

Pair Trading

Purpose

Statistical arbitrage through cointegration analysis of stock pairs for mean-reversion trading strategies.

Screenshot

Pair trading analysis: cointegration test, z-score time series, and dual-axis price comparison for EGAN.US / LAES.US.

Statistical Methods

• Engle-Granger Cointegration Test: Tests for long-term equilibrium relationship (p-value < 0.05 indicates cointegration)
• Augmented Dickey-Fuller (ADF): Stationarity test for spread time series
• Ordinary Least Squares (OLS): Hedge ratio estimation for optimal position sizing
• Half-Life Calculation: Mean-reversion speed using Ornstein-Uhlenbeck process

Key Metrics

Trading Signals

• LONG: Z-score < -2.0 (spread undervalued → buy Stock 1, sell Stock 2)
• SHORT: Z-score > 2.0 (spread overvalued → sell Stock 1, buy Stock 2)
• NEUTRAL: -2.0 ≤ Z-score ≤ 2.0 (no position or close existing)

Workflow

1. Create empty pair with auto-generated name
2. Drag and drop Stock 1 from Stocks section to Ticker 1 slot
3. Drag and drop Stock 2 to Ticker 2 slot
4. System automatically fetches 2 years of historical data
5. Runs Engle-Granger cointegration test (10-20 seconds)
6. Calculates hedge ratio, half-life, current z-score
7. Generates trading signal based on z-score thresholds
8. Displays z-score time series chart and dual-axis price comparison
9. Shows historical performance metrics (win rate, avg profit, avg duration)

Benchmarks

Purpose

Market index tracking and relative performance comparison for portfolio and stock analysis.

Interactive benchmark charts with technical indicators (SMA 50, SMA 200) for market index analysis.

Supported Indices

Comparison Metrics

• Alpha (Annualized): Excess return compared to benchmark
• Beta: Systematic risk relative to benchmark (1.0 = same volatility)
• Correlation: Degree of linear relationship (-1 to 1)
• Tracking Error: Standard deviation of return differences (annualized)
• Up Capture Ratio: Performance on benchmark's up days (> 100% = outperformance)
• Down Capture Ratio: Performance on benchmark's down days (< 100% = less downside)
• Sharpe Ratios: Risk-adjusted returns for both stock and benchmark

Data Management

• Auto-Sync: Daily EOD data updates via cron job or manual trigger
• Data Caching: Efficient storage with last-update tracking
• Historical Range: 2+ years of daily OHLCV data

Strategy Generator Module

Purpose

Automated QuantConnect algorithm generation from academic research papers using CrewAI.

Screenshot

Strategy Generator - Paper to Code

Upload academic research papers (left panel) and generate complete QuantConnect algorithm code (right panel) using CrewAI multi-agent workflow. Monaco editor with Python syntax highlighting and line numbers.

CrewAI Workflow

Crew 1: Paper Extraction

• Agent: Paper Analyzer Agent
• Role: Extract strategy from research paper
• Tool: PDFAnalyserTool (PDF parsing)
• Output: Structured strategy summary (JSON)

Crew 2: Code Generation

• Agent 1: Strategy Summarizer (condense paper into trading rules)
• Agent 2: Code Generator (write QuantConnect algorithm)
• Agent 3: Code Validator (review and fix code issues)
• Output: Complete QuantConnect .py algorithm file

QuantConnect Integration

Endpoint: POST /api/backtest/trigger-backtest

Workflow:

1. Get QC credentials from database
2. Create QC project via REST API
3. Upload algorithm code to project
4. Compile code
5. Wait for compilation
6. Create backtest
7. Return backtest ID and project URL

Request Example:

{
  "code": "# QuantConnect algorithm code",
  "project_name": "My Momentum Strategy"
}

Response Example:

{
  "status": "success",
  "project_id": 12345678,
  "backtest_id": "abc123",
  "project_url": "https://www.quantconnect.com/project/12345678"
}

Strategies API Reference

Upload PDF Paper

POST /api/papers/upload
Content-Type: multipart/form-data

file: (binary PDF data)

Response 200:
{
  "filename": "momentum_strategy.pdf",
  "size": 1024000,
  "path": "/path/to/papers/momentum_strategy.pdf"
}

List Papers

GET /api/papers/list

Response 200:
[
  {
    "filename": "momentum_strategy.pdf",
    "size_kb": 1000,
    "uploaded": "2025-10-14T10:00:00"
  }
]

Generate Code from Paper

POST /api/papers/generate-code/momentum_strategy.pdf

Response 200:
{
  "filename": "momentum_strategy.py",
  "code": "# region imports\nfrom AlgorithmImports import *\n...",
  "summary": "Strategy extracted from paper"
}

List Generated Code

GET /api/papers/list?folder=codes

Response 200:
[
  {
    "filename": "momentum_strategy.py",
    "size_kb": 15,
    "generated": "2025-10-14T10:30:00"
  }
]

Backtest API Reference

Push to QuantConnect

POST /api/backtest/trigger-backtest
Content-Type: application/json

{
  "code": "# Algorithm code here",
  "project_name": "My Momentum Strategy"
}

Response 200:
{
  "status": "success",
  "project_id": 12345678,
  "backtest_id": "abc123def456",
  "project_url": "https://www.quantconnect.com/project/12345678"
}

Portfolios API Reference

Create Portfolio

POST /api/portfolios
Content-Type: application/json

{
  "name": "Tech Portfolio"
}

Response 200:
{
  "id": 1,
  "name": "Tech Portfolio",
  "created_at": "2025-10-17T12:00:00Z"
}

List Portfolios

GET /api/portfolios

Response 200:
{
  "portfolios": [
    {
      "id": 1,
      "name": "Tech Portfolio",
      "stock_count": 5,
      "created_at": "2025-10-17T12:00:00Z"
    }
  ]
}

Get Portfolio

GET /api/portfolios/{portfolio_id}

Response 200:
{
  "id": 1,
  "name": "Tech Portfolio",
  "stocks": [
    {"ticker": "AAPL", "weight": 0.25},
    {"ticker": "MSFT", "weight": 0.25},
    {"ticker": "GOOGL", "weight": 0.25},
    {"ticker": "AMZN", "weight": 0.25}
  ],
  "created_at": "2025-10-17T12:00:00Z",
  "updated_at": "2025-10-17T12:30:00Z"
}

Update Portfolio (Rename)

PATCH /api/portfolios/{portfolio_id}
Content-Type: application/json

{
  "name": "New Portfolio Name"
}

Response 200:
{
  "id": 1,
  "name": "New Portfolio Name",
  "updated_at": "2025-10-17T12:30:00Z"
}

Add Stock to Portfolio

POST /api/portfolios/{portfolio_id}/stocks
Content-Type: application/json

{
  "ticker": "GOOGL"
}

Response 200:
{
  "message": "Stock added successfully",
  "portfolio_id": 1,
  "ticker": "GOOGL"
}

Remove Stock from Portfolio

DELETE /api/portfolios/{portfolio_id}/stocks/{ticker}

Response 200:
{
  "message": "Stock removed successfully"
}

Optimize Portfolio

POST /api/portfolios/{portfolio_id}/optimize
Content-Type: application/json

{
  "algorithm": "mvo",
  "risk_free_rate": 0.02,
  "target_return": 0.15
}

Response 200:
{
  "algorithm": "mvo",
  "optimal_weights": {
    "AAPL": 0.30,
    "MSFT": 0.25,
    "GOOGL": 0.25,
    "AMZN": 0.20
  },
  "expected_return": 0.15,
  "volatility": 0.18,
  "sharpe_ratio": 0.72
}

Monte Carlo Simulation

POST /api/portfolios/{portfolio_id}/monte-carlo
Content-Type: application/json

{
  "num_simulations": 1000,
  "time_horizon_days": 252
}

Response 200:
{
  "num_simulations": 1000,
  "mean_return": 0.12,
  "median_return": 0.11,
  "std_dev": 0.18,
  "percentiles": {
    "5": -0.25,
    "25": 0.05,
    "50": 0.11,
    "75": 0.20,
    "95": 0.45
  },
  "probability_positive": 0.68
}

Calculate VaR

POST /api/portfolios/{portfolio_id}/var
Content-Type: application/json

{
  "confidence_level": 0.95,
  "time_horizon_days": 1
}

Response 200:
{
  "var_95": -0.025,
  "cvar_95": -0.035,
  "confidence_level": 0.95,
  "interpretation": "With 95% confidence, maximum 1-day loss is 2.5%"
}

Pairs API Reference

Create Pair

POST /api/pairs
Content-Type: application/json

{
  "name": "Tech Pair",
  "ticker1": "AAPL",  // Optional
  "ticker2": "MSFT"   // Optional
}

Response 200:
{
  "id": 1,
  "name": "Tech Pair",
  "ticker1": null,
  "ticker2": null,
  "created_at": "2025-10-17T12:00:00Z"
}

List Pairs

GET /api/pairs

Response 200:
{
  "pairs": [
    {
      "id": 1,
      "name": "AAPL / MSFT",
      "ticker1": "AAPL",
      "ticker2": "MSFT",
      "is_cointegrated": true,
      "last_signal": "LONG",
      "created_at": "2025-10-17T12:00:00Z"
    }
  ]
}

Get Pair Analysis

GET /api/pairs/{pair_id}

Response 200 (Complete Pair):
{
  "pair": {
    "id": 1,
    "name": "AAPL / MSFT",
    "ticker1": "AAPL",
    "ticker2": "MSFT"
  },
  "cointegration": {
    "is_cointegrated": true,
    "p_value": 0.02,
    "hedge_ratio": 1.25,
    "half_life": 15.5
  },
  "current_status": {
    "z_score": -2.5,
    "signal": "LONG",
    "signal_date": "2025-10-17T12:00:00Z"
  },
  "historical_performance": {
    "win_rate": 0.65,
    "avg_profit_per_trade": 0.03,
    "avg_trade_duration": 12.5
  },
  "charts": {
    "z_scores": [...],
    "prices": [...]
  }
}

Response 200 (Incomplete Pair):
{
  "pair": {
    "id": 1,
    "name": "New Pair 2025-10-17 12:00:00",
    "ticker1": null,
    "ticker2": null
  },
  "incomplete": true,
  "message": "Add both tickers to run analysis"
}

Add Ticker to Pair

POST /api/pairs/{pair_id}/tickers
Content-Type: application/json

{
  "ticker": "AAPL",
  "position": 1  // 1 or 2
}

Response 200:
{
  "id": 1,
  "name": "AAPL / ...",
  "ticker1": "AAPL",
  "ticker2": null,
  "message": "Ticker added. Analysis will run when both tickers are present."
}

Analyze Pair

POST /api/pairs/{pair_id}/analyze

Response 200:
{
  "message": "Analysis started",
  "pair_id": 1
}

Delete Pair

DELETE /api/pairs/{pair_id}

Response 200:
{
  "message": "Pair deleted successfully"
}

Benchmarks API Reference

List Benchmarks

GET /api/benchmarks/list

Response 200:
{
  "benchmarks": [
    {
      "ticker": "SPY",
      "name": "S&P 500 ETF",
      "last_updated": "2025-10-17T00:00:00Z"
    },
    {
      "ticker": "QQQ",
      "name": "Nasdaq 100 ETF",
      "last_updated": "2025-10-17T00:00:00Z"
    },
    {
      "ticker": "DIA",
      "name": "Dow Jones Industrial Average ETF",
      "last_updated": "2025-10-17T00:00:00Z"
    },
    {
      "ticker": "IWM",
      "name": "Russell 2000 ETF",
      "last_updated": "2025-10-17T00:00:00Z"
    }
  ]
}

Sync Benchmark Data

POST /api/benchmarks/sync/{ticker}

Response 200:
{
  "ticker": "SPY",
  "records_updated": 500,
  "last_updated": "2025-10-17T12:00:00Z",
  "message": "Benchmark data synced successfully"
}

Get Benchmark Data

GET /api/benchmarks/{ticker}/data?start_date=2024-01-01&end_date=2025-01-01&limit=500

Response 200:
{
  "ticker": "SPY",
  "name": "S&P 500 ETF",
  "data": [
    {
      "date": "2025-10-16",
      "open": 450.0,
      "high": 452.0,
      "low": 449.0,
      "close": 451.0,
      "volume": 50000000,
      "adjusted_close": 451.0
    }
  ]
}

Agentic Frameworks

Market Intelligence: Custom Multi-Agent System

Inspiration: MarketSense AI (Fatouros et al., 2024)

Paper: https://arxiv.org/abs/2401.03737

Agent Weighting:

• Fundamentals: 30%
• News: 25%
• Price Dynamics: 25%
• Macro: 20%

Key Differences from MarketSense AI Paper:

• Implementation uses FastAPI instead of standalone Python scripts
• LLM provider is configurable (OpenAI/Anthropic/Ollama)
• Agents use different prompts tuned for specific data sources
• Signal persistence in SQL database

Strategy Generator: v4 Robust Workflow

Architecture: Multi-phase direct LLM workflow (no CrewAI overhead)

Workflow Evolution

v4 Workflow Phases

The v4 workflow consists of 5 sequential phases that mirror how Claude codes directly:

Why v4 Achieves 90-95% Success Rate

v4 replicates the same process that makes Claude's direct coding successful:

1. Complete Context Understanding - Deep PDF analysis before coding (Phase 1)
2. Use of Real Examples - Knowledge base with 5 real QuantConnect algorithms (Phase 2)
3. Specific Pattern Matching - 9 validation checks targeting known errors (Phase 3)
4. Actionable Error Feedback - Targeted refinement with error context (Phase 4)
5. Safety Net - Auto-fix post-processing handles edge cases (Phase 5)

Key Differences from v3 (Fast)

Implementation Files

• backend/strategy_generator/flows/code_v4_robust.py - Main workflow
• backend/strategy_generator/knowledge_base/quantconnect_examples.md - Knowledge base (13KB)
• backend/strategy_generator/knowledge_base/__init__.py - KB loader
• backend/strategy_generator/routers/coder.py - API endpoints

LLM Providers

Supported Providers

1. OpenAI (Default)

• Models Used: GPT-4, GPT-3.5-turbo
• Cost: ~$0.03 per 1K tokens (GPT-4)
• Usage: Both modules

2. Anthropic Claude

• Models Used: Claude 3 Opus, Claude 3 Sonnet
• Cost: ~$0.015 per 1K tokens
• Usage: Market Intelligence signals only (user selectable)

3. Ollama (Local)

• Models Used: llama2, mixtral, etc.
• Cost: Free (requires local GPU)
• Usage: Market Intelligence signals only (user selectable)

Provider Selection

• Market Intelligence: User chooses via query parameter (?llm_provider=openai)
• Strategy Generator: Always uses OpenAI (CrewAI default)

Database Schema

UserSettings Table

CREATE TABLE user_settings (
    id INTEGER PRIMARY KEY,
    eodhd_api_key TEXT,
    openai_api_key TEXT,
    anthropic_api_key TEXT,
    tavily_api_key TEXT,
    qc_user_id TEXT,
    qc_api_token TEXT,
    qc_organization_id TEXT,
    default_llm_provider TEXT DEFAULT 'openai',
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

TradingSignal Table

CREATE TABLE trading_signals (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    ticker TEXT NOT NULL,
    signal TEXT NOT NULL,  -- BUY, HOLD, SELL
    conviction INTEGER,     -- 1-10
    confidence REAL,        -- 0.0-1.0
    reasoning TEXT,
    weighted_score REAL,
    llm_provider TEXT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

AgentOutput Table

CREATE TABLE agent_outputs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    signal_id INTEGER NOT NULL,  -- FK to trading_signals
    agent_name TEXT NOT NULL,    -- fundamentals, news, etc.
    summary TEXT,
    score REAL,
    raw_output TEXT,             -- JSON blob
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (signal_id) REFERENCES trading_signals(id)
);

Installation & Setup

Prerequisites

• Python 3.12+
• Node.js 18+
• EODHD API key (required)
• OpenAI API key (required)

Backend Setup

# Extract licensed software package
# (Provided after subscription at quantcoderfs.substack.com)
cd quantcoderfs/backend

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run database migrations
alembic upgrade head

# Start backend server
uvicorn main:app --reload --port 8000

Backend runs at: http://localhost:8000

API docs: http://localhost:8000/docs

Frontend Setup

cd ../electron

# Install dependencies
npm install

# Create environment file
echo "NEXT_PUBLIC_API_BASE_URL=http://localhost:8000" > .env.local

# Start development server
npm run dev

Frontend runs at: http://localhost:3001

Configuration

1. Open http://localhost:3001
2. Navigate to Settings page
3. Enter API keys:
   • EODHD API Key (required)
   • OpenAI API Key (required)
   • Tavily API Key (optional)
   • QuantConnect User ID (optional)
   • QuantConnect API Token (optional)
4. Save settings

./launch.sh

References

1. Fatouros, G., Soldatos, J., Kouroumali, K., Makridis, G., & Kyriazis, D. (2024). MarketSense AI: Multi-Agent LLM Framework for Stock Market Analysis. arXiv preprint arXiv:2401.03737. https://arxiv.org/abs/2401.03737
2. QuantConnect. (2025). LEAN Algorithmic Trading Engine Documentation. https://www.quantconnect.com/docs
3. CrewAI. (2025). Multi-Agent Framework Documentation. https://docs.crewai.com

GitHub Repository & Release Plan

Deep Research Report Generation

Generate comprehensive research reports using LLM analysis. Optional Telegram notifications keep you informed when reports are complete. Example shows automated research analysis for NVDA.US with detailed company overview, key features, and investment considerations.

Planned Release Tiers

QuantCoderFS v2.0 will be released with a tiered pricing model:

Free Tier

• EODHD Data Wrapper - Market data integration (BYOK: Bring Your Own Key)
• Deep Research Tool - Fundamental analysis and research report generation
• Algorithm Generation - QuantConnect algorithm creation from research papers
• Portfolio Analytics - Basic portfolio optimization (Equal-Weight, MVO, Min Variance)

Paid Tier (Premium)

• All Free Tier Features
• MarketSense AI Analysis - Multi-agent LLM framework for stock market analysis (based on MarketSense AI paper)
• Advanced Portfolio Strategies - Black-Litterman, Risk Parity, Factor Models
• QuantConnect Integration - Direct deployment, backtesting, and live trading management
• Risk Analysis Suite - Monte Carlo simulations, VaR/CVaR, stress testing
• Pair Trading System - Cointegration analysis, z-score strategies, automated backtesting
• Priority Support - Dedicated support channel and feature requests

Release Timeline

Get Early Access - Subscribe to Our Substack

Contributing & Feedback

For bug reports, feature requests, or general feedback:

• Email: smr.laignel@gmail.com
• Substack Newsletter: Subscribe for updates
• GitHub Issues: Currently only for v1.0 - v2.0 issue tracker will open with public beta