Documentation Index
Fetch the complete documentation index at: https://mintlify.com/deniszidbaev-cmyk/polyclaw-trading/llms.txt
Use this file to discover all available pages before exploring further.
PolyClaw Trading includes a multi-role LLM orchestration layer that reads runtime artifacts and produces analysis, critique, risk notes, copy text, explanations, and a final synthesis. This layer is entirely separate from the deterministic execution engine and has no authority over whether a trade is placed.
The LLM orchestration layer is advisory only. It may read runtime artifacts such as runtime/decisions.json, runtime/bankroll_state.json, and runtime/market_analysis.json, but it does not control the deterministic execution gate. Signal generation, risk gating, and order submission are handled by the deterministic engine in src/polyclaw_engine/ — these never depend on an LLM response. An LLM timeout, error, or misconfiguration will not prevent dry-run or live execution from proceeding normally.
Provider & API key configuration
Four cloud providers and one local endpoint are supported. Configure only the keys for providers you intend to use; unused providers can be left blank or set to disabled at the role level.
| Variable | Purpose |
|---|
OPENROUTER_API_KEY | OpenRouter multi-provider gateway key |
OPENROUTER_BASE_URL | Optional base URL override for OpenRouter |
OPENAI_API_KEY | OpenAI API key; also used for local Ollama-compatible endpoints |
OPENAI_BASE_URL | Base URL override; set to http://127.0.0.1:11434/v1 for local Ollama |
ANTHROPIC_API_KEY | Anthropic Claude API key |
ANTHROPIC_BASE_URL | Base URL override for Anthropic (e.g. Tokenator gateway) |
GEMINI_API_KEY | Google Gemini API key |
ANTHROPIC_VERSION | Anthropic API version header sent with every request (default: 2023-06-01) |
HTTPS_PROXY | Optional HTTP/S proxy for all outbound LLM calls |
Per-role configuration
Each orchestration role is independently configured with a provider ID, model name, and per-request timeout. Set ORCH_ROLE_<ROLE>_PROVIDER=disabled to skip a role entirely.
| Role | Provider variable | Model variable | Timeout variable | Default provider | Default model |
|---|
memory | ORCH_ROLE_MEMORY_PROVIDER | ORCH_ROLE_MEMORY_MODEL | ORCH_ROLE_MEMORY_TIMEOUT_SEC | openai | qwen2.5:14b-instruct |
scoreboard | ORCH_ROLE_SCOREBOARD_PROVIDER | ORCH_ROLE_SCOREBOARD_MODEL | ORCH_ROLE_SCOREBOARD_TIMEOUT_SEC | openai | qwen2.5:14b-instruct |
context | ORCH_ROLE_CONTEXT_PROVIDER | ORCH_ROLE_CONTEXT_MODEL | ORCH_ROLE_CONTEXT_TIMEOUT_SEC | openai | qwen2.5:14b-instruct |
market | ORCH_ROLE_MARKET_PROVIDER | ORCH_ROLE_MARKET_MODEL | ORCH_ROLE_MARKET_TIMEOUT_SEC | openai | gpt-5.5 |
volatility | ORCH_ROLE_VOLATILITY_PROVIDER | ORCH_ROLE_VOLATILITY_MODEL | ORCH_ROLE_VOLATILITY_TIMEOUT_SEC | disabled | sonar |
macro | ORCH_ROLE_MACRO_PROVIDER | ORCH_ROLE_MACRO_MODEL | ORCH_ROLE_MACRO_TIMEOUT_SEC | disabled | sonar |
microstructure | ORCH_ROLE_MICROSTRUCTURE_PROVIDER | ORCH_ROLE_MICROSTRUCTURE_MODEL | ORCH_ROLE_MICROSTRUCTURE_TIMEOUT_SEC | disabled | sonar |
critic | ORCH_ROLE_CRITIC_PROVIDER | ORCH_ROLE_CRITIC_MODEL | ORCH_ROLE_CRITIC_TIMEOUT_SEC | anthropic | claude-sonnet-4-6 |
risk | ORCH_ROLE_RISK_PROVIDER | ORCH_ROLE_RISK_MODEL | ORCH_ROLE_RISK_TIMEOUT_SEC | anthropic | claude-sonnet-4-6 |
copy | ORCH_ROLE_COPY_PROVIDER | ORCH_ROLE_COPY_MODEL | ORCH_ROLE_COPY_TIMEOUT_SEC | anthropic | claude-haiku-4-5 |
explainer | ORCH_ROLE_EXPLAINER_PROVIDER | ORCH_ROLE_EXPLAINER_MODEL | ORCH_ROLE_EXPLAINER_TIMEOUT_SEC | anthropic | claude-haiku-4-5 |
final | ORCH_ROLE_FINAL_PROVIDER | ORCH_ROLE_FINAL_MODEL | ORCH_ROLE_FINAL_TIMEOUT_SEC | anthropic | claude-opus-4-7 |
memory, scoreboard, and context default to 20 seconds; volatility, macro, and microstructure default to 60 seconds; all remaining Anthropic-backed roles (market, critic, risk, copy, explainer, final) default to 90 seconds. A minimal production configuration using only Anthropic roles looks like this:
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_VERSION=2023-06-01
ORCH_ROLE_CRITIC_PROVIDER=anthropic
ORCH_ROLE_CRITIC_MODEL=claude-sonnet-4-6
ORCH_ROLE_CRITIC_TIMEOUT_SEC=90
ORCH_ROLE_RISK_PROVIDER=anthropic
ORCH_ROLE_RISK_MODEL=claude-sonnet-4-6
ORCH_ROLE_RISK_TIMEOUT_SEC=90
ORCH_ROLE_COPY_PROVIDER=anthropic
ORCH_ROLE_COPY_MODEL=claude-haiku-4-5
ORCH_ROLE_COPY_TIMEOUT_SEC=90
ORCH_ROLE_EXPLAINER_PROVIDER=anthropic
ORCH_ROLE_EXPLAINER_MODEL=claude-haiku-4-5
ORCH_ROLE_EXPLAINER_TIMEOUT_SEC=90
ORCH_ROLE_FINAL_PROVIDER=anthropic
ORCH_ROLE_FINAL_MODEL=claude-opus-4-7
ORCH_ROLE_FINAL_TIMEOUT_SEC=90
Default model shortcuts
These convenience variables set fallback models used when a role-specific variable is absent. Role-specific variables always take precedence.
| Variable | Default | Purpose |
|---|
ORCH_DEFAULT_MARKET_MODEL | gpt-5.5 | Default model for market-facing roles |
ORCH_DEFAULT_CLAUDE_MODEL | claude-sonnet-4-6 | Default Claude model for analysis roles |
ORCH_DEFAULT_COPY_MODEL | claude-haiku-4-5 | Default model for the copy role |
ORCH_DEFAULT_EXPLAINER_MODEL | claude-haiku-4-5 | Default model for the explainer role |
ORCH_DEFAULT_FINAL_MODEL | claude-opus-4-7 | Default model for the final synthesis role |
Token budgets
Each role has an independent token budget that limits how much context it may consume per orchestration cycle. Setting a budget to 0 does not disable the role; use ORCH_ROLE_<ROLE>_PROVIDER=disabled for that.
| Variable | Default | Description |
|---|
ORCH_TOKEN_BUDGET_TOTAL | 60000000 | Aggregate token budget across all roles in one orchestration run |
ORCH_ROLE_MARKET_TOKEN_BUDGET | 14000000 | Token budget for the market role |
ORCH_ROLE_VOLATILITY_TOKEN_BUDGET | 6000000 | Token budget for the volatility role |
ORCH_ROLE_MACRO_TOKEN_BUDGET | 6000000 | Token budget for the macro role |
ORCH_ROLE_MICROSTRUCTURE_TOKEN_BUDGET | 6000000 | Token budget for the microstructure role |
ORCH_ROLE_CRITIC_TOKEN_BUDGET | 10000000 | Token budget for the critic role |
ORCH_ROLE_RISK_TOKEN_BUDGET | 10000000 | Token budget for the risk role |
ORCH_ROLE_COPY_TOKEN_BUDGET | 4000000 | Token budget for the copy role |
ORCH_ROLE_EXPLAINER_TOKEN_BUDGET | 6000000 | Token budget for the explainer role |
ORCH_ROLE_FINAL_TOKEN_BUDGET | 16000000 | Token budget for the final synthesis role |
Kilo worker
The Kilo worker is a separate recurring LLM analysis loop that runs independently of the main trading pipeline. It reads runtime state, produces a compressed analysis report to runtime/kilo_orchestrator_latest.md, and optionally proposes BTC/ETH filter rule updates that the llm_bundle.py simulation gate may auto-apply if they pass a minimum quality bar.
| Variable | Default | Description |
|---|
KILO_PROVIDER_ID | tokenator | Provider ID string used to identify the Kilo provider |
KILO_DISPLAY_NAME | Tokenator | Human-readable display name for the Kilo provider |
KILO_BASE_URL | https://api.tokenator.cloud/v1 | OpenAI-compatible base URL for the Kilo provider |
KILO_ANTHROPIC_BASE_URL | https://api.tokenator.cloud/anthropic | Anthropic-compatible base URL for the Kilo provider |
KILO_API_KEY | (empty) | API key for the Kilo provider |
KILO_MODEL | tokenator/claude-opus-4-7 | Primary model for Kilo analysis |
KILO_FALLBACK_MODELS | tokenator/gpt-5.5,tokenator/gemini-3.1-pro-preview | Comma-separated fallback models if the primary is unavailable |
KILO_VARIANT | medium | Kilo analysis depth variant |
KILO_AVAILABLE_MODELS | gpt-5.5,claude-opus-4-7,gemini-3.1-pro-preview,claude-sonnet-4-6,claude-opus-4-6,claude-haiku-4-5 | Comma-separated list of models the Kilo provider supports |
KILO_TOKEN_BUDGET | 20000000 | Maximum tokens per Kilo analysis pass |
KILO_ANALYSIS_TIMEOUT_SEC | 75 | Per-request timeout for Kilo analysis calls |
KILO_WORKER_INTERVAL_SEC | 90 | Seconds between Kilo worker analysis cycles |
On macOS/Linux, launch the Kilo worker as a background process using the provided shell script:./scripts/launch_kilo_worker.sh
scripts\launch_kilo_worker.bat
.build/release/polyclaw-mac kilo-worker --once # single analysis pass
.build/release/polyclaw-mac kilo-worker # continuous loop
runtime/kilo_orchestrator_latest.md. The llm_bundle.py module reads this file on each signal cycle and may auto-apply LLM-proposed filter rules if the simulation gate approves them (requires at least 3 evaluated trades, at least 1 blocked losing trade, and a winner-keep ratio of ≥ 60%). Orchestration loop settings
| Variable | Default | Description |
|---|
ORCH_HEARTBEAT_SEC | 300 | Seconds between orchestrator heartbeat ticks |
ORCH_REDEEM_CRON_SEC | 900 | Seconds between automated redeem checks (when ALLOW_REDEEM=1) |
ORCH_LLM_RETRY_ATTEMPTS | 2 | Number of retry attempts for a failed LLM API call |
ORCH_LOCAL_OPENAI_BASE_URL | http://127.0.0.1:11434/v1 | Base URL for the local OpenAI-compatible endpoint used in orchestration |
Role prompts
System prompts for each orchestration role are stored as plain-text files under the prompts/ directory. Edit them to change how each role reasons about the runtime snapshot without modifying any Python code. The filenames correspond to role names (e.g. prompts/critic.txt, prompts/risk.txt). Refer to prompts/README.md for the full list and editing guidelines.
Local Qwen / Ollama endpoint
The memory, scoreboard, and context roles default to a local Qwen model served by Ollama. Configure the endpoint with:
LOCAL_QWEN_MODEL=qwen2.5:14b-instruct
LOCAL_QWEN_BASE_URL=http://127.0.0.1:11434/v1
LOCAL_QWEN_API_KEY=local
LOCAL_QWEN_TIMEOUT_SEC=90
# Used by the orchestrator's local OpenAI-compatible path
ORCH_LOCAL_OPENAI_BASE_URL=http://127.0.0.1:11434/v1
OPENAI_BASE_URL is not set, the local memory step is skipped and a missing_OPENAI_BASE_URL reason is logged; the rest of the pipeline continues normally.