feat: yaml files for llm reasoning

artifacts/exchanges/base_exchange.yaml

@@ -0,0 +1,65 @@
+source_file: exch_live/__init__.py
+schema_version: v1.1
+
+factual_summary: >
+  Defines shared utilities and base behavior for exchange integrations,
+  including standardized order string formatting and basic exchange
+  health/state tracking used across concrete exchange implementations.
+
+methods:
+  - name: order_str
+    signature: "(inst, order_dict, eOid) -> str"
+    description: >
+      Formats a human-readable string representation of an order, including
+      side, quantity, symbol, price, exchange name, and external order ID.
+
+  - name: all_up
+    signature: "() -> bool"
+    description: >
+      Returns whether all tracked exchange subsystems are currently marked
+      as operational.
+
+  - name: set_up
+    signature: "(kind) -> None"
+    description: >
+      Marks a specific exchange subsystem as operational and logs the updated
+      exchange state, including any remaining subsystems that are not yet up.
+
+interpretive_summary: >
+  Provides a minimal base abstraction for exchange integrations, centralizing
+  shared concerns such as operational state tracking and consistent logging.
+  This base class deliberately avoids order placement or strategy logic,
+  serving instead as a foundation that concrete exchange implementations
+  can extend while preserving uniform health semantics and observability.
+
+invariants:
+  - Exchange operational state is represented consistently via string values
+  - An exchange is considered fully operational only when all subsystems are up
+  - Logging reflects partial readiness when subsystems are still initializing
+
+tags:
+  domain:
+    - exchange_integration
+    - monitoring
+  trading_function:
+    - order_execution
+  strategy_layer:
+    - execution
+  system_layer:
+    - engine
+  intent:
+    - abstraction
+    - observability
+  data_type:
+    - orders
+    - configs
+  risk:
+    - latency
+    - data_corruption
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: llm_assisted
+  confidence_score: 0.70

artifacts/exchanges/binance.yaml

@@ -0,0 +1,108 @@
+source_file: exch_live/binance.py
+schema_version: v1.1
+
+factual_summary: >
+  Provides asynchronous utilities for discovering available perpetual futures
+  contracts, normalizing symbol representations, and streaming real-time order
+  book depth and trade data from a futures exchange via REST and websocket
+  interfaces. The module coordinates contract discovery, websocket subscription,
+  message parsing, and queue-based data distribution.
+
+methods:
+  - name: propose_contracts
+    signature: "() -> list"
+    description: >
+      Retrieves metadata for all available perpetual futures contracts from the
+      exchange, filters for actively trading instruments, normalizes symbol names,
+      and returns the resulting contract list for downstream consumption.
+
+  - name: get_depths
+    signature: "(qDepth: asyncio.Queue, qOut: asyncio.Queue, sendRaw: bool) -> None"
+    description: >
+      Continuously fetches order book depth snapshots for symbols received via an
+      asyncio queue and forwards either raw or processed depth data to an output
+      queue depending on configuration.
+
+  - name: run_ws
+    signature: "(contract_data: list, qDepth: asyncio.Queue, qOut: asyncio.Queue, sendRaw: bool) -> None"
+    description: >
+      Establishes and maintains websocket subscriptions for depth and trade streams
+      for a set of contracts, receives and parses streaming messages, and forwards
+      structured data to downstream consumers with basic timeout handling.
+
+  - name: get_normalized_symbols
+    signature: "(cd: list) -> list"
+    description: >
+      Extracts and returns the standardized symbol identifiers from a list of
+      contract metadata objects.
+
+  - name: get_native_symbols
+    signature: "(cd: list) -> list"
+    description: >
+      Extracts and returns the exchange-native symbol identifiers from a list of
+      contract metadata objects.
+
+  - name: price_precision_from_ticksize
+    signature: "(ts: str) -> int"
+    description: >
+      Derives the price precision implied by a tick size representation.
+
+  - name: get_price_precision_map
+    signature: "(cd: list) -> dict"
+    description: >
+      Builds a mapping from symbol to price precision based on exchange-provided
+      price filter metadata.
+
+  - name: get_min_qty_map
+    signature: "(cd: list) -> dict"
+    description: >
+      Builds a mapping from symbol to minimum tradable quantity using exchange
+      contract metadata.
+
+  - name: main
+    signature: "(runWriter: bool, contracts: list, args) -> None"
+    description: >
+      Orchestrates contract selection, data stream initialization, and optional
+      downstream writing or processing behavior based on runtime configuration.
+
+interpretive_summary: >
+  Acts as a market data ingestion and normalization layer for perpetual futures
+  trading, abstracting away exchange-specific REST and websocket mechanics.
+  This module is intentionally focused on data acquisition and standardization,
+  avoiding any trading or decision logic so that downstream components can rely
+  on consistent, exchange-agnostic market data streams.
+
+invariants:
+  - Only actively trading perpetual contracts are streamed
+  - Symbol normalization is applied consistently across all downstream consumers
+  - Market data is distributed via asynchronous queues to avoid tight coupling
+  - Websocket reconnection logic preserves the original contract set
+
+tags:
+  domain:
+    - market_data
+    - exchange_integration
+  trading_function:
+    - data_ingest
+    - feature_engineering
+  strategy_layer:
+    - signal
+  system_layer:
+    - worker
+  intent:
+    - abstraction
+    - isolation
+    - observability
+  data_type:
+    - raw_market_ticks
+    - aggregated_candles
+  risk:
+    - latency
+    - data_corruption
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: manual_from_docs
+  confidence_score: 0.75

