AgentSkillsCN

ibkr-flex-query

了解 IBKR Flex Query 的 XML 结构，并掌握其与 SegmentedTrades 的映射关系。当您需要编辑 IBKR 提取与转换逻辑、新增交易类型、调试 XML 解析，或处理 IBKR 测试用例时，可调用此技能。

SKILL.md
--- frontmatter
name: ibkr-flex-query
description: IBKR Flex Query XML structure and how it maps to SegmentedTrades. Use when editing IBKR Extract/Transform, adding transaction types, debugging XML parsing, or working with IBKR test fixtures.

IBKR Flex Query (broker-specific)

Complement to the generic pipeline-and-structure skill. This skill covers only the Interactive Brokers Flex Query format and its handling in this project.

Source and layout

  • •Input: XML files produced by IBKR Flex Queries (Activity Statement / Tax-Relevant export). Placed in imports/; discovered by IbkrBrokerageExportProvider (all *.xml in that folder).
  • •Extract: src/BrokerageExportProviders/Brokerages/IBKR/Transforms/Extract.py parses the XML into SegmentedTrades (IBKR’s implementation of CommonBrokerageEvents).
  • •Transform: Transform.py converts SegmentedTrades to a sequence of StagingFinancialGrouping (broker-agnostic).

XML structure (XPath roots)

Root path: /FlexQueryResponse/FlexStatements/FlexStatement/. Extract uses:

SectionXPathExtractorResult
Cash transactionsCashTransactions/*extractCashTransactionTransactionCash
Corporate actionsCorporateActions/*extractCorporateActionsCorporateAction
Stock tradesTrades/Trade[@assetCategory='STK']extractStockTradeTradeStock
Stock lotsTrades/Lot[@assetCategory='STK']extractStockLotLotStock
Option tradesTrades/Trade[@assetCategory='OPT']extractOptionTradeTradeDerivative
Option lotsTrades/Lot[@assetCategory='OPT']extractOptionLotLotDerivative

Elements are XML nodes with attributes; Extract reads node.attrib["..."] and maps to schemas in Schemas.py (e.g. TradeStock, LotStock, TransactionCash, CorporateAction). Parsing helpers (dates, optional values) are in ValueParsingUtils.

Schemas and types

  • •Schemas.py – Dataclasses and enums for IBKR concepts: AssetClass (STK, CASH, OPT), SubCategory, SecurityIDType, Codes (transaction notes), TradeStock, LotStock, TradeDerivative, LotDerivative, TransactionCash, CorporateAction, etc.
  • •SegmentedTrades.py – Container type: cashTransactions, corporateActions, stockTrades, stockLots, derivativeTrades, derivativeLots. This is the type returned by extractFromXML(root) and passed to merge and Transform.

Adding or changing extraction

  1. •Adjust or add XPath in extractFromXML and the corresponding extractor function.
  2. •Add or extend dataclasses in Schemas.py if new attributes or node types are needed.
  3. •Use ValueParsingUtils for optional attributes and date parsing to stay consistent with existing code.
  4. •Add or update fixtures under Brokerages/IBKR/Tests/*.xml and tests in TestIbkrExtract.py / TestIbkrTransform.py.

Test fixtures

Sample XMLs in src/BrokerageExportProviders/Brokerages/IBKR/Tests/ (e.g. SimpleStockTrade.xml, SimpleCashTransactionOfDividends.xml, SimpleOptionTrade.xml) are used by the IBKR tests. When changing Extract or schema, update or add fixtures and tests accordingly.