Phase 2A: WHAT/WHO/WHY intelligence layer — participant archetypes, IPO microstructure, DeepSeek motivation engine

[Copilot]

Implements Phase 2A of the system: real-time three-question analysis for every order event — WHAT is being ordered, WHO is placing it (behavioural archetype, never identity), and WHY they are placing it (motivation taxonomy). Adds SPCX IPO-specific microstructure detection and an optional DeepSeek-R1 reasoning engine.

New agents

• ParticipantArchetypeAgent — scores 7 mutually exclusive archetypes (institutional_accumulator, retail_sentiment_buyer, algorithmic_market_maker, momentum_ignitor, strategic_seller, informed_flow_proxy, unknown_mixed) from observable L2 signals; returns probability + compliance-cleared evidence
• IPOMicrostructureAgent — classifies IPO trading phase (price_discovery, stabilisation, normal_trading, etc.), detects greenshoe-like bid support and lock-up proximity selling patterns; SPCX pre-configured via IPO_SYMBOLS env var
• MotivationInferenceAgent — maps dominant archetype to a 14-label taxonomy across accumulation / distribution / neutral motivations; rule-based engine always runs first, DeepSeek-R1 enriches the reasoning trace when DEEPSEEK_API_KEY is set (silent fallback if unavailable)

Pipeline integration

All three agents wired into Orchestrator.process() after the existing Phase 1 agents. DecisionParliament.deliberate() accepts them as optional kwargs — fully backward compatible. Archetype votes now contribute to bullish/bearish conviction tallying. Motivation reports written to the Audit Ledger via new log_motivation().

Extended chatbot commands

who SPCX          → participant archetype + probability
why SPCX          → motivation taxonomy + reasoning trace
what SPCX         → order classification signals
ipo SPCX          → price discovery phase, greenshoe, lock-up signals
archetype SPCX    → full archetype breakdown
motivation SPCX   → full motivation inference detail
analyze SPCX      → combined WHAT / WHO / WHY view

Config additions (.env.example)

DEEPSEEK_API_KEY=          # leave blank for rule-based-only mode
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1  # override for local deployment
DEEPSEEK_MODEL=deepseek-reasoner
IPO_SYMBOLS=SPCX           # comma-separated list of monitored IPO tickers

Compliance

Phase 2A outputs are fully compliance-gated: archetypes are behavioural labels only, motivation inferences are probabilistic hypotheses, DeepSeek reasoning traces are stored in the immutable Audit Ledger. Compliance Agent veto authority unchanged.