🤖 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 9-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 (DEEPSEEK_API_KEY / GOOGLE_STUDIO_API_KEY / OPENROUTER_API_KEY)
python start.py               # dashboard at http://localhost:8000

• 🧠 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 (DeepSeek V4.1 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.

• ✅ 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) + 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: DeepSeek V4.1 Flash (deepseek-flash, native chart vision). Fallback chain through Google Gemini / OpenRouter / LM Studio. Chart vision support on every provider that allows it.

• 🧪 1,380+ 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).

• 🗂️ Layered Agent Documentation — Root AGENTS.md carries the system-wide rules and a map into per-package AGENTS.md files (src/trading/, src/analyzer/, src/dashboard/, src/managers/, src/indicators/, src/rag/, src/trading/guards/), so a coding model reads only the package it touches instead of the whole manual.

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 (3 collections)<br/>Experiences + Rules +<br/>Blocked Trades"]
        REFL["Reflection Engine<br/>Rules from closed trades"]
        CTX["Context Builder<br/>Similarity retrieval +<br/>surprise ratio + confidence calibration"]
    end
    subgraph Execution["Paper Execution"]
        RP["Risk Manager<br/>SL/TP, sizing, R:R,<br/>friction tracking"]
        GP["Guard Pipeline<br/>Symbol → Size"]
        STRAT["Trading Strategy<br/>ExitMonitor +<br/>PositionStatusMonitor"]
    end
    Data --> Analysis
    Analysis --> Brain
    Brain --> AI["AI Provider<br/>(DeepSeek / 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,380+ tests)
pytest tests/ -q

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

# Linting
ruff check src tests start.py

Key settings in config/config.ini:

Required API keys in keys.env:

Contributors (human or model) get the rules in layers, so nobody has to read the whole manual:

Each file links back to the root; the root never duplicates package detail.

🔄 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