foxhunt/risk/README.md

# Risk Management Crate

## Overview

The `risk` crate is the comprehensive risk management and compliance framework for the Foxhunt High-Frequency Trading (HFT) System. It is engineered to safeguard trading operations by providing robust tools for real-time risk assessment, limit enforcement, and regulatory adherence, which are critical for maintaining stability and integrity in fast-paced trading environments.

## Features

*   **Value at Risk (VaR) Calculation**: Supports multiple models including historical simulation, parametric (e.g., variance-covariance), and Monte Carlo methods to quantify potential financial losses.
*   **Position Tracking & Limits Enforcement**: Real-time monitoring of all trading positions and strict enforcement of pre-defined limits (e.g., notional, delta, gross/net exposure).
*   **Automated Circuit Breakers**: Mechanisms to automatically pause or restrict trading activities when predefined market volatility, price movement, or risk thresholds are breached.
*   **Multi-faceted Kill Switches**: Provides immediate cessation of trading operations via local, remote, and Unix socket-based triggers for emergency risk containment.
*   **Integrated Compliance Framework**: Embeds logic to ensure adherence to critical regulatory standards such as Sarbanes-Oxley (SOX), MiFID II, and best execution principles.
*   **Drawdown Monitoring & Prevention**: Continuous monitoring of portfolio performance to detect and prevent significant declines from peak equity, triggering alerts or automated actions.
*   **Advanced Stress Testing Capabilities**: Simulates extreme market conditions and hypothetical shocks to evaluate portfolio resilience and identify vulnerabilities.
*   **Kelly Criterion Position Sizing**: Implements the Kelly criterion for optimal bet sizing, aiming to maximize long-term capital growth by dynamically adjusting trade sizes.
*   **Emergency Response Coordination**: Facilitates structured shutdown, recovery, and communication protocols during critical risk events to ensure an efficient and controlled response.

## Risk Components

The `risk` crate is composed of several specialized components working in concert to provide a holistic risk management solution:

*   **VaR Engine**: Computes Value at Risk using configurable models, providing quantitative insights into market risk.
*   **Position Limiter**: Manages and enforces exposure limits across all trading instruments and strategies, preventing concentration risks.
*   **Circuit Breaker System**: A configurable system that monitors market and internal metrics, triggering pre-defined actions upon threshold breaches.
*   **Kill Switch Module**: Offers various interfaces (local API, remote RPC, Unix socket) for immediate, system-wide trading cessation in emergency scenarios.
*   **Compliance Module**: Integrates regulatory checks and reporting capabilities for standards like SOX and MiFID II, ensuring legal and ethical trading practices.
*   **Drawdown Monitor**: Continuously tracks P&L and equity curves, alerting or acting when predefined drawdown percentages are hit.
*   **Stress Tester**: A simulation environment to subject the portfolio to historical or hypothetical extreme market events.
*   **Kelly Sizer**: Dynamically calculates optimal position sizes based on the Kelly criterion, integrating with trading strategies.
*   **Emergency Coordinator**: Orchestrates the system's response to critical events, ensuring orderly shutdowns, data preservation, and communication.

## Architecture

The `risk` crate is designed with a clear separation of concerns, integrating seamlessly with other core components of the Foxhunt system:

*   **Safety Coordinator**: Serves as the central hub for system-wide risk management. It aggregates risk signals, evaluates the overall risk posture, and orchestrates responses across the system.
*   **Position Limiter**: A dedicated component responsible for maintaining real-time tracking of all open positions and enforcing pre-configured exposure limits. It directly interfaces with the `trading_engine` to validate and potentially block orders.
*   **Trading Gate**: Acts as a critical pre-trade risk and compliance check layer. All outgoing orders from the `trading_engine` must pass through the Trading Gate for immediate validation against risk limits and regulatory rules before submission to exchanges.
*   **Integration with `trading_engine`**: Provides deep integration with the core `trading_engine` for intercepting order flow, receiving position updates, and exercising control over trade execution.
*   **Integration with `config`**: Leverages the system's `config` crate for dynamic loading, management, and hot-reloading of all risk parameters, limits, and compliance rules, ensuring flexibility and adaptability.

## Usage

To integrate the `risk` crate into your trading application:

```rust
use risk::{RiskEngine, CircuitBreaker, KillSwitch};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = /* ... load your system configuration ... */;

    // Initialize risk engine
    let risk_engine = RiskEngine::new(config).await?;

    let order = /* ... create your trade order ... */;

    // Check position limits before trade
    risk_engine.check_position_limit(&order).await?;

    // Monitor drawdown
    let current_pnl = 1000.0;
    risk_engine.monitor_drawdown(current_pnl).await?;

    Ok(())
}
```

## Testing

To run the test suite for the `risk` crate:

```bash
cargo test --package risk
```

## Documentation

For detailed API documentation, please refer to [docs.rs/risk](https://docs.rs/risk).