AI Trading Module

Overview

The ai-trading module turns clone strategy graphs and market/account context into auditable proposed actions. It owns decision creation and explanation, not execution truth.

Prop Trading is the only writer for balances, fills, positions, orders, and execution ledger rows. Backtesting reuses AI Trading primitives but owns replay job state and artifacts.

Responsibilities

• Compile workflow strategy graphs into executable branches.
• Resolve effective market context from Data Ingestion tables.
• Build durable decision_v1 prompts.
• Route to no-op or model-backed decision engines.
• Persist decision runs, actions, metadata, token usage, and artifact references.
• Enforce topology and model entitlement limits before runtime decisions.
• Run clone-scoped debug decisions.
• Run prop-account decisions by account, branch, and symbol, then submit accepted proposed actions to Prop Trading.

Boundary Rules

• AI Trading can reject, skip, or propose actions. It cannot fill or settle them.
• Prop-account decisions must be scoped to the account's allowed symbols and execution policy.
• Backtesting may call AI Trading decision logic but writes backtest-owned state.
• Source freshness belongs to Data Ingestion; AI Trading records context warnings but does not repair source data.
• Cost/token usage is audit/operator data; user-facing strategy limits are topology and entitlement limits.

Runtime Flow

Decision runtime:

Load clone and strategy graph
-> compile graph into branches
-> enforce topology and model entitlement
-> resolve market context for connected data streams
-> narrow branch to one symbol
-> check cadence/due state
-> create queued decision run
-> mark running
-> call no-op or model engine
-> validate model actions
-> persist actions and artifacts
-> submit executable prop-account actions to Prop Trading
-> mark completed, failed, or skipped

A branch is the expanded form of:

Data Stream Block(s) -> Asset Block -> Trading Prompt Block

The compiler rejects duplicate prompt claims for the same asset because v1 has no arbitration layer between prompts.

Main Code Paths

Path	Purpose
backend/src/modules/ai-trading/pipeline/*	Strategy graph config, compiler, topology validation.
backend/src/modules/ai-trading/context/*	Effective decision context and Hyperliquid market context.
backend/src/modules/ai-trading/prompts/decision-prompt-v1.ts	Durable prompt contract.
backend/src/modules/ai-trading/decision/dry-run.ts	Workflow dry-run service.
backend/src/modules/ai-trading/decision/execution.ts	Decision engine interface and no-op/model boundary.
backend/src/modules/ai-trading/decision/model-engine.ts	Provider/model registry and model-backed execution.
backend/src/modules/ai-trading/decision-execution-service.ts	Clone-scoped debug decision runner.
backend/src/modules/ai-trading/prop-account-decision-runner.ts	Prop-account per-symbol decision runner.
backend/src/modules/ai-trading/repositories/decisions.ts	Decision run/action persistence.
backend/src/modules/ai-trading/artifacts/*	Prompt/context/response artifact storage.
backend/src/workers/decisions.ts	Clone-scoped decision worker.
backend/src/workers/prop-decisions.ts	Prop-account decision worker.

State And Tables

Migration	Tables
0001_initial.sql	clone_decision_runs, clone_decision_actions
0011_decision_artifacts.sql	decision_artifacts
0019_ai_trading_prop_account_audit.sql	Prop-account runtime columns and indexes on decision runs/actions.

Table	Technical significance
clone_decision_runs	One audit row per clone-debug or prop-account decision subject. Runtime mode separates clone_debug and prop_account.
clone_decision_actions	Proposed action rows linked to decision runs and, when submitted, Prop Trading action/order ids.
decision_artifacts	Large prompt, context, and model response payload references.

Decision run statuses include queued, running, completed, failed, and skipped. Action statuses include proposed, validated, rejected, queued, executed, failed, and skipped.

Routes And Workers

Surface	Purpose
POST /api/v1/clone/clones/:id/decision-dry-run	Build context/prompt/action output without prop execution.
GET /api/v1/clones/:id/decision-runs	List decision runs for a clone.
backend/src/workers/decisions.ts	Clone-scoped debug decision worker.
backend/src/workers/prop-decisions.ts	Prop-account decision worker.

Worker defaults:

Worker	Command	Default cadence	Due key
Clone debug decisions	npm run decisions:worker	60s	cloneId + branchId + symbol
Prop-account decisions	npm run prop:decisions:worker	60s	propAccountId + cloneId + branchId/tradingPromptNodeId + symbol

--force bypasses cadence for run-once/debug paths.

Prompt Contract

The model-backed engine builds decision_v1 prompts.

System prompt constraints:

• The model is a dry-run trading decision engine.
• It must return JSON only and does not place orders.
• It may only use provided structured context and the strategy prompt.
• It should choose hold when context is missing, stale, conflicting, or insufficient.
• Allowed actions are constrained by the account direction policy.
• Response shape includes actions[], action reason summaries, top-level summary, and metadata.

User prompt includes:

• promptVersion
• target.symbol
• resolved strategyPrompt
• marketContext.asOf
• compacted marketContext.sources
• accountContext for prop-account runs, otherwise null
• decisionMemory, currently null

The prompt does not include raw canvas data, payment facts, lifecycle state, Prop Trading ledger rows, or arbitrary public profile text unless that text is part of the Trading Prompt Block.

Topology Limits

Runtime topology limits are enforced across save/dry-run/backtest/runtime paths:

Tier	Max trading prompts	Max data links per active asset	Max expanded data links
starter	1	3	9
builder	3	5	30
pro	5	8	80

Active asset count must be within the clone entitlement's maxActiveAssets, and asset prompt assignment must match active assets.

Failure Behavior

• Missing required market memory creates context warnings and should push the model toward hold.
• Engine/model errors fail the specific decision run.
• Prop-account runner isolates subject failures so other due subjects can continue.
• Artifact write failures do not abort the decision; the decision row records available metadata.
• Unsupported actions, symbol mismatches, hold, entitlement blocks, and Prop Trading rejections become durable skipped/rejected audit outcomes.
• AI Trading links accepted/rejected Prop Trading submissions through prop_action_id, order_id, and action error/rejection fields.

Debugging Notes

• Start with clone_decision_runs filtered by runtime_mode, clone_id, prop_account_id, branch, and symbol.
• Use decision run metadata for prompt hash, model id, token usage, latency, and artifact references.
• If a prop account is not deciding, check account status, allowed symbols, executable branches, entitlement violations, and cadence.
• If model output looks valid but no trade happens, inspect clone_decision_actions and then Prop Trading prop_decision_actions.
• If every action is hold, inspect context freshness warnings and Data Ingestion source health.

Tests

cd backend
npm run typecheck
node --import tsx --test test/pipeline-*.test.ts test/effective-context.test.ts test/decision-*.test.ts test/prop-account-decision-runner.test.ts

Known Gaps

• Production provider spend alerts and model routing policy are not finalized.
• Long-term support level for clone-scoped debug execution paths still needs a product decision.