feat: yaml files for llm reasoning

artifacts/execution/trader.yaml

@@ -0,0 +1,149 @@
+source_file: ./trader.py
+schema_version: v1.1
+
+factual_summary: >
+  Implements the execution component responsible for placing and managing
+  long and short trades, including associated hedge operations, across
+  supported exchanges. Maintains order book state, open positions, fees,
+  and profit and loss tracking while supporting both live trading and
+  backtesting modes.
+
+methods:
+  _getBracket(exch: str, sym: str) -> List[]:
+    description: >
+      Retrieves the current bid and ask information for a given symbol
+      on a specified exchange using maintained order book state.
+
+  startBidding(exch: str, sym: str, ts: float, entryPrice: float or None) -> None:
+   description: >
+     Used in the Strat class to update the entry price of a symbol on a particular exchange. Logic for updating the 
+     entry price is contained there.
+
+  stopBidding(exch: str, sym: str, ts: float) -> None:
+   description: >
+     Halts the bidding by removing the order from the limitBuy dictionary.
+
+  updateBracket(exch: str, sym: str, bidQuote: float, askQuote: float) -> None:
+   description: >
+     Updates the bracketed strings in our brackets dictionary.
+
+  startOffering(exch: str, sym: str, ts: float, entryPrice: float or None) -> None:
+   description: >
+     Executes the trades when we are going short.
+
+  stopOffering(exch: str, sym: str, ts: float) -> None:
+   description: >
+     Stops the short position.
+
+  logIntradayPnl(val: float) -> None:
+   description: >
+     Updates the value of our account to our pnl database
+
+  fpnl() -> None:
+    description: >
+      Returns a list of floating profit and loss summaries
+
+  posCounts() -> dict:
+    description: >
+      Returns a python dictionary of the total positions we have on each exchange.
+
+  logFee(fee: float) -> None:
+    description: >
+      Updates our fees in our database
+
+  posValueAtExchOld(exch: str, sym: str) -> int:
+    description: >
+      Calculates the values of the long and short positions.
+
+  fpnlnotional() -> int:
+    description: >
+      This method calculates the profit/loss (P&L) based on the notional value of long and short positions for each 
+      unique symbol across different exchanges. It computes the average price of long positions, sums the notional 
+      values of both long and short positions, and then uses these to compute the P&L.
+
+  fillLong(exch: str, sym: str, price: float, quan: float, ts: int, tag: str, feeType: str) -> None:
+    description: >
+      The fillLong method handles the process of filling a buy order for a specified asset on an exchange. It updates 
+      the trader's position with the new quantity and calculates the average price if necessary. If there was a short 
+      position, it also calculates the profit/loss from buying back some or all of the shorted amount. Additionally, 
+      it logs the trade, applies fees, and ensures data integrity by asserting non-negative values.
+
+  fillShort(exch: str, sym: str, price: float, quan: float, ts: int, tag: str, feeType: str) -> None:
+    description: >
+      The fillShort method handles the process of filling a sell order for a specified asset on an exchange. It updates 
+      the trader's position with the new quantity and calculates the average price if necessary. If there was a long 
+      position, it also calculates the profit/loss from selling some or all of the held amount. Additionally, it logs 
+      the trade, applies fees, and ensures data integrity by asserting non-negative values.
+
+  hedgeLong(exch: str, sym: str, price: float, quan: float, ts: int, force: bool) -> Exchange:
+    description: >
+      The hedgeLong method finds an appropriate exchange to hedge a long position by executing a corresponding sell 
+      order. It iterates over possible exchanges, calculates adjusted bid prices based on offsets, and selects the 
+      highest bid price for execution. If no suitable exchange is found without forcing, it forces hedging. The method 
+      ensures that the hedge does not exceed maximum allowed positions and logs relevant information throughout the 
+      process.
+
+  hedgeShort(exch: str, sym: str, price: float, quan: float, ts: int, force: bool) -> Exchange:
+    description: >
+      The hedgeShort method finds an appropriate exchange to hedge a short position by executing a corresponding buy 
+      order. It iterates over possible exchanges, calculates adjusted ask prices based on offsets, and selects the 
+      lowest ask price for execution. If no suitable exchange is found without forcing, it forces hedging. The method 
+      ensures that the hedge does not exceed maximum allowed positions and logs relevant information throughout the 
+      process.
+
+  processTrade(exch: str, sym: str, price: float, tradeDir: list) -> None:
+    description: >
+      The first half of the processTrade method handles the scenario where a market sell order results in hitting a 
+      limit buy order. It processes the fill, hedges the position, and logs various portfolio and holdings-related 
+      details. The second half of the processTrade method handles the scenario where a market buy order results in 
+      hitting a limit sell order. It processes the fill, hedges the position, and logs various portfolio and 
+      holdings-related details.
+      
+
+interpretive_summary: >
+  Acts as the execution boundary between strategy decision logic and
+  exchange interaction, encapsulating trade placement, position tracking,
+  and operational mode handling. Designed to centralize execution-side
+  concerns such as fee application, position state, and environment-aware
+  behavior for live and simulated trading.
+
+invariants:
+  - Trades must only be executed when trading is explicitly enabled.
+  - Exchange-specific state must be initialized before order execution.
+  - Position and profit tracking must remain consistent with executed trades.
+  - Execution behavior must respect live versus backtest operating modes.
+
+tags:
+  domain:
+    - order_execution
+    - exchange_integration
+    - pnl_accounting
+
+  trading_function:
+    - entry_logic
+    - exit_logic
+
+  strategy_layer:
+    - execution
+
+  system_layer:
+    - service
+
+  intent:
+    - abstraction
+    - safety
+    - isolation
+
+  data_type:
+    - orders
+    - positions
+    - pnl
+    - exchanges
+
+  risk:
+    - capital_loss
+    - latency
+    - data_corruption
+
+  maturity:
+    - production