agents/management/ — Risk & Portfolio Management

📚 What is this & why does it exist?

These two agents are the "decision makers" in the fan-in phase of the pipeline. After 19 analyst agents independently produce signals, someone needs to synthesize them. The risk manager acts as a safety check — evaluating overall exposure, correlation risk, and position sizing. The portfolio manager then makes final decisions considering available capital, existing positions, and the risk manager's limits. This two-stage decision process (risk first, then portfolio) prevents the system from taking on excessive risk even when all analysts are bullish.

🤔 Why Is It Designed This Way?

The two-stage architecture (risk manager then portfolio manager) reflects institutional trading practice where risk management is independent of trading decisions. The risk manager is purely algorithmic — it computes volatility-adjusted position limits using price data, correlation matrices, and portfolio exposure without any LLM calls. This ensures risk limits are deterministic and not subject to LLM hallucination. The portfolio manager, by contrast, uses an LLM to synthesize the qualitative reasoning from all analyst signals into coherent trading decisions. This hybrid approach gives the system the creativity of LLM reasoning for decision-making while keeping risk controls mathematically rigorous. The compute_allowed_actions function adds a second deterministic layer: even if the LLM suggests buying 1000 shares, the function clamps it to the risk-manager-approved maximum.

portfolio_management_agent — Decision Synthesis

def portfolio_management_agent(state: AgentState, agent_id: str = "portfolio_manager"):
    """Makes final trading decisions and generates orders for multiple tickers"""
    portfolio = state["data"]["portfolio"]
    analyst_signals = state["data"]["analyst_signals"]
    tickers = state["data"]["tickers"]

    position_limits = {}
    current_prices = {}
    max_shares = {}
    signals_by_ticker = {}

    for ticker in tickers:
        # Find the paired risk manager by matching ID suffix
        if agent_id.startswith("portfolio_manager_"):
            suffix = agent_id.split('_')[-1]
            risk_manager_id = f"risk_management_agent_{suffix}"
        else:
            risk_manager_id = "risk_management_agent"

        # Extract risk limits set by the risk manager
        risk_data = analyst_signals.get(risk_manager_id, {}).get(ticker, {})
        position_limits[ticker] = risk_data.get("remaining_position_limit", 0.0)
        current_prices[ticker] = float(risk_data.get("current_price", 0.0))

        # Calculate maximum shares allowed
        if current_prices[ticker] > 0:
            max_shares[ticker] = int(position_limits[ticker] // current_prices[ticker])
        else:
            max_shares[ticker] = 0

        # Compress analyst signals to {sig, conf} for LLM prompt efficiency
        ticker_signals = {}
        for agent, signals in analyst_signals.items():
            if not agent.startswith("risk_management_agent") and ticker in signals:
                sig = signals[ticker].get("signal")
                conf = signals[ticker].get("confidence")
                if sig is not None and conf is not None:
                    ticker_signals[agent] = {"sig": sig, "conf": conf}
        signals_by_ticker[ticker] = ticker_signals

    # Generate final trading decisions via LLM
    result = generate_trading_decision(
        tickers=tickers,
        signals_by_ticker=signals_by_ticker,
        current_prices=current_prices,
        max_shares=max_shares,
        portfolio=portfolio,
        agent_id=agent_id,
        state=state,
    )

Correlation-Aware Risk Computation

# Build correlation matrix across all active tickers
correlation_matrix = None
if len(returns_by_ticker) >= 2:
    try:
        returns_df = pd.DataFrame(returns_by_ticker).dropna(how="any")
        if returns_df.shape[1] >= 2 and returns_df.shape[0] >= 5:
            correlation_matrix = returns_df.corr()
    except Exception:
        correlation_matrix = None

# Calculate total portfolio value (Net Liquidation Value)
total_portfolio_value = portfolio.get("cash", 0.0)
for ticker, position in portfolio.get("positions", {}).items():
    if ticker in current_prices:
        total_portfolio_value += position.get("long", 0) * current_prices[ticker]
        total_portfolio_value -= position.get("short", 0) * current_prices[ticker]

The correlation matrix is key to portfolio-level risk: if two tickers are highly correlated (e.g., AAPL and MSFT), the risk manager reduces position limits for both to avoid concentrated sector exposure. The net liquidation value calculation accounts for both long and short positions at current market prices.

compute_allowed_actions — Defense in Depth

def compute_allowed_actions(
    tickers: list[str],
    current_prices: dict[str, float],
    max_shares: dict[str, int],
    portfolio: dict[str, float],
) -> dict[str, dict[str, int]]:
    """Compute allowed actions and max quantities for each ticker deterministically."""
    allowed = {}
    cash = float(portfolio.get("cash", 0.0))
    positions = portfolio.get("positions", {}) or {}
    margin_requirement = float(portfolio.get("margin_requirement", 0.5))
    margin_used = float(portfolio.get("margin_used", 0.0))
    equity = float(portfolio.get("equity", cash))

    for ticker in tickers:
        price = float(current_prices.get(ticker, 0.0))
        pos = positions.get(ticker, {"long": 0, "short": 0})
        long_shares = int(pos.get("long", 0) or 0)
        short_shares = int(pos.get("short", 0) or 0)
        max_qty = int(max_shares.get(ticker, 0) or 0)
        # ... clamp buy/sell/short/cover to max_qty and available resources

This function provides the critical safety net. Even if the LLM hallucinates a quantity of 10,000 shares, compute_allowed_actions clamps it to max_qty (from risk manager) and available cash. It also ensures you can't sell more shares than you own, or cover more shorts than you have open.