aria-code 0.52.0__py3-none-any.whl

aria_code/brokers/paper_broker.py

@@ -0,0 +1,266 @@
+"""Local paper-trading broker.
+
+The paper broker implements the same BrokerBase contract as live adapters, but
+all orders are filled into a local JSON ledger. It is meant for simulation,
+strategy rehearsal, and TradingView alert dry-runs.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import AccountInfo, BrokerBase, Order, OrderResult, Position
+from .config import BROKERS_CONFIG_PATH
+
+
+PAPER_LEDGER_PATH = BROKERS_CONFIG_PATH.parent / "paper_ledger.json"
+
+
+def _now_id(prefix: str) -> str:
+    return f"{prefix}_{int(time.time() * 1000)}"
+
+
+def _load_ledger() -> Dict[str, Any]:
+    if not PAPER_LEDGER_PATH.exists():
+        return {"accounts": {}}
+    try:
+        data = json.loads(PAPER_LEDGER_PATH.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            data.setdefault("accounts", {})
+            return data
+    except Exception:
+        pass
+    return {"accounts": {}}
+
+
+def _save_ledger(data: Dict[str, Any]) -> None:
+    PAPER_LEDGER_PATH.parent.mkdir(parents=True, exist_ok=True)
+    PAPER_LEDGER_PATH.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+class PaperBroker(BrokerBase):
+    broker_type = "paper"
+    broker_name = "Aria Paper Broker"
+    market = "GLOBAL"
+
+    def __init__(self, broker_id: str, config: Dict[str, Any]):
+        super().__init__(broker_id, config)
+        self.currency = str(config.get("currency", "USD") or "USD").upper()
+        self.starting_cash = float(config.get("starting_cash", 100000.0) or 100000.0)
+
+    def connect(self) -> bool:
+        ledger = _load_ledger()
+        accounts = ledger.setdefault("accounts", {})
+        if self.broker_id not in accounts:
+            accounts[self.broker_id] = {
+                "broker_id": self.broker_id,
+                "label": self.label,
+                "currency": self.currency,
+                "starting_cash": self.starting_cash,
+                "cash": self.starting_cash,
+                "positions": {},
+                "orders": [],
+                "created_at": int(time.time()),
+            }
+            _save_ledger(ledger)
+        self._connected = True
+        return True
+
+    def ping(self) -> bool:
+        """Real liveness probe: the local ledger account must exist."""
+        try:
+            return self.broker_id in (_load_ledger().get("accounts") or {})
+        except Exception:
+            return False
+
+    def reset(self, starting_cash: float | None = None, currency: str | None = None) -> None:
+        ledger = _load_ledger()
+        accounts = ledger.setdefault("accounts", {})
+        cash = float(starting_cash if starting_cash is not None else self.starting_cash)
+        curr = str(currency or self.currency).upper()
+        accounts[self.broker_id] = {
+            "broker_id": self.broker_id,
+            "label": self.label,
+            "currency": curr,
+            "starting_cash": cash,
+            "cash": cash,
+            "positions": {},
+            "orders": [],
+            "created_at": int(time.time()),
+        }
+        _save_ledger(ledger)
+        self.currency = curr
+        self.starting_cash = cash
+        self._connected = True
+
+    def _account(self) -> Dict[str, Any]:
+        if not self._connected:
+            self.connect()
+        ledger = _load_ledger()
+        return ledger.setdefault("accounts", {}).setdefault(self.broker_id, {
+            "broker_id": self.broker_id,
+            "label": self.label,
+            "currency": self.currency,
+            "starting_cash": self.starting_cash,
+            "cash": self.starting_cash,
+            "positions": {},
+            "orders": [],
+        })
+
+    def _save_account(self, account: Dict[str, Any]) -> None:
+        ledger = _load_ledger()
+        ledger.setdefault("accounts", {})[self.broker_id] = account
+        _save_ledger(ledger)
+
+    def account_info(self) -> AccountInfo:
+        account = self._account()
+        positions = self._positions_from_account(account)
+        market_value = sum(p.market_value for p in positions)
+        cost_basis = sum(p.cost_price * p.quantity for p in positions)
+        pnl_total = market_value - cost_basis
+        cash = float(account.get("cash", 0.0) or 0.0)
+        return AccountInfo(
+            broker_id=self.broker_id,
+            broker_type=self.broker_type,
+            label=self.label,
+            account_id=f"PAPER-{self.broker_id}",
+            currency=str(account.get("currency", self.currency)),
+            total_assets=cash + market_value,
+            cash=cash,
+            market_value=market_value,
+            pnl_total=pnl_total,
+            pnl_pct=(pnl_total / cost_basis * 100) if cost_basis > 0 else 0.0,
+            extra={"mode": "paper", "ledger_path": str(PAPER_LEDGER_PATH)},
+        )
+
+    def positions(self) -> List[Position]:
+        return self._positions_from_account(self._account())
+
+    def _positions_from_account(self, account: Dict[str, Any]) -> List[Position]:
+        out: List[Position] = []
+        for symbol, raw in sorted((account.get("positions") or {}).items()):
+            qty = float(raw.get("quantity", 0.0) or 0.0)
+            if qty <= 0:
+                continue
+            price = float(raw.get("current_price", raw.get("cost_price", 0.0)) or 0.0)
+            cost = float(raw.get("cost_price", 0.0) or 0.0)
+            market_value = qty * price
+            pnl = (price - cost) * qty
+            out.append(Position(
+                symbol=symbol,
+                name=symbol,
+                quantity=qty,
+                available_qty=qty,
+                cost_price=cost,
+                current_price=price,
+                market_value=market_value,
+                pnl=pnl,
+                pnl_pct=(pnl / (cost * qty) * 100) if cost > 0 and qty > 0 else 0.0,
+                currency=str(account.get("currency", self.currency)),
+                market="paper",
+            ))
+        return out
+
+    def orders(self, status: str = "all", limit: int = 50) -> List[Order]:
+        raw_orders = list(self._account().get("orders") or [])
+        raw_orders = list(reversed(raw_orders))[: max(0, int(limit or 50))]
+        out: List[Order] = []
+        for raw in raw_orders:
+            mapped = str(raw.get("status", "filled"))
+            if status != "all" and mapped != status:
+                continue
+            out.append(Order(
+                order_id=str(raw.get("order_id", "")),
+                symbol=str(raw.get("symbol", "")),
+                name=str(raw.get("symbol", "")),
+                side=str(raw.get("side", "")),
+                order_type=str(raw.get("order_type", "")),
+                quantity=float(raw.get("quantity", 0.0) or 0.0),
+                filled_qty=float(raw.get("filled_qty", raw.get("quantity", 0.0)) or 0.0),
+                price=float(raw.get("price", 0.0) or 0.0),
+                avg_price=float(raw.get("avg_price", raw.get("price", 0.0)) or 0.0),
+                status=mapped,
+                created_at=str(raw.get("created_at", "")),
+                currency=str(raw.get("currency", self.currency)),
+            ))
+        return out
+
+    def place_order(
+        self,
+        symbol: str,
+        side: str,
+        quantity: float,
+        order_type: str = "limit",
+        price: float = 0.0,
+        **kwargs: Any,
+    ) -> OrderResult:
+        symbol = str(symbol or "").strip().upper()
+        side = str(side or "").lower()
+        qty = float(quantity or 0.0)
+        if not symbol:
+            return OrderResult(False, message="symbol is required", broker_id=self.broker_id)
+        if side not in ("buy", "sell"):
+            return OrderResult(False, message="side must be buy or sell", broker_id=self.broker_id)
+        if qty <= 0:
+            return OrderResult(False, message="quantity must be positive", broker_id=self.broker_id)
+
+        account = self._account()
+        positions = account.setdefault("positions", {})
+        pos = dict(positions.get(symbol) or {})
+        current_price = float(price or pos.get("current_price", pos.get("cost_price", 0.0)) or 0.0)
+        if current_price <= 0:
+            return OrderResult(False, message="paper order requires a positive price", broker_id=self.broker_id)
+
+        cash = float(account.get("cash", 0.0) or 0.0)
+        notional = qty * current_price
+        existing_qty = float(pos.get("quantity", 0.0) or 0.0)
+        existing_cost = float(pos.get("cost_price", current_price) or current_price)
+
+        if side == "buy":
+            if notional > cash:
+                return OrderResult(False, message="paper cash insufficient", broker_id=self.broker_id)
+            new_qty = existing_qty + qty
+            new_cost = ((existing_qty * existing_cost) + notional) / new_qty if new_qty > 0 else current_price
+            pos.update({"quantity": new_qty, "cost_price": new_cost, "current_price": current_price})
+            account["cash"] = cash - notional
+            positions[symbol] = pos
+        else:
+            if qty > existing_qty:
+                return OrderResult(False, message="paper position insufficient", broker_id=self.broker_id)
+            new_qty = existing_qty - qty
+            account["cash"] = cash + notional
+            if new_qty <= 0:
+                positions.pop(symbol, None)
+            else:
+                pos.update({"quantity": new_qty, "cost_price": existing_cost, "current_price": current_price})
+                positions[symbol] = pos
+
+        order_id = _now_id("paper")
+        account.setdefault("orders", []).append({
+            "order_id": order_id,
+            "symbol": symbol,
+            "side": side,
+            "order_type": order_type,
+            "quantity": qty,
+            "filled_qty": qty,
+            "price": current_price,
+            "avg_price": current_price,
+            "status": "filled",
+            "created_at": int(time.time()),
+            "currency": str(account.get("currency", self.currency)),
+        })
+        self._save_account(account)
+        return OrderResult(True, order_id=order_id, message="paper order filled", broker_id=self.broker_id)
+
+
+def reset_paper_account(broker_id: str = "paper_main", starting_cash: float = 100000.0, currency: str = "USD") -> None:
+    PaperBroker(broker_id, {
+        "id": broker_id,
+        "type": "paper",
+        "label": "Aria 仿盘账户",
+        "starting_cash": starting_cash,
+        "currency": currency,
+    }).reset(starting_cash=starting_cash, currency=currency)

aria_code/brokers/planning.py

@@ -0,0 +1,296 @@
+"""Broker-aware portfolio snapshot, order planning, and risk gates.
+
+This module intentionally does not place orders. It converts strategy output or
+user order intent into an auditable plan that a human must approve first.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional
+
+from .base import AccountInfo, Position
+
+
+@dataclass(frozen=True)
+class PortfolioSnapshot:
+    broker_id: str
+    broker_label: str
+    currency: str
+    total_assets: float
+    cash: float
+    market_value: float
+    positions: List[Position] = field(default_factory=list)
+
+    def position_for(self, symbol: str) -> Optional[Position]:
+        sym = (symbol or "").upper()
+        for pos in self.positions:
+            if (pos.symbol or "").upper() == sym:
+                return pos
+        return None
+
+    def current_weight(self, symbol: str) -> float:
+        if self.total_assets <= 0:
+            return 0.0
+        pos = self.position_for(symbol)
+        return float(pos.market_value / self.total_assets) if pos else 0.0
+
+
+@dataclass(frozen=True)
+class StrategyIntent:
+    symbol: str
+    action: str = "hold"  # buy | sell | hold | rebalance
+    target_weight: Optional[float] = None
+    confidence: Optional[float] = None
+    reason: str = ""
+    source: str = "manual"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RiskRuleSet:
+    max_single_position_weight: float = 0.20
+    min_cash_reserve_weight: float = 0.02
+    max_order_value_weight: float = 0.10
+    allow_short: bool = False
+    allow_fractional: bool = False
+
+
+@dataclass(frozen=True)
+class PlannedOrder:
+    symbol: str
+    side: str
+    quantity: float
+    order_type: str
+    price: float
+    estimated_value: float
+
+
+@dataclass(frozen=True)
+class OrderPlan:
+    symbol: str
+    action: str
+    current_weight: float
+    target_weight: float
+    current_quantity: float
+    estimated_price: float
+    estimated_order: Optional[PlannedOrder]
+    cash_before: float
+    cash_after: float
+    requires_approval: bool
+    reason: str = ""
+    source: str = "manual"
+    risk: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "action": self.action,
+            "current_weight": round(self.current_weight, 6),
+            "target_weight": round(self.target_weight, 6),
+            "current_quantity": self.current_quantity,
+            "estimated_price": self.estimated_price,
+            "estimated_order": self.estimated_order.__dict__ if self.estimated_order else None,
+            "cash_before": round(self.cash_before, 4),
+            "cash_after": round(self.cash_after, 4),
+            "requires_approval": self.requires_approval,
+            "reason": self.reason,
+            "source": self.source,
+            "risk": self.risk,
+        }
+
+
+def _as_float(value: Any, default: float = 0.0) -> float:
+    try:
+        out = float(value)
+        return out if math.isfinite(out) else default
+    except Exception:
+        return default
+
+
+def snapshot_from_broker(broker: Any) -> PortfolioSnapshot:
+    account: AccountInfo = broker.account_info()
+    positions = list(broker.positions() or [])
+    return PortfolioSnapshot(
+        broker_id=getattr(broker, "broker_id", ""),
+        broker_label=getattr(broker, "label", getattr(broker, "broker_id", "")),
+        currency=account.currency,
+        total_assets=_as_float(account.total_assets),
+        cash=_as_float(account.cash),
+        market_value=_as_float(account.market_value),
+        positions=positions,
+    )
+
+
+def infer_intent_from_backtest(result: Dict[str, Any], target_weight: Optional[float] = None) -> StrategyIntent:
+    total_return = _as_float(result.get("total_return"))
+    alpha = _as_float(result.get("alpha"))
+    max_dd = _as_float(result.get("max_drawdown"))
+    symbol = str(result.get("symbol", "")).upper()
+    if target_weight is None:
+        if total_return > 0 and alpha >= 0:
+            target_weight = 0.10
+        elif total_return > 0:
+            target_weight = 0.05
+        else:
+            target_weight = 0.0
+    action = "rebalance" if target_weight > 0 else "sell"
+    confidence = max(0.0, min(1.0, 0.5 + alpha - abs(max_dd) * 0.25))
+    return StrategyIntent(
+        symbol=symbol,
+        action=action,
+        target_weight=target_weight,
+        confidence=round(confidence, 4),
+        reason=f"backtest total={total_return:.2%}, alpha={alpha:.2%}, max_dd={max_dd:.2%}",
+        source="backtest",
+        metadata={
+            "strategy": result.get("strategy"),
+            "report_path": result.get("report_path"),
+            "total_return": result.get("total_return"),
+            "alpha": result.get("alpha"),
+            "max_drawdown": result.get("max_drawdown"),
+        },
+    )
+
+
+def _resolve_price(symbol: str, explicit_price: Optional[float], snapshot: PortfolioSnapshot) -> float:
+    price = _as_float(explicit_price)
+    if price > 0:
+        return price
+    pos = snapshot.position_for(symbol)
+    return _as_float(pos.current_price if pos else 0.0)
+
+
+def plan_order(
+    snapshot: PortfolioSnapshot,
+    intent: StrategyIntent,
+    price: Optional[float] = None,
+    quantity: Optional[float] = None,
+    order_type: str = "limit",
+    rules: Optional[RiskRuleSet] = None,
+) -> OrderPlan:
+    rules = rules or RiskRuleSet()
+    symbol = intent.symbol.upper()
+    current_pos = snapshot.position_for(symbol)
+    current_qty = _as_float(current_pos.quantity if current_pos else 0.0)
+    resolved_price = _resolve_price(symbol, price, snapshot)
+    current_weight = snapshot.current_weight(symbol)
+    target_weight = current_weight
+    if intent.target_weight is not None:
+        target_weight = max(0.0 if not rules.allow_short else -1.0, _as_float(intent.target_weight))
+
+    if quantity is not None:
+        qty = _as_float(quantity)
+        side = "buy" if intent.action in ("buy", "rebalance") else "sell"
+    else:
+        if resolved_price <= 0 or snapshot.total_assets <= 0:
+            qty = 0.0
+            side = "hold"
+        else:
+            target_value = snapshot.total_assets * target_weight
+            current_value = snapshot.total_assets * current_weight
+            delta_value = target_value - current_value
+            side = "buy" if delta_value > 0 else "sell" if delta_value < 0 else "hold"
+            qty = abs(delta_value) / resolved_price
+
+    if not rules.allow_fractional:
+        qty = math.floor(qty)
+    if side == "sell":
+        qty = min(qty, max(current_qty, 0.0))
+
+    estimated_value = max(qty, 0.0) * max(resolved_price, 0.0)
+    order = None
+    cash_after = snapshot.cash
+    if side in ("buy", "sell") and qty > 0 and resolved_price > 0:
+        order = PlannedOrder(
+            symbol=symbol,
+            side=side,
+            quantity=qty,
+            order_type=order_type,
+            price=resolved_price,
+            estimated_value=estimated_value,
+        )
+        cash_after = snapshot.cash - estimated_value if side == "buy" else snapshot.cash + estimated_value
+
+    plan = OrderPlan(
+        symbol=symbol,
+        action=intent.action,
+        current_weight=current_weight,
+        target_weight=target_weight,
+        current_quantity=current_qty,
+        estimated_price=resolved_price,
+        estimated_order=order,
+        cash_before=snapshot.cash,
+        cash_after=cash_after,
+        requires_approval=order is not None,
+        reason=intent.reason,
+        source=intent.source,
+    )
+    risk = evaluate_risk(plan, snapshot, rules)
+    return OrderPlan(**{**plan.__dict__, "risk": risk})
+
+
+def evaluate_risk(plan: OrderPlan, snapshot: PortfolioSnapshot, rules: Optional[RiskRuleSet] = None) -> Dict[str, Any]:
+    rules = rules or RiskRuleSet()
+    violations: List[str] = []
+    warnings: List[str] = []
+    order = plan.estimated_order
+    total_assets = max(snapshot.total_assets, 0.0)
+    if total_assets <= 0:
+        violations.append("账户总资产不可用，无法评估仓位")
+    if plan.target_weight > rules.max_single_position_weight:
+        violations.append(f"目标单票仓位 {plan.target_weight:.1%} 超过上限 {rules.max_single_position_weight:.1%}")
+    if order and order.side == "buy":
+        if order.estimated_value > snapshot.cash:
+            violations.append("可用现金不足")
+        reserve = total_assets * rules.min_cash_reserve_weight
+        if plan.cash_after < reserve:
+            warnings.append(f"交易后现金低于保留比例 {rules.min_cash_reserve_weight:.1%}")
+    projected_position_value = 0.0
+    projected_position_weight = 0.0
+    if order and total_assets > 0:
+        current_value = total_assets * plan.current_weight
+        if order.side == "buy":
+            projected_position_value = current_value + order.estimated_value
+        else:
+            projected_position_value = max(0.0, current_value - order.estimated_value)
+        projected_position_weight = projected_position_value / total_assets
+        if projected_position_weight > rules.max_single_position_weight:
+            violations.append(
+                f"成交后单票仓位 {projected_position_weight:.1%} 超过上限 {rules.max_single_position_weight:.1%}"
+            )
+    if order and total_assets > 0 and order.estimated_value / total_assets > rules.max_order_value_weight:
+        warnings.append(f"单笔订单金额超过账户 {rules.max_order_value_weight:.1%}")
+    if order and order.side == "sell" and order.quantity > plan.current_quantity and not rules.allow_short:
+        violations.append("卖出数量超过当前持仓，且未允许做空")
+    return {
+        "passed": not violations,
+        "requires_manual_review": bool(warnings or violations),
+        "violations": violations,
+        "warnings": warnings,
+        "rules": {
+            "max_single_position_weight": rules.max_single_position_weight,
+            "min_cash_reserve_weight": rules.min_cash_reserve_weight,
+            "max_order_value_weight": rules.max_order_value_weight,
+            "allow_short": rules.allow_short,
+            "allow_fractional": rules.allow_fractional,
+        },
+        "projected_position_weight": round(projected_position_weight, 6),
+    }
+
+
+def plans_from_strategy_results(
+    snapshot: PortfolioSnapshot,
+    results: Iterable[Dict[str, Any]],
+    rules: Optional[RiskRuleSet] = None,
+) -> List[OrderPlan]:
+    plans: List[OrderPlan] = []
+    for result in results:
+        intent = infer_intent_from_backtest(result)
+        last_price = None
+        curve = result.get("equity_curve") or []
+        if curve and isinstance(curve[-1], dict):
+            last_price = curve[-1].get("close")
+        plans.append(plan_order(snapshot, intent, price=last_price, rules=rules))
+    return plans