AI Co-Pilot Assistant

The AIAssistant (api/ai_assistant.py, ~2,380 lines) allows users to generate strategy configurations from plain-text descriptions or chart screenshots. It acts as a bridge between the visual editor frontend and Large Language Models (Google Gemini / OpenRouter), transforming natural language into executable strategy JSON.

---

AI Ingestion Architecture

The Co-Pilot service accepts text and media assets, enriches them with real-time market data, and requests structured JSON outputs from the LLM.

Provider Selection

Sources: oracle.py

The provider is configured via environment variable, allowing operators to switch between Google's direct GenAI SDK and OpenRouter's unified API.

---

Real-Time Context Hydration

To prevent the LLM from generating obsolete or irrelevant strategy recommendations, DepthSight "hydrates" the user's prompt with real-time telemetry before sending the query.

enrich_market_context_for_ai() (lines 1017–1076)

The function:

1. Parses the user prompt for ticker symbols matching \b[A-Z0-9]{2,10}USDT\b.
2. Filters out stop-words (LONG, SHORT, GRID, DCA, AND, OR).
3. Queries the Screener API (http://localhost:8050/api/v1/metrics/{symbol}) for up to 2 detected symbols:

Sources: oracle.py

The resulting context block is injected into the LLM prompt, providing the AI with current market conditions to base its strategy recommendations on.

Context Content Injected

Data Point	Source	Purpose
Last Price	Screener API	Entry/exit level calibration
NATR (Volatility)	Screener API	Stop-loss distance suggestion
Macro Trend	Screener API	Directional bias alignment
Oracle Regime	Screener API	Risk mode adjustment
24h Volume	Screener API	Liquidity assessment

---

Image-to-Strategy Ingestion

Gemini and modern multimodal models can read image pixels directly. When a user uploads a screenshot of a trading setup:

1. Image Normalization (lines 1323–1340)

Sources: oracle.py

The image is converted to a base64 string and wrapped in the correct MIME type payload.

2. Provider-Specific Attachment

Google Gemini (lines 1359–1364): Converts base64 to bytes via base64.b64decode() and attaches as types.Part.from_bytes(data=..., mime_type=...).

OpenRouter (lines 1487–1495): Embeds as {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{data}"}}.

3. Visual Parsing

The system prompt instructs the model to:

• Extract technical indicators visible on the screen (Bollinger Bands, RSI, MACD).
• Identify chart structures (ascending triangle, breakout levels, moving average crosses).
• Map visual patterns to mathematical block JSON nodes:
  • Ascending triangle → local_level + level_touch_analyzer + price_action_analyzer.
  • RSI divergence → rsi_condition with specific threshold + trend filter.

4. JSON Mapping

The model generates block JSON nodes mapped to the visual builder canvas schema, which the frontend renders as draggable logic blocks.

---

Response Validation

LLMs can suffer from hallucinations, producing invalid JSON or referencing nonexistent logic blocks. DepthSight implements multi-layer validation:

Layer 1 — Python Code Detection (lines 974–1013)

A critical security filter scans for Python code injection:

Sources: oracle.py

If Python code is detected, the response is blocked and a safe message is returned.

Layer 2 — JSON Extraction & Syntax Check (lines 2120–2133)

If the AI wraps JSON in markdown or explanatory text, the first {...} block is extracted via str.find("{") / str.rfind("}"):

Sources: oracle.py

Layer 3 — Block Schema Validation

All generated block type fields are checked against the existing canvas schemas. Missing or invalid block types are rejected.

Layer 4 — Parameter Default Injection (lines 813–855)

Missing parameters are merged with defaults via _ensure_default_params():

Sources: oracle.py

This prevents bot engine crashes from missing configuration fields.

Layer 5 — Pydantic Validation

The final JSON is validated against schemas.StrategyV2ConfigData.model_validate(), ensuring type correctness.

---

Full Query Flow

Generator Mode (get_chat_response(), line 1601)

Used for strategy generation from text/screenshots:

1. Achievement Grant (line 1613): Unlocks "used_ai_assistant" achievement.
2. Quota Check (lines 1628–1633): QuotaManager.check_and_consume("use_ai_assistant").
3. Chat History Retrieval: Pulls last 6 messages from ai_chat_messages table.
4. Modification vs Generation: Detects if the user is asking to modify an existing strategy or create a new one.
5. RAG Injection: Calls enrich_market_context_for_ai().
6. Tier Context: Informs the AI about the user's plan restrictions.
7. Backtest Context: If a backtest_id is provided, appends backtest analytics to the prompt.
8. LLM Call: _generate_json_response() with structured JSON output.
9. Validation Pipeline: JSON extraction → schema validation → default injection → Pydantic validation.
10. Return: schemas.AIChatResponse with strategy_json.

Advisor Mode

Used for strategy analysis and questions:

1. Chat history retrieval.
2. RAG injection with current market context.
3. Tier context.
4. Backtest Analytics: Parses decision traces into combination/individual foundation stats, best/worst trades.
5. Real Trade Analytics: If available, includes live trade performance.
6. LLM Call: _generate_text_response() for natural language output.
7. Python Code Security Check: Scans for code injection.
8. Return: AIChatResponse with text_response.