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