Code Explorer

"""Beginner-friendly capital / fee / compounding example calculations.

Paper trading and simulation only -- see src/capital/__init__.py. Every
number here is computed live from the same Decimal formulas the real
capital engine uses (position sizing = risk_amount / stop_distance,
cost = notional * rate, compounding = previous_equity + net_pnl) -- nothing
in this module is a hand-typed example figure. These are illustrative,
deterministic example calculations for education (win/loss trade math,
fee and compounding demonstrations), not a report of real observed paper
trading results and never a promise of a specific outcome.
"""
from __future__ import annotations

from decimal import Decimal

from pydantic import BaseModel

from src.capital.decimal_math import to_decimal

DEFAULT_RISK_COMPARISON_FRACTIONS: list[Decimal] = [Decimal("0.005"), Decimal("0.01"), Decimal("0.02")]


class TradeExample(BaseModel):
    """One illustrative trade: sizing, modelled costs, and the resulting
    next-equity figure for either a target-hit (win) or stop-hit (loss)."""

    label: str
    outcome: str  # "win" | "loss"
    starting_equity: Decimal
    risk_fraction: Decimal
    risk_amount: Decimal
    stop_distance_fraction: Decimal
    target_distance_fraction: Decimal
    r_multiple: Decimal
    notional_value: Decimal
    entry_fee: Decimal
    exit_fee: Decimal
    slippage_total: Decimal
    total_costs: Decimal
    gross_pnl: Decimal
    net_pnl: Decimal
    next_equity: Decimal


class CostAssumptions(BaseModel):

DEFAULT_DAILY_LOSS_LIMIT_FRACTION = Decimal("0.02")
DEFAULT_WEEKLY_LOSS_LIMIT_FRACTION = Decimal("0.05")
DEFAULT_MAX_DRAWDOWN_GATE_FRACTION = Decimal("0.10")


class DecimalModel(BaseModel):
    """Base class for models with Decimal fields. Pydantic v2 already
    serialises Decimal as a JSON string by default (never as a JSON
    number/float, which would silently reintroduce binary floating-point
    error at the API boundary) -- this class exists as a single, explicit
    place documenting that guarantee for every model that inherits it."""


class CapitalConfig(DecimalModel):
    """Research configuration for one simulation run. Every limit here is a
    ceiling the engine enforces, not a target to size up to. All monetary
    fields are USD -- see SYSTEM_CURRENCY."""

    initial_usd: Decimal = Decimal("2000.00")
    risk_fraction: Decimal = DEFAULT_RISK_FRACTION
    max_risk_fraction: Decimal = MAX_RISK_FRACTION
    max_active_observations: int = DEFAULT_MAX_ACTIVE_OBSERVATIONS
    max_total_open_risk_fraction: Decimal = DEFAULT_MAX_TOTAL_OPEN_RISK_FRACTION
    min_cash_reserve_fraction: Decimal = DEFAULT_MIN_CASH_RESERVE_FRACTION
    daily_loss_limit_fraction: Decimal = DEFAULT_DAILY_LOSS_LIMIT_FRACTION
    weekly_loss_limit_fraction: Decimal = DEFAULT_WEEKLY_LOSS_LIMIT_FRACTION

"""Governance gate: blocks a candidate from ever reaching the capital
engine unless it has already cleared the governed research pipeline.

Paper trading and simulation only -- see src/capital/__init__.py.

This module does not implement source governance, semantic validation,
deduplication, or freshness checking itself -- those live upstream (the
research pipeline in src/research_terminal, src/market_analysis,
src/extraction). It only refuses to let a candidate through if its
upstream-assigned status says it hasn't passed. No strategy may call
run_paper_observation() directly without going through this gate first.
"""
from __future__ import annotations

from dataclasses import dataclass

# Statuses that must never be allowed to open a paper observation, exactly
# as named in the mission. A candidate carrying any of these in either its
# data_quality_status or semantic_status field is blocked here, before the
# capital engine (position sizing, risk limits, ledger) ever sees it.
BLOCKED_STATUSES = {
    "DATA_STALE",
    "SEMANTIC_REVIEW_REQUIRED",
    "NO_GOVERNED_SETUP",
    "RISK_LIMIT_BLOCKED",
    "CAPITAL_TOO_SMALL_FOR_VALID_SIZE",
}

"""FastAPI routes for the capital-compounding engine.

Paper trading and simulation only -- see src/capital/__init__.py. Every
mutating route here requires an authenticated ADMIN session plus CSRF,
exactly like the rest of the research terminal API. No response body in
this file ever contains a session ID, CSRF token, cookie, MFA value, or
private key -- capital_schemas.py has no field for any of those.
"""
from __future__ import annotations

import json
from decimal import Decimal

from fastapi import APIRouter, HTTPException, Query, Request

from capital_schemas import (
    CapitalConfigResponse,
    CapitalEducationResponse,
    CapitalSequenceResponse,
    CapitalStatusResponse,
    CapitalSummaryResponse,
    CompoundingComparisonResponse,
    CompoundingModeComparisonRow,
    LedgerRowResponse,
    PaperObservationEvaluateRequest,
    PaperObservationEvaluateResponse,
    RiskStateResponse,
)
from src.capital import risk_limits
from src.capital.compounding import calculate_drawdown_fraction
from src.capital.education import CostAssumptions, calculate_trade_example, risk_comparison_table, trade_sequence_example
from src.capital.models import CapitalConfig, CompoundingMode, LedgerRow
from src.paper_execution.cost_model import DEFAULT_MAKER_FEE_RATE
from src.capital.sequence_ledger import SequenceLedger
from src.config import resolve_path
from src.paper_execution.observation_engine import EquityState, run_paper_observation
from src.research_terminal.api import _require_csrf, _require_session

router = APIRouter(prefix="/api/v1/capital")

#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

#[cfg(not(target_os = "macos"))]
use keyring::Entry;
use reqwest::header::{HeaderMap, HeaderValue, CONTENT_TYPE};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::path::{Path, PathBuf};
use std::process::Command as StdCommand;
use std::sync::Arc;
use tauri::{AppHandle, Emitter, State};
use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::process::{Child, Command};
use tokio::sync::Mutex;

const KEYRING_SERVICE: &str = "OVResearchDesktop";
const KEYRING_USERNAME: &str = "desktop-session";
const BACKEND_PORT: u16 = 8766;
const LOG_PREVIEW_LIMIT: usize = 20;