AUTHOR: Tony Mudau

Portfolio Agent Concept

This document explains how portfolio_agent works conceptually and how it influences trade proposals.

Purpose

portfolio_agent is the portfolio-aware decision layer between signal generation and risk shaping.

It takes a candidate proposal and evaluates it against:

• current portfolio exposure
• recent trade history
• 1-week recent candle behavior for the selected symbol
• LLM guidance with an aggressive growth objective (targeting portfolio growth)

Its output is either:

• adjusted proposal (accepted), or
• rejection (None) if portfolio constraints fail.

Inputs

• symbol
• proposal from upstream signal logic
• portfolio snapshot (balance/equity/margin/open positions)
• market_context (from market agent)
• technical_signal (from technical agent)
• weekly_df (1-week candle window prepared by orchestration)

End-to-End Flow

1. Trade history summary

   • Reads recent scheduled/executed trade records from DB.
   • Produces compact stats:
     • executed/failed/pending counts
     • buy vs sell share
     • execution rate
     • recent symbol activity

2. Weekly candle summary

   • Computes short-term behavior from weekly candle set:
     • weekly return
     • range ratio
     • trend label (up/down/flat)

3. LLM portfolio suggestion

   • Prompts LLM with:
     • current portfolio state
     • technical + market context
     • trade history summary
     • weekly candle summary
   • Requests strict JSON:
     • action (buy/sell/hold)
     • confidence_adjustment
     • aggressiveness_multiplier
     • rationale
   • Fallback is deterministic if LLM is unavailable.

4. Exposure gate

   • Rejects if too many same-symbol positions already exist.

5. Proposal adjustment

   • Optionally override direction when LLM strongly signals aggressive conviction.
   • Adjust proposal confidence by bounded LLM adjustment.
   • Attach portfolio_analysis block for explainability.

Output Contract

Accepted proposals include portfolio_analysis with:

• growth objective label
• same-symbol exposure count
• trade history summary
• weekly candle summary
• LLM suggestion and rationale

If rejected, decision is logged with reason and context.

Design Intent

• Growth-focused but bounded: uses aggressive objective while keeping hard portfolio gates.
• Explainable: every adjustment includes structured context for frontend and audit trail.
• Composable: runs before risk_agent and validation_agent, so later agents still enforce lot sizing and final approval.

Role in Orchestration

In orchestration_agent, portfolio_agent is called after initial proposal and LLM reviewer, and before risk shaping:

1. select symbol
2. build proposal
3. portfolio-aware adjustment/rejection (portfolio_agent)
4. lot/risk shape (risk_agent)
5. final approve/reject (validation_agent)
6. execute/schedule (execution_agent)