ledgerline 0.3.0__tar.gz

ledgerline-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run pytest -q

ledgerline-0.3.0/.gitignore

@@ -0,0 +1,31 @@
+# Financial data never enters git (Security Invariant 1)
+data/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.csv
+*.ofx
+*.qfx
+.env
+
+# Analysis notebooks carry real query output — never committable
+analysis/
+*.ipynb
+
+# Test fixtures are the one sanctioned exception: fabricated data only
+!tests/fixtures/*.csv
+!tests/fixtures/*.ofx
+!tests/fixtures/*.qfx
+
+# Local tool state (per-machine permission grants, never publishable)
+.claude/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

ledgerline-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerald Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ledgerline-0.3.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: ledgerline
+Version: 0.3.0
+Summary: Local-first personal finance pipeline: ingest bank exports, categorize, detect recurring payments, and expose read-only finance tools to AI agents over MCP
+Project-URL: Homepage, https://github.com/jeraldhu-yuan/ledgerline
+Project-URL: Repository, https://github.com/jeraldhu-yuan/ledgerline
+Project-URL: Issues, https://github.com/jeraldhu-yuan/ledgerline/issues
+Author: Jerald Yuan
+License: MIT License
+        
+        Copyright (c) 2026 Jerald Yuan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: budgeting,local-first,mcp,model-context-protocol,personal-finance,simplefin,sqlite,transactions
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: click>=8.1
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# ledgerline
+
+[![CI](https://github.com/jeraldhu-yuan/ledgerline/actions/workflows/ci.yml/badge.svg)](https://github.com/jeraldhu-yuan/ledgerline/actions/workflows/ci.yml)
+
+Give AI agents read-only access to your finances without giving anyone your
+data: one SQLite file on your machine, no cloud, exact integer-cent answers
+over MCP.
+
+Everything runs locally. Bank access (via SimpleFIN Bridge) is read-only by
+construction — Ledgerline never sees your banking credentials and cannot
+move money. Account numbers are dropped at parse time, so the model can
+never see what the database never contains. Delete the one `.db` file and
+every trace is gone.
+
+<!-- demo.gif goes here
+
+Record this 60-second flow (terminal at ~100x30, then your MCP client):
+  1. (0:00) In an empty directory: `uvx --from ledgerline ledgerline demo`
+     — let the seed summary and "Try these next" block render.
+  2. (0:10) `uvx --from ledgerline ledgerline summary`
+     — pause ~3s on the category table.
+  3. (0:20) `uvx --from ledgerline ledgerline upcoming`
+     — pause ~3s on the expected-charges table.
+  4. (0:30) Paste the `claude mcp add ...` one-liner printed by the demo.
+  5. (0:35) Open Claude Code and ask: "What recurring charges are coming up,
+     and can my checking balance cover them?" — show the answer citing
+     exact amounts from the upcoming_payments tool.
+  6. (0:55) End on the answer.
+-->
+
+## Try it in 90 seconds
+
+No clone, no signup, no API key, no real financial data — the demo seeds six
+months of clearly fabricated transactions so you can evaluate everything
+before connecting anything. [uv](https://docs.astral.sh/uv/getting-started/installation/)
+is the only prerequisite.
+
+```sh
+uvx --from ledgerline ledgerline demo
+uvx --from ledgerline ledgerline summary    # income/outflow by category
+uvx --from ledgerline ledgerline upcoming   # expected charges, next 30 days
+```
+
+`demo` prints copy-paste one-liners that connect the MCP server to Codex or
+Claude Code; then ask things like "What recurring charges are coming up?" or
+"Why was last month so expensive?". When you're done evaluating, delete
+`data/ledgerline.db` and start fresh with real data below. (`demo` refuses
+to write into a database that already has transactions.)
+
+## Quick start with real data
+
+```sh
+git clone https://github.com/jeraldhu-yuan/ledgerline
+cd ledgerline
+uv sync
+```
+
+Then get transactions in. Both paths work, and they can be mixed freely —
+the importer deduplicates.
+
+**Bank sync.** Sign up at <https://bridge.simplefin.org> (SimpleFIN Bridge,
+a small paid service that turns your bank logins into read-only transaction
+feeds — Ledgerline never sees your banking credentials), link your bank(s),
+and create a new app on your account page to get a one-time setup token.
+Then:
+
+```sh
+uv run ledgerline connect    # paste the setup token when prompted
+uv run ledgerline sync       # pull your transactions
+```
+
+`connect` stores the resulting access URL owner-only in
+`~/.config/ledgerline/simplefin.env`. The first `sync` prompts to map each
+bank account to a local label; re-running is always safe, and a stale
+database catches up in provider-friendly 45-day windows. If an institution
+is missing from SimpleFIN's catalog, that account just stays on file
+import — mixing both paths is a supported steady state.
+
+**File import.** Download a CSV/OFX/QFX export from your bank's website:
+
+```sh
+uv run ledgerline ingest export.csv --account "Checking"
+```
+
+The database lives at `data/ledgerline.db` (gitignored); override with
+`--db` or `LEDGERLINE_DB`. No API key is needed for any of this — the two
+optional embedded LLM commands (`categorize`, `ask`) read
+`ANTHROPIC_API_KEY` from the environment, and everything else runs keyless.
+
+## AI agent access (recommended)
+
+Ledgerline runs as a local stdio MCP server exposing read-only tools: data
+freshness, transaction search, spending summaries, period comparisons,
+account balances, upcoming payments, and constrained SQL. The contract is
+deliberately small and uniform — exact integer cents, totals always per
+currency and never combined, and limitations (staleness, uncategorized
+spend, unknown account purpose) reported as data rather than prescriptive
+workflow text. The reasoning is the client model's job; the server's job is
+exact, truthful primitives.
+
+The one cache-writing tool, `refresh_data`, pulls from SimpleFIN at most
+once an hour. A refresh that hits provider errors is recorded as an attempt
+but not a success, and `data_status` discloses the difference.
+
+```sh
+# Codex (user scope)
+codex mcp add ledgerline --env LEDGERLINE_DB=/absolute/path/to/ledgerline.db -- \
+  uvx --from ledgerline ledgerline-mcp
+
+# Claude Code (user scope)
+claude mcp add --scope user --transport stdio \
+  --env LEDGERLINE_DB=/absolute/path/to/ledgerline.db ledgerline -- \
+  uvx --from ledgerline ledgerline-mcp
+```
+
+(From a repo checkout, point the command at
+`/path/to/ledgerline/.venv/bin/ledgerline-mcp` instead of `uvx`.) Restart
+the client, then ask things like "How much did I spend on dining in
+January?" or "What recurring charges are coming up?"
+
+## Usage
+
+```sh
+# Monthly summary: income/outflow by category, top merchants, deltas
+uv run ledgerline summary --month 2026-06
+
+# Resolve uncached merchants with ONE batched LLM call
+uv run ledgerline categorize
+
+# Confirm/correct categories; corrections apply retroactively
+uv run ledgerline review
+
+# Recurring payments
+uv run ledgerline recurring detect
+uv run ledgerline recurring add --label "Course tuition installment" \
+    --amount 850.00 --cadence monthly --day 21
+uv run ledgerline upcoming --days 30
+
+# Embedded Q&A for use without an MCP client (needs ANTHROPIC_API_KEY)
+uv run ledgerline ask "why was June so expensive?"
+
+# CSV dump for analysis elsewhere
+uv run ledgerline export --month 2026-06 --out june.csv
+
+# Durable account context for agents and reports
+uv run ledgerline accounts set-context "Chequing" --purpose mixed \
+  --entity "Northwind Consulting" --business-use-percent 70 \
+  --context "Business income plus personal spending"
+```
+
+Account context (`personal`/`business`/`mixed`/`unknown`, owning entity,
+business-use percentage, free-form note) persists in SQLite and rides along
+on every MCP result, so agents segment cash flow before judging it.
+
+## Contributing a bank profile
+
+If your bank's CSV doesn't auto-detect, the fix is a ~10-line pull request:
+add one dict to `PROFILES` in
+[`ledgerline/ingest/profiles.py`](ledgerline/ingest/profiles.py). OFX/QFX
+needs no profile.
+
+```python
+"us_checking": {
+    "columns": {"date": "Posting Date", "amount": "Amount", "description": "Description"},
+    "date_format": "%m/%d/%Y",
+    "sign": 1,            # -1 if the export shows charges as positive
+    "skip_rows": 0,
+    "external_id_column": None,  # column with a bank-side unique id, if any
+},
+```
+
+Include a small fabricated CSV fixture (invented merchants, never real
+account data) in `tests/fixtures/` and a test asserting it ingests with the
+right sign convention — see `test_sign_convention_profile` in
+[`tests/test_ingest.py`](tests/test_ingest.py) for the pattern.
+
+## Idempotency
+
+Re-importing a file, overlapping export ranges, and sync + file import of the
+same period all produce zero duplicates (tested in `tests/test_ingest.py` and
+`tests/test_sync.py`).
+
+**Design note — one deliberate deviation from the spec:** the spec folds
+FITID into `dedupe_hash` when present. Done literally, that would *create*
+duplicates in mixed mode: a CSV row (no FITID) and a SimpleFIN row (with id)
+for the same transaction would hash differently. Instead:
+
+- `dedupe_hash = sha256(account_id | posted_date | amount_cents | merchant_raw | occurrence_index)`
+  with occurrence counting — the Nth identical row in a batch is a duplicate
+  only if the DB already holds more than N such rows. Two genuinely distinct
+  same-day, same-amount, same-merchant transactions survive because they
+  arrive in the same export with occurrence indexes 0 and 1.
+- Bank-side ids (OFX FITID, SimpleFIN txn id) are stored in `external_id`
+  with a unique per-account index, short-circuit re-imports, and are
+  backfilled onto rows that originally arrived without one.
+
+This satisfies every acceptance test, including both orders of mixed-mode.
+Caveat: cross-source dedupe matches on the raw description, so it works when
+both sources export the same description string (typical for OFX/SimpleFIN
+from the same institution).
+
+## Security invariants
+
+- `data/`, `*.db`, `*.csv`, `*.ofx`, `*.qfx`, `.env`, `analysis/`, and
+  `*.ipynb` gitignored from the first commit; test fixtures and `demo`
+  data are fabricated only.
+- Account numbers are never parsed: the OFX reader and SimpleFIN connector
+  drop `ACCTID`/`BANKID`-class fields at parse time. Only short labels
+  ("US Checking") identify accounts. Asserted in `tests/test_security.py`.
+- The model gets full transaction detail through `run_sql` — by design. What
+  it can never see is what the DB never contains: account numbers,
+  credentials, raw export files.
+- `run_sql`: read-only connection (`mode=ro` URI), single-statement
+  SELECT/WITH only, keyword denylist, SQLite authorizer denying everything
+  but reads, 200-row cap, 5-second time limit, statement/result size limits.
+  Literals and comments are stripped before the keyword scan (a merchant
+  named "UPDATE" is not a false positive); the authorizer and read-only mode
+  are the real guards. Tested with hostile inputs.
+- SimpleFIN access URL from `SIMPLEFIN_ACCESS_URL` or a `0600` config file
+  only — never the repo, the DB, or the LLM context. `https` is required,
+  HTTP redirects are refused (credentials are never replayed to another
+  host), and loose file permissions produce a warning.
+- New database files are created owner-only (`0600`).
+- `ANTHROPIC_API_KEY` from env only; LLM steps fail loudly without it,
+  everything else runs keyless.
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+The suite covers the acceptance checklist: mixed-mode dedupe in both
+orders, quarantine of malformed rows, integer-cents math, per-currency
+reporting, `run_sql` hardening against hostile inputs, recurring detection
+with gap tolerance, the MCP tools, the demo seeder, and the security
+invariants above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ledgerline-0.3.0/README.md

@@ -0,0 +1,241 @@
+# ledgerline
+
+[![CI](https://github.com/jeraldhu-yuan/ledgerline/actions/workflows/ci.yml/badge.svg)](https://github.com/jeraldhu-yuan/ledgerline/actions/workflows/ci.yml)
+
+Give AI agents read-only access to your finances without giving anyone your
+data: one SQLite file on your machine, no cloud, exact integer-cent answers
+over MCP.
+
+Everything runs locally. Bank access (via SimpleFIN Bridge) is read-only by
+construction — Ledgerline never sees your banking credentials and cannot
+move money. Account numbers are dropped at parse time, so the model can
+never see what the database never contains. Delete the one `.db` file and
+every trace is gone.
+
+<!-- demo.gif goes here
+
+Record this 60-second flow (terminal at ~100x30, then your MCP client):
+  1. (0:00) In an empty directory: `uvx --from ledgerline ledgerline demo`
+     — let the seed summary and "Try these next" block render.
+  2. (0:10) `uvx --from ledgerline ledgerline summary`
+     — pause ~3s on the category table.
+  3. (0:20) `uvx --from ledgerline ledgerline upcoming`
+     — pause ~3s on the expected-charges table.
+  4. (0:30) Paste the `claude mcp add ...` one-liner printed by the demo.
+  5. (0:35) Open Claude Code and ask: "What recurring charges are coming up,
+     and can my checking balance cover them?" — show the answer citing
+     exact amounts from the upcoming_payments tool.
+  6. (0:55) End on the answer.
+-->
+
+## Try it in 90 seconds
+
+No clone, no signup, no API key, no real financial data — the demo seeds six
+months of clearly fabricated transactions so you can evaluate everything
+before connecting anything. [uv](https://docs.astral.sh/uv/getting-started/installation/)
+is the only prerequisite.
+
+```sh
+uvx --from ledgerline ledgerline demo
+uvx --from ledgerline ledgerline summary    # income/outflow by category
+uvx --from ledgerline ledgerline upcoming   # expected charges, next 30 days
+```
+
+`demo` prints copy-paste one-liners that connect the MCP server to Codex or
+Claude Code; then ask things like "What recurring charges are coming up?" or
+"Why was last month so expensive?". When you're done evaluating, delete
+`data/ledgerline.db` and start fresh with real data below. (`demo` refuses
+to write into a database that already has transactions.)
+
+## Quick start with real data
+
+```sh
+git clone https://github.com/jeraldhu-yuan/ledgerline
+cd ledgerline
+uv sync
+```
+
+Then get transactions in. Both paths work, and they can be mixed freely —
+the importer deduplicates.
+
+**Bank sync.** Sign up at <https://bridge.simplefin.org> (SimpleFIN Bridge,
+a small paid service that turns your bank logins into read-only transaction
+feeds — Ledgerline never sees your banking credentials), link your bank(s),
+and create a new app on your account page to get a one-time setup token.
+Then:
+
+```sh
+uv run ledgerline connect    # paste the setup token when prompted
+uv run ledgerline sync       # pull your transactions
+```
+
+`connect` stores the resulting access URL owner-only in
+`~/.config/ledgerline/simplefin.env`. The first `sync` prompts to map each
+bank account to a local label; re-running is always safe, and a stale
+database catches up in provider-friendly 45-day windows. If an institution
+is missing from SimpleFIN's catalog, that account just stays on file
+import — mixing both paths is a supported steady state.
+
+**File import.** Download a CSV/OFX/QFX export from your bank's website:
+
+```sh
+uv run ledgerline ingest export.csv --account "Checking"
+```
+
+The database lives at `data/ledgerline.db` (gitignored); override with
+`--db` or `LEDGERLINE_DB`. No API key is needed for any of this — the two
+optional embedded LLM commands (`categorize`, `ask`) read
+`ANTHROPIC_API_KEY` from the environment, and everything else runs keyless.
+
+## AI agent access (recommended)
+
+Ledgerline runs as a local stdio MCP server exposing read-only tools: data
+freshness, transaction search, spending summaries, period comparisons,
+account balances, upcoming payments, and constrained SQL. The contract is
+deliberately small and uniform — exact integer cents, totals always per
+currency and never combined, and limitations (staleness, uncategorized
+spend, unknown account purpose) reported as data rather than prescriptive
+workflow text. The reasoning is the client model's job; the server's job is
+exact, truthful primitives.
+
+The one cache-writing tool, `refresh_data`, pulls from SimpleFIN at most
+once an hour. A refresh that hits provider errors is recorded as an attempt
+but not a success, and `data_status` discloses the difference.
+
+```sh
+# Codex (user scope)
+codex mcp add ledgerline --env LEDGERLINE_DB=/absolute/path/to/ledgerline.db -- \
+  uvx --from ledgerline ledgerline-mcp
+
+# Claude Code (user scope)
+claude mcp add --scope user --transport stdio \
+  --env LEDGERLINE_DB=/absolute/path/to/ledgerline.db ledgerline -- \
+  uvx --from ledgerline ledgerline-mcp
+```
+
+(From a repo checkout, point the command at
+`/path/to/ledgerline/.venv/bin/ledgerline-mcp` instead of `uvx`.) Restart
+the client, then ask things like "How much did I spend on dining in
+January?" or "What recurring charges are coming up?"
+
+## Usage
+
+```sh
+# Monthly summary: income/outflow by category, top merchants, deltas
+uv run ledgerline summary --month 2026-06
+
+# Resolve uncached merchants with ONE batched LLM call
+uv run ledgerline categorize
+
+# Confirm/correct categories; corrections apply retroactively
+uv run ledgerline review
+
+# Recurring payments
+uv run ledgerline recurring detect
+uv run ledgerline recurring add --label "Course tuition installment" \
+    --amount 850.00 --cadence monthly --day 21
+uv run ledgerline upcoming --days 30
+
+# Embedded Q&A for use without an MCP client (needs ANTHROPIC_API_KEY)
+uv run ledgerline ask "why was June so expensive?"
+
+# CSV dump for analysis elsewhere
+uv run ledgerline export --month 2026-06 --out june.csv
+
+# Durable account context for agents and reports
+uv run ledgerline accounts set-context "Chequing" --purpose mixed \
+  --entity "Northwind Consulting" --business-use-percent 70 \
+  --context "Business income plus personal spending"
+```
+
+Account context (`personal`/`business`/`mixed`/`unknown`, owning entity,
+business-use percentage, free-form note) persists in SQLite and rides along
+on every MCP result, so agents segment cash flow before judging it.
+
+## Contributing a bank profile
+
+If your bank's CSV doesn't auto-detect, the fix is a ~10-line pull request:
+add one dict to `PROFILES` in
+[`ledgerline/ingest/profiles.py`](ledgerline/ingest/profiles.py). OFX/QFX
+needs no profile.
+
+```python
+"us_checking": {
+    "columns": {"date": "Posting Date", "amount": "Amount", "description": "Description"},
+    "date_format": "%m/%d/%Y",
+    "sign": 1,            # -1 if the export shows charges as positive
+    "skip_rows": 0,
+    "external_id_column": None,  # column with a bank-side unique id, if any
+},
+```
+
+Include a small fabricated CSV fixture (invented merchants, never real
+account data) in `tests/fixtures/` and a test asserting it ingests with the
+right sign convention — see `test_sign_convention_profile` in
+[`tests/test_ingest.py`](tests/test_ingest.py) for the pattern.
+
+## Idempotency
+
+Re-importing a file, overlapping export ranges, and sync + file import of the
+same period all produce zero duplicates (tested in `tests/test_ingest.py` and
+`tests/test_sync.py`).
+
+**Design note — one deliberate deviation from the spec:** the spec folds
+FITID into `dedupe_hash` when present. Done literally, that would *create*
+duplicates in mixed mode: a CSV row (no FITID) and a SimpleFIN row (with id)
+for the same transaction would hash differently. Instead:
+
+- `dedupe_hash = sha256(account_id | posted_date | amount_cents | merchant_raw | occurrence_index)`
+  with occurrence counting — the Nth identical row in a batch is a duplicate
+  only if the DB already holds more than N such rows. Two genuinely distinct
+  same-day, same-amount, same-merchant transactions survive because they
+  arrive in the same export with occurrence indexes 0 and 1.
+- Bank-side ids (OFX FITID, SimpleFIN txn id) are stored in `external_id`
+  with a unique per-account index, short-circuit re-imports, and are
+  backfilled onto rows that originally arrived without one.
+
+This satisfies every acceptance test, including both orders of mixed-mode.
+Caveat: cross-source dedupe matches on the raw description, so it works when
+both sources export the same description string (typical for OFX/SimpleFIN
+from the same institution).
+
+## Security invariants
+
+- `data/`, `*.db`, `*.csv`, `*.ofx`, `*.qfx`, `.env`, `analysis/`, and
+  `*.ipynb` gitignored from the first commit; test fixtures and `demo`
+  data are fabricated only.
+- Account numbers are never parsed: the OFX reader and SimpleFIN connector
+  drop `ACCTID`/`BANKID`-class fields at parse time. Only short labels
+  ("US Checking") identify accounts. Asserted in `tests/test_security.py`.
+- The model gets full transaction detail through `run_sql` — by design. What
+  it can never see is what the DB never contains: account numbers,
+  credentials, raw export files.
+- `run_sql`: read-only connection (`mode=ro` URI), single-statement
+  SELECT/WITH only, keyword denylist, SQLite authorizer denying everything
+  but reads, 200-row cap, 5-second time limit, statement/result size limits.
+  Literals and comments are stripped before the keyword scan (a merchant
+  named "UPDATE" is not a false positive); the authorizer and read-only mode
+  are the real guards. Tested with hostile inputs.
+- SimpleFIN access URL from `SIMPLEFIN_ACCESS_URL` or a `0600` config file
+  only — never the repo, the DB, or the LLM context. `https` is required,
+  HTTP redirects are refused (credentials are never replayed to another
+  host), and loose file permissions produce a warning.
+- New database files are created owner-only (`0600`).
+- `ANTHROPIC_API_KEY` from env only; LLM steps fail loudly without it,
+  everything else runs keyless.
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+The suite covers the acceptance checklist: mixed-mode dedupe in both
+orders, quarantine of malformed rows, integer-cents math, per-currency
+reporting, `run_sql` hardening against hostile inputs, recurring detection
+with gap tolerance, the MCP tools, the demo seeder, and the security
+invariants above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ledgerline-0.3.0/ledgerline/__init__.py

@@ -0,0 +1,7 @@
+"""ledgerline — local-first personal finance tracker."""
+
+__version__ = "0.3.0"
+
+
+class LedgerlineError(Exception):
+    """User-facing error: print message and exit nonzero, no traceback."""

ledgerline-0.3.0/ledgerline/accounts.py

@@ -0,0 +1,60 @@
+"""Durable account metadata used to interpret financial activity."""
+
+import sqlite3
+from typing import Any
+
+PURPOSES = ("personal", "business", "mixed", "unknown")
+ANALYSIS_TREATMENTS = ("include", "monitor_only", "exclude")
+
+
+def set_context(
+    conn: sqlite3.Connection,
+    account_name: str,
+    *,
+    purpose: str | None = None,
+    entity_name: str | None = None,
+    business_use_percent: int | None = None,
+    context_note: str | None = None,
+    analysis_treatment: str | None = None,
+) -> dict[str, Any]:
+    """Update interpretive metadata without changing bank-sourced fields."""
+    row = conn.execute("SELECT * FROM accounts WHERE name = ?", (account_name,)).fetchone()
+    if not row:
+        raise ValueError(f"unknown account: {account_name}")
+    if purpose is not None and purpose not in PURPOSES:
+        raise ValueError(f"purpose must be one of {', '.join(PURPOSES)}")
+    if business_use_percent is not None and not 0 <= business_use_percent <= 100:
+        raise ValueError("business_use_percent must be between 0 and 100")
+    if analysis_treatment is not None and analysis_treatment not in ANALYSIS_TREATMENTS:
+        raise ValueError(
+            f"analysis_treatment must be one of {', '.join(ANALYSIS_TREATMENTS)}"
+        )
+
+    updates: dict[str, object | None] = {}
+    if purpose is not None:
+        updates["purpose"] = purpose
+        if business_use_percent is None:
+            if purpose == "personal":
+                updates["business_use_percent"] = 0
+            elif purpose == "business":
+                updates["business_use_percent"] = 100
+            elif purpose == "unknown":
+                updates["business_use_percent"] = None
+    if entity_name is not None:
+        updates["entity_name"] = entity_name.strip() or None
+    if business_use_percent is not None:
+        updates["business_use_percent"] = business_use_percent
+    if context_note is not None:
+        updates["context_note"] = context_note.strip() or None
+    if analysis_treatment is not None:
+        updates["analysis_treatment"] = analysis_treatment
+    if not updates:
+        raise ValueError("provide at least one account metadata field to update")
+
+    assignments = ", ".join(f"{column} = ?" for column in updates)
+    conn.execute(
+        f"UPDATE accounts SET {assignments} WHERE id = ?",
+        [*updates.values(), row["id"]],
+    )
+    conn.commit()
+    return dict(conn.execute("SELECT * FROM accounts WHERE id = ?", (row["id"],)).fetchone())