🤖 SEMANTIC SIGNAL LLM (LLM Trader)

An autonomous AI trading agent that reads charts, remembers outcomes, sharpens its strategy in real time, and can search its own codebase using vector semantics.

🌐 Public Landing Page — Interactive architecture overview & system showcase
📊 Live Dashboard — Watch the neural trading brain in action
📖 Interactive Web Story & Tech | GitHub Article Document — Read the 7-month development story
💬 Join the Discord

💡 Paper trading by default. A real exchange execution service (llm_trader_executor) is currently in testing — it consumes this bot's decisions and places live CCXT orders. Coming soon. Stay tuned.

git clone https://github.com/qrak/LLM_trader.git && cd LLM_trader
python -m venv .venv && source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
pip install -r requirements.txt
cp keys.env.example keys.env  # add your API keys (Google Gemini free tier works)
python start.py               # dashboard at http://localhost:8000

Query the entire codebase using natural language — the AST-level vector index finds relevant classes, functions, and modules:

# Search all indexed symbols
python scripts/query_codebase.py "how does the risk manager calculate position size"

# Filter by symbol type
python scripts/query_codebase.py --type function "RSI calculation"

# Force re-index before searching
python scripts/query_codebase.py --reindex "vector memory retrieval"

# Show index statistics
python scripts/query_codebase.py --stats

The index auto-updates on bot startup. Currently indexes 160 files → 2,306 semantic chunks across all Python source and Markdown documentation.

RL Policy Training (optional [rl_training] enabled=true):

• Model: Qwen3-0.6B-Instruct (~1.2 GB download, HuggingFace)
• Inference: CPU-viable at ~2-5 tokens/sec on modern desktop CPUs
• Training: PPO requires 8+ GB RAM; GPU strongly recommended for training speed
• First run auto-downloads the model from HuggingFace

• 🧠 Brain with Memory — ChromaDB vector store retains trade experiences, semantic rules, system rejections, and confidence statistics. Past outcomes are retrieved by similarity to current market conditions and injected into every LLM prompt.

• 📈 Vision AI Chart Analysis — Generates 4K PNG candlestick charts with indicators, sends them to a multimodal LLM (Gemini 3.6 Flash) for visual pattern recognition. Chart-pattern code was dropped because the AI reads charts better than hardcoded rules.

• 🔄 Reflection Engine — After every N closed trades, the system synthesizes best-practice rules, anti-patterns, and AI-mistake rules with surprise ratio annotation — high-surprise outcomes are flagged so the LLM discounts lucky/unlucky noise. Rules persist in vector memory and influence future decisions. The bot learns from its own outcomes.

• 🧠 VectorMemoryRulesMixin — Semantic rule lifecycle management with decay scoring, evidence-weighted ranking, contradiction tracking, and surprise-ratio annotation. Rules are soft-ranked by similarity, evidence quality, timeframe freshness, and contradiction count — no hard pruning on age alone.

• 🔍 AST Codebase Vector Index — Parses every Python source file at the AST level into ChromaDB (data/codebase_index/). Enables natural-language queries against the entire codebase via scripts/query_codebase.py. Auto-updates on bot startup. Zero secrets or sensitive files indexed (verified by security audit).

• ✅ Claim Validation — Every LLM response is cross-checked against computed indicators. Reported trend strength is compared against actual ADX; pattern quality is replaced by a deterministic scorer. No blind trust in AI numeric claims.

• 📰 RAG News Engine — Aggregates crypto news from free RSS feeds (CoinDesk, CoinTelegraph, Decrypt, CryptoSlate) with optional Crawl4AI enrichment, plus fundamentals from DeFiLlama and CoinGecko.

• 📊 Live Dashboard — FastAPI + WebSocket real-time SPA at 0.0.0.0:8000 (or semanticsignal.qrak.org). Nine tabs with brain activity, last prompt/response, position state, performance stats, news, market data, and memory bank.

