"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Normalization and valuation helpers for connector payloads.
The generic path is the default: any connector whose account and position rows
use the common field names is handled without a line of code here. Two
connectors ship payload shapes the generic reader cannot express and therefore
have dedicated branches:
* ``ibkr`` — the account is a tag/value ``summary`` list, and positions carry
``position``/``avg_cost`` with an IB ``sec_type``.
* ``longbridge`` — the account is a per-currency ``balances`` list, and
positions are market-suffixed symbols with a ``symbol_name``.
Inside the generic path, ``binance`` and ``okx`` additionally classify holdings
as crypto/stablecoin and quote against USDT. Futu uses its explicit
average_cost, because its securities cost_price includes realized gains.
Other connectors fall through unchanged when their field semantics match.
"""
from __future__ import annotations
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation
from typing import Any
from src.portfolio.fx import Rates, from_usd, to_usd
from src.trading.types import TradingProfile
STABLECOINS = frozenset({"USDT", "USDC", "FDUSD", "TUSD", "BUSD"})
_TRANSPORT_AUTH = {
"remote_mcp": ("OAuth", "automatic"),
"local_tws": ("Local broker session", "session"),
"broker_sdk": ("API credentials", "provider_managed"),
"local_plugin": ("Local connector", "provider_managed"),
}
def _decimal(value: Any, default: Decimal = Decimal("0")) -> Decimal:
try:
if value is None or value == "":
return default
result = Decimal(str(value))
return result if result.is_finite() else default
except (InvalidOperation, ValueError, TypeError):
return default
def _number(value: Decimal) -> float:
return float(value.quantize(Decimal("0.00000001")))
def _now() -> str:
return datetime.now(timezone.utc).isoformat()
def normalize_position(broker: str, row: dict[str, Any]) -> dict[str, Any]:
"""Convert a connector position row to the portfolio wire shape.
Args:
broker: The connector key, used only to select a dedicated payload
shape; unknown connectors take the generic path.
row: One raw position row as the connector reported it.
Returns:
A position dict in the portfolio wire shape, unpriced fields left as
``None`` rather than guessed.
"""
if broker == "ibkr":
symbol = str(row.get("symbol") or row.get("local_symbol") or "").upper()
sec_type = str(row.get("sec_type") or "STK").upper()
market_price = _decimal(row.get("market_price", row.get("current_price")))
return {
"broker": broker,
"symbol": symbol,
"quote_symbol": symbol,
"name": symbol,
"asset_type": "etf" if sec_type == "ETF" else "stock",
"market": str(row.get("exchange") or ""),
"exchange": row.get("exchange"),
"currency": str(row.get("currency") or "USD").upper(),
"quantity": _number(_decimal(row.get("position", row.get("quantity")))),
"cost_price": _number(_decimal(row.get("avg_cost", row.get("average_cost")))),
"market_price": _number(market_price) if market_price > 0 else None,
"source_market_value": row.get("market_value"),
"source_unrealized_pnl": row.get("unrealized_pnl"),
"contract_id": row.get("contract_id"),
"updated_at": _now(),
}
if broker == "longbridge":
symbol = str(row.get("symbol") or "").upper()
market = str(row.get("market") or symbol.rsplit(".", 1)[-1]).upper()
return {
"broker": broker,
"symbol": symbol,
"quote_symbol": symbol,
"name": str(row.get("symbol_name") or symbol),
"asset_type": "stock",
"market": market,
"currency": str(row.get("currency") or "USD").upper(),
"quantity": _number(_decimal(row.get("quantity"))),
"cost_price": _number(_decimal(row.get("cost_price"))),
"updated_at": _now(),
}
symbol = str(row.get("symbol") or row.get("code") or row.get("ticker") or "").upper()
source = str(row.get("source") or ("spot" if broker == "binance" else "account"))
market = str(row.get("market") or row.get("exchange") or broker).upper()
currency = str(row.get("currency") or "").upper()
if not currency:
currency = (
"HKD"
if symbol.endswith(".HK") or symbol.startswith("HK.")
else "CNY"
if symbol.startswith(("SH.", "SZ.", "BJ."))
else "USD"
)
quantity = _decimal(
row.get(
"quantity",
row.get(
"qty",
row.get(
"position",
row.get("position_qty", row.get("volume", row.get("units"))),
),
),
)
)
cost = _decimal(
row.get(
"cost_price",
row.get(
"average_cost",
row.get(
"avg_cost",
row.get(
"avg_entry_price",
row.get(
"average_price",
row.get("price_open", row.get("open_rate")),
),
),
),
),
)
)
if broker == "futu":
# Futu's cost_price is diluted by realized gains, not the remaining
# position's purchase cost. Never derive unrealized P&L from it.
# If neither average_cost nor unrealized_pl was reported, P&L stays
# unavailable; the connector still preserves both raw cost bases.
cost = _decimal(row.get("average_cost"))
market_price = _decimal(
row.get(
"market_price",
row.get("current_price", row.get("ltp", row.get("price_current"))),
)
)
source_market_value = row.get("market_value", row.get("market_val", row.get("value")))
if market_price <= 0 and quantity != 0 and _decimal(source_market_value) > 0:
market_price = abs(_decimal(source_market_value) / quantity)
sec_type = str(row.get("sec_type") or "").upper()
declared_asset_type = str(row.get("asset_type") or "").strip().lower()
crypto = broker in {"binance", "okx"} or declared_asset_type in {
"crypto",
"stablecoin",
}
asset_type = declared_asset_type or (
"stablecoin" if symbol in STABLECOINS else "crypto" if crypto else "etf" if sec_type == "ETF" else "stock"
)
return {
"broker": broker,
"symbol": symbol,
"quote_symbol": str(row.get("quote_symbol") or (f"{symbol}/USDT" if broker == "binance" else symbol)),
"name": str(
row.get("name")
or row.get("symbol_name")
or (f"{symbol} (Simple Earn)" if source == "simple_earn_flexible" else symbol)
),
"asset_type": asset_type,
"market": market,
"currency": currency,
"quantity": _number(quantity),
"cost_price": _number(cost) if cost > 0 else None,
"market_price": _number(market_price) if market_price > 0 else None,
"price_currency": str(row.get("price_currency") or currency).upper(),
"source_market_value": source_market_value,
"source_unrealized_pnl": row.get(
"unrealized_pnl",
row.get("unrealized_pl", row.get("pnl", row.get("profit"))),
),
"free": row.get("free"),
"used": row.get("used"),
"source": source,
"updated_at": _now(),
}
def value_position(row: dict[str, Any], *, rates: Rates) -> dict[str, Any]:
"""Calculate USD/CNY market value and unrealized P/L.
Args:
row: A normalized position row; it is updated in place.
rates: Currency units per USD used to convert non-USD rows. A row in a
valid ISO currency without a rate fails closed here instead of
being priced as USD.
Returns:
The same row, with ``priced``, ``market_value_usd``,
``market_value_cny`` and ``unrealized_pnl_usd`` filled in and the
connector-only fields dropped.
"""
price = _decimal(row.get("market_price"))
quantity = _decimal(row.get("quantity"))
currency = str(row.get("price_currency") or row.get("currency") or "USD").upper()
priced = price > 0
market_usd = to_usd(quantity * price, currency, rates) if priced else Decimal("0")
cost = _decimal(row.get("cost_price"))
source_pnl = row.get("source_unrealized_pnl")
pnl_usd = (
to_usd(_decimal(source_pnl), currency, rates)
if priced and source_pnl is not None
else to_usd((price - cost) * quantity, currency, rates)
if priced and cost > 0
else None
)
row.update(
priced=priced,
market_value_usd=_number(market_usd),
market_value_cny=_number(from_usd(market_usd, "CNY", rates)),
unrealized_pnl_usd=_number(pnl_usd) if pnl_usd is not None else None,
)
for key in (
"quote_symbol",
"exchange",
"source_market_value",
"source_unrealized_pnl",
"contract_id",
):
row.pop(key, None)
return row
def _to_usd(value: Decimal, currency: str, rates: Rates) -> Decimal:
return to_usd(value, currency, rates)
def account_total_usd(
broker: str,
account: dict[str, Any],
rates: Rates,
fallback: Decimal = Decimal("0"),
) -> Decimal:
"""Extract a connector-reported net liquidation value.
Args:
broker: The connector key selecting the account payload shape.
account: The raw account payload.
rates: Currency units per USD for non-USD balances.
fallback: Value returned when the connector reports no total, so a
missing figure never silently becomes zero.
Returns:
The account's total value in USD.
"""
if broker == "longbridge":
total = Decimal("0")
for row in account.get("balances", []):
total += _to_usd(
_decimal(row.get("net_assets")),
str(row.get("currency") or "USD").upper(),
rates,
)
return total
if broker == "ibkr":
candidates: dict[str, Decimal] = {}
for row in account.get("summary", []):
if str(row.get("tag") or "").lower() == "netliquidation":
currency = str(row.get("currency") or "USD").upper()
candidates[currency] = max(candidates.get(currency, Decimal("0")), _decimal(row.get("value")))
if "USD" in candidates:
return candidates["USD"]
return sum(
(_to_usd(value, currency, rates) for currency, value in candidates.items()),
Decimal("0"),
)
nested = account.get("account") if isinstance(account.get("account"), dict) else {}
currency = str(nested.get("currency") or "USD").upper()
for key in ("portfolio_value", "total_equity", "equity"):
value = _decimal(nested.get(key))
if value > 0:
return _to_usd(value, currency, rates)
total = Decimal("0")
for row in account.get("assets", []):
value = _decimal(row.get("net_liquidation", row.get("total_assets", row.get("equity"))))
total += _to_usd(value, str(row.get("currency") or currency).upper(), rates)
return total if total > 0 else fallback
def account_balance_details(broker: str, account: dict[str, Any]) -> list[dict[str, Any]]:
"""Expose reported cash legs and financing without adding them to totals.
Args:
broker: Connector whose balance schema is being read.
account: Connector-reported account payload.
Returns:
Balance disclosures in their original currencies; unavailable amounts
remain None, and negative balances retain their sign.
"""
if broker != "longbridge":
return []
def amount(value: Any) -> float | None:
parsed = _decimal(value, Decimal("NaN"))
return float(parsed) if parsed.is_finite() else None
details = []
for row in account.get("balances", []):
details.append({
"currency": row.get("currency"),
"max_finance_amount": amount(row.get("max_finance_amount")),
"remaining_finance_amount": amount(row.get("remaining_finance_amount")),
"cash_infos": [
{
"currency": cash.get("currency"),
**{key: amount(cash.get(key)) for key in (
"available_cash", "withdraw_cash", "frozen_cash", "settling_cash"
)},
}
for cash in row.get("cash_infos") or []
],
})
return details
def account_cash_usd(broker: str, account: dict[str, Any], rates: Rates) -> Decimal:
"""Return broker-reported cash without guessing from missing quotes.
Args:
broker: The connector key selecting the account payload shape.
account: The raw account payload.
rates: Currency units per USD for non-USD balances.
Returns:
Cash in USD, never negative and never inferred from an unpriced
position.
"""
rows = account.get("balances", []) if broker == "longbridge" else []
if rows:
return max(
Decimal("0"),
sum(
(
_to_usd(
_decimal(row.get("total_cash")),
str(row.get("currency") or "USD").upper(),
rates,
)
for row in rows
),
Decimal("0"),
),
)
if broker == "ibkr":
candidates: dict[str, Decimal] = {}
for row in account.get("summary", []):
if str(row.get("tag") or "").lower() in {"totalcashvalue", "cashbalance"}:
currency = str(row.get("currency") or "USD").upper()
candidates[currency] = max(candidates.get(currency, Decimal("0")), _decimal(row.get("value")))
if "USD" in candidates:
return max(Decimal("0"), candidates["USD"])
return max(
Decimal("0"),
sum(
(_to_usd(value, currency, rates) for currency, value in candidates.items()),
Decimal("0"),
),
)
nested = account.get("account") if isinstance(account.get("account"), dict) else {}
currency = str(nested.get("currency") or "USD").upper()
nested_cash = _decimal(nested.get("cash"))
if nested_cash > 0:
return _to_usd(nested_cash, currency, rates)
return max(
Decimal("0"),
sum(
(
_to_usd(
_decimal(row.get("cash", row.get("cash_balance"))),
str(row.get("currency") or currency).upper(),
rates,
)
for row in account.get("assets", [])
),
Decimal("0"),
),
)
def auth_metadata(profile: TradingProfile) -> dict[str, Any]:
"""Return public profile metadata without inferring broker-side key permissions.
Args:
profile: The connector profile backing a portfolio source.
Returns:
The authentication method, renewal model, read-only flag and the
profile's own notes.
"""
method, renewal = _TRANSPORT_AUTH.get(
profile.transport,
(profile.transport.replace("_", " ").title(), "provider_managed"),
)
return {
"method": method,
"renewal": renewal,
"readonly": profile.readonly,
"detail": profile.notes or "Read-only connector profile.",
}