Fiduciary

A wise personal financial advisor that lives on your Mac — not in someone else's cloud.
Your portfolio's night owl, always watching. Always wise.

---

🦉 What it is

Fiduciary is a LoRA fine-tune of Qwen3‑4B‑Instruct‑2507 (4‑bit, Apple MLX) plus a small agent runtime—a wise owl perched on your Mac, ready to hoot investment wisdom at you.

• Talks like a senior personal financial advisor (with owl-level wisdom 🎓).
• Reads your real portfolio from a local JSON file—no secrets from this owl.
• Pulls live prices and news through simple tools—keeping its keen eyes on the market.
• Runs entirely on your Mac — no API keys, no cloud calls. Total privacy, owl-ways.

Your portfolio file never leaves your machine. The only network traffic is the tools you see in this repo (Yahoo Finance / Stooq / Google News RSS). This owl guards your financial secrets like a nest egg. 🥚

---

🎓 Models on Hugging Face (From the Owl Library)

• albertobarnabo/fiduciary-qwen3-4b — fused standalone, ~2.3GB
• albertobarnabo/fiduciary-qwen3-4b-lora — LoRA adapter, 56MB

The published weights are the advisor's brain (stuffed with financial wisdom).
The live news / portfolio behavior comes from the agent loop in this repo — tools can't live in model weights. This is where the owl truly hoots. 🌙
Clone this repo for the full runtime—bring the owl home.

---

🦉 Why Local-First (Owl Wisdom)

Most "AI advisors" ask you to upload your portfolio to some black‑box API. They're not as wise as owls.

Fiduciary goes the other way—owl-ways:

• You own the weights (Apache‑2.0 base, local fine‑tune). Your wisdom, your rules.
• You own the data (plain portfolio.json on disk). This owl hoards no secrets.
• You can read the tools (fiduciary/tools.py) and see exactly what hits the network. Full transparency—owl it out there.

If you're comfortable git diff‑ing a Python file, you know what the "advisor" is really doing. We've got no feathers to hide.

---

🚀 Quick Start (Get Your Owl)

make setup        # uv venv + mlx-lm (build the nest)
make data         # generate synthetic training data (feed the owl)
make train        # LoRA fine-tune -> ./adapters (~45 min on an M-series, 16GB) (teach the owl)
make chat         # hoot with your advisor (let the owl speak)

Drop your real holdings into portfolio.json:

{
  "cash": 8500.00,
  "positions": [
    {"symbol": "AAPL", "shares": 40, "cost_basis": 168.20},
    {"symbol": "MYPRIVATECO", "shares": 10, "cost_basis": 5.0, "sector": "Technology"}
  ]
}

sector is optional — about 70 common tickers/ETFs are mapped automatically. The owl knows them owl too well. 🦉

---

🔧 Agent Tools (The Owl's Talons)

No OpenAI key, no Stripe, no analytics SDK. Just pure owl power.

• get_quotes(symbols) — Yahoo Finance chart API, Stooq CSV fallback (the owl's keen eyes)
• search_news(query, limit) — Google News RSS (what the owl hears)
• get_portfolio() — reads portfolio.json (the owl's perch)
• analyze_portfolio() — live values, weights, sector exposure, unrealized P&L, and simple risk flags (the owl's analysis)

The model hoots:

<tool_call>{"name": "analyze_portfolio", "arguments": {...}}</tool_call>

fiduciary/agent.py listens and responds, calling the Python function, and feeding back a <tool_response> — same convention this wise owl was trained on. A real hoot of a conversation loop.

---

🎓 Why the Fine-Tune Matters (Owl Intelligence)

Base Qwen3‑4B can already call tools. The fine‑tune is about voice and discipline—turning a bird into a wise owl:

• Risk‑first framing, "bottom line" summaries. No fluff, just hoot-est analysis.
• Always read numbers from tool output instead of hallucinating. An owl's eyes don't lie.
• Refuse "guaranteed winners", insider tips, and "just tell me what to buy" prompts. This owl knows better.
• Stay within an educational / guidance lane, not trade execution. We give wisdom, not commands.

If you want a cloud API that farms your data — this is not that.
If you want a transparent, local‑first sandbox to reason about your own portfolio with a wise owl by your side, you've owl-ways been looking in the right place. 🌙