Asset Management

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:

 the model wrote                             │  the reader gets

─────────────────────────────────────────────┼───────────────────────────────────────────── "Your deepest stretch fell │ "Your deepest stretch fell -9.84% from {{max_drawdown}} from its peak, and an │ its peak, and an ulcer index of 2.38% ulcer index of {{ulcer}} says the ride │ says the ride stayed shallow." stayed shallow." │ ✔ every figure substituted from the │ validated core ─────────────────────────────────────────────┼───────────────────────────────────────────── "Your portfolio fell 12% but recovered │ (no summary at all) nicely — don't worry." │ ✘ REFUSED — one model-typed numeral voids │ the entire note; the brief prints │ without it

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)

uvx --from git+https://github.com/disin7c9/asset-management asset-management --demo

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:

uvx --from git+https://github.com/disin7c9/asset-management asset-management --demo --allocate moderate --allocate-out demo_target.csv

uvx --from git+https://github.com/disin7c9/asset-management asset-management --demo --backtest --target demo_target.csv --benchmark 60-40 --rebalance bands --metadata

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.

Already use [Ghostfolio](https://ghostfol.io)? Point the input straight at a Ghostfolio JSON export (Portfolio → Activities → ⋯ → Export) — the loader detects it and reads it directly, no conversion step. It reads the activities (a dividend's cash = quantity × unitPrice; Ghostfolio's UTC timestamps are rounded back to your local date) and skips non-USD, crypto, and non-security (ITEM/LIABILITY) rows with a warning (USD-only, long-only equity/ETF for now). Brokers without a native Ghostfolio account can run a community converter such as Export-To-Ghostfolio (26 brokers → a Ghostfolio JSON) first.

uv run python -m app --book your.csv                     # or ghostfolio-export.json — auto-detected

uv run python -m app --book your.csv --dry-run # preview an import BEFORE trusting it:

format, events, skipped rows with reasons,

derived holdings — fetches nothing

Set your default once in a gitignored .env at the repo root — ASSET_BOOK=path/to/your.csv (and optionally ASSET_TARGET=path/to/target.csv) — and a bare python -m app becomes your brief. Explicit flags always win. There is no silent built-in default: without --book or ASSET_BOOK, a book-dependent action errors out and a bare run prints a hint — the bundled example is opt-in (--demo), never assumed.

Step 2 — warm the cache (once)

The core is offline-first: prices come from an on-disk cache, refreshed when you run online. After a fresh clone, fill it once:

uv run python -m app --book your.csv --warm        # your tickers + the benchmark references

uv run python -m app --book your.csv --warm full # + the ~375-ETF discovery universe (slow) —

only needed for offline --discover

After that, --offline runs and the Claude Desktop addon serve entirely from this cache (--cache-dir / ASSET_CACHE_DIR override the location).

Optional but recommended: add a free Tiingo API key to .env — TIINGO_API_KEY=... — to enable the second price source. Yahoo Finance throttles bursts of requests now and then; with a key the fetch falls back to Tiingo instead of reporting tickers missing. Without one, the tool fetches from Yahoo only.

Step 3 — choose a target

Most of the decision features (--rebalance, --backtest, the held-out checks) work toward a target allocation — a small CSV (Ticker,Weight) that *you* own and edit. Three ways to get one, by where you're starting from:

• You already hold a portfolio → --dump-target target.csv writes your current allocation; edit it toward the mix you want. (A target is a *complete spec* — see Rebalance modes for the exit semantics.)
• Start from a risk posture → --onboard asks three plain questions in the terminal (horizon / loss response / cash buffer) and builds the matched preset; or pick it yourself with --allocate conservative|moderate|aggressive. Save with --allocate-out target.csv. Both run with no book at all — before your first trade, every role fills from the curated universe. These are strategic role-bucket templates (stocks / bonds / diversifiers split by posture, core-satellite within each bucket): a role you already hold resolves to *your* largest fund in it, a role you're missing is filled with a sensible default ETF from the curated universe.
• Explore and build it yourself → --discover suggests screened ETFs for the roles you're light in; --screen QQQM,SCHD judges any candidate against your book (cost, liquidity, age, overlap, and whether it actually diversified *your* worst drawdowns). Then write the CSV by hand.

Two simpler re-weighting rules also exist — --allocate equal_weight (1/N; the robust baseline) and --allocate inverse_vol (each holding contributes roughly the same *risk* rather than the same dollars; cap any single weight with --allocate-cap 0.30). Deliberately not included: return-forecasting optimizers (mean-variance / max-Sharpe) — they overfit, so they stay behind an *edge* gate for a later version.

Validate the target before following it:

uv run python -m app --backtest --target target.csv --benchmark 60-40   # or all-weather | permanent

simulates your target and the reference over their common history (notional $10k, drawdown-first legs with CIs) and adds a held-out recent-window verdict: shallower / deeper / inconclusive / insufficient — never "beats". The verdic