• 🛡️ Risk Pipeline — Pre-execution guard chain (symbol whitelist, max position size, cooldown) + dynamic SL/TP scaling with minimum 1.5 R:R enforced. Soft exits at candle close, hard exits at configurable intervals against live ticker price.

• 🔄 Multi-Provider AI Routing — Primary: Google Gemini 3.6 Flash (free tier). Fallback chain through OpenRouter and LM Studio. Chart vision support on every provider that allows it.

• 🧪 1,300+ Tests — Fully mocked test suite covering LLM output corruption, async races, rate-limit backoff, vector-DB boundaries, friction-reporting, closed-loop feedback, AST code indexing, and positional market types (spot / perpetual futures).

• 🤖 Multi-Agent AI Development — Eight specialized AI agents (Supervisor 🧠 + Bolt ⚡, Palette 🎨, Sentinel 🛡️, Refactor ✨, Concise ✂️, Smoke Tests 🔥, Bugfixer 🐛) coordinate via a Supervisor 🧠. Each agent writes journal entries to .ai/ — the project's collective memory. Journals auto-rotate on startup.

flowchart TB
    subgraph Data["Data Sources"]
        EX["Exchanges (CCXT) → OHLCV + Order Book + Trade Flow"]
        NEWS["RSS Feeds + Crawl4AI"]
        FUND["CoinGecko + DeFiLlama + Alternative.me"]
    end
    subgraph Analysis["Analysis Engine"]
        TC["Technical Calculator<br/>50+ indicators"]
        PE["Pattern Engine<br/>Deterministic indicator patterns"]
        CG["Chart Generator<br/>4K PNG with SMA/RSI/Volume"]
        RAG["RAG Engine<br/>News relevance scoring"]
    end
    subgraph Brain["🧠 Brain Layer"]
        VM["Vector Memory<br/>ChromaDB (4 collections)<br/>Experiences + Rules +<br/>Blocked Trades + Codebase Index"]
        REFL["Reflection Engine<br/>Rules from closed trades"]
        CTX["Context Builder<br/>Similarity retrieval +<br/>surprise ratio + confidence calibration"]
    end
    subgraph Search["🔍 Codebase Index"]
        CVI["AST Codebase Indexer<br/>160 files · 2,306 chunks<br/>Types: class/function/method/docs"]
        QUERY["query_codebase.py CLI<br/>Semantic code search<br/>by type, re-index, stats"]
    end
    subgraph Execution["Paper Execution"]
        RP["Risk Manager<br/>SL/TP, sizing, R:R,<br/>friction tracking"]
        GP["Guard Pipeline<br/>Symbol → Size → Cooldown"]
        STRAT["Trading Strategy<br/>ExitMonitor +<br/>PositionStatusMonitor"]
    end
    Data --> Analysis
    Analysis --> Brain
    Brain --> AI["AI Provider<br/>(Gemini / OpenRouter / LM Studio)"]
    AI --> RP --> GP --> STRAT
    STRAT -.->|Closed trade feedback| Brain
    CVI -.->|Indexes source| Analysis
    CVI -.->|Indexes source| Brain
    QUERY --> CVI

# Full suite (1,300+ tests)
pytest tests/ -q

# Focused
pytest tests/test_ticker_retry.py tests/test_brain_integration.py tests/test_code_vector_index.py -q

# Linting
ruff check src tests start.py

Key settings in config/config.ini:

Required API keys in keys.env:

The codebase uses a Supervisor + 7 specialized agents pattern for AI-assisted development:

Journals auto-rotate on startup via scripts/rotate_journals.py. The full architecture blueprint lives in AGENTS.md.

🔄 Live Trading — Real exchange order execution via llm_trader_executor — currently in testing

• ⏳ Multiple Trading Agent Personalities — Conservative, aggressive, contrarian, trend-following strategists (aspirational)
• ⏳ Multi-Model Consensus — "Council of Models" architecture for collective decision-making (aspirational)

NOT FINANCIAL ADVICE. This software is experimental and in BETA. A real exchange execution service is in testing — use with caution. No warranty provided. Use at your own risk.

MIT