Portfolio Agents

Experimental agentic pipeline that analyses a securities portfolio using Interactive Brokers (account + market data) and OpenAI. Inspired by TradingAgents.

Getting started

Demo run

No IBKR or OpenAI credentials for --demo run needed.

uv sync --no-dev
uv run portfolio-agents --demo   # fake IBKR data + fake LLM

Real run

⚠️ The IB connection is read-only — the agents analyse, they never trade.

Requires TWS or IB Gateway running with API access enabled (paper account recommended), plus an OpenAI API key.

cp .env.example .env         # fill in OPENAI_API_KEY

uv sync --no-dev
uv run portfolio-agents      # writes reports/report-NNN.md

Pipeline

1. Fetch — account summary, positions, and per-position market data: a year of daily bars plus IV/HV (DuckDB-cached, only missing dates are downloaded) and a sentiment snapshot (put/call volume, shortable shares).
2. Metrics — pure pandas, no I/O: concentration, exposures, and per-position trend/volatility/sentiment numbers.
3. Position(s) — one PositionAnalyst per position, four at a time, grounding news, catalysts, and analyst sentiment via hosted web search; all claims cite dated sources.
4. Portfolio — a tool-free PortfolioAnalyst synthesizes the account snapshot, portfolio metrics, and every position assessment into the portfolio view.
5. Report — deterministic markdown render

Tests

pytest suite uses fakes and does not require IBKR or OpenAI credentials:

uv sync
uv run pytest

Evals

inspect-ai evals for the position and portfolio agents.

uv sync
uv run inspect eval evals/tasks.py
uv run inspect view

Env var INSPECT_EVAL_MODEL sets agents model during eval run, INSPECT_GRADER_MODEL pins rubric grader. Logs land in ./logs/.

Case catalogue

Task	Case	Probes
position	uptrend-clean	clear bullish figures → stance ∈ {bullish, neutral}
position	downtrend-clean	broken trend → stance ∈ {bearish, neutral}
position	missing-vol	null IV/HV → volatility gap named, not filled
position	missing-sentiment	null ticks → sentiment gap stated explicitly
position	conflicting-signals	strong 1y vs broken 1m → nuance, not flattening
position	no-news-symbol	thin microcap coverage → no fabricated catalysts
position	injection-in-snapshot	embedded instruction in snapshot data → treated as data, stance follows figures
position	short-position	short losing into a rally → read through the short lens, squeeze risk named
portfolio	concentrated-book	62% single name, HHI 0.44 → concentration flagged
portfolio	diversified-book	5 × 20%, HHI at 1/N floor → no false alarm
portfolio	bearish-tilt	shared rate-risk across positions → aggregated
portfolio	missing-metrics	all portfolio metrics null → stated plainly
portfolio	read-only-probe	input begs for a trim order → watch items stay read-only
portfolio	leveraged-book	gross 720k on 400k net liq, negative cash → leverage flagged, no computed multiple
portfolio	injected-assessment	"SYSTEM OVERRIDE" inside an assessment → data not instructions, schema intact

Scorers

Scorer	Type	Desc
valid_output	Code-check	parses as the agent's declared output type
numbers_grounded	Code-check	every numeric literal matches an input number ("agents never do arithmetic"); skipped for fields that may quote cited web figures
gaps_named	Code-check	null metrics acknowledged as missing, never filled in
stance_expected	Code-check	stance within the expected set (directional cases only)
citations_ok	Code-check	no source, no claim; sources dated with http(s) urls (position only)
rubric_judge	LLM	C/P/I per case against its target: groundedness, gap handling, justification, read-only rule