Semantic Signal — an LLM trading agent that reads charts and keeps memory of its closed trades

Read this in: English · Polski · 中文 · 日本語 · 한국어 · Español · Deutsch · Português · Русский

Semantic Signal is an experimental LLM trading agent that runs on paper. Once per closed candle it
renders a 1920×1080 chart, sends the image with 65 Numba-compiled indicators and its own closed-trade
memory to a multimodal model, then checks the answer with deterministic rules before a paper trade is
booked. The prompt, the retrieved memory and the decision are published for every cycle.

• Live dashboard — semanticsignal.qrak.org: the next cycle, the exact prompt, the raw response, the memory it pulled.
• The ledger — qrak.org/results: every closed trade since 2026-09-20, next to buy-and-hold.
• How one cycle works — qrak.org/story: the long version, with the file that implements each step.

Paper trading only; no real funds are involved. crypto_pair takes any CCXT market and timeframe
sets the candle. The public deployment runs BTC/USDC on 4h.

Results

Window: 2026-09-20 → 2026-11-10 (52 days), BTC/USDC, 4h candles, 10 000 USDC simulated capital.
Source: the bot's own ledger, frozen at results/2026-11-12/; python scripts/results_report.py --data-dir results/2026-11-12 reprints every number below.

Over those 52 days the bot returned +0.05% while the underlying fell 9.27%. That is 9.3 percentage
points on fourteen counted trades — not evidence of an edge. The paper book records zero fees, so the
number is gross of trading costs; at a 0.15% round trip the result would be clearly negative. Two trades
are excluded from the statistics because their sandbox fills diverged from the real market. The
numbers above come from that frozen snapshot, not from the live ledger, so they do not move with every
cycle the bot runs. Method, per-trade table and the reproduction command:
python scripts/results_report.py --data-dir results/2026-11-12.

What this is not

• Not profitable. Fourteen counted trades are not a track record, and the paper book records zero fees.
• Not live trading. The executor runs against an exchange testnet; no real funds are involved anywhere.
• Not a black box. The prompt, the retrieved memories and the verdict behind every decision are on the dashboard.

Quick start

git clone https://github.com/qrak/LLM_trader.git && cd LLM_trader
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
pip install --no-compile -r requirements.txt -c constraints.txt
cp config/config.ini.example config/config.ini  # tracked template; edit provider if needed
cp keys.env.example keys.env  # or export one provider key; `provider = local` needs none
python start.py               # dashboard at http://localhost:8000

Python 3.13 only, ~3 GB of disk, one API key (or a local LM Studio server). Platform launchers,
Windows quirks and the full secret table: docs/SETUP.md.

While the bot runs, http://localhost:8000/admin/ is the local settings desk: config.ini,
keys.env and the project documentation in one page. It is loopback-only, never displays a stored
secret, validates config changes with the loader, and needs a restart to apply. Details:
docs/SETTINGS_PANEL.md.

Features

Long version, with the file that implements each of them: docs/FEATURES.md.

Architecture

flowchart TB
    subgraph Data["Data Sources"]
        EX["Exchanges (CCXT) → OHLCV + Order Book + Trade Flow"]
        NEWS["RSS Feeds + trafilatura"]
        FUND["CoinGecko + DeFiLlama + Alternative.me"]
    end
    subgraph Analysis["Analysis Engine"]
        TC["Technical Calculator<br/>65 Numba-compiled indicator functions"]
        PE["Pattern Engine<br/>Deterministic indicator patterns"]
        CG["Chart Generator<br/>1920×1080 PNG"]
        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 / Google / OpenRouter / OpenCode Go / LM Studio / BlockRun)"]
    AI --> RP --> GP --> STRAT
    STRAT -.->|Closed trade feedback| Brain

Testing

python -m pytest tests -q              # 2,728 tests, ~135 s
ruff check src scripts start.py        # clean
pyright src start.py                   # 0 errors
python scripts/check_dead_symbols.py   # 0 dead, 0 test-only
python scripts/check_comment_policy.py # 0 comments outside machine directives

Test directories: domain_trading, domain_brain, domain_rag_indicators and domain_infra.
The collected count is larger
than the number of def test_ functions because of parametrisation. CI runs ruff, pyright,
pytest -m "not integration", the dead-symbol and comment-policy gates, check_claims.py and CodeQL on
every push; a pull request labelled refactor also has a net-deletion budget. The showcase site is
built and deployed from its own repository.

Documentation map

Not built yet

• Live trading. Order placement is a separate service that currently runs against an exchange testnet. Its code is not in this repository.
• Several trading personalities (conservative, contrarian, etc.). Not implemented.
• Multi-model consensus. Not implemented; the bot calls one provider per cycle, with fallbacks.

Disclaimer

Not financial advice. This software is experimental and in BETA; it trades a simulated book by
default and no real funds are involved. Profitability is unproven and paper results are not live
results. No warranty; use at your own risk.

License

MIT