artifacts/exchanges/btcc.yaml

@@ -0,0 +1,104 @@
+source_file: exch_live/btcc.py
+schema_version: v1.1
+
+factual_summary: >
+  Implements the exchange integration for the BTCC perpetual futures exchange.
+  This module manages authentication, HTTP and websocket connectivity, order
+  lifecycle handling, and synchronization of positions and execution state
+  between the exchange and the trading system. It extends shared exchange
+  behavior from a base exchange abstraction.
+
+methods:
+  - name: CustomAdapter.process
+    signature: "(msg, kwargs) -> str"
+    description: >
+      Modifies log messages by applying a standardized prefix to improve
+      identification of BTCC-related log output.
+
+  - name: sympathToSymbol
+    signature: "(sympath: str) -> str"
+    description: >
+      Converts BTCC-specific symbol path representations into standardized
+      symbol identifiers used internally by the trading system.
+
+  - name: volumesListToLeverage
+    signature: "(vl: str) -> int"
+    description: >
+      Extracts leverage information from a volume list string provided by
+      the exchange.
+
+  - name: __init__
+    signature: "(trader, exchName) -> None"
+    description: >
+      Initializes the BTCC exchange instance, sets up internal state tracking,
+      and schedules asynchronous initialization tasks.
+
+  - name: up
+    signature: "() -> None"
+    description: >
+      Establishes authenticated websocket and HTTP sessions, initializes
+      exchange state, retrieves position information, and synchronizes
+      positions with the trader component.
+
+  - name: run
+    signature: "() -> None"
+    description: >
+      Coordinates asynchronous processing of websocket messages and queued
+      tasks, ensuring proper handling once all exchange subsystems are ready.
+
+  - name: send_order
+    signature: "(instr, side, price, qty, isHedge=0) -> None"
+    description: >
+      Submits a new order to the exchange and tracks its lifecycle using
+      exchange-provided order identifiers.
+
+  - name: cancel_order
+    signature: "(sym, eOid) -> None"
+    description: >
+      Cancels an existing order on the exchange using the exchange order ID.
+
+interpretive_summary: >
+  Serves as the concrete execution-layer integration for the BTCC exchange,
+  encapsulating all exchange-specific protocols, state management, and
+  authentication details. This module deliberately isolates exchange mechanics
+  from trading strategy logic, allowing the broader system to interact with
+  BTCC through a consistent interface while reducing coupling and operational
+  risk across exchanges.
+
+invariants:
+  - Exchange connectivity must be fully established before order processing
+  - Exchange order IDs are the source of truth for order lifecycle tracking
+  - Internal state reflects readiness of user, trade, position, and instrument subsystems
+  - Symbol normalization is applied consistently across all exchange interactions
+
+tags:
+  domain:
+    - exchange_integration
+    - order_execution
+  trading_function:
+    - order_execution
+    - position_management
+  strategy_layer:
+    - execution
+  system_layer:
+    - engine
+  intent:
+    - abstraction
+    - isolation
+    - fault_tolerance
+    - observability
+  data_type:
+    - orders
+    - positions
+    - configs
+  risk:
+    - capital_loss
+    - latency
+    - exchange_ban
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: manual_from_docs
+  confidence_score: 0.78

artifacts/exchanges/bullish.yaml

@@ -0,0 +1,92 @@
+source_file: exch_live/bullish.py
+schema_version: v1.1
+
+factual_summary: >
+  Implements the exchange integration for the Bullish exchange, providing
+  authenticated access via HTTP and private WebSocket connections. This module
+  manages authentication using HMAC and JWT tokens, establishes exchange
+  connectivity, retrieves position data, and maintains readiness state for
+  downstream trading operations.
+
+methods:
+  - name: __init__
+    signature: "(trader, exchName) -> None"
+    description: >
+      Initializes the Bullish exchange instance, configures authentication
+      parameters, and prepares internal state for asynchronous startup.
+
+  - name: up
+    signature: "() -> None"
+    description: >
+      Retrieves an authentication token, establishes a private WebSocket
+      connection, and fetches initial position data from the exchange.
+
+  - name: run
+    signature: "() -> None"
+    description: >
+      Waits for all required exchange subsystems to be fully initialized before
+      allowing further processing or interaction.
+
+  - name: get_jwt_token
+    signature: "() -> str"
+    description: >
+      Generates and retrieves a JWT token using HMAC-based authentication for
+      authorized access to the Bullish API.
+
+  - name: http_get
+    signature: "(url: str) -> dict"
+    description: >
+      Performs an asynchronous HTTP GET request to the specified API endpoint
+      and returns the parsed JSON response.
+
+  - name: all_up
+    signature: "() -> bool"
+    description: >
+      Determines whether all exchange components, including connectivity and
+      position state, are fully initialized and operational.
+
+interpretive_summary: >
+  Serves as the execution-layer adapter for the Bullish exchange, encapsulating
+  all exchange-specific authentication, connectivity, and state initialization
+  logic. This module intentionally isolates Bullish protocol details from the
+  rest of the trading system, enabling consistent exchange interaction while
+  reducing coupling and simplifying multi-exchange support.
+
+invariants:
+  - Authentication must be completed successfully before private data access
+  - Position data must be synchronized before the exchange is considered ready
+  - Trading operations are gated on full exchange readiness
+  - Exchange-specific credentials are handled exclusively within this module
+
+tags:
+  domain:
+    - exchange_integration
+    - order_execution
+  trading_function:
+    - order_execution
+    - position_management
+  strategy_layer:
+    - execution
+  system_layer:
+    - engine
+  intent:
+    - abstraction
+    - isolation
+    - safety
+    - observability
+  data_type:
+    - orders
+    - positions
+    - configs
+  risk:
+    - capital_loss
+    - latency
+    - exchange_ban
+    - security
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: manual_from_docs
+  confidence_score: 0.76

artifacts/exchanges/bybit.yaml

@@ -0,0 +1,109 @@
+# artifacts/exchange/bybit_exchange.yaml
+
+source_file: exch_live/bybit.py
+schema_version: v1.1
+
+factual_summary: >
+  Implements the exchange integration for the Bybit exchange, supporting
+  authenticated HTTP and websocket connectivity for order, trade, position,
+  and instrument data. This module manages exchange state tracking, order
+  lifecycle mapping, rate limit observability, and synchronization of execution
+  and position information with the trading system.
+
+methods:
+  - name: gen_signature
+    signature: "(param_str: str) -> str"
+    description: >
+      Generates an HMAC SHA256 signature for authenticated API requests using
+      exchange credentials.
+
+  - name: parse_and_print_rate_limiting_data
+    signature: "(d: dict) -> None"
+    description: >
+      Parses and logs rate limit usage information provided by the exchange.
+
+  - name: __init__
+    signature: "(trader, exchName, mode) -> None"
+    description: >
+      Initializes the Bybit exchange instance, configures operational mode,
+      prepares websocket endpoints, and initializes internal state tracking.
+
+  - name: up
+    signature: "() -> None"
+    description: >
+      Establishes authenticated connections to order and trade websockets and
+      handles exchange authentication responses.
+
+  - name: run
+    signature: "() -> None"
+    description: >
+      Executes the main asynchronous processing loop, monitoring websocket
+      messages and handling order updates, executions, and cancellations.
+
+  - name: send_auth
+    signature: "(ws) -> None"
+    description: >
+      Sends authentication messages to a websocket connection to authorize
+      private data access.
+
+  - name: set_up
+    signature: "(component: str) -> None"
+    description: >
+      Marks a specific exchange subsystem as operational.
+
+  - name: all_up
+    signature: "() -> bool"
+    description: >
+      Returns whether all exchange subsystems are fully initialized and ready.
+
+  - name: update_pos_for_pos_entry_line
+    signature: "(posEntry: dict) -> None"
+    description: >
+      Updates internal position state using position entry data received from
+      the exchange.
+
+interpretive_summary: >
+  Serves as the execution-layer adapter for the Bybit exchange, encapsulating
+  all exchange-specific authentication, websocket coordination, and order and
+  position state management. This module deliberately isolates Bybit protocol
+  details from strategy and decision logic, enabling consistent multi-exchange
+  execution while maintaining clear readiness and lifecycle semantics.
+
+invariants:
+  - Exchange subsystems must be fully initialized before trading operations proceed
+  - Exchange order identifiers are consistently mapped to internal order IDs
+  - Position state reflects the latest exchange-provided execution data
+  - Authentication is required before processing private websocket messages
+
+tags:
+  domain:
+    - exchange_integration
+    - order_execution
+  trading_function:
+    - order_execution
+    - position_management
+  strategy_layer:
+    - execution
+  system_layer:
+    - engine
+  intent:
+    - abstraction
+    - isolation
+    - observability
+    - fault_tolerance
+  data_type:
+    - orders
+    - positions
+    - configs
+  risk:
+    - capital_loss
+    - latency
+    - exchange_ban
+    - security
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: manual_from_docs
+  confidence_score: 0.77

artifacts/exchanges/mexc.yaml

@@ -0,0 +1,94 @@
+# artifacts/exchange/mexc_exchange.yaml
+
+source_file: exchange/mexc.py
+schema_version: v1.1
+
+factual_summary: >
+  Implements the exchange integration for the MEXC exchange, providing
+  authenticated REST and websocket connectivity for order execution and
+  exchange state monitoring. This module manages request signing, connection
+  setup, instrument discovery, and asynchronous processing of exchange events
+  using a shared base exchange abstraction.
+
+methods:
+  - name: sign_rest
+    signature: "(key, obj) -> MexcSignature"
+    description: >
+      Generates a REST API signature for authenticated requests by serializing
+      request data and producing a signed representation.
+
+  - name: sign_ws
+    signature: "() -> MexcSignature"
+    description: >
+      Generates a signature required for authenticated websocket connections
+      to the exchange.
+
+  - name: headers_for_sign
+    signature: "(s: MexcSignature) -> dict"
+    description: >
+      Constructs HTTP headers required for authenticated REST requests using
+      a previously generated signature.
+
+  - name: __init__
+    signature: "(trader, exchName) -> None"
+    description: >
+      Initializes the MEXC exchange instance, configures internal state tracking,
+      and starts background tasks required for exchange interaction.
+
+  - name: up
+    signature: "() -> None"
+    description: >
+      Establishes authenticated websocket and HTTP connections, retrieves
+      instrument information, and initializes exchange readiness state.
+
+  - name: run
+    signature: "() -> None"
+    description: >
+      Monitors websocket streams and asynchronous task queues, processes
+      incoming exchange events, and logs relevant operational information.
+
+interpretive_summary: >
+  Serves as the execution-layer adapter for the MEXC exchange, encapsulating
+  all exchange-specific authentication, request signing, and connectivity
+  logic. This module isolates MEXC protocol and security requirements from
+  trading strategy and decision-making components, enabling consistent and
+  safer multi-exchange execution within the trading system.
+
+invariants:
+  - Exchange authentication must be completed before private data is processed
+  - Request signing is required for all authenticated REST and websocket interactions
+  - Instrument information is fetched before the exchange is considered ready
+  - Exchange readiness state reflects user, trade, position, and instrument subsystems
+
+tags:
+  domain:
+    - exchange_integration
+    - order_execution
+  trading_function:
+    - order_execution
+    - position_management
+  strategy_layer:
+    - execution
+  system_layer:
+    - engine
+  intent:
+    - abstraction
+    - isolation
+    - security
+    - observability
+  data_type:
+    - orders
+    - positions
+    - configs
+  risk:
+    - capital_loss
+    - latency
+    - exchange_ban
+    - security
+  maturity:
+    - production
+
+provenance:
+  generated_at: 2026-02-02
+  generated_by: manual_from_docs
+  confidence_score: 0.77