feat: portfolio manager data foundation — docs, SQL migration, and module scaffolding
Co-authored-by: aguzererler <6199053+aguzererler@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
29e75384cc
commit
f1cabe7a4a
|
|
@ -0,0 +1,245 @@
|
||||||
|
# Portfolio Manager Agent — Design Overview
|
||||||
|
|
||||||
|
<!-- Last verified: 2026-03-20 -->
|
||||||
|
|
||||||
|
## Feature Description
|
||||||
|
|
||||||
|
The Portfolio Manager Agent (PMA) is an autonomous agent that manages a simulated
|
||||||
|
investment portfolio end-to-end. It performs the following actions in sequence:
|
||||||
|
|
||||||
|
1. **Initiates market research** — triggers the existing `ScannerGraph` to produce a
|
||||||
|
macro watchlist of top candidate tickers.
|
||||||
|
2. **Initiates per-ticker analysis** — feeds scan results into the existing
|
||||||
|
`MacroBridge` / `TradingAgentsGraph` pipeline for high-conviction candidates.
|
||||||
|
3. **Loads current holdings** — queries the Supabase database for the active portfolio
|
||||||
|
state (positions, cash balance, sector weights).
|
||||||
|
4. **Requests lightweight holding reviews** — for each existing holding, runs a
|
||||||
|
quick `HoldingReviewerAgent` (quick_think) that checks price action and recent
|
||||||
|
news — no full bull/bear debate needed.
|
||||||
|
5. **Computes portfolio-level risk metrics** — pure Python, no LLM:
|
||||||
|
Sharpe ratio, Sortino ratio, beta, 95 % VaR, max drawdown, sector concentration,
|
||||||
|
correlation matrix, and what-if buy/sell scenarios.
|
||||||
|
6. **Makes allocation decisions** — the Portfolio Manager Agent (deep_think +
|
||||||
|
memory) reads all inputs and outputs a structured JSON with sells, buys, holds,
|
||||||
|
target cash %, and detailed rationale.
|
||||||
|
7. **Executes mock trades** — validates decisions against constraints, records trades
|
||||||
|
in Supabase, updates holdings, and takes an immutable snapshot.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Decision: Supabase (PostgreSQL) + Filesystem
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ Supabase (PostgreSQL) │
|
||||||
|
│ │
|
||||||
|
│ portfolios holdings trades snapshots │
|
||||||
|
│ │
|
||||||
|
│ "What do I own right now?" │
|
||||||
|
│ "What trades did I make?" │
|
||||||
|
│ "What was my portfolio value on date X?" │
|
||||||
|
└────────────────────┬────────────────────────────┘
|
||||||
|
│ report_path column
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ Filesystem (reports/) │
|
||||||
|
│ │
|
||||||
|
│ reports/daily/{date}/ │
|
||||||
|
│ market/ ← scan output │
|
||||||
|
│ {TICKER}/ ← per-ticker analysis │
|
||||||
|
│ portfolio/ │
|
||||||
|
│ holdings_review.json │
|
||||||
|
│ risk_metrics.json │
|
||||||
|
│ pm_decision.json │
|
||||||
|
│ pm_decision.md (human-readable) │
|
||||||
|
│ │
|
||||||
|
│ "Why did I decide this?" │
|
||||||
|
│ "What was the macro context?" │
|
||||||
|
│ "What did the risk model say?" │
|
||||||
|
└─────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rationale:**
|
||||||
|
|
||||||
|
| Concern | Storage | Why |
|
||||||
|
|---------|---------|-----|
|
||||||
|
| Transactional integrity (trades) | Supabase | ACID, foreign keys, row-level security |
|
||||||
|
| Fast portfolio queries (weights, cash) | Supabase | SQL aggregations |
|
||||||
|
| LLM reports (large text, markdown) | Filesystem | Avoids bloating the DB |
|
||||||
|
| Agent memory / rationale | Filesystem | Easy to inspect and version |
|
||||||
|
| Audit trail of decisions | Filesystem | Markdown readable by humans |
|
||||||
|
|
||||||
|
The `report_path` column in the `portfolios` table points to the daily portfolio
|
||||||
|
subdirectory on disk: `reports/daily/{date}/portfolio/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5-Phase Workflow
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 1 (parallel) │
|
||||||
|
│ │
|
||||||
|
│ 1a. ScannerGraph.scan(date) 1b. Load Holdings + Fetch Prices │
|
||||||
|
│ → macro_scan_summary.json → List[Holding] with │
|
||||||
|
│ watchlist of top candidates current_price, current_value │
|
||||||
|
└───────────────────────────────────┬───────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 2 (parallel) │
|
||||||
|
│ │
|
||||||
|
│ 2a. New Candidate Analysis 2b. Holding Re-evaluation │
|
||||||
|
│ MacroBridge.run_all_tickers() HoldingReviewerAgent (quick_think)│
|
||||||
|
│ Full bull/bear pipeline per 7-day price + 3-day news │
|
||||||
|
│ HIGH/MEDIUM conviction → JSON: signal/confidence/reason │
|
||||||
|
│ candidates that are NOT urgency per holding │
|
||||||
|
│ already held │
|
||||||
|
└───────────────────────────────────┬───────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 3 (Python, no LLM) │
|
||||||
|
│ │
|
||||||
|
│ Risk Metrics Computation │
|
||||||
|
│ • Sharpe ratio (annualised, rf = 0) │
|
||||||
|
│ • Sortino ratio (downside deviation) │
|
||||||
|
│ • Portfolio beta (vs SPY) │
|
||||||
|
│ • 95 % VaR (historical simulation, 30-day window) │
|
||||||
|
│ • Max drawdown (peak-to-trough, 90-day window) │
|
||||||
|
│ • Sector concentration (weight per GICS sector) │
|
||||||
|
│ • Correlation matrix (all holdings) │
|
||||||
|
│ • What-if scenarios (buy X, sell Y → new weights) │
|
||||||
|
└───────────────────────────────────┬───────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 4 Portfolio Manager Agent (deep_think + memory) │
|
||||||
|
│ │
|
||||||
|
│ Reads: macro context, holdings, candidate signals, re-eval signals, │
|
||||||
|
│ risk metrics, budget constraint, past decisions (memory) │
|
||||||
|
│ │
|
||||||
|
│ Outputs structured JSON: │
|
||||||
|
│ { │
|
||||||
|
│ "sells": [{"ticker": "X", "shares": 10, "reason": "..."}], │
|
||||||
|
│ "buys": [{"ticker": "Y", "shares": 5, "reason": "..."}], │
|
||||||
|
│ "holds": ["Z"], │
|
||||||
|
│ "target_cash_pct": 0.08, │
|
||||||
|
│ "rationale": "...", │
|
||||||
|
│ "risk_summary": "..." │
|
||||||
|
│ } │
|
||||||
|
└───────────────────────────────────┬───────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 5 Trade Execution (Mock) │
|
||||||
|
│ │
|
||||||
|
│ • Validate decisions against constraints (position size, sector, cash) │
|
||||||
|
│ • Record each trade in Supabase (trades table) │
|
||||||
|
│ • Update holdings (avg cost basis, shares) │
|
||||||
|
│ • Deduct / credit cash balance │
|
||||||
|
│ • Take immutable portfolio snapshot │
|
||||||
|
│ • Save PM decision + risk report to filesystem │
|
||||||
|
└────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Specifications
|
||||||
|
|
||||||
|
### Portfolio Manager Agent (PMA)
|
||||||
|
|
||||||
|
| Property | Value |
|
||||||
|
|----------|-------|
|
||||||
|
| LLM tier | `deep_think` |
|
||||||
|
| Memory | Enabled — reads previous PM decision files from filesystem |
|
||||||
|
| Output format | Structured JSON (validated before trade execution) |
|
||||||
|
| Invocation | Once per run, after Phases 1–3 |
|
||||||
|
|
||||||
|
**Prompt inputs:**
|
||||||
|
- Macro scan summary (top candidates + context)
|
||||||
|
- Current holdings list (ticker, shares, avg cost, current price, weight, sector)
|
||||||
|
- Candidate analysis signals (BUY/SELL/HOLD per ticker from Phase 2a)
|
||||||
|
- Holding review signals (signal, confidence, reason, urgency per holding from Phase 2b)
|
||||||
|
- Risk metrics report (Phase 3 output)
|
||||||
|
- Budget constraint (available cash)
|
||||||
|
- Portfolio constraints (see below)
|
||||||
|
- Previous decision (last PM decision file for memory continuity)
|
||||||
|
|
||||||
|
### Holding Reviewer Agent
|
||||||
|
|
||||||
|
| Property | Value |
|
||||||
|
|----------|-------|
|
||||||
|
| LLM tier | `quick_think` |
|
||||||
|
| Memory | Disabled |
|
||||||
|
| Output format | Structured JSON |
|
||||||
|
| Tools | `get_stock_data` (7-day window), `get_news` (3-day window), RSI, MACD |
|
||||||
|
| Invocation | Once per existing holding (parallelisable) |
|
||||||
|
|
||||||
|
**Output schema per holding:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"ticker": "AAPL",
|
||||||
|
"signal": "HOLD",
|
||||||
|
"confidence": 0.72,
|
||||||
|
"reason": "Price action neutral; no material news. RSI 52, MACD flat.",
|
||||||
|
"urgency": "LOW"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PM Agent Constraints
|
||||||
|
|
||||||
|
These constraints are **hard limits** enforced during Phase 5 (trade execution).
|
||||||
|
The PM Agent is also instructed to respect them in its prompt.
|
||||||
|
|
||||||
|
| Constraint | Value |
|
||||||
|
|------------|-------|
|
||||||
|
| Max position size | 15 % of portfolio value |
|
||||||
|
| Max sector exposure | 35 % of portfolio value |
|
||||||
|
| Min cash reserve | 5 % of portfolio value |
|
||||||
|
| Max number of positions | 15 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PM Risk Management Rules
|
||||||
|
|
||||||
|
These rules trigger specific actions and are part of the PM Agent's system prompt:
|
||||||
|
|
||||||
|
| Trigger | Action |
|
||||||
|
|---------|--------|
|
||||||
|
| Portfolio beta > 1.3 | Reduce cyclical / high-beta positions |
|
||||||
|
| Sector exposure > 35 % | Diversify — sell smallest position in that sector |
|
||||||
|
| Sharpe ratio < 0.5 | Raise cash — reduce overall exposure |
|
||||||
|
| Max drawdown > 15 % | Go defensive — reduce equity allocation |
|
||||||
|
| Daily 95 % VaR > 3 % | Reduce position sizes to lower tail risk |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10-Phase Implementation Roadmap
|
||||||
|
|
||||||
|
| Phase | Deliverable | Effort |
|
||||||
|
|-------|-------------|--------|
|
||||||
|
| 1 | Data foundation (this PR) — models, DB, filesystem, repository | ~2–3 days |
|
||||||
|
| 2 | Holding Reviewer Agent | ~1 day |
|
||||||
|
| 3 | Risk metrics engine (Phase 3 of workflow) | ~1–2 days |
|
||||||
|
| 4 | Portfolio Manager Agent (LLM, structured output) | ~2 days |
|
||||||
|
| 5 | Trade execution engine (Phase 5 of workflow) | ~1 day |
|
||||||
|
| 6 | Full orchestration graph (LangGraph) tying all phases | ~2 days |
|
||||||
|
| 7 | CLI command `pm run` | ~0.5 days |
|
||||||
|
| 8 | End-to-end integration tests | ~1 day |
|
||||||
|
| 9 | Performance tuning + concurrency (Phase 2 parallelism) | ~1 day |
|
||||||
|
| 10 | Documentation, memory system update, PR review | ~0.5 days |
|
||||||
|
|
||||||
|
**Total estimate: ~15–22 days**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- `tradingagents/pipeline/macro_bridge.py` — existing scan → per-ticker bridge
|
||||||
|
- `tradingagents/report_paths.py` — filesystem path conventions
|
||||||
|
- `tradingagents/default_config.py` — config pattern to follow
|
||||||
|
- `tradingagents/agents/scanners/` — scanner agent examples
|
||||||
|
- `tradingagents/graph/scanner_setup.py` — parallel graph node patterns
|
||||||
|
|
@ -0,0 +1,352 @@
|
||||||
|
# Phase 1 Implementation Plan — Data Foundation
|
||||||
|
|
||||||
|
<!-- Last verified: 2026-03-20 -->
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Build the data foundation layer for the Portfolio Manager feature.
|
||||||
|
|
||||||
|
After Phase 1 you should be able to:
|
||||||
|
- Create and retrieve portfolios
|
||||||
|
- Manage holdings (add, update, remove) with correct avg-cost-basis accounting
|
||||||
|
- Record mock trades
|
||||||
|
- Take immutable portfolio snapshots
|
||||||
|
- Save and load all report types (scans, analysis, holding reviews, risk, PM decisions)
|
||||||
|
- Pass a 90 %+ test coverage gate on all new modules
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
tradingagents/portfolio/
|
||||||
|
├── __init__.py ← public exports
|
||||||
|
├── models.py ← Portfolio, Holding, Trade, PortfolioSnapshot dataclasses
|
||||||
|
├── config.py ← PORTFOLIO_CONFIG dict + helpers
|
||||||
|
├── exceptions.py ← domain exception hierarchy
|
||||||
|
├── supabase_client.py ← Supabase CRUD wrapper
|
||||||
|
├── report_store.py ← Filesystem document storage
|
||||||
|
├── repository.py ← Unified data-access façade (Supabase + filesystem)
|
||||||
|
└── migrations/
|
||||||
|
└── 001_initial_schema.sql
|
||||||
|
|
||||||
|
tests/portfolio/
|
||||||
|
├── __init__.py
|
||||||
|
├── conftest.py ← shared fixtures
|
||||||
|
├── test_models.py
|
||||||
|
├── test_report_store.py
|
||||||
|
└── test_repository.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 1 — Data Models (`models.py`)
|
||||||
|
|
||||||
|
**Estimated effort:** 2–3 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
Four dataclasses fully type-annotated:
|
||||||
|
|
||||||
|
- `Portfolio`
|
||||||
|
- `Holding`
|
||||||
|
- `Trade`
|
||||||
|
- `PortfolioSnapshot`
|
||||||
|
|
||||||
|
Each class must implement:
|
||||||
|
- `to_dict() -> dict` — serialise for DB / JSON
|
||||||
|
- `from_dict(data: dict) -> Self` — deserialise from DB / JSON
|
||||||
|
- `enrich(**kwargs)` — attach runtime-computed fields (prices, weights, P&L)
|
||||||
|
|
||||||
|
### Field Specifications
|
||||||
|
|
||||||
|
See `docs/portfolio/02_data_models.md` for full field tables.
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- All fields have explicit Python type annotations
|
||||||
|
- `to_dict()` → `from_dict()` round-trip is lossless for all fields
|
||||||
|
- `enrich()` correctly computes `current_value`, `unrealized_pnl`, `unrealized_pnl_pct`, `weight`
|
||||||
|
- 100 % line coverage in `test_models.py`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 2 — Portfolio Config (`config.py`)
|
||||||
|
|
||||||
|
**Estimated effort:** 1 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
```python
|
||||||
|
PORTFOLIO_CONFIG: dict # all tunable parameters
|
||||||
|
get_portfolio_config() -> dict # returns merged config (defaults + env overrides)
|
||||||
|
validate_config(cfg: dict) # raises ValueError on invalid values
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
All are optional and default to the values shown:
|
||||||
|
|
||||||
|
| Env Var | Default | Description |
|
||||||
|
|---------|---------|-------------|
|
||||||
|
| `SUPABASE_URL` | `""` | Supabase project URL |
|
||||||
|
| `SUPABASE_KEY` | `""` | Supabase anon/service key |
|
||||||
|
| `PORTFOLIO_DATA_DIR` | `"reports"` | Root dir for filesystem reports |
|
||||||
|
| `PM_MAX_POSITIONS` | `15` | Max number of open positions |
|
||||||
|
| `PM_MAX_POSITION_PCT` | `0.15` | Max single-position weight |
|
||||||
|
| `PM_MAX_SECTOR_PCT` | `0.35` | Max sector weight |
|
||||||
|
| `PM_MIN_CASH_PCT` | `0.05` | Minimum cash reserve |
|
||||||
|
| `PM_DEFAULT_BUDGET` | `100000.0` | Default starting cash (USD) |
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- All env vars read with `os.getenv`, defaulting gracefully when unset
|
||||||
|
- `validate_config` raises `ValueError` for `max_position_pct > 1.0`,
|
||||||
|
`min_cash_pct < 0`, `max_positions < 1`, etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 3 — Supabase Migration (`migrations/001_initial_schema.sql`)
|
||||||
|
|
||||||
|
**Estimated effort:** 1–2 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
A single idempotent SQL file (`CREATE TABLE IF NOT EXISTS`) that creates:
|
||||||
|
|
||||||
|
- `portfolios` table
|
||||||
|
- `holdings` table
|
||||||
|
- `trades` table
|
||||||
|
- `snapshots` table
|
||||||
|
- All CHECK constraints
|
||||||
|
- All FOREIGN KEY constraints
|
||||||
|
- All indexes (PK + query-path indexes)
|
||||||
|
- `updated_at` trigger function + triggers on portfolios, holdings
|
||||||
|
|
||||||
|
See `docs/portfolio/03_database_schema.md` for full schema.
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- File runs without error on a fresh Supabase PostgreSQL database
|
||||||
|
- All tables created with correct column types and constraints
|
||||||
|
- `updated_at` auto-updates on every row modification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 4 — Supabase Client (`supabase_client.py`)
|
||||||
|
|
||||||
|
**Estimated effort:** 3–4 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
`SupabaseClient` class (singleton pattern) with:
|
||||||
|
|
||||||
|
**Portfolio CRUD**
|
||||||
|
- `create_portfolio(portfolio: Portfolio) -> Portfolio`
|
||||||
|
- `get_portfolio(portfolio_id: str) -> Portfolio`
|
||||||
|
- `list_portfolios() -> list[Portfolio]`
|
||||||
|
- `update_portfolio(portfolio: Portfolio) -> Portfolio`
|
||||||
|
- `delete_portfolio(portfolio_id: str) -> None`
|
||||||
|
|
||||||
|
**Holdings CRUD**
|
||||||
|
- `upsert_holding(holding: Holding) -> Holding`
|
||||||
|
- `get_holding(portfolio_id: str, ticker: str) -> Holding | None`
|
||||||
|
- `list_holdings(portfolio_id: str) -> list[Holding]`
|
||||||
|
- `delete_holding(portfolio_id: str, ticker: str) -> None`
|
||||||
|
|
||||||
|
**Trades**
|
||||||
|
- `record_trade(trade: Trade) -> Trade`
|
||||||
|
- `list_trades(portfolio_id: str, limit: int = 100) -> list[Trade]`
|
||||||
|
|
||||||
|
**Snapshots**
|
||||||
|
- `save_snapshot(snapshot: PortfolioSnapshot) -> PortfolioSnapshot`
|
||||||
|
- `get_latest_snapshot(portfolio_id: str) -> PortfolioSnapshot | None`
|
||||||
|
- `list_snapshots(portfolio_id: str, limit: int = 30) -> list[PortfolioSnapshot]`
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
All methods translate Supabase/HTTP errors into domain exceptions (see Task below).
|
||||||
|
Methods that query a single row raise `PortfolioNotFoundError` when no row is found.
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- Singleton — only one Supabase connection per process
|
||||||
|
- All public methods fully type-annotated
|
||||||
|
- Supabase integration tests auto-skip when `SUPABASE_URL` is unset
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 5 — Report Store (`report_store.py`)
|
||||||
|
|
||||||
|
**Estimated effort:** 3–4 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
`ReportStore` class with typed save/load methods for each report type:
|
||||||
|
|
||||||
|
| Method | Description |
|
||||||
|
|--------|-------------|
|
||||||
|
| `save_scan(date, data)` | Save macro scan JSON |
|
||||||
|
| `load_scan(date)` | Load macro scan JSON |
|
||||||
|
| `save_analysis(date, ticker, data)` | Save per-ticker analysis report |
|
||||||
|
| `load_analysis(date, ticker)` | Load per-ticker analysis report |
|
||||||
|
| `save_holding_review(date, ticker, data)` | Save holding reviewer output |
|
||||||
|
| `load_holding_review(date, ticker)` | Load holding reviewer output |
|
||||||
|
| `save_risk_metrics(date, portfolio_id, data)` | Save risk computation output |
|
||||||
|
| `load_risk_metrics(date, portfolio_id)` | Load risk computation output |
|
||||||
|
| `save_pm_decision(date, portfolio_id, data)` | Save PM agent decision JSON + MD |
|
||||||
|
| `load_pm_decision(date, portfolio_id)` | Load PM agent decision JSON |
|
||||||
|
| `list_pm_decisions(portfolio_id)` | List all saved PM decision paths |
|
||||||
|
|
||||||
|
### Directory Convention
|
||||||
|
|
||||||
|
```
|
||||||
|
reports/daily/{date}/
|
||||||
|
├── market/
|
||||||
|
│ └── macro_scan_summary.json ← save_scan / load_scan
|
||||||
|
├── {TICKER}/
|
||||||
|
│ └── complete_report.md ← save_analysis / load_analysis (existing)
|
||||||
|
└── portfolio/
|
||||||
|
├── {TICKER}_holding_review.json ← save_holding_review / load_holding_review
|
||||||
|
├── {portfolio_id}_risk_metrics.json
|
||||||
|
├── {portfolio_id}_pm_decision.json
|
||||||
|
└── {portfolio_id}_pm_decision.md (human-readable version)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- Directories created automatically on first write
|
||||||
|
- `load_*` returns `None` when the file doesn't exist (no exception)
|
||||||
|
- JSON serialisation uses `json.dumps(indent=2)`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 6 — Repository (`repository.py`)
|
||||||
|
|
||||||
|
**Estimated effort:** 4–5 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
`PortfolioRepository` class — unified façade over `SupabaseClient` + `ReportStore`.
|
||||||
|
|
||||||
|
**Key business logic:**
|
||||||
|
|
||||||
|
```
|
||||||
|
add_holding(portfolio_id, ticker, shares, price):
|
||||||
|
existing = client.get_holding(portfolio_id, ticker)
|
||||||
|
if existing:
|
||||||
|
new_avg_cost = (existing.avg_cost * existing.shares + price * shares)
|
||||||
|
/ (existing.shares + shares)
|
||||||
|
holding.shares += shares
|
||||||
|
holding.avg_cost = new_avg_cost
|
||||||
|
else:
|
||||||
|
holding = Holding(ticker=ticker, shares=shares, avg_cost=price, ...)
|
||||||
|
portfolio.cash -= shares * price # deduct cash
|
||||||
|
client.upsert_holding(holding)
|
||||||
|
client.update_portfolio(portfolio) # persist cash change
|
||||||
|
|
||||||
|
remove_holding(portfolio_id, ticker, shares, price):
|
||||||
|
existing = client.get_holding(portfolio_id, ticker)
|
||||||
|
if existing.shares < shares:
|
||||||
|
raise InsufficientSharesError(...)
|
||||||
|
if shares == existing.shares:
|
||||||
|
client.delete_holding(portfolio_id, ticker)
|
||||||
|
else:
|
||||||
|
existing.shares -= shares
|
||||||
|
client.upsert_holding(existing)
|
||||||
|
portfolio.cash += shares * price # credit proceeds
|
||||||
|
client.update_portfolio(portfolio)
|
||||||
|
```
|
||||||
|
|
||||||
|
All DB operations execute as a logical unit (best-effort; full Supabase transactions
|
||||||
|
require PG functions — deferred to Phase 3+).
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- `add_holding` correctly updates avg cost basis on repeated buys
|
||||||
|
- `remove_holding` raises `InsufficientSharesError` when shares would go negative
|
||||||
|
- `add_holding` raises `InsufficientCashError` when cash < `shares * price`
|
||||||
|
- Repository integration tests auto-skip when `SUPABASE_URL` is unset
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 7 — Package Setup
|
||||||
|
|
||||||
|
**Estimated effort:** 1 h
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
1. `tradingagents/portfolio/__init__.py` — export public symbols
|
||||||
|
2. `pyproject.toml` — add `supabase>=2.0.0` to dependencies
|
||||||
|
3. `.env.example` — add new env vars (`SUPABASE_URL`, `SUPABASE_KEY`, `PM_*`)
|
||||||
|
4. `tradingagents/default_config.py` — merge `PORTFOLIO_CONFIG` into `DEFAULT_CONFIG`
|
||||||
|
under a `"portfolio"` key (non-breaking addition)
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
|
||||||
|
- `from tradingagents.portfolio import PortfolioRepository` works after install
|
||||||
|
- `pip install -e ".[dev]"` succeeds with the new dependency
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 8 — Tests
|
||||||
|
|
||||||
|
**Estimated effort:** 3–4 h
|
||||||
|
|
||||||
|
### Test List
|
||||||
|
|
||||||
|
**`test_models.py`**
|
||||||
|
- `test_portfolio_to_dict_round_trip`
|
||||||
|
- `test_holding_to_dict_round_trip`
|
||||||
|
- `test_trade_to_dict_round_trip`
|
||||||
|
- `test_snapshot_to_dict_round_trip`
|
||||||
|
- `test_holding_enrich_computes_current_value`
|
||||||
|
- `test_holding_enrich_computes_unrealized_pnl`
|
||||||
|
- `test_holding_enrich_computes_weight`
|
||||||
|
- `test_holding_enrich_handles_zero_cost`
|
||||||
|
|
||||||
|
**`test_report_store.py`**
|
||||||
|
- `test_save_and_load_scan`
|
||||||
|
- `test_save_and_load_analysis`
|
||||||
|
- `test_save_and_load_holding_review`
|
||||||
|
- `test_save_and_load_risk_metrics`
|
||||||
|
- `test_save_and_load_pm_decision_json`
|
||||||
|
- `test_load_returns_none_for_missing_file`
|
||||||
|
- `test_list_pm_decisions`
|
||||||
|
- `test_directories_created_on_write`
|
||||||
|
|
||||||
|
**`test_repository.py`** (Supabase tests skip when `SUPABASE_URL` unset)
|
||||||
|
- `test_add_holding_new_position`
|
||||||
|
- `test_add_holding_updates_avg_cost`
|
||||||
|
- `test_remove_holding_full_position`
|
||||||
|
- `test_remove_holding_partial_position`
|
||||||
|
- `test_remove_holding_raises_insufficient_shares`
|
||||||
|
- `test_add_holding_raises_insufficient_cash`
|
||||||
|
- `test_record_and_list_trades`
|
||||||
|
- `test_save_and_load_snapshot`
|
||||||
|
|
||||||
|
### Coverage Target
|
||||||
|
|
||||||
|
90 %+ for `models.py` and `report_store.py`.
|
||||||
|
Integration tests (`test_repository.py`) auto-skip when Supabase is unavailable.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution Order
|
||||||
|
|
||||||
|
```
|
||||||
|
Day 1 (parallel tracks)
|
||||||
|
Track A: Task 1 (models) → Task 3 (SQL migration)
|
||||||
|
Track B: Task 2 (config) → Task 7 (package setup partial)
|
||||||
|
|
||||||
|
Day 2 (parallel tracks)
|
||||||
|
Track A: Task 4 (SupabaseClient)
|
||||||
|
Track B: Task 5 (ReportStore)
|
||||||
|
|
||||||
|
Day 3
|
||||||
|
Task 6 (Repository)
|
||||||
|
Task 8 (Tests)
|
||||||
|
Task 7 (package setup final — pyproject.toml, .env.example)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Total estimate: ~18–24 hours**
|
||||||
|
|
@ -0,0 +1,230 @@
|
||||||
|
# Data Models — Full Specification
|
||||||
|
|
||||||
|
<!-- Last verified: 2026-03-20 -->
|
||||||
|
|
||||||
|
All models live in `tradingagents/portfolio/models.py` as Python `dataclass` types.
|
||||||
|
They must be fully type-annotated and support lossless `to_dict` / `from_dict`
|
||||||
|
round-trips.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `Portfolio`
|
||||||
|
|
||||||
|
Represents a single managed portfolio (one user may eventually have multiple).
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| `portfolio_id` | `str` | Yes | UUID, primary key |
|
||||||
|
| `name` | `str` | Yes | Human-readable name, e.g. "Main Portfolio" |
|
||||||
|
| `cash` | `float` | Yes | Available cash balance in USD |
|
||||||
|
| `initial_cash` | `float` | Yes | Starting capital (immutable after creation) |
|
||||||
|
| `currency` | `str` | Yes | ISO 4217 code, default `"USD"` |
|
||||||
|
| `created_at` | `str` | Yes | ISO-8601 UTC datetime string |
|
||||||
|
| `updated_at` | `str` | Yes | ISO-8601 UTC datetime string |
|
||||||
|
| `report_path` | `str \| None` | No | Filesystem path to today's portfolio report dir |
|
||||||
|
| `metadata` | `dict` | No | Free-form JSON for agent notes / tags |
|
||||||
|
|
||||||
|
### Computed / Derived Fields (not stored in DB)
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `total_value` | `float` | `cash` + sum of all holding `current_value` |
|
||||||
|
| `equity_value` | `float` | sum of all holding `current_value` |
|
||||||
|
| `cash_pct` | `float` | `cash / total_value` |
|
||||||
|
|
||||||
|
### Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
"""Serialise all stored fields to a flat dict suitable for JSON / Supabase insert."""
|
||||||
|
|
||||||
|
def from_dict(cls, data: dict) -> "Portfolio":
|
||||||
|
"""Deserialise from a DB row or JSON dict. Missing optional fields default gracefully."""
|
||||||
|
|
||||||
|
def enrich(self, holdings: list["Holding"]) -> "Portfolio":
|
||||||
|
"""Compute total_value, equity_value, cash_pct from the provided holdings list."""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `Holding`
|
||||||
|
|
||||||
|
Represents a single open position within a portfolio.
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| `holding_id` | `str` | Yes | UUID, primary key |
|
||||||
|
| `portfolio_id` | `str` | Yes | FK → portfolios.portfolio_id |
|
||||||
|
| `ticker` | `str` | Yes | Stock ticker symbol, e.g. `"AAPL"` |
|
||||||
|
| `shares` | `float` | Yes | Number of shares held |
|
||||||
|
| `avg_cost` | `float` | Yes | Average cost basis per share (USD) |
|
||||||
|
| `sector` | `str \| None` | No | GICS sector name |
|
||||||
|
| `industry` | `str \| None` | No | GICS industry name |
|
||||||
|
| `created_at` | `str` | Yes | ISO-8601 UTC datetime string |
|
||||||
|
| `updated_at` | `str` | Yes | ISO-8601 UTC datetime string |
|
||||||
|
|
||||||
|
### Runtime-Computed Fields (not stored in DB)
|
||||||
|
|
||||||
|
These are populated by `enrich()` and available for agent/analysis use:
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `current_price` | `float \| None` | Latest market price per share |
|
||||||
|
| `current_value` | `float \| None` | `current_price * shares` |
|
||||||
|
| `cost_basis` | `float` | `avg_cost * shares` |
|
||||||
|
| `unrealized_pnl` | `float \| None` | `current_value - cost_basis` |
|
||||||
|
| `unrealized_pnl_pct` | `float \| None` | `unrealized_pnl / cost_basis` (0 if cost_basis == 0) |
|
||||||
|
| `weight` | `float \| None` | `current_value / portfolio_total_value` |
|
||||||
|
|
||||||
|
### Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
"""Serialise stored fields only (not runtime-computed fields)."""
|
||||||
|
|
||||||
|
def from_dict(cls, data: dict) -> "Holding":
|
||||||
|
"""Deserialise from DB row or JSON dict."""
|
||||||
|
|
||||||
|
def enrich(self, current_price: float, portfolio_total_value: float) -> "Holding":
|
||||||
|
"""
|
||||||
|
Populate runtime-computed fields in-place and return self.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
current_price: Latest market price for this ticker.
|
||||||
|
portfolio_total_value: Total portfolio value (cash + equity) for weight calc.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `Trade`
|
||||||
|
|
||||||
|
Immutable record of a single mock trade execution. Never modified after creation.
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| `trade_id` | `str` | Yes | UUID, primary key |
|
||||||
|
| `portfolio_id` | `str` | Yes | FK → portfolios.portfolio_id |
|
||||||
|
| `ticker` | `str` | Yes | Stock ticker symbol |
|
||||||
|
| `action` | `str` | Yes | `"BUY"` or `"SELL"` |
|
||||||
|
| `shares` | `float` | Yes | Number of shares traded |
|
||||||
|
| `price` | `float` | Yes | Execution price per share (USD) |
|
||||||
|
| `total_value` | `float` | Yes | `shares * price` |
|
||||||
|
| `trade_date` | `str` | Yes | ISO-8601 UTC datetime of execution |
|
||||||
|
| `rationale` | `str \| None` | No | PM agent rationale for this trade |
|
||||||
|
| `signal_source` | `str \| None` | No | `"scanner"`, `"holding_review"`, `"pm_agent"` |
|
||||||
|
| `metadata` | `dict` | No | Free-form JSON |
|
||||||
|
|
||||||
|
### Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
"""Serialise all fields."""
|
||||||
|
|
||||||
|
def from_dict(cls, data: dict) -> "Trade":
|
||||||
|
"""Deserialise from DB row or JSON dict."""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `PortfolioSnapshot`
|
||||||
|
|
||||||
|
Point-in-time immutable record of the portfolio state. Taken after every trade
|
||||||
|
execution session (Phase 5 of the workflow). Used for performance tracking.
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| `snapshot_id` | `str` | Yes | UUID, primary key |
|
||||||
|
| `portfolio_id` | `str` | Yes | FK → portfolios.portfolio_id |
|
||||||
|
| `snapshot_date` | `str` | Yes | ISO-8601 UTC datetime |
|
||||||
|
| `total_value` | `float` | Yes | Cash + equity at snapshot time |
|
||||||
|
| `cash` | `float` | Yes | Cash balance at snapshot time |
|
||||||
|
| `equity_value` | `float` | Yes | Sum of position values at snapshot time |
|
||||||
|
| `num_positions` | `int` | Yes | Number of open positions |
|
||||||
|
| `holdings_snapshot` | `list[dict]` | Yes | Serialised list of holding dicts (as-of) |
|
||||||
|
| `metadata` | `dict` | No | Free-form JSON (e.g. PM decision path) |
|
||||||
|
|
||||||
|
### Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
"""Serialise all fields. `holdings_snapshot` is already a list[dict]."""
|
||||||
|
|
||||||
|
def from_dict(cls, data: dict) -> "PortfolioSnapshot":
|
||||||
|
"""Deserialise. `holdings_snapshot` parsed from JSON string if needed."""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Serialisation Contract
|
||||||
|
|
||||||
|
### `to_dict()`
|
||||||
|
|
||||||
|
- Returns a flat `dict[str, Any]`
|
||||||
|
- All values must be JSON-serialisable (str, int, float, bool, list, dict, None)
|
||||||
|
- `datetime` objects → ISO-8601 string (`isoformat()`)
|
||||||
|
- `Decimal` values → `float`
|
||||||
|
- Runtime-computed fields (`current_price`, `weight`, etc.) are **excluded**
|
||||||
|
- Complex nested fields (`metadata`, `holdings_snapshot`) are included as-is
|
||||||
|
|
||||||
|
### `from_dict()`
|
||||||
|
|
||||||
|
- Class method; must be callable as `Portfolio.from_dict(row)`
|
||||||
|
- Handles missing optional fields with `data.get("field", default)`
|
||||||
|
- Does **not** raise on extra keys in `data`
|
||||||
|
- Does **not** populate runtime-computed fields (call `enrich()` separately)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Enrichment Logic
|
||||||
|
|
||||||
|
### `Holding.enrich(current_price, portfolio_total_value)`
|
||||||
|
|
||||||
|
```python
|
||||||
|
self.current_price = current_price
|
||||||
|
self.current_value = current_price * self.shares
|
||||||
|
self.cost_basis = self.avg_cost * self.shares
|
||||||
|
self.unrealized_pnl = self.current_value - self.cost_basis
|
||||||
|
if self.cost_basis > 0:
|
||||||
|
self.unrealized_pnl_pct = self.unrealized_pnl / self.cost_basis
|
||||||
|
else:
|
||||||
|
self.unrealized_pnl_pct = 0.0
|
||||||
|
if portfolio_total_value > 0:
|
||||||
|
self.weight = self.current_value / portfolio_total_value
|
||||||
|
else:
|
||||||
|
self.weight = 0.0
|
||||||
|
return self
|
||||||
|
```
|
||||||
|
|
||||||
|
### `Portfolio.enrich(holdings)`
|
||||||
|
|
||||||
|
```python
|
||||||
|
self.equity_value = sum(h.current_value or 0 for h in holdings)
|
||||||
|
self.total_value = self.cash + self.equity_value
|
||||||
|
if self.total_value > 0:
|
||||||
|
self.cash_pct = self.cash / self.total_value
|
||||||
|
else:
|
||||||
|
self.cash_pct = 1.0
|
||||||
|
return self
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Type Alias Reference
|
||||||
|
|
||||||
|
```python
|
||||||
|
from __future__ import annotations
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from typing import Any
|
||||||
|
```
|
||||||
|
|
||||||
|
All `metadata` fields use `dict[str, Any]` with `field(default_factory=dict)`.
|
||||||
|
All optional fields default to `None` unless noted otherwise.
|
||||||
|
|
@ -0,0 +1,305 @@
|
||||||
|
# Database & Filesystem Schema
|
||||||
|
|
||||||
|
<!-- Last verified: 2026-03-20 -->
|
||||||
|
|
||||||
|
## Supabase (PostgreSQL) Schema
|
||||||
|
|
||||||
|
All tables are created in the `public` schema (Supabase default).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `portfolios`
|
||||||
|
|
||||||
|
Stores one row per managed portfolio.
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS portfolios (
|
||||||
|
portfolio_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
cash NUMERIC(18,4) NOT NULL CHECK (cash >= 0),
|
||||||
|
initial_cash NUMERIC(18,4) NOT NULL CHECK (initial_cash > 0),
|
||||||
|
currency CHAR(3) NOT NULL DEFAULT 'USD',
|
||||||
|
report_path TEXT,
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}',
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Constraints:**
|
||||||
|
- `cash >= 0` — portfolio can be fully invested but never negative
|
||||||
|
- `initial_cash > 0` — must start with positive capital
|
||||||
|
- `currency` is 3-char ISO 4217 code
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `holdings`
|
||||||
|
|
||||||
|
Stores one row per open position per portfolio. Row is deleted when shares reach 0.
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS holdings (
|
||||||
|
holding_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
ticker TEXT NOT NULL,
|
||||||
|
shares NUMERIC(18,6) NOT NULL CHECK (shares > 0),
|
||||||
|
avg_cost NUMERIC(18,4) NOT NULL CHECK (avg_cost >= 0),
|
||||||
|
sector TEXT,
|
||||||
|
industry TEXT,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
|
||||||
|
CONSTRAINT holdings_portfolio_ticker_unique UNIQUE (portfolio_id, ticker)
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Constraints:**
|
||||||
|
- `shares > 0` — zero-share positions are deleted, not stored
|
||||||
|
- `avg_cost >= 0` — cost basis is non-negative
|
||||||
|
- `UNIQUE (portfolio_id, ticker)` — one row per ticker per portfolio (upsert pattern)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `trades`
|
||||||
|
|
||||||
|
Immutable append-only log of every mock trade execution.
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS trades (
|
||||||
|
trade_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
ticker TEXT NOT NULL,
|
||||||
|
action TEXT NOT NULL CHECK (action IN ('BUY', 'SELL')),
|
||||||
|
shares NUMERIC(18,6) NOT NULL CHECK (shares > 0),
|
||||||
|
price NUMERIC(18,4) NOT NULL CHECK (price > 0),
|
||||||
|
total_value NUMERIC(18,4) NOT NULL CHECK (total_value > 0),
|
||||||
|
trade_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
rationale TEXT,
|
||||||
|
signal_source TEXT,
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}',
|
||||||
|
|
||||||
|
CONSTRAINT trades_action_values CHECK (action IN ('BUY', 'SELL'))
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Constraints:**
|
||||||
|
- `action IN ('BUY', 'SELL')` — only two valid actions
|
||||||
|
- `shares > 0`, `price > 0` — all quantities positive
|
||||||
|
- No `updated_at` — trades are immutable
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `snapshots`
|
||||||
|
|
||||||
|
Point-in-time portfolio state snapshots taken after each trade session.
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS snapshots (
|
||||||
|
snapshot_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
snapshot_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
total_value NUMERIC(18,4) NOT NULL,
|
||||||
|
cash NUMERIC(18,4) NOT NULL,
|
||||||
|
equity_value NUMERIC(18,4) NOT NULL,
|
||||||
|
num_positions INTEGER NOT NULL CHECK (num_positions >= 0),
|
||||||
|
holdings_snapshot JSONB NOT NULL DEFAULT '[]',
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}'
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Constraints:**
|
||||||
|
- `num_positions >= 0` — can have 0 positions (fully in cash)
|
||||||
|
- `holdings_snapshot` is a JSONB array of serialised `Holding.to_dict()` objects
|
||||||
|
- No `updated_at` — snapshots are immutable
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Indexes
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- portfolios: fast lookup by name
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_portfolios_name
|
||||||
|
ON portfolios (name);
|
||||||
|
|
||||||
|
-- holdings: list all holdings for a portfolio (most common query)
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_holdings_portfolio_id
|
||||||
|
ON holdings (portfolio_id);
|
||||||
|
|
||||||
|
-- holdings: fast ticker lookup within a portfolio
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_holdings_portfolio_ticker
|
||||||
|
ON holdings (portfolio_id, ticker);
|
||||||
|
|
||||||
|
-- trades: list recent trades for a portfolio, newest first
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_trades_portfolio_id_date
|
||||||
|
ON trades (portfolio_id, trade_date DESC);
|
||||||
|
|
||||||
|
-- trades: filter by ticker within a portfolio
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_trades_portfolio_ticker
|
||||||
|
ON trades (portfolio_id, ticker);
|
||||||
|
|
||||||
|
-- snapshots: get latest snapshot for a portfolio
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_snapshots_portfolio_id_date
|
||||||
|
ON snapshots (portfolio_id, snapshot_date DESC);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `updated_at` Trigger
|
||||||
|
|
||||||
|
Automatically updates `updated_at` on every row modification for `portfolios`
|
||||||
|
and `holdings` (trades and snapshots are immutable).
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Trigger function (shared across tables)
|
||||||
|
CREATE OR REPLACE FUNCTION update_updated_at_column()
|
||||||
|
RETURNS TRIGGER AS $$
|
||||||
|
BEGIN
|
||||||
|
NEW.updated_at = NOW();
|
||||||
|
RETURN NEW;
|
||||||
|
END;
|
||||||
|
$$ LANGUAGE plpgsql;
|
||||||
|
|
||||||
|
-- Apply to portfolios
|
||||||
|
CREATE OR REPLACE TRIGGER trg_portfolios_updated_at
|
||||||
|
BEFORE UPDATE ON portfolios
|
||||||
|
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
|
||||||
|
-- Apply to holdings
|
||||||
|
CREATE OR REPLACE TRIGGER trg_holdings_updated_at
|
||||||
|
BEFORE UPDATE ON holdings
|
||||||
|
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Queries
|
||||||
|
|
||||||
|
### Get active portfolio with cash balance
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT portfolio_id, name, cash, initial_cash, currency
|
||||||
|
FROM portfolios
|
||||||
|
WHERE portfolio_id = $1;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get all holdings with sector summary
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
ticker,
|
||||||
|
shares,
|
||||||
|
avg_cost,
|
||||||
|
shares * avg_cost AS cost_basis,
|
||||||
|
sector
|
||||||
|
FROM holdings
|
||||||
|
WHERE portfolio_id = $1
|
||||||
|
ORDER BY shares * avg_cost DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sector concentration (cost-basis weighted)
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
COALESCE(sector, 'Unknown') AS sector,
|
||||||
|
SUM(shares * avg_cost) AS sector_cost_basis
|
||||||
|
FROM holdings
|
||||||
|
WHERE portfolio_id = $1
|
||||||
|
GROUP BY sector
|
||||||
|
ORDER BY sector_cost_basis DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recent 20 trades for a portfolio
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT ticker, action, shares, price, total_value, trade_date, rationale
|
||||||
|
FROM trades
|
||||||
|
WHERE portfolio_id = $1
|
||||||
|
ORDER BY trade_date DESC
|
||||||
|
LIMIT 20;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Latest portfolio snapshot
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT *
|
||||||
|
FROM snapshots
|
||||||
|
WHERE portfolio_id = $1
|
||||||
|
ORDER BY snapshot_date DESC
|
||||||
|
LIMIT 1;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Portfolio performance over time (snapshot series)
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT snapshot_date, total_value, cash, equity_value, num_positions
|
||||||
|
FROM snapshots
|
||||||
|
WHERE portfolio_id = $1
|
||||||
|
ORDER BY snapshot_date ASC;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Filesystem Directory Structure
|
||||||
|
|
||||||
|
Reports and documents are stored under the project's `reports/` directory using
|
||||||
|
the existing convention from `tradingagents/report_paths.py`.
|
||||||
|
|
||||||
|
```
|
||||||
|
reports/
|
||||||
|
└── daily/
|
||||||
|
└── {YYYY-MM-DD}/
|
||||||
|
├── market/
|
||||||
|
│ ├── geopolitical_report.md
|
||||||
|
│ ├── market_movers_report.md
|
||||||
|
│ ├── sector_report.md
|
||||||
|
│ ├── industry_deep_dive_report.md
|
||||||
|
│ ├── macro_synthesis_report.md
|
||||||
|
│ └── macro_scan_summary.json ← ReportStore.save_scan / load_scan
|
||||||
|
│
|
||||||
|
├── {TICKER}/ ← one dir per analysed ticker
|
||||||
|
│ ├── 1_analysts/
|
||||||
|
│ ├── 2_research/
|
||||||
|
│ ├── 3_trader/
|
||||||
|
│ ├── 4_risk/
|
||||||
|
│ ├── complete_report.md ← ReportStore.save_analysis / load_analysis
|
||||||
|
│ └── eval/
|
||||||
|
│ └── full_states_log.json
|
||||||
|
│
|
||||||
|
├── daily_digest.md
|
||||||
|
│
|
||||||
|
└── portfolio/ ← NEW: portfolio manager artifacts
|
||||||
|
├── {TICKER}_holding_review.json ← ReportStore.save_holding_review
|
||||||
|
├── {portfolio_id}_risk_metrics.json
|
||||||
|
├── {portfolio_id}_pm_decision.json
|
||||||
|
└── {portfolio_id}_pm_decision.md (human-readable)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Supabase ↔ Filesystem Link
|
||||||
|
|
||||||
|
The `portfolios.report_path` column stores the **absolute or relative path** to the
|
||||||
|
daily portfolio subdirectory:
|
||||||
|
|
||||||
|
```
|
||||||
|
report_path = "reports/daily/2026-03-20/portfolio"
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows the Repository layer to load the PM decision, risk metrics, and holding
|
||||||
|
reviews by constructing:
|
||||||
|
|
||||||
|
```python
|
||||||
|
Path(portfolio.report_path) / f"{portfolio_id}_pm_decision.json"
|
||||||
|
```
|
||||||
|
|
||||||
|
The path is set by the Repository after the first write on each run day.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Schema Version Notes
|
||||||
|
|
||||||
|
- Migration file: `tradingagents/portfolio/migrations/001_initial_schema.sql`
|
||||||
|
- All `CREATE TABLE` and `CREATE INDEX` use `IF NOT EXISTS` — safe to re-run
|
||||||
|
- `CREATE OR REPLACE TRIGGER` / `CREATE OR REPLACE FUNCTION` — idempotent
|
||||||
|
- Supabase project dashboard: run via SQL Editor or the Supabase CLI
|
||||||
|
(`supabase db push`)
|
||||||
|
|
@ -0,0 +1,492 @@
|
||||||
|
# Repository Layer API
|
||||||
|
|
||||||
|
<!-- Last verified: 2026-03-20 -->
|
||||||
|
|
||||||
|
This document is the authoritative API reference for all classes in
|
||||||
|
`tradingagents/portfolio/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Exception Hierarchy
|
||||||
|
|
||||||
|
Defined in `tradingagents/portfolio/exceptions.py`.
|
||||||
|
|
||||||
|
```
|
||||||
|
PortfolioError # Base exception for all portfolio errors
|
||||||
|
├── PortfolioNotFoundError # Requested portfolio_id does not exist
|
||||||
|
├── HoldingNotFoundError # Requested holding (portfolio_id, ticker) does not exist
|
||||||
|
├── DuplicatePortfolioError # Portfolio name or ID already exists
|
||||||
|
├── InsufficientCashError # Not enough cash for a BUY trade
|
||||||
|
├── InsufficientSharesError # Not enough shares for a SELL trade
|
||||||
|
├── ConstraintViolationError # PM constraint breached (position size, sector, cash)
|
||||||
|
└── ReportStoreError # Filesystem read/write failure
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```python
|
||||||
|
from tradingagents.portfolio.exceptions import (
|
||||||
|
PortfolioError,
|
||||||
|
PortfolioNotFoundError,
|
||||||
|
InsufficientCashError,
|
||||||
|
InsufficientSharesError,
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
repo.add_holding(portfolio_id, "AAPL", shares=100, price=195.50)
|
||||||
|
except InsufficientCashError as e:
|
||||||
|
print(f"Cannot buy: {e}")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `SupabaseClient`
|
||||||
|
|
||||||
|
Location: `tradingagents/portfolio/supabase_client.py`
|
||||||
|
|
||||||
|
Thin wrapper around the `supabase-py` client that:
|
||||||
|
- Manages a singleton connection
|
||||||
|
- Translates HTTP / Supabase errors into domain exceptions
|
||||||
|
- Converts raw DB rows into model instances
|
||||||
|
|
||||||
|
### Constructor / Singleton
|
||||||
|
|
||||||
|
```python
|
||||||
|
client = SupabaseClient.get_instance()
|
||||||
|
# or
|
||||||
|
client = SupabaseClient(url=SUPABASE_URL, key=SUPABASE_KEY)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Portfolio Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def create_portfolio(self, portfolio: Portfolio) -> Portfolio:
|
||||||
|
"""Insert a new portfolio row.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
DuplicatePortfolioError: If portfolio_id already exists.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def get_portfolio(self, portfolio_id: str) -> Portfolio:
|
||||||
|
"""Fetch a portfolio by ID.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If no portfolio has that ID.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def list_portfolios(self) -> list[Portfolio]:
|
||||||
|
"""Return all portfolios ordered by created_at DESC."""
|
||||||
|
|
||||||
|
def update_portfolio(self, portfolio: Portfolio) -> Portfolio:
|
||||||
|
"""Update mutable fields (cash, report_path, metadata, updated_at).
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def delete_portfolio(self, portfolio_id: str) -> None:
|
||||||
|
"""Delete a portfolio and all its holdings, trades, and snapshots (CASCADE).
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Holdings Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def upsert_holding(self, holding: Holding) -> Holding:
|
||||||
|
"""Insert or update a holding row (upsert on portfolio_id + ticker).
|
||||||
|
|
||||||
|
Returns the holding with updated DB-assigned fields (updated_at).
|
||||||
|
"""
|
||||||
|
|
||||||
|
def get_holding(self, portfolio_id: str, ticker: str) -> Holding | None:
|
||||||
|
"""Return the holding for (portfolio_id, ticker), or None if not found."""
|
||||||
|
|
||||||
|
def list_holdings(self, portfolio_id: str) -> list[Holding]:
|
||||||
|
"""Return all holdings for a portfolio ordered by cost_basis DESC."""
|
||||||
|
|
||||||
|
def delete_holding(self, portfolio_id: str, ticker: str) -> None:
|
||||||
|
"""Delete the holding for (portfolio_id, ticker).
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
HoldingNotFoundError: If no such holding exists.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Trades Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def record_trade(self, trade: Trade) -> Trade:
|
||||||
|
"""Insert a new trade record. Immutable — no update method.
|
||||||
|
|
||||||
|
Returns the trade with DB-assigned trade_id and trade_date.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def list_trades(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str | None = None,
|
||||||
|
limit: int = 100,
|
||||||
|
) -> list[Trade]:
|
||||||
|
"""Return recent trades for a portfolio, newest first.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: Filter by portfolio.
|
||||||
|
ticker: Optional additional filter by ticker symbol.
|
||||||
|
limit: Maximum number of rows to return.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Snapshots Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_snapshot(self, snapshot: PortfolioSnapshot) -> PortfolioSnapshot:
|
||||||
|
"""Insert a new snapshot. Immutable — no update method."""
|
||||||
|
|
||||||
|
def get_latest_snapshot(self, portfolio_id: str) -> PortfolioSnapshot | None:
|
||||||
|
"""Return the most recent snapshot, or None if none exist."""
|
||||||
|
|
||||||
|
def list_snapshots(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
limit: int = 30,
|
||||||
|
) -> list[PortfolioSnapshot]:
|
||||||
|
"""Return snapshots newest-first up to limit."""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `ReportStore`
|
||||||
|
|
||||||
|
Location: `tradingagents/portfolio/report_store.py`
|
||||||
|
|
||||||
|
Filesystem document store for all non-transactional portfolio artifacts.
|
||||||
|
Integrates with the existing `tradingagents/report_paths.py` path conventions.
|
||||||
|
|
||||||
|
### Constructor
|
||||||
|
|
||||||
|
```python
|
||||||
|
store = ReportStore(base_dir: str | Path = "reports")
|
||||||
|
```
|
||||||
|
|
||||||
|
`base_dir` defaults to `"reports"` (relative to CWD). Override via
|
||||||
|
`PORTFOLIO_DATA_DIR` env var or config.
|
||||||
|
|
||||||
|
### Scan Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_scan(self, date: str, data: dict) -> Path:
|
||||||
|
"""Save macro scan summary JSON.
|
||||||
|
|
||||||
|
Path: {base_dir}/daily/{date}/market/macro_scan_summary.json
|
||||||
|
|
||||||
|
Returns the path written.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_scan(self, date: str) -> dict | None:
|
||||||
|
"""Load macro scan summary. Returns None if file doesn't exist."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Analysis Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_analysis(self, date: str, ticker: str, data: dict) -> Path:
|
||||||
|
"""Save per-ticker analysis report as JSON.
|
||||||
|
|
||||||
|
Path: {base_dir}/daily/{date}/{TICKER}/complete_report.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_analysis(self, date: str, ticker: str) -> dict | None:
|
||||||
|
"""Load per-ticker analysis JSON. Returns None if file doesn't exist."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Holding Review Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_holding_review(self, date: str, ticker: str, data: dict) -> Path:
|
||||||
|
"""Save holding reviewer output for one ticker.
|
||||||
|
|
||||||
|
Path: {base_dir}/daily/{date}/portfolio/{TICKER}_holding_review.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_holding_review(self, date: str, ticker: str) -> dict | None:
|
||||||
|
"""Load holding review. Returns None if file doesn't exist."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Risk Metrics Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_risk_metrics(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
data: dict,
|
||||||
|
) -> Path:
|
||||||
|
"""Save risk computation results.
|
||||||
|
|
||||||
|
Path: {base_dir}/daily/{date}/portfolio/{portfolio_id}_risk_metrics.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_risk_metrics(self, date: str, portfolio_id: str) -> dict | None:
|
||||||
|
"""Load risk metrics. Returns None if file doesn't exist."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### PM Decision Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_pm_decision(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
data: dict,
|
||||||
|
markdown: str | None = None,
|
||||||
|
) -> Path:
|
||||||
|
"""Save PM agent decision.
|
||||||
|
|
||||||
|
JSON path: {base_dir}/daily/{date}/portfolio/{portfolio_id}_pm_decision.json
|
||||||
|
MD path: {base_dir}/daily/{date}/portfolio/{portfolio_id}_pm_decision.md
|
||||||
|
(written only when markdown is not None)
|
||||||
|
|
||||||
|
Returns JSON path.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_pm_decision(self, date: str, portfolio_id: str) -> dict | None:
|
||||||
|
"""Load PM decision JSON. Returns None if file doesn't exist."""
|
||||||
|
|
||||||
|
def list_pm_decisions(self, portfolio_id: str) -> list[Path]:
|
||||||
|
"""Return all saved PM decision JSON paths for portfolio_id, newest first.
|
||||||
|
|
||||||
|
Scans {base_dir}/daily/*/portfolio/{portfolio_id}_pm_decision.json
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `PortfolioRepository`
|
||||||
|
|
||||||
|
Location: `tradingagents/portfolio/repository.py`
|
||||||
|
|
||||||
|
Unified façade that combines `SupabaseClient` and `ReportStore`.
|
||||||
|
This is the **primary interface** for all portfolio operations — callers should
|
||||||
|
not interact with `SupabaseClient` or `ReportStore` directly.
|
||||||
|
|
||||||
|
### Constructor
|
||||||
|
|
||||||
|
```python
|
||||||
|
repo = PortfolioRepository(
|
||||||
|
client: SupabaseClient | None = None, # uses singleton if None
|
||||||
|
store: ReportStore | None = None, # uses default if None
|
||||||
|
config: dict | None = None, # uses get_portfolio_config() if None
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Portfolio Lifecycle
|
||||||
|
|
||||||
|
```python
|
||||||
|
def create_portfolio(
|
||||||
|
self,
|
||||||
|
name: str,
|
||||||
|
initial_cash: float,
|
||||||
|
currency: str = "USD",
|
||||||
|
) -> Portfolio:
|
||||||
|
"""Create a new portfolio with the given starting capital.
|
||||||
|
|
||||||
|
Generates a UUID for portfolio_id. Sets cash = initial_cash.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
DuplicatePortfolioError: If name is already in use.
|
||||||
|
ValueError: If initial_cash <= 0.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def get_portfolio(self, portfolio_id: str) -> Portfolio:
|
||||||
|
"""Fetch portfolio by ID.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If not found.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def get_portfolio_with_holdings(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
prices: dict[str, float] | None = None,
|
||||||
|
) -> tuple[Portfolio, list[Holding]]:
|
||||||
|
"""Fetch portfolio + all holdings, optionally enriched with current prices.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: Target portfolio.
|
||||||
|
prices: Optional dict of {ticker: current_price}. When provided,
|
||||||
|
holdings are enriched and portfolio.total_value is computed.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
(Portfolio, list[Holding]) — Portfolio.enrich() called if prices given.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Holdings Management
|
||||||
|
|
||||||
|
```python
|
||||||
|
def add_holding(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str,
|
||||||
|
shares: float,
|
||||||
|
price: float,
|
||||||
|
sector: str | None = None,
|
||||||
|
industry: str | None = None,
|
||||||
|
) -> Holding:
|
||||||
|
"""Buy shares and update portfolio cash and holdings.
|
||||||
|
|
||||||
|
Business logic:
|
||||||
|
- Raises InsufficientCashError if portfolio.cash < shares * price
|
||||||
|
- If holding already exists: updates avg_cost = weighted average
|
||||||
|
- portfolio.cash -= shares * price
|
||||||
|
- Records a BUY trade automatically
|
||||||
|
|
||||||
|
Returns the updated/created Holding.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def remove_holding(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str,
|
||||||
|
shares: float,
|
||||||
|
price: float,
|
||||||
|
) -> Holding | None:
|
||||||
|
"""Sell shares and update portfolio cash and holdings.
|
||||||
|
|
||||||
|
Business logic:
|
||||||
|
- Raises HoldingNotFoundError if no holding exists for ticker
|
||||||
|
- Raises InsufficientSharesError if holding.shares < shares
|
||||||
|
- If shares == holding.shares: deletes the holding row, returns None
|
||||||
|
- Otherwise: decrements holding.shares (avg_cost unchanged on sell)
|
||||||
|
- portfolio.cash += shares * price
|
||||||
|
- Records a SELL trade automatically
|
||||||
|
|
||||||
|
Returns the updated Holding (or None if fully sold).
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Snapshot Management
|
||||||
|
|
||||||
|
```python
|
||||||
|
def take_snapshot(self, portfolio_id: str, prices: dict[str, float]) -> PortfolioSnapshot:
|
||||||
|
"""Take an immutable snapshot of the current portfolio state.
|
||||||
|
|
||||||
|
Enriches all holdings with current prices, computes total_value,
|
||||||
|
then persists to Supabase via SupabaseClient.save_snapshot().
|
||||||
|
|
||||||
|
Returns the saved PortfolioSnapshot.
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Report Convenience Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
def save_pm_decision(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
decision: dict,
|
||||||
|
markdown: str | None = None,
|
||||||
|
) -> Path:
|
||||||
|
"""Delegate to ReportStore.save_pm_decision and update portfolio.report_path."""
|
||||||
|
|
||||||
|
def load_pm_decision(self, portfolio_id: str, date: str) -> dict | None:
|
||||||
|
"""Delegate to ReportStore.load_pm_decision."""
|
||||||
|
|
||||||
|
def save_risk_metrics(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
metrics: dict,
|
||||||
|
) -> Path:
|
||||||
|
"""Delegate to ReportStore.save_risk_metrics."""
|
||||||
|
|
||||||
|
def load_risk_metrics(self, portfolio_id: str, date: str) -> dict | None:
|
||||||
|
"""Delegate to ReportStore.load_risk_metrics."""
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Avg Cost Basis Calculation
|
||||||
|
|
||||||
|
When buying more shares of an existing holding, the average cost basis is updated
|
||||||
|
using the **weighted average** formula:
|
||||||
|
|
||||||
|
```
|
||||||
|
new_avg_cost = (old_shares * old_avg_cost + new_shares * new_price)
|
||||||
|
/ (old_shares + new_shares)
|
||||||
|
```
|
||||||
|
|
||||||
|
When **selling** shares, the average cost basis is **not changed** — only `shares`
|
||||||
|
is decremented. This follows the FIFO approximation used by most brokerages for
|
||||||
|
tax-reporting purposes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cash Management Rules
|
||||||
|
|
||||||
|
| Operation | Effect on `portfolio.cash` |
|
||||||
|
|-----------|---------------------------|
|
||||||
|
| BUY `n` shares at `p` | `cash -= n * p` |
|
||||||
|
| SELL `n` shares at `p` | `cash += n * p` |
|
||||||
|
| Snapshot | Read-only |
|
||||||
|
| Portfolio creation | `cash = initial_cash` |
|
||||||
|
|
||||||
|
Cash can never go below 0 after a trade. `add_holding` raises
|
||||||
|
`InsufficientCashError` if the trade would exceed available cash.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Usage
|
||||||
|
|
||||||
|
```python
|
||||||
|
from tradingagents.portfolio import PortfolioRepository
|
||||||
|
|
||||||
|
repo = PortfolioRepository()
|
||||||
|
|
||||||
|
# Create a portfolio
|
||||||
|
portfolio = repo.create_portfolio("Main Portfolio", initial_cash=100_000.0)
|
||||||
|
|
||||||
|
# Buy some shares
|
||||||
|
holding = repo.add_holding(
|
||||||
|
portfolio.portfolio_id,
|
||||||
|
ticker="AAPL",
|
||||||
|
shares=50,
|
||||||
|
price=195.50,
|
||||||
|
sector="Technology",
|
||||||
|
)
|
||||||
|
# portfolio.cash is now 100_000 - 50 * 195.50 = 90_225.00
|
||||||
|
# holding.avg_cost = 195.50
|
||||||
|
|
||||||
|
# Buy more (avg cost update)
|
||||||
|
holding = repo.add_holding(
|
||||||
|
portfolio.portfolio_id,
|
||||||
|
ticker="AAPL",
|
||||||
|
shares=25,
|
||||||
|
price=200.00,
|
||||||
|
)
|
||||||
|
# holding.avg_cost = (50*195.50 + 25*200.00) / 75 = 197.00
|
||||||
|
|
||||||
|
# Sell half
|
||||||
|
holding = repo.remove_holding(
|
||||||
|
portfolio.portfolio_id,
|
||||||
|
ticker="AAPL",
|
||||||
|
shares=37,
|
||||||
|
price=205.00,
|
||||||
|
)
|
||||||
|
# portfolio.cash += 37 * 205.00 = 7_585.00
|
||||||
|
|
||||||
|
# Take snapshot
|
||||||
|
prices = {"AAPL": 205.00}
|
||||||
|
snapshot = repo.take_snapshot(portfolio.portfolio_id, prices)
|
||||||
|
|
||||||
|
# Save PM decision
|
||||||
|
repo.save_pm_decision(
|
||||||
|
portfolio.portfolio_id,
|
||||||
|
date="2026-03-20",
|
||||||
|
decision={"sells": [], "buys": [...], "rationale": "..."},
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
# tests/portfolio package marker
|
||||||
|
|
@ -0,0 +1,110 @@
|
||||||
|
"""Shared pytest fixtures for portfolio tests.
|
||||||
|
|
||||||
|
Fixtures provided:
|
||||||
|
|
||||||
|
- ``tmp_reports`` — temporary directory used as ReportStore base_dir
|
||||||
|
- ``sample_portfolio`` — a Portfolio instance for testing (not persisted)
|
||||||
|
- ``sample_holding`` — a Holding instance for testing (not persisted)
|
||||||
|
- ``sample_trade`` — a Trade instance for testing (not persisted)
|
||||||
|
- ``sample_snapshot`` — a PortfolioSnapshot instance for testing
|
||||||
|
- ``report_store`` — a ReportStore instance backed by tmp_reports
|
||||||
|
- ``mock_supabase_client`` — MagicMock of SupabaseClient for unit tests
|
||||||
|
|
||||||
|
Supabase integration tests use ``pytest.mark.skipif`` to auto-skip when
|
||||||
|
``SUPABASE_URL`` is not set in the environment.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import uuid
|
||||||
|
from pathlib import Path
|
||||||
|
from unittest.mock import MagicMock
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Skip marker for Supabase integration tests
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
requires_supabase = pytest.mark.skipif(
|
||||||
|
not os.getenv("SUPABASE_URL"),
|
||||||
|
reason="SUPABASE_URL not set — skipping Supabase integration tests",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Data fixtures
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_portfolio_id() -> str:
|
||||||
|
"""Return a fixed UUID for deterministic testing."""
|
||||||
|
return "11111111-1111-1111-1111-111111111111"
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_holding_id() -> str:
|
||||||
|
"""Return a fixed UUID for deterministic testing."""
|
||||||
|
return "22222222-2222-2222-2222-222222222222"
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_portfolio(sample_portfolio_id: str):
|
||||||
|
"""Return an unsaved Portfolio instance for testing."""
|
||||||
|
# TODO: implement — construct a Portfolio dataclass with test values
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_holding(sample_portfolio_id: str, sample_holding_id: str):
|
||||||
|
"""Return an unsaved Holding instance for testing."""
|
||||||
|
# TODO: implement — construct a Holding dataclass with test values
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_trade(sample_portfolio_id: str):
|
||||||
|
"""Return an unsaved Trade instance for testing."""
|
||||||
|
# TODO: implement — construct a Trade dataclass with test values
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def sample_snapshot(sample_portfolio_id: str):
|
||||||
|
"""Return an unsaved PortfolioSnapshot instance for testing."""
|
||||||
|
# TODO: implement — construct a PortfolioSnapshot dataclass with test values
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Filesystem fixtures
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def tmp_reports(tmp_path: Path) -> Path:
|
||||||
|
"""Temporary reports directory, cleaned up after each test."""
|
||||||
|
reports_dir = tmp_path / "reports"
|
||||||
|
reports_dir.mkdir()
|
||||||
|
return reports_dir
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def report_store(tmp_reports: Path):
|
||||||
|
"""ReportStore instance backed by a temporary directory."""
|
||||||
|
# TODO: implement — return ReportStore(base_dir=tmp_reports)
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Mock Supabase client fixture
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def mock_supabase_client():
|
||||||
|
"""MagicMock of SupabaseClient for unit tests that don't hit the DB."""
|
||||||
|
# TODO: implement — return MagicMock(spec=SupabaseClient)
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,132 @@
|
||||||
|
"""Tests for tradingagents/portfolio/models.py.
|
||||||
|
|
||||||
|
Tests the four dataclass models: Portfolio, Holding, Trade, PortfolioSnapshot.
|
||||||
|
|
||||||
|
Coverage targets:
|
||||||
|
- to_dict() / from_dict() round-trips
|
||||||
|
- enrich() computed-field logic
|
||||||
|
- Edge cases (zero cost basis, zero portfolio value)
|
||||||
|
|
||||||
|
Run::
|
||||||
|
|
||||||
|
pytest tests/portfolio/test_models.py -v
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Portfolio round-trip
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_portfolio_to_dict_round_trip(sample_portfolio):
|
||||||
|
"""Portfolio.to_dict() -> Portfolio.from_dict() must be lossless."""
|
||||||
|
# TODO: implement
|
||||||
|
# d = sample_portfolio.to_dict()
|
||||||
|
# restored = Portfolio.from_dict(d)
|
||||||
|
# assert restored.portfolio_id == sample_portfolio.portfolio_id
|
||||||
|
# assert restored.cash == sample_portfolio.cash
|
||||||
|
# ... all stored fields
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_portfolio_to_dict_excludes_runtime_fields(sample_portfolio):
|
||||||
|
"""to_dict() must not include computed fields (total_value, equity_value, cash_pct)."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Holding round-trip
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_to_dict_round_trip(sample_holding):
|
||||||
|
"""Holding.to_dict() -> Holding.from_dict() must be lossless."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_to_dict_excludes_runtime_fields(sample_holding):
|
||||||
|
"""to_dict() must not include current_price, current_value, weight, etc."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Trade round-trip
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_trade_to_dict_round_trip(sample_trade):
|
||||||
|
"""Trade.to_dict() -> Trade.from_dict() must be lossless."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# PortfolioSnapshot round-trip
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_snapshot_to_dict_round_trip(sample_snapshot):
|
||||||
|
"""PortfolioSnapshot.to_dict() -> PortfolioSnapshot.from_dict() round-trip."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Holding.enrich()
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_enrich_computes_current_value(sample_holding):
|
||||||
|
"""enrich() must set current_value = current_price * shares."""
|
||||||
|
# TODO: implement
|
||||||
|
# sample_holding.enrich(current_price=200.0, portfolio_total_value=100_000.0)
|
||||||
|
# assert sample_holding.current_value == 200.0 * sample_holding.shares
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_enrich_computes_unrealized_pnl(sample_holding):
|
||||||
|
"""enrich() must set unrealized_pnl = current_value - cost_basis."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_enrich_computes_weight(sample_holding):
|
||||||
|
"""enrich() must set weight = current_value / portfolio_total_value."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_enrich_handles_zero_cost(sample_holding):
|
||||||
|
"""When avg_cost == 0, unrealized_pnl_pct must be 0 (no ZeroDivisionError)."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_holding_enrich_handles_zero_portfolio_value(sample_holding):
|
||||||
|
"""When portfolio_total_value == 0, weight must be 0 (no ZeroDivisionError)."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Portfolio.enrich()
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_portfolio_enrich_computes_total_value(sample_portfolio, sample_holding):
|
||||||
|
"""Portfolio.enrich() must compute total_value = cash + sum(holding.current_value)."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_portfolio_enrich_computes_cash_pct(sample_portfolio, sample_holding):
|
||||||
|
"""Portfolio.enrich() must compute cash_pct = cash / total_value."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,145 @@
|
||||||
|
"""Tests for tradingagents/portfolio/report_store.py.
|
||||||
|
|
||||||
|
Tests filesystem save/load operations for all report types.
|
||||||
|
|
||||||
|
All tests use a temporary directory (``tmp_reports`` fixture) and do not
|
||||||
|
require Supabase or network access.
|
||||||
|
|
||||||
|
Run::
|
||||||
|
|
||||||
|
pytest tests/portfolio/test_report_store.py -v
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Macro scan
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_and_load_scan(report_store, tmp_reports):
|
||||||
|
"""save_scan() then load_scan() must return the original data."""
|
||||||
|
# TODO: implement
|
||||||
|
# data = {"watchlist": ["AAPL", "MSFT"], "date": "2026-03-20"}
|
||||||
|
# path = report_store.save_scan("2026-03-20", data)
|
||||||
|
# assert path.exists()
|
||||||
|
# loaded = report_store.load_scan("2026-03-20")
|
||||||
|
# assert loaded == data
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_load_scan_returns_none_for_missing_file(report_store):
|
||||||
|
"""load_scan() must return None when the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Per-ticker analysis
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_and_load_analysis(report_store):
|
||||||
|
"""save_analysis() then load_analysis() must return the original data."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_analysis_ticker_stored_as_uppercase(report_store, tmp_reports):
|
||||||
|
"""Ticker symbol must be stored as uppercase in the directory path."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Holding reviews
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_and_load_holding_review(report_store):
|
||||||
|
"""save_holding_review() then load_holding_review() must round-trip."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_load_holding_review_returns_none_for_missing(report_store):
|
||||||
|
"""load_holding_review() must return None when the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Risk metrics
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_and_load_risk_metrics(report_store):
|
||||||
|
"""save_risk_metrics() then load_risk_metrics() must round-trip."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# PM decisions
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_and_load_pm_decision_json(report_store):
|
||||||
|
"""save_pm_decision() then load_pm_decision() must round-trip JSON."""
|
||||||
|
# TODO: implement
|
||||||
|
# decision = {"sells": [], "buys": [{"ticker": "AAPL", "shares": 10}]}
|
||||||
|
# report_store.save_pm_decision("2026-03-20", "pid-123", decision)
|
||||||
|
# loaded = report_store.load_pm_decision("2026-03-20", "pid-123")
|
||||||
|
# assert loaded == decision
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_pm_decision_writes_markdown_when_provided(report_store, tmp_reports):
|
||||||
|
"""When markdown is passed to save_pm_decision(), .md file must be written."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_save_pm_decision_no_markdown_file_when_not_provided(report_store, tmp_reports):
|
||||||
|
"""When markdown=None, no .md file should be written."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_load_pm_decision_returns_none_for_missing(report_store):
|
||||||
|
"""load_pm_decision() must return None when the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_list_pm_decisions(report_store):
|
||||||
|
"""list_pm_decisions() must return all saved decision paths, newest first."""
|
||||||
|
# TODO: implement
|
||||||
|
# Save decisions for multiple dates, verify order
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Filesystem behaviour
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_directories_created_on_write(report_store, tmp_reports):
|
||||||
|
"""Directories must be created automatically on first write."""
|
||||||
|
# TODO: implement
|
||||||
|
# assert not (tmp_reports / "daily" / "2026-03-20" / "portfolio").exists()
|
||||||
|
# report_store.save_risk_metrics("2026-03-20", "pid-123", {"sharpe": 1.2})
|
||||||
|
# assert (tmp_reports / "daily" / "2026-03-20" / "portfolio").is_dir()
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_json_formatted_with_indent(report_store, tmp_reports):
|
||||||
|
"""Written JSON files must use indent=2 for human readability."""
|
||||||
|
# TODO: implement
|
||||||
|
# Write a file, read the raw bytes, verify indentation
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,198 @@
|
||||||
|
"""Tests for tradingagents/portfolio/repository.py.
|
||||||
|
|
||||||
|
Tests the PortfolioRepository façade — business logic for holdings management,
|
||||||
|
cash accounting, avg-cost-basis updates, and snapshot creation.
|
||||||
|
|
||||||
|
Supabase integration tests are automatically skipped when ``SUPABASE_URL`` is
|
||||||
|
not set in the environment (use the ``requires_supabase`` fixture marker).
|
||||||
|
|
||||||
|
Unit tests use ``mock_supabase_client`` to avoid DB access.
|
||||||
|
|
||||||
|
Run (unit tests only)::
|
||||||
|
|
||||||
|
pytest tests/portfolio/test_repository.py -v -k "not integration"
|
||||||
|
|
||||||
|
Run (with Supabase)::
|
||||||
|
|
||||||
|
SUPABASE_URL=... SUPABASE_KEY=... pytest tests/portfolio/test_repository.py -v
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
from tests.portfolio.conftest import requires_supabase
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# add_holding — new position
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_add_holding_new_position(mock_supabase_client, report_store):
|
||||||
|
"""add_holding() on a ticker not yet held must create a new Holding."""
|
||||||
|
# TODO: implement
|
||||||
|
# repo = PortfolioRepository(client=mock_supabase_client, store=report_store)
|
||||||
|
# mock portfolio with enough cash
|
||||||
|
# repo.add_holding(portfolio_id, "AAPL", shares=10, price=200.0)
|
||||||
|
# assert mock_supabase_client.upsert_holding.called
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# add_holding — avg cost basis update
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_add_holding_updates_avg_cost(mock_supabase_client, report_store):
|
||||||
|
"""add_holding() on an existing position must update avg_cost correctly.
|
||||||
|
|
||||||
|
Formula: new_avg_cost = (old_shares * old_avg_cost + new_shares * price)
|
||||||
|
/ (old_shares + new_shares)
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
# existing holding: 50 shares @ 190.0
|
||||||
|
# buy 25 more @ 200.0
|
||||||
|
# expected avg_cost = (50*190 + 25*200) / 75 = 193.33...
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# add_holding — insufficient cash
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_add_holding_raises_insufficient_cash(mock_supabase_client, report_store):
|
||||||
|
"""add_holding() must raise InsufficientCashError when cash < shares * price."""
|
||||||
|
# TODO: implement
|
||||||
|
# portfolio with cash=500.0, try to buy 10 shares @ 200.0 (cost=2000)
|
||||||
|
# with pytest.raises(InsufficientCashError):
|
||||||
|
# repo.add_holding(portfolio_id, "AAPL", shares=10, price=200.0)
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# remove_holding — full position
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_full_position(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() selling all shares must delete the holding row."""
|
||||||
|
# TODO: implement
|
||||||
|
# holding: 50 shares
|
||||||
|
# sell 50 shares → holding deleted, cash credited
|
||||||
|
# assert mock_supabase_client.delete_holding.called
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# remove_holding — partial position
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_partial_position(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() selling a subset must reduce shares, not delete."""
|
||||||
|
# TODO: implement
|
||||||
|
# holding: 50 shares
|
||||||
|
# sell 20 → holding.shares == 30, avg_cost unchanged
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# remove_holding — errors
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_raises_insufficient_shares(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() must raise InsufficientSharesError when shares > held."""
|
||||||
|
# TODO: implement
|
||||||
|
# holding: 10 shares
|
||||||
|
# try sell 20 → InsufficientSharesError
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_raises_when_ticker_not_held(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() must raise HoldingNotFoundError for unknown tickers."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Cash accounting
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_add_holding_deducts_cash(mock_supabase_client, report_store):
|
||||||
|
"""add_holding() must reduce portfolio.cash by shares * price."""
|
||||||
|
# TODO: implement
|
||||||
|
# portfolio.cash = 10_000, buy 10 @ 200 → cash should be 8_000
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_credits_cash(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() must increase portfolio.cash by shares * price."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Trade recording
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_add_holding_records_buy_trade(mock_supabase_client, report_store):
|
||||||
|
"""add_holding() must call client.record_trade() with action='BUY'."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def test_remove_holding_records_sell_trade(mock_supabase_client, report_store):
|
||||||
|
"""remove_holding() must call client.record_trade() with action='SELL'."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Snapshot
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_take_snapshot(mock_supabase_client, report_store):
|
||||||
|
"""take_snapshot() must enrich holdings and persist a PortfolioSnapshot."""
|
||||||
|
# TODO: implement
|
||||||
|
# assert mock_supabase_client.save_snapshot.called
|
||||||
|
# snapshot.total_value == cash + equity
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Supabase integration tests (auto-skip without SUPABASE_URL)
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@requires_supabase
|
||||||
|
def test_integration_create_and_get_portfolio():
|
||||||
|
"""Integration: create a portfolio, retrieve it, verify fields match."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@requires_supabase
|
||||||
|
def test_integration_add_and_remove_holding():
|
||||||
|
"""Integration: add holding, verify DB row; remove, verify deletion."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@requires_supabase
|
||||||
|
def test_integration_record_and_list_trades():
|
||||||
|
"""Integration: record BUY + SELL trades, list them, verify order."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@requires_supabase
|
||||||
|
def test_integration_save_and_load_snapshot():
|
||||||
|
"""Integration: take snapshot, retrieve latest, verify total_value."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,55 @@
|
||||||
|
"""Portfolio Manager — public package exports.
|
||||||
|
|
||||||
|
Import the primary interface classes from this package:
|
||||||
|
|
||||||
|
from tradingagents.portfolio import (
|
||||||
|
PortfolioRepository,
|
||||||
|
Portfolio,
|
||||||
|
Holding,
|
||||||
|
Trade,
|
||||||
|
PortfolioSnapshot,
|
||||||
|
PortfolioError,
|
||||||
|
PortfolioNotFoundError,
|
||||||
|
InsufficientCashError,
|
||||||
|
InsufficientSharesError,
|
||||||
|
)
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from tradingagents.portfolio.exceptions import (
|
||||||
|
PortfolioError,
|
||||||
|
PortfolioNotFoundError,
|
||||||
|
HoldingNotFoundError,
|
||||||
|
DuplicatePortfolioError,
|
||||||
|
InsufficientCashError,
|
||||||
|
InsufficientSharesError,
|
||||||
|
ConstraintViolationError,
|
||||||
|
ReportStoreError,
|
||||||
|
)
|
||||||
|
from tradingagents.portfolio.models import (
|
||||||
|
Holding,
|
||||||
|
Portfolio,
|
||||||
|
PortfolioSnapshot,
|
||||||
|
Trade,
|
||||||
|
)
|
||||||
|
from tradingagents.portfolio.repository import PortfolioRepository
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
# Models
|
||||||
|
"Portfolio",
|
||||||
|
"Holding",
|
||||||
|
"Trade",
|
||||||
|
"PortfolioSnapshot",
|
||||||
|
# Repository (primary interface)
|
||||||
|
"PortfolioRepository",
|
||||||
|
# Exceptions
|
||||||
|
"PortfolioError",
|
||||||
|
"PortfolioNotFoundError",
|
||||||
|
"HoldingNotFoundError",
|
||||||
|
"DuplicatePortfolioError",
|
||||||
|
"InsufficientCashError",
|
||||||
|
"InsufficientSharesError",
|
||||||
|
"ConstraintViolationError",
|
||||||
|
"ReportStoreError",
|
||||||
|
]
|
||||||
|
|
@ -0,0 +1,87 @@
|
||||||
|
"""Portfolio Manager configuration.
|
||||||
|
|
||||||
|
Reads all portfolio-related settings from environment variables with sensible
|
||||||
|
defaults. Integrates with the existing ``tradingagents/default_config.py``
|
||||||
|
pattern.
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
from tradingagents.portfolio.config import get_portfolio_config, validate_config
|
||||||
|
|
||||||
|
cfg = get_portfolio_config()
|
||||||
|
validate_config(cfg)
|
||||||
|
print(cfg["max_positions"]) # 15
|
||||||
|
|
||||||
|
Environment variables (all optional):
|
||||||
|
|
||||||
|
SUPABASE_URL Supabase project URL (default: "")
|
||||||
|
SUPABASE_KEY Supabase anon/service role key (default: "")
|
||||||
|
PORTFOLIO_DATA_DIR Root dir for filesystem reports (default: "reports")
|
||||||
|
PM_MAX_POSITIONS Max open positions (default: 15)
|
||||||
|
PM_MAX_POSITION_PCT Max single-position weight 0–1 (default: 0.15)
|
||||||
|
PM_MAX_SECTOR_PCT Max sector weight 0–1 (default: 0.35)
|
||||||
|
PM_MIN_CASH_PCT Minimum cash reserve 0–1 (default: 0.05)
|
||||||
|
PM_DEFAULT_BUDGET Default starting cash in USD (default: 100000.0)
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Defaults
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
PORTFOLIO_CONFIG: dict = {
|
||||||
|
# Supabase connection
|
||||||
|
"supabase_url": "",
|
||||||
|
"supabase_key": "",
|
||||||
|
# Filesystem report root (matches report_paths.py REPORTS_ROOT)
|
||||||
|
"data_dir": "reports",
|
||||||
|
# PM constraint defaults
|
||||||
|
"max_positions": 15,
|
||||||
|
"max_position_pct": 0.15,
|
||||||
|
"max_sector_pct": 0.35,
|
||||||
|
"min_cash_pct": 0.05,
|
||||||
|
"default_budget": 100_000.0,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Public API
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def get_portfolio_config() -> dict:
|
||||||
|
"""Return the merged portfolio config (defaults overridden by env vars).
|
||||||
|
|
||||||
|
Reads ``SUPABASE_URL``, ``SUPABASE_KEY``, ``PORTFOLIO_DATA_DIR``,
|
||||||
|
``PM_MAX_POSITIONS``, ``PM_MAX_POSITION_PCT``, ``PM_MAX_SECTOR_PCT``,
|
||||||
|
``PM_MIN_CASH_PCT``, and ``PM_DEFAULT_BUDGET`` from the environment.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
A dict with all portfolio configuration keys.
|
||||||
|
"""
|
||||||
|
# TODO: implement — merge PORTFOLIO_CONFIG with env var overrides
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
def validate_config(cfg: dict) -> None:
|
||||||
|
"""Validate a portfolio config dict, raising ValueError on invalid values.
|
||||||
|
|
||||||
|
Checks:
|
||||||
|
- ``max_positions >= 1``
|
||||||
|
- ``0 < max_position_pct <= 1``
|
||||||
|
- ``0 < max_sector_pct <= 1``
|
||||||
|
- ``0 <= min_cash_pct < 1``
|
||||||
|
- ``default_budget > 0``
|
||||||
|
- ``min_cash_pct + max_position_pct <= 1`` (can always meet both constraints)
|
||||||
|
|
||||||
|
Args:
|
||||||
|
cfg: Config dict as returned by ``get_portfolio_config()``.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
ValueError: With a descriptive message on the first failed check.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,60 @@
|
||||||
|
"""Domain exception hierarchy for the portfolio management package.
|
||||||
|
|
||||||
|
All exceptions raised by this package inherit from ``PortfolioError`` so that
|
||||||
|
callers can catch the entire family with a single ``except PortfolioError``.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
from tradingagents.portfolio.exceptions import (
|
||||||
|
PortfolioError,
|
||||||
|
InsufficientCashError,
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
repo.add_holding(pid, "AAPL", shares=100, price=195.50)
|
||||||
|
except InsufficientCashError as e:
|
||||||
|
print(f"Cannot buy: {e}")
|
||||||
|
except PortfolioError as e:
|
||||||
|
print(f"Unexpected portfolio error: {e}")
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
|
||||||
|
class PortfolioError(Exception):
|
||||||
|
"""Base exception for all portfolio-management errors."""
|
||||||
|
|
||||||
|
|
||||||
|
class PortfolioNotFoundError(PortfolioError):
|
||||||
|
"""Raised when a requested portfolio_id does not exist in the database."""
|
||||||
|
|
||||||
|
|
||||||
|
class HoldingNotFoundError(PortfolioError):
|
||||||
|
"""Raised when a requested (portfolio_id, ticker) holding does not exist."""
|
||||||
|
|
||||||
|
|
||||||
|
class DuplicatePortfolioError(PortfolioError):
|
||||||
|
"""Raised when attempting to create a portfolio that already exists."""
|
||||||
|
|
||||||
|
|
||||||
|
class InsufficientCashError(PortfolioError):
|
||||||
|
"""Raised when a BUY order exceeds the portfolio's available cash balance."""
|
||||||
|
|
||||||
|
|
||||||
|
class InsufficientSharesError(PortfolioError):
|
||||||
|
"""Raised when a SELL order exceeds the number of shares held."""
|
||||||
|
|
||||||
|
|
||||||
|
class ConstraintViolationError(PortfolioError):
|
||||||
|
"""Raised when a trade would violate a PM constraint.
|
||||||
|
|
||||||
|
Constraints enforced:
|
||||||
|
- Max position size (default 15 % of portfolio value)
|
||||||
|
- Max sector exposure (default 35 % of portfolio value)
|
||||||
|
- Min cash reserve (default 5 % of portfolio value)
|
||||||
|
- Max number of positions (default 15)
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ReportStoreError(PortfolioError):
|
||||||
|
"""Raised on filesystem read/write failures in ReportStore."""
|
||||||
|
|
@ -0,0 +1,161 @@
|
||||||
|
-- =============================================================================
|
||||||
|
-- Portfolio Manager Agent — Initial Schema
|
||||||
|
-- Migration: 001_initial_schema.sql
|
||||||
|
-- Description: Creates all tables, indexes, and triggers for the portfolio
|
||||||
|
-- management data layer.
|
||||||
|
-- Safe to re-run: all statements use IF NOT EXISTS / CREATE OR REPLACE.
|
||||||
|
-- =============================================================================
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- Table: portfolios
|
||||||
|
-- Purpose: One row per managed portfolio. Tracks cash balance, initial capital,
|
||||||
|
-- and a pointer to the filesystem report directory.
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
CREATE TABLE IF NOT EXISTS portfolios (
|
||||||
|
portfolio_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
cash NUMERIC(18,4) NOT NULL CHECK (cash >= 0),
|
||||||
|
initial_cash NUMERIC(18,4) NOT NULL CHECK (initial_cash > 0),
|
||||||
|
currency CHAR(3) NOT NULL DEFAULT 'USD',
|
||||||
|
report_path TEXT, -- relative FS path to daily report dir
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}',
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
COMMENT ON TABLE portfolios IS
|
||||||
|
'One row per managed portfolio. Tracks cash balance and links to filesystem reports.';
|
||||||
|
COMMENT ON COLUMN portfolios.report_path IS
|
||||||
|
'Relative path to the daily portfolio report directory, e.g. reports/daily/2026-03-20/portfolio';
|
||||||
|
COMMENT ON COLUMN portfolios.metadata IS
|
||||||
|
'Free-form JSONB for agent notes, tags, or strategy parameters.';
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- Table: holdings
|
||||||
|
-- Purpose: Current open positions. One row per (portfolio, ticker). Deleted
|
||||||
|
-- when shares reach zero — zero-share rows are never stored.
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
CREATE TABLE IF NOT EXISTS holdings (
|
||||||
|
holding_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
ticker TEXT NOT NULL,
|
||||||
|
shares NUMERIC(18,6) NOT NULL CHECK (shares > 0),
|
||||||
|
avg_cost NUMERIC(18,4) NOT NULL CHECK (avg_cost >= 0),
|
||||||
|
sector TEXT,
|
||||||
|
industry TEXT,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
|
||||||
|
CONSTRAINT holdings_portfolio_ticker_unique UNIQUE (portfolio_id, ticker)
|
||||||
|
);
|
||||||
|
|
||||||
|
COMMENT ON TABLE holdings IS
|
||||||
|
'Open positions. Upserted on BUY (avg-cost update), deleted when fully sold.';
|
||||||
|
COMMENT ON COLUMN holdings.avg_cost IS
|
||||||
|
'Weighted-average cost basis per share in portfolio currency.';
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- Table: trades
|
||||||
|
-- Purpose: Immutable append-only log of every mock trade. Never modified.
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
CREATE TABLE IF NOT EXISTS trades (
|
||||||
|
trade_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
ticker TEXT NOT NULL,
|
||||||
|
action TEXT NOT NULL,
|
||||||
|
shares NUMERIC(18,6) NOT NULL CHECK (shares > 0),
|
||||||
|
price NUMERIC(18,4) NOT NULL CHECK (price > 0),
|
||||||
|
total_value NUMERIC(18,4) NOT NULL CHECK (total_value > 0),
|
||||||
|
trade_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
rationale TEXT, -- PM agent rationale for this trade
|
||||||
|
signal_source TEXT, -- 'scanner' | 'holding_review' | 'pm_agent'
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}',
|
||||||
|
|
||||||
|
CONSTRAINT trades_action_values CHECK (action IN ('BUY', 'SELL'))
|
||||||
|
);
|
||||||
|
|
||||||
|
COMMENT ON TABLE trades IS
|
||||||
|
'Immutable trade log. Records every mock BUY/SELL with PM rationale.';
|
||||||
|
COMMENT ON COLUMN trades.rationale IS
|
||||||
|
'Natural-language reason provided by the Portfolio Manager Agent.';
|
||||||
|
COMMENT ON COLUMN trades.signal_source IS
|
||||||
|
'Which sub-system generated the trade signal: scanner, holding_review, or pm_agent.';
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- Table: snapshots
|
||||||
|
-- Purpose: Immutable point-in-time portfolio state. Taken after each trade
|
||||||
|
-- execution session for performance tracking and time-series analysis.
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
CREATE TABLE IF NOT EXISTS snapshots (
|
||||||
|
snapshot_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
portfolio_id UUID NOT NULL REFERENCES portfolios(portfolio_id) ON DELETE CASCADE,
|
||||||
|
snapshot_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
total_value NUMERIC(18,4) NOT NULL,
|
||||||
|
cash NUMERIC(18,4) NOT NULL,
|
||||||
|
equity_value NUMERIC(18,4) NOT NULL,
|
||||||
|
num_positions INTEGER NOT NULL CHECK (num_positions >= 0),
|
||||||
|
holdings_snapshot JSONB NOT NULL DEFAULT '[]', -- serialised List[Holding.to_dict()]
|
||||||
|
metadata JSONB NOT NULL DEFAULT '{}'
|
||||||
|
);
|
||||||
|
|
||||||
|
COMMENT ON TABLE snapshots IS
|
||||||
|
'Immutable portfolio snapshots for performance tracking (NAV series).';
|
||||||
|
COMMENT ON COLUMN snapshots.holdings_snapshot IS
|
||||||
|
'JSONB array of Holding.to_dict() objects at snapshot time.';
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- Indexes
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
-- portfolios: lookup by name (uniqueness enforced at application level)
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_portfolios_name
|
||||||
|
ON portfolios (name);
|
||||||
|
|
||||||
|
-- holdings: list all holdings for a portfolio (most frequent query)
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_holdings_portfolio_id
|
||||||
|
ON holdings (portfolio_id);
|
||||||
|
|
||||||
|
-- holdings: fast (portfolio, ticker) point lookup for upserts
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_holdings_portfolio_ticker
|
||||||
|
ON holdings (portfolio_id, ticker);
|
||||||
|
|
||||||
|
-- trades: list recent trades for a portfolio, newest first
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_trades_portfolio_id_date
|
||||||
|
ON trades (portfolio_id, trade_date DESC);
|
||||||
|
|
||||||
|
-- trades: filter by ticker within a portfolio
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_trades_portfolio_ticker
|
||||||
|
ON trades (portfolio_id, ticker);
|
||||||
|
|
||||||
|
-- snapshots: get latest snapshot for a portfolio
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_snapshots_portfolio_id_date
|
||||||
|
ON snapshots (portfolio_id, snapshot_date DESC);
|
||||||
|
|
||||||
|
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
-- updated_at trigger
|
||||||
|
-- Purpose: Automatically sets updated_at = NOW() on every UPDATE for mutable
|
||||||
|
-- tables (portfolios, holdings). Trades and snapshots are immutable.
|
||||||
|
-- ---------------------------------------------------------------------------
|
||||||
|
CREATE OR REPLACE FUNCTION update_updated_at_column()
|
||||||
|
RETURNS TRIGGER AS $$
|
||||||
|
BEGIN
|
||||||
|
NEW.updated_at = NOW();
|
||||||
|
RETURN NEW;
|
||||||
|
END;
|
||||||
|
$$ LANGUAGE plpgsql;
|
||||||
|
|
||||||
|
-- Apply to portfolios
|
||||||
|
CREATE OR REPLACE TRIGGER trg_portfolios_updated_at
|
||||||
|
BEFORE UPDATE ON portfolios
|
||||||
|
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
|
||||||
|
-- Apply to holdings
|
||||||
|
CREATE OR REPLACE TRIGGER trg_holdings_updated_at
|
||||||
|
BEFORE UPDATE ON holdings
|
||||||
|
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
|
@ -0,0 +1,207 @@
|
||||||
|
"""Data models for the Portfolio Manager Agent.
|
||||||
|
|
||||||
|
All models are Python ``dataclass`` types with:
|
||||||
|
- Full type annotations
|
||||||
|
- ``to_dict()`` for serialisation (JSON / Supabase)
|
||||||
|
- ``from_dict()`` class method for deserialisation
|
||||||
|
- ``enrich()`` for attaching runtime-computed fields
|
||||||
|
|
||||||
|
See ``docs/portfolio/02_data_models.md`` for full field specifications.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Portfolio
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Portfolio:
|
||||||
|
"""A managed investment portfolio.
|
||||||
|
|
||||||
|
Stored fields are persisted to Supabase. Computed fields (total_value,
|
||||||
|
equity_value, cash_pct) are populated by ``enrich()`` and are *not*
|
||||||
|
persisted.
|
||||||
|
"""
|
||||||
|
|
||||||
|
portfolio_id: str
|
||||||
|
name: str
|
||||||
|
cash: float
|
||||||
|
initial_cash: float
|
||||||
|
currency: str = "USD"
|
||||||
|
created_at: str = ""
|
||||||
|
updated_at: str = ""
|
||||||
|
report_path: str | None = None
|
||||||
|
metadata: dict[str, Any] = field(default_factory=dict)
|
||||||
|
|
||||||
|
# Runtime-computed (not stored in DB)
|
||||||
|
total_value: float | None = field(default=None, repr=False)
|
||||||
|
equity_value: float | None = field(default=None, repr=False)
|
||||||
|
cash_pct: float | None = field(default=None, repr=False)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict[str, Any]:
|
||||||
|
"""Serialise stored fields to a flat dict for JSON / Supabase.
|
||||||
|
|
||||||
|
Runtime-computed fields are excluded.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, data: dict[str, Any]) -> "Portfolio":
|
||||||
|
"""Deserialise from a DB row or JSON dict.
|
||||||
|
|
||||||
|
Missing optional fields default gracefully. Extra keys are ignored.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def enrich(self, holdings: list["Holding"]) -> "Portfolio":
|
||||||
|
"""Compute total_value, equity_value, cash_pct from holdings.
|
||||||
|
|
||||||
|
Modifies self in-place and returns self for chaining.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
holdings: List of Holding objects with current_value populated
|
||||||
|
(i.e., ``holding.enrich()`` already called).
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Holding
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Holding:
|
||||||
|
"""An open position within a portfolio.
|
||||||
|
|
||||||
|
Stored fields are persisted to Supabase. Runtime-computed fields
|
||||||
|
(current_price, current_value, etc.) are populated by ``enrich()``.
|
||||||
|
"""
|
||||||
|
|
||||||
|
holding_id: str
|
||||||
|
portfolio_id: str
|
||||||
|
ticker: str
|
||||||
|
shares: float
|
||||||
|
avg_cost: float
|
||||||
|
sector: str | None = None
|
||||||
|
industry: str | None = None
|
||||||
|
created_at: str = ""
|
||||||
|
updated_at: str = ""
|
||||||
|
|
||||||
|
# Runtime-computed (not stored in DB)
|
||||||
|
current_price: float | None = field(default=None, repr=False)
|
||||||
|
current_value: float | None = field(default=None, repr=False)
|
||||||
|
cost_basis: float | None = field(default=None, repr=False)
|
||||||
|
unrealized_pnl: float | None = field(default=None, repr=False)
|
||||||
|
unrealized_pnl_pct: float | None = field(default=None, repr=False)
|
||||||
|
weight: float | None = field(default=None, repr=False)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict[str, Any]:
|
||||||
|
"""Serialise stored fields only (runtime-computed fields excluded)."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, data: dict[str, Any]) -> "Holding":
|
||||||
|
"""Deserialise from a DB row or JSON dict."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def enrich(self, current_price: float, portfolio_total_value: float) -> "Holding":
|
||||||
|
"""Populate runtime-computed fields in-place and return self.
|
||||||
|
|
||||||
|
Formula:
|
||||||
|
current_value = current_price * shares
|
||||||
|
cost_basis = avg_cost * shares
|
||||||
|
unrealized_pnl = current_value - cost_basis
|
||||||
|
unrealized_pnl_pct = unrealized_pnl / cost_basis (0 when cost_basis == 0)
|
||||||
|
weight = current_value / portfolio_total_value (0 when total == 0)
|
||||||
|
|
||||||
|
Args:
|
||||||
|
current_price: Latest market price for this ticker.
|
||||||
|
portfolio_total_value: Total portfolio value (cash + equity).
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Trade
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Trade:
|
||||||
|
"""An immutable record of a single mock trade execution.
|
||||||
|
|
||||||
|
Trades are never modified after creation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
trade_id: str
|
||||||
|
portfolio_id: str
|
||||||
|
ticker: str
|
||||||
|
action: str # "BUY" or "SELL"
|
||||||
|
shares: float
|
||||||
|
price: float
|
||||||
|
total_value: float
|
||||||
|
trade_date: str = ""
|
||||||
|
rationale: str | None = None
|
||||||
|
signal_source: str | None = None # "scanner" | "holding_review" | "pm_agent"
|
||||||
|
metadata: dict[str, Any] = field(default_factory=dict)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict[str, Any]:
|
||||||
|
"""Serialise all fields."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, data: dict[str, Any]) -> "Trade":
|
||||||
|
"""Deserialise from a DB row or JSON dict."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# PortfolioSnapshot
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class PortfolioSnapshot:
|
||||||
|
"""An immutable point-in-time snapshot of portfolio state.
|
||||||
|
|
||||||
|
Taken after every trade execution session (Phase 5 of the PM workflow).
|
||||||
|
Used for NAV time-series, performance attribution, and risk backtesting.
|
||||||
|
"""
|
||||||
|
|
||||||
|
snapshot_id: str
|
||||||
|
portfolio_id: str
|
||||||
|
snapshot_date: str
|
||||||
|
total_value: float
|
||||||
|
cash: float
|
||||||
|
equity_value: float
|
||||||
|
num_positions: int
|
||||||
|
holdings_snapshot: list[dict[str, Any]] = field(default_factory=list)
|
||||||
|
metadata: dict[str, Any] = field(default_factory=dict)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict[str, Any]:
|
||||||
|
"""Serialise all fields. ``holdings_snapshot`` is already a list[dict]."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, data: dict[str, Any]) -> "PortfolioSnapshot":
|
||||||
|
"""Deserialise from DB row or JSON dict.
|
||||||
|
|
||||||
|
``holdings_snapshot`` is parsed from a JSON string when needed.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,245 @@
|
||||||
|
"""Filesystem document store for Portfolio Manager reports.
|
||||||
|
|
||||||
|
Saves and loads all non-transactional portfolio artifacts (scans, per-ticker
|
||||||
|
analysis, holding reviews, risk metrics, PM decisions) using the existing
|
||||||
|
``tradingagents/report_paths.py`` path convention.
|
||||||
|
|
||||||
|
Directory layout::
|
||||||
|
|
||||||
|
reports/daily/{date}/
|
||||||
|
├── market/
|
||||||
|
│ └── macro_scan_summary.json ← save_scan / load_scan
|
||||||
|
├── {TICKER}/
|
||||||
|
│ └── complete_report.json ← save_analysis / load_analysis
|
||||||
|
└── portfolio/
|
||||||
|
├── {TICKER}_holding_review.json ← save/load_holding_review
|
||||||
|
├── {portfolio_id}_risk_metrics.json
|
||||||
|
├── {portfolio_id}_pm_decision.json
|
||||||
|
└── {portfolio_id}_pm_decision.md
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
from tradingagents.portfolio.report_store import ReportStore
|
||||||
|
|
||||||
|
store = ReportStore()
|
||||||
|
store.save_scan("2026-03-20", {"watchlist": [...]})
|
||||||
|
data = store.load_scan("2026-03-20")
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
|
||||||
|
class ReportStore:
|
||||||
|
"""Filesystem document store for all portfolio-related reports.
|
||||||
|
|
||||||
|
Directories are created automatically on first write.
|
||||||
|
All load methods return ``None`` when the file does not exist.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, base_dir: str | Path = "reports") -> None:
|
||||||
|
"""Initialise the store with a base reports directory.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
base_dir: Root directory for all reports. Defaults to ``"reports"``
|
||||||
|
(relative to CWD), matching ``report_paths.REPORTS_ROOT``.
|
||||||
|
Override via the ``PORTFOLIO_DATA_DIR`` env var or
|
||||||
|
``get_portfolio_config()["data_dir"]``.
|
||||||
|
"""
|
||||||
|
# TODO: implement — store Path(base_dir), resolve as needed
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Internal helpers
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def _portfolio_dir(self, date: str) -> Path:
|
||||||
|
"""Return the portfolio subdirectory for a given date.
|
||||||
|
|
||||||
|
Path: ``{base_dir}/daily/{date}/portfolio/``
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def _write_json(self, path: Path, data: dict[str, Any]) -> Path:
|
||||||
|
"""Write a dict to a JSON file, creating parent directories as needed.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
path: Target file path.
|
||||||
|
data: Data to serialise.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
The path written.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
ReportStoreError: On filesystem write failure.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def _read_json(self, path: Path) -> dict[str, Any] | None:
|
||||||
|
"""Read a JSON file, returning None if the file does not exist.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
ReportStoreError: On JSON parse error (file exists but is corrupt).
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Macro Scan
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_scan(self, date: str, data: dict[str, Any]) -> Path:
|
||||||
|
"""Save macro scan summary JSON.
|
||||||
|
|
||||||
|
Path: ``{base_dir}/daily/{date}/market/macro_scan_summary.json``
|
||||||
|
|
||||||
|
Args:
|
||||||
|
date: ISO date string, e.g. ``"2026-03-20"``.
|
||||||
|
data: Scan output dict (typically the macro_scan_summary).
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Path of the written file.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_scan(self, date: str) -> dict[str, Any] | None:
|
||||||
|
"""Load macro scan summary. Returns None if the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Per-Ticker Analysis
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_analysis(self, date: str, ticker: str, data: dict[str, Any]) -> Path:
|
||||||
|
"""Save per-ticker analysis report as JSON.
|
||||||
|
|
||||||
|
Path: ``{base_dir}/daily/{date}/{TICKER}/complete_report.json``
|
||||||
|
|
||||||
|
Args:
|
||||||
|
date: ISO date string.
|
||||||
|
ticker: Ticker symbol (stored as uppercase).
|
||||||
|
data: Analysis output dict.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_analysis(self, date: str, ticker: str) -> dict[str, Any] | None:
|
||||||
|
"""Load per-ticker analysis JSON. Returns None if the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Holding Reviews
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_holding_review(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
ticker: str,
|
||||||
|
data: dict[str, Any],
|
||||||
|
) -> Path:
|
||||||
|
"""Save holding reviewer output for one ticker.
|
||||||
|
|
||||||
|
Path: ``{base_dir}/daily/{date}/portfolio/{TICKER}_holding_review.json``
|
||||||
|
|
||||||
|
Args:
|
||||||
|
date: ISO date string.
|
||||||
|
ticker: Ticker symbol (stored as uppercase).
|
||||||
|
data: HoldingReviewerAgent output dict.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_holding_review(self, date: str, ticker: str) -> dict[str, Any] | None:
|
||||||
|
"""Load holding review output. Returns None if the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Risk Metrics
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_risk_metrics(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
data: dict[str, Any],
|
||||||
|
) -> Path:
|
||||||
|
"""Save risk computation results.
|
||||||
|
|
||||||
|
Path: ``{base_dir}/daily/{date}/portfolio/{portfolio_id}_risk_metrics.json``
|
||||||
|
|
||||||
|
Args:
|
||||||
|
date: ISO date string.
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
data: Risk metrics dict (Sharpe, Sortino, VaR, etc.).
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_risk_metrics(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
) -> dict[str, Any] | None:
|
||||||
|
"""Load risk metrics. Returns None if the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# PM Decisions
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_pm_decision(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
data: dict[str, Any],
|
||||||
|
markdown: str | None = None,
|
||||||
|
) -> Path:
|
||||||
|
"""Save PM agent decision.
|
||||||
|
|
||||||
|
JSON path: ``{base_dir}/daily/{date}/portfolio/{portfolio_id}_pm_decision.json``
|
||||||
|
MD path: ``{base_dir}/daily/{date}/portfolio/{portfolio_id}_pm_decision.md``
|
||||||
|
(written only when ``markdown`` is not None)
|
||||||
|
|
||||||
|
Args:
|
||||||
|
date: ISO date string.
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
data: PM decision dict (sells, buys, holds, rationale, …).
|
||||||
|
markdown: Optional human-readable version; written when provided.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Path of the written JSON file.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_pm_decision(
|
||||||
|
self,
|
||||||
|
date: str,
|
||||||
|
portfolio_id: str,
|
||||||
|
) -> dict[str, Any] | None:
|
||||||
|
"""Load PM decision JSON. Returns None if the file does not exist."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def list_pm_decisions(self, portfolio_id: str) -> list[Path]:
|
||||||
|
"""Return all saved PM decision JSON paths for portfolio_id, newest first.
|
||||||
|
|
||||||
|
Scans ``{base_dir}/daily/*/portfolio/{portfolio_id}_pm_decision.json``.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Sorted list of Path objects, newest date first.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,315 @@
|
||||||
|
"""Unified data-access façade for the Portfolio Manager.
|
||||||
|
|
||||||
|
``PortfolioRepository`` combines ``SupabaseClient`` (transactional data) and
|
||||||
|
``ReportStore`` (filesystem documents) into a single, business-logic-aware
|
||||||
|
interface.
|
||||||
|
|
||||||
|
Callers should **only** interact with ``PortfolioRepository`` — do not use
|
||||||
|
``SupabaseClient`` or ``ReportStore`` directly from outside this package.
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
from tradingagents.portfolio import PortfolioRepository
|
||||||
|
|
||||||
|
repo = PortfolioRepository()
|
||||||
|
|
||||||
|
# Create a portfolio
|
||||||
|
portfolio = repo.create_portfolio("Main Portfolio", initial_cash=100_000.0)
|
||||||
|
|
||||||
|
# Buy shares
|
||||||
|
holding = repo.add_holding(portfolio.portfolio_id, "AAPL", shares=50, price=195.50)
|
||||||
|
|
||||||
|
# Sell shares
|
||||||
|
repo.remove_holding(portfolio.portfolio_id, "AAPL", shares=25, price=200.00)
|
||||||
|
|
||||||
|
# Snapshot
|
||||||
|
snapshot = repo.take_snapshot(portfolio.portfolio_id, prices={"AAPL": 200.00})
|
||||||
|
|
||||||
|
See ``docs/portfolio/04_repository_api.md`` for full API documentation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
from tradingagents.portfolio.exceptions import (
|
||||||
|
HoldingNotFoundError,
|
||||||
|
InsufficientCashError,
|
||||||
|
InsufficientSharesError,
|
||||||
|
)
|
||||||
|
from tradingagents.portfolio.models import (
|
||||||
|
Holding,
|
||||||
|
Portfolio,
|
||||||
|
PortfolioSnapshot,
|
||||||
|
Trade,
|
||||||
|
)
|
||||||
|
from tradingagents.portfolio.report_store import ReportStore
|
||||||
|
from tradingagents.portfolio.supabase_client import SupabaseClient
|
||||||
|
|
||||||
|
|
||||||
|
class PortfolioRepository:
|
||||||
|
"""Unified façade over SupabaseClient and ReportStore.
|
||||||
|
|
||||||
|
Implements business logic for:
|
||||||
|
- Average cost basis updates on repeated buys
|
||||||
|
- Cash deduction / credit on trades
|
||||||
|
- Constraint enforcement (cash, position size)
|
||||||
|
- Snapshot management
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
client: SupabaseClient | None = None,
|
||||||
|
store: ReportStore | None = None,
|
||||||
|
config: dict[str, Any] | None = None,
|
||||||
|
) -> None:
|
||||||
|
"""Initialise the repository.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
client: SupabaseClient instance. Uses ``SupabaseClient.get_instance()``
|
||||||
|
when None.
|
||||||
|
store: ReportStore instance. Creates a default instance when None.
|
||||||
|
config: Portfolio config dict. Uses ``get_portfolio_config()`` when None.
|
||||||
|
"""
|
||||||
|
# TODO: implement — resolve defaults, store as self._client, self._store, self._cfg
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Portfolio lifecycle
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def create_portfolio(
|
||||||
|
self,
|
||||||
|
name: str,
|
||||||
|
initial_cash: float,
|
||||||
|
currency: str = "USD",
|
||||||
|
) -> Portfolio:
|
||||||
|
"""Create a new portfolio with the given starting capital.
|
||||||
|
|
||||||
|
Generates a UUID for ``portfolio_id``. Sets ``cash = initial_cash``.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
name: Human-readable portfolio name.
|
||||||
|
initial_cash: Starting capital in USD (or configured currency).
|
||||||
|
currency: ISO 4217 currency code.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Persisted Portfolio instance.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
DuplicatePortfolioError: If the name is already in use.
|
||||||
|
ValueError: If ``initial_cash <= 0``.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_portfolio(self, portfolio_id: str) -> Portfolio:
|
||||||
|
"""Fetch a portfolio by ID.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If not found.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_portfolio_with_holdings(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
prices: dict[str, float] | None = None,
|
||||||
|
) -> tuple[Portfolio, list[Holding]]:
|
||||||
|
"""Fetch portfolio + all holdings, optionally enriched with current prices.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
prices: Optional ``{ticker: current_price}`` dict. When provided,
|
||||||
|
holdings are enriched and ``Portfolio.enrich()`` is called.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
``(Portfolio, list[Holding])`` — enriched when prices are supplied.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Holdings management
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def add_holding(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str,
|
||||||
|
shares: float,
|
||||||
|
price: float,
|
||||||
|
sector: str | None = None,
|
||||||
|
industry: str | None = None,
|
||||||
|
) -> Holding:
|
||||||
|
"""Buy shares and update portfolio cash and holdings.
|
||||||
|
|
||||||
|
Business logic:
|
||||||
|
- Raises ``InsufficientCashError`` if ``portfolio.cash < shares * price``
|
||||||
|
- If holding already exists: updates ``avg_cost`` using weighted average
|
||||||
|
- ``portfolio.cash -= shares * price``
|
||||||
|
- Records a BUY trade automatically
|
||||||
|
|
||||||
|
Avg cost formula::
|
||||||
|
|
||||||
|
new_avg_cost = (old_shares * old_avg_cost + new_shares * price)
|
||||||
|
/ (old_shares + new_shares)
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
ticker: Ticker symbol.
|
||||||
|
shares: Number of shares to buy (must be > 0).
|
||||||
|
price: Execution price per share.
|
||||||
|
sector: Optional GICS sector name.
|
||||||
|
industry: Optional GICS industry name.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Updated or created Holding.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
InsufficientCashError: If cash would go negative.
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
ValueError: If shares <= 0 or price <= 0.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def remove_holding(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str,
|
||||||
|
shares: float,
|
||||||
|
price: float,
|
||||||
|
) -> Holding | None:
|
||||||
|
"""Sell shares and update portfolio cash and holdings.
|
||||||
|
|
||||||
|
Business logic:
|
||||||
|
- Raises ``HoldingNotFoundError`` if no holding exists for ticker
|
||||||
|
- Raises ``InsufficientSharesError`` if ``holding.shares < shares``
|
||||||
|
- If ``shares == holding.shares``: deletes the holding row, returns None
|
||||||
|
- Otherwise: decrements ``holding.shares`` (avg_cost unchanged on sell)
|
||||||
|
- ``portfolio.cash += shares * price``
|
||||||
|
- Records a SELL trade automatically
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
ticker: Ticker symbol.
|
||||||
|
shares: Number of shares to sell (must be > 0).
|
||||||
|
price: Execution price per share.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Updated Holding, or None if the position was fully closed.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
HoldingNotFoundError: If no holding exists for this ticker.
|
||||||
|
InsufficientSharesError: If holding.shares < shares.
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
ValueError: If shares <= 0 or price <= 0.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Snapshots
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def take_snapshot(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
prices: dict[str, float],
|
||||||
|
) -> PortfolioSnapshot:
|
||||||
|
"""Take an immutable snapshot of the current portfolio state.
|
||||||
|
|
||||||
|
Fetches all holdings, enriches them with ``prices``, computes
|
||||||
|
``total_value``, then persists via ``SupabaseClient.save_snapshot()``.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
prices: ``{ticker: current_price}`` for all held tickers.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Persisted PortfolioSnapshot.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Report convenience methods
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_pm_decision(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
decision: dict[str, Any],
|
||||||
|
markdown: str | None = None,
|
||||||
|
) -> Path:
|
||||||
|
"""Save a PM agent decision and update portfolio.report_path.
|
||||||
|
|
||||||
|
Delegates to ``ReportStore.save_pm_decision()`` then updates the
|
||||||
|
``portfolio.report_path`` column in Supabase to point to the daily
|
||||||
|
portfolio directory.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
date: ISO date string, e.g. ``"2026-03-20"``.
|
||||||
|
decision: PM decision dict.
|
||||||
|
markdown: Optional human-readable markdown version.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Path of the written JSON file.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_pm_decision(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
) -> dict[str, Any] | None:
|
||||||
|
"""Load a PM decision JSON. Returns None if not found.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
date: ISO date string.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def save_risk_metrics(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
metrics: dict[str, Any],
|
||||||
|
) -> Path:
|
||||||
|
"""Save risk computation results. Delegates to ReportStore.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
date: ISO date string.
|
||||||
|
metrics: Risk metrics dict (Sharpe, Sortino, VaR, beta, etc.).
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Path of the written file.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def load_risk_metrics(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
date: str,
|
||||||
|
) -> dict[str, Any] | None:
|
||||||
|
"""Load risk metrics. Returns None if not found.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
date: ISO date string.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
@ -0,0 +1,252 @@
|
||||||
|
"""Supabase database client for the Portfolio Manager.
|
||||||
|
|
||||||
|
Thin wrapper around ``supabase-py`` that:
|
||||||
|
- Provides a singleton connection (one client per process)
|
||||||
|
- Translates Supabase / HTTP errors into domain exceptions
|
||||||
|
- Converts raw DB rows into typed model instances
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
from tradingagents.portfolio.supabase_client import SupabaseClient
|
||||||
|
from tradingagents.portfolio.models import Portfolio
|
||||||
|
|
||||||
|
client = SupabaseClient.get_instance()
|
||||||
|
portfolio = client.get_portfolio("some-uuid")
|
||||||
|
|
||||||
|
Configuration (read from environment via ``get_portfolio_config()``):
|
||||||
|
SUPABASE_URL — Supabase project URL
|
||||||
|
SUPABASE_KEY — Supabase anon or service-role key
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from tradingagents.portfolio.exceptions import (
|
||||||
|
DuplicatePortfolioError,
|
||||||
|
HoldingNotFoundError,
|
||||||
|
PortfolioNotFoundError,
|
||||||
|
)
|
||||||
|
from tradingagents.portfolio.models import (
|
||||||
|
Holding,
|
||||||
|
Portfolio,
|
||||||
|
PortfolioSnapshot,
|
||||||
|
Trade,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class SupabaseClient:
|
||||||
|
"""Singleton Supabase CRUD client for portfolio data.
|
||||||
|
|
||||||
|
All public methods translate Supabase / HTTP errors into domain exceptions
|
||||||
|
and return typed model instances.
|
||||||
|
|
||||||
|
Do not instantiate directly — use ``SupabaseClient.get_instance()``.
|
||||||
|
"""
|
||||||
|
|
||||||
|
_instance: "SupabaseClient | None" = None
|
||||||
|
|
||||||
|
def __init__(self, url: str, key: str) -> None:
|
||||||
|
"""Initialise the Supabase client.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
url: Supabase project URL.
|
||||||
|
key: Supabase anon or service-role key.
|
||||||
|
"""
|
||||||
|
# TODO: implement — create supabase.create_client(url, key)
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def get_instance(cls) -> "SupabaseClient":
|
||||||
|
"""Return the singleton instance, creating it if necessary.
|
||||||
|
|
||||||
|
Reads SUPABASE_URL and SUPABASE_KEY from ``get_portfolio_config()``.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioError: If SUPABASE_URL or SUPABASE_KEY are not configured.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Portfolio CRUD
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def create_portfolio(self, portfolio: Portfolio) -> Portfolio:
|
||||||
|
"""Insert a new portfolio row.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio: Portfolio instance with all required fields set.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Portfolio with DB-assigned timestamps.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
DuplicatePortfolioError: If portfolio_id already exists.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_portfolio(self, portfolio_id: str) -> Portfolio:
|
||||||
|
"""Fetch a portfolio by ID.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Portfolio instance.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If no portfolio has that ID.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def list_portfolios(self) -> list[Portfolio]:
|
||||||
|
"""Return all portfolios ordered by created_at DESC."""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def update_portfolio(self, portfolio: Portfolio) -> Portfolio:
|
||||||
|
"""Update mutable portfolio fields (cash, report_path, metadata).
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio: Portfolio with updated field values.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Updated Portfolio with refreshed updated_at.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def delete_portfolio(self, portfolio_id: str) -> None:
|
||||||
|
"""Delete a portfolio and all associated data (CASCADE).
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the portfolio to delete.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
PortfolioNotFoundError: If portfolio_id does not exist.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Holdings CRUD
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def upsert_holding(self, holding: Holding) -> Holding:
|
||||||
|
"""Insert or update a holding row (upsert on portfolio_id + ticker).
|
||||||
|
|
||||||
|
Args:
|
||||||
|
holding: Holding instance with all required fields set.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Holding with DB-assigned / refreshed timestamps.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_holding(self, portfolio_id: str, ticker: str) -> Holding | None:
|
||||||
|
"""Return the holding for (portfolio_id, ticker), or None if not found.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
ticker: Ticker symbol (case-insensitive, stored as uppercase).
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def list_holdings(self, portfolio_id: str) -> list[Holding]:
|
||||||
|
"""Return all holdings for a portfolio ordered by cost_basis DESC.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def delete_holding(self, portfolio_id: str, ticker: str) -> None:
|
||||||
|
"""Delete the holding for (portfolio_id, ticker).
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
ticker: Ticker symbol.
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
HoldingNotFoundError: If no such holding exists.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Trades
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def record_trade(self, trade: Trade) -> Trade:
|
||||||
|
"""Insert a new trade record. Immutable — no update method.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
trade: Trade instance with all required fields set.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Trade with DB-assigned trade_id and trade_date.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def list_trades(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
ticker: str | None = None,
|
||||||
|
limit: int = 100,
|
||||||
|
) -> list[Trade]:
|
||||||
|
"""Return recent trades for a portfolio, newest first.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: Filter by portfolio.
|
||||||
|
ticker: Optional additional filter by ticker symbol.
|
||||||
|
limit: Maximum number of rows to return.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Snapshots
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def save_snapshot(self, snapshot: PortfolioSnapshot) -> PortfolioSnapshot:
|
||||||
|
"""Insert a new immutable portfolio snapshot.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
snapshot: PortfolioSnapshot with all required fields set.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Snapshot with DB-assigned snapshot_id and snapshot_date.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_latest_snapshot(self, portfolio_id: str) -> PortfolioSnapshot | None:
|
||||||
|
"""Return the most recent snapshot for a portfolio, or None.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def list_snapshots(
|
||||||
|
self,
|
||||||
|
portfolio_id: str,
|
||||||
|
limit: int = 30,
|
||||||
|
) -> list[PortfolioSnapshot]:
|
||||||
|
"""Return snapshots newest-first up to limit.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
portfolio_id: UUID of the target portfolio.
|
||||||
|
limit: Maximum number of snapshots to return.
|
||||||
|
"""
|
||||||
|
# TODO: implement
|
||||||
|
raise NotImplementedError
|
||||||
Loading…
Reference in New Issue