Capital Allocation Agent

Risk governor for the QuantTradingOS modular trading system. Constrains position sizing, enforces risk limits, and gates trade eligibility. Does not generate trade signals, alpha, or entry/exit recommendations.

Part of the QuantTradingOS ecosystem — see organization overview for related agents and frameworks.

---

Table of Contents

• Responsibilities
• Architecture
• Upstream Dependencies
• Downstream Consumers
• Input / Output
• Installation
• Quick Start
• Project Structure
• Requirements
• Engineering Constraints
• Style & Philosophy

---

Responsibilities

• Risk Budgeting — Allocate risk capital across open and prospective positions
• Position Sizing — Compute maximum position size per trade given portfolio constraints
• Regime Adjustment — Scale risk parameters based on detected market regime
• Drawdown Controls — Reduce or halt risk-taking when drawdown thresholds are breached
• Execution Gating — Incorporate execution discipline scores into allocation decisions
• Decision Output — Emit structured allocation decisions (allow/deny, multipliers, reason codes)

---

Architecture

                    ┌─────────────────────────┐
                    │  Market Regime Agent    │ ◄── Regime classification
                    └───────────┬─────────────┘
                                │
┌─────────────────────────┐     │     ┌─────────────────────────────┐
│ Portfolio Analyst Agent │─────┼────►│   Capital Allocation Agent   │
└─────────────────────────┘     │     └──────────────┬──────────────┘
                                │                    │
┌─────────────────────────┐     │                    │ Allocation decision
│Execution Discipline Agent│────┘                    ▼
└─────────────────────────┘              ┌──────────────────────────┐
                                         │ Execution Engine /       │
                                         │ Strategy Agents          │
                                         └──────────────────────────┘

The Capital Allocation Agent governs risk by evaluating rules in strict order (base rules → regime adjustments → drawdown controls) and producing allow/deny decisions with risk bounds. Style: institutional, conservative, auditable. Clarity over cleverness.

---

Upstream Dependencies

The Capital Allocation Agent consumes outputs from three upstream agents. Each must be run or queried before allocation decisions are made.

Agent	Purpose	Outputs Used
Market Regime Agent	Classifies current market regime	regime, confidence — used for regime multipliers
Portfolio Analyst Agent	Supplies portfolio metrics	PnL, portfolio_heat, drawdown, exposure — used for risk limits
Execution Discipline Agent	Evaluates execution compliance	compliance_score (0–1) — used for trade gating

Integration Notes

• Market Regime Agent: Provides regime (e.g., trending, ranging, volatile) and confidence. Regime multipliers in config.yaml scale base risk accordingly.
• Portfolio Analyst Agent: Provides portfolio_metrics including drawdown, portfolio_heat, and exposure. Drawdown thresholds trigger risk reduction or halt.
• Execution Discipline Agent: Provides a compliance score (0.0–1.0). Trades are gated when score is below min_execution_score in config.

---

Downstream Consumers

Consumer	Purpose
Execution Engine	Receives allocation decisions to size and route orders; respects allow_trade, position_size_multiplier, max_risk_per_trade
Strategy Agents	Use risk_mode and position_size_multiplier to constrain signal generation and sizing

---

Input / Output

Input Schema

Inputs conform to schemas/inputs.json:

Field	Source Agent	Description
market_regime	Market Regime Agent	regime, confidence
portfolio_metrics	Portfolio Analyst Agent	current_pnl, portfolio_heat, drawdown, open_positions, total_exposure
execution_discipline_score	Execution Discipline Agent	Compliance score 0.0–1.0

Output Schema

Outputs conform to schemas/outputs.json:

Field	Description
risk_mode	normal | reduced | halt | emergency
max_risk_per_trade	Maximum risk (fraction or dollar) allowed per new trade
position_size_multiplier	Multiplier applied to base position size (0–1)
allow_trade	Boolean — allow or deny new trade execution
reason	Human-readable explanation for the decision

---

Installation

Prerequisites

• Python 3.10+
• No external dependencies (standard library only)

Setup

1. Clone the repository

   git clone https://github.com/QuantTradingOS/Capital-Allocation-Agent.git
   cd Capital-Allocation-Agent

2. Run tests (optional)

   pip install pytest
   pytest tests/ -v

---

Quick Start

from agent import CapitalAllocationAgent

agent = CapitalAllocationAgent(config_path="config.yaml")

# Load inputs from upstream agents
inputs = {
    "market_regime": {"regime": "trending", "confidence": 0.85},
    "portfolio_metrics": {
        "current_pnl": 12500.0,
        "portfolio_heat": 0.12,
        "drawdown": 0.02,
        "open_positions": 5,
        "total_exposure": 450000.0,
    },
    "execution_discipline_score": 0.92,
}
# Option 1: Fail-closed pipeline (recommended for production)
decision = agent.decide(inputs)

# Option 2: Step-by-step (raises on invalid inputs)
agent.load_inputs(inputs)
agent.apply_rules()
decision = agent.generate_decision()

# {'risk_mode': '...', 'max_risk_per_trade': ..., 'position_size_multiplier': ..., 'allow_trade': ..., 'reason': '...'}

See examples/sample_run.py for a basic example and examples/orchestration_example.py for integration with Market Regime Agent and Portfolio Analyst Agent outputs.

---

Project Structure

Capital-Allocation-Agent/
├── README.md
├── agent.py              # CapitalAllocationAgent orchestrator
├── config.yaml           # Risk parameters, drawdown thresholds, regime multipliers
├── schemas/
│   ├── inputs.json       # JSON schema for inputs
│   └── outputs.json      # JSON schema for outputs
├── rules/
│   ├── base_rules.py     # Core risk limits, portfolio heat, execution gating
│   ├── regime_adjustments.py  # Regime-based scaling
│   └── drawdown_controls.py   # Drawdown-threshold logic
├── examples/
│   └── sample_run.py     # Example invocation with mock data
└── tests/
    └── test_allocation_logic.py

---

Requirements

• Python 3.10+
• Standard library only — no external dependencies for core logic
• Optional: pytest for running tests

---

Engineering Constraints

Constraint	Description
Python 3.10+	Required for union syntax and typing.
No external dependencies	Uses only stdlib (json, pathlib, typing).
Clear docstrings	All public functions document intent, not just implementation.
Deterministic	Same inputs always produce same outputs; no randomness.
Fail closed	Invalid inputs or errors produce deny-risk decisions (allow_trade=False, max_risk=0) rather than raising. Use decide(inputs) for fail-closed behavior.

---

Style & Philosophy

Principle	Description
Risk governor, not signal generator	Constrains and gates risk. Does not generate trade signals, alpha, or entry/exit recommendations.
Institutional, conservative, auditable	Explicit rule order, full variable names, clear logic flow. Easy to trace and audit.
Clarity over cleverness	Prefer readable, straightforward code. No dense one-liners or shortcuts.

---

Related Agents

Agent	Role
Capital Guardian Agent	Pre-execution risk governor; complementary focus on drawdown, regime, and psychology
Market Regime Agent	Regime classification — upstream input
Portfolio Analyst Agent	Portfolio metrics — upstream input
Execution Discipline Agent	Execution compliance score — upstream input

---

Built for QuantTradingOS — risk governor, not signal generator. Institutional, conservative, auditable.