Learning data structure

This page describes the public model for judgment, market, account, risk, execution, and explanation records used by NoahAI Client. Its purpose is traceability, audit, and reproducibility, with separate venue, account, PAPER/LIVE, and strategy-version boundaries.

Why it matters

Financial AI must support trace, audit, and reproduction of supported decisions, not just outcome prediction. NoahAI records rationale, controls, requests, and outcomes within the applicable service boundary.

Who should read it

This structure separates PAPER and LIVE, venue and broker, account, currency, and strategy version so it can support product validation, venue review, and audit.

Production data flow

Real-time market data (price, volatility, order book)
AI decision generation (signals, confidence, guardrail application)
Order execution feedback (fill, slippage, reject)
Post-trade review and learning loop

The key is "standardization of record".

Judgment, context, and outcome must be stored in the same schema for replay, learning, audit, and user trust. Below are the main data structures in a CareLog-like schema.

DecisionLog

Decision log

Field	Type	Description
decision_id	UUID	Unique decision ID
timestamp	TIMESTAMP	Decision time
strategy	STRING	Selected strategy
action	ENUM	Action type (BUY/SELL/HOLD)
reasoning	JSON	Reasoning (pattern, signal, weights)
confidence	FLOAT	Confidence score (0–1)
model_version	STRING	AI model version used

MarketSnapshot

Market data snapshot

Field	Type	Description
snapshot_id	UUID	Unique snapshot ID
timestamp	TIMESTAMP	Snapshot time
symbol	STRING	Trading symbol
price	DECIMAL	Current price
volume	DECIMAL	Volume
volatility	DECIMAL	Volatility indicator
orderbook_depth	JSON	Order book depth
market_signals	JSON	Detected market signals

AccountSnapshot

Account state snapshot

Field	Type	Description
snapshot_id	UUID	Unique snapshot ID
timestamp	TIMESTAMP	Snapshot time
balance	DECIMAL	Balance
positions	JSON	Current positions
leverage	DECIMAL	Leverage ratio
margin_used	DECIMAL	Margin in use
unrealized_pnl	DECIMAL	Unrealized P&L

RiskEvent

Risk event

Field	Type	Description
event_id	UUID	Unique event ID
timestamp	TIMESTAMP	Event time
risk_type	ENUM	Risk type (LOSS_LIMIT/VOLATILITY/LEVERAGE/ANOMALY)
severity	ENUM	Severity (LOW/MEDIUM/HIGH/CRITICAL)
trigger_value	DECIMAL	Trigger value
action_taken	STRING	Action taken
guardrail_applied	BOOLEAN	Whether guardrail was applied

ExecutionResult

Execution result

Field	Type	Description
execution_id	UUID	Unique execution ID
decision_id	UUID	Linked decision ID
timestamp	TIMESTAMP	Execution time
order_type	ENUM	Order type (MARKET/LIMIT/STOP)
quantity	DECIMAL	Quantity
executed_price	DECIMAL	Executed price
slippage	DECIMAL	Slippage
fee	DECIMAL	Fee
status	ENUM	Status (PENDING/FILLED/PARTIAL/CANCELLED/FAILED)

XAITrace

XAI trace log

Field	Type	Description
trace_id	UUID	Unique trace ID
decision_id	UUID	Linked decision ID
timestamp	TIMESTAMP	Trace time
explanation	TEXT	Decision explanation (human-readable)
evidence	JSON	Evidence (pattern, signal, stats)
confidence_breakdown	JSON	Confidence breakdown
alternative_options	JSON	Options considered but not chosen

Learning data structure example

The JSON below is a synthetic field example, not real user, account, order, or performance data.

The learning data structure in use includes:

{
  "example_only": true,
  "ai_learning_data": {
    "decision_history": [
      {
        "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
        "asset_type": "crypto",
        "decision": "long_entry",
        "reasoning": {
          "signal_strength": null,
          "pattern": "bull_flag",
          "market_conditions": "high_volatility"
        },
        "confidence": null,
        "tp": null,
        "sl": null,
        "exchange": "example_venue",
        "execution_status": "example_status",
        "result": "example_result"
      }
    ],
    "conversation_patterns": {
      "common_questions": [
        "Deposit method",
        "Withdrawal procedure",
        "API key setup",
        "Fee guide"
      ],
      "response_effectiveness": {
        "step_by_step_guide": null,
        "simple_language": null
      }
    },
    "user_satisfaction_metrics": {
      "comprehension_rate": null,
      "task_completion_rate": null
    }
  }
}

This structure supports real-time crypto decision-making, execution tracking, and learning from market conditions.

Schema design principles

Standardization: All judgment/context/outcome in the same format for replay
Traceability: Each record has unique ID and timestamp for time-order trace
Connectivity: DecisionLog, ExecutionResult, XAITrace link for full flow trace
Anonymization roadmap: cross-user learning requires explicit consent, anonymization, revocation, and operational validation; it is not an operating feature in the current public release
Extensibility: JSON fields allow new fields without breaking existing structure

Data usage examples

Trade pattern similarity

Compare past crypto trade patterns with current market to analyze performance in similar patterns; used for risk management via pattern verification before entry.

Regime-dependent thresholds

Adjust confidence and risk thresholds by regime (volatility spike, sideways, trend) to support better decisions.

Guardrail effect and loss prevention

Analyze guardrail application and max drawdown for policy improvement and risk strategy optimization.

Related technical docs

Explain, record, and learning pipelines that use this data structure are described in the documents below.