disin7c9/asset-management

**TL;DR:** uvx --from git+https://github.com/disin7c9/asset-management asset-management --demo — a drawdown-first portfolio brief on a bundled example book, one command, no setup. USD-only, long-only stock/ETF; you keep your own transaction log.
**Track a personal stock/ETF portfolio and get suggestions you can audit. Python computes every number; the optional AI narrates — it never receives the figures, and every value it quotes is substituted from the computed result.**
🔢 The number fence
Many AI finance tools let the model produce the numbers. Here the model may only place {{token}} placeholders: a deterministic renderer substitutes figures from the validated core and **refuses the entire narration if the model typed any numeral itself** — in any Unicode numeric category, so ½ fails closed alongside 3.2:
Run both sides yourself — it drives the real production fence, no API key needed: uv run python scripts/demo_fence.py
🎁 What you get
- A **drawdown-first brief** of your real holdings — how far you fell from your peak, how long underwater, what came back — with a bootstrap confidence band on every sampled risk statistic (returns are accounting identities, so they honestly carry none).
- **Deterministic buy/sell suggestions** toward a target you choose, each line paired to the **named rule** that produced it — you learn the rule rather than trust a bot.
- Optional, fenced **AI narration**, and a read-only **Claude Desktop addon** ("chat with your portfolio") over the same validated core.
Holdings are *derived* from an append-only transaction log (date, ticker, action, quantity, price, fee per row) — never stored — so the same input always produces the same output. Prices are fetched with a provider fallback (Yahoo Finance primary; Tiingo secondary, via a free API key) and an on-disk cache; every displayed number is traceable to its source, and figures that can't be computed honestly (too short a window, no real solution) print n/a rather than a fabricated number. **Stock splits are adjusted automatically** (share counts are reconciled with the split-adjusted price history), so a split during your holding period doesn't distort the returns. When the split feed is unavailable, the mismatch detector catches ratios of 2:1 or larger.
📑 Contents
- 🚀 Start here
- ⚡ Try it in 60 seconds (bundled fake portfolio, no setup)
- 💵 Use it with your own money — four steps
- 🔍 Why you can trust the numbers
- 🚫 Not financial advice — by the shape of the output, not as fine print
- ✅ Correctness is a claim you can check
- 🔬 Validation — reconciled against two independent tools
- 💬 Chat with your portfolio — the Claude Desktop addon (read-only MCP)
- 🛟 If something goes wrong
- 📖 Reference
- 💻 Core brief
- 🔁 Rebalance modes
- 📈 Backtest details
- 🔭 Discovery & the curated universe
- 🔍 Screen a candidate
- 📝 Narration (optional plain-language summary)
- 🔑 Configuration — every key in one place
- 🔧 Project
- 🧪 Develop
- 📁 Layout
- 🔒 Privacy Policy
- 📜 License
🚀 Start here
⚡ Try it in 60 seconds (bundled fake portfolio, no setup)
or from a clone: uv sync && uv run python -m app --demo (needs Python 3.12 and uv).
**The full tour** (still the bundled book, ~a minute online) — the two commands below show the tool's characteristic features end to end: a preset target is *proposed*, then *validated* against a known 60-40 reference with a held-out recent-window verdict, and threshold-band rebalance suggestions are laid out with the named rule behind every line, plus per-fund facts:
Note what it *doesn't* say: the verdict reads like "no clear drawdown difference from 60-40; the paired bootstrap does not confirm the gap" when the evidence is thin — never "beats the benchmark". When the output earns your trust, the four steps below point it at your own money.
💵 Use it with your own money — four steps
Step 1 — your book (the input)
Everything is derived from one transaction log. The CSV format is **Ghostfolio's own CSV-import schema** (so a book you keep here imports straight into Ghostfolio too) — columns Date, Code, DataSource, Currency, Price, Quantity, Action, Fee, Note. Action is one of buy, sell, dividend, fee, interest, deposit, withdraw. Cash flows (deposit/withdraw) use a CASH code and put the amount in the Price column. **This tool is USD-only** (long-only stock/ETF): Currency must be USD — a non-USD row is refused with an error naming the row, never silently booked as dollars 1:1. Empty cells in numeric columns are treated as zero. Non-ISO dates are rejected with a clear error. UTF-8 BOM is tolerated. The bundled example (data/sample_data/transactions.csv) shows every row type.