getfin 1.0.0__tar.gz

getfin-1.0.0/.gitignore

@@ -0,0 +1,23 @@
+.env
+
+data/
+exports/
+
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+*.log
+*.pyc
+*.pyo
+*.pyd
+*.sqlite
+*.db
+*.test_backup
+.vscode/
+
+# Local files
+.claude/
+BACKLOG.md
+buglist.txt

getfin-1.0.0/LICENSE

@@ -0,0 +1,133 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright Arclight Engineering (http://www.arclighteng.com)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

getfin-1.0.0/PKG-INFO

@@ -0,0 +1,499 @@
+Metadata-Version: 2.4
+Name: getfin
+Version: 1.0.0
+Summary: Local-first personal finance — sync with your bank, detect subscriptions, track spending. All data stays on your machine.
+Project-URL: Homepage, https://github.com/arclighteng/fin
+Project-URL: Documentation, https://github.com/arclighteng/fin#readme
+Author-email: Arclight Engineering <hello@arclighteng.com>
+License: # PolyForm Noncommercial License 1.0.0
+        
+        <https://polyformproject.org/licenses/noncommercial/1.0.0>
+        
+        Required Notice: Copyright Arclight Engineering (http://www.arclighteng.com)
+        
+        ## Acceptance
+        
+        In order to get any license under these terms, you must agree
+        to them as both strict obligations and conditions to all
+        your licenses.
+        
+        ## Copyright License
+        
+        The licensor grants you a copyright license for the
+        software to do everything you might do with the software
+        that would otherwise infringe the licensor's copyright
+        in it for any permitted purpose.  However, you may
+        only distribute the software according to [Distribution
+        License](#distribution-license) and make changes or new works
+        based on the software according to [Changes and New Works
+        License](#changes-and-new-works-license).
+        
+        ## Distribution License
+        
+        The licensor grants you an additional copyright license
+        to distribute copies of the software.  Your license
+        to distribute covers distributing the software with
+        changes and new works permitted by [Changes and New Works
+        License](#changes-and-new-works-license).
+        
+        ## Notices
+        
+        You must ensure that anyone who gets a copy of any part of
+        the software from you also gets a copy of these terms or the
+        URL for them above, as well as copies of any plain-text lines
+        beginning with `Required Notice:` that the licensor provided
+        with the software.  For example:
+        
+        > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+        
+        ## Changes and New Works License
+        
+        The licensor grants you an additional copyright license to
+        make changes and new works based on the software for any
+        permitted purpose.
+        
+        ## Patent License
+        
+        The licensor grants you a patent license for the software that
+        covers patent claims the licensor can license, or becomes able
+        to license, that you would infringe by using the software.
+        
+        ## Noncommercial Purposes
+        
+        Any noncommercial purpose is a permitted purpose.
+        
+        ## Personal Uses
+        
+        Personal use for research, experiment, and testing for
+        the benefit of public knowledge, personal study, private
+        entertainment, hobby projects, amateur pursuits, or religious
+        observance, without any anticipated commercial application,
+        is use for a permitted purpose.
+        
+        ## Noncommercial Organizations
+        
+        Use by any charitable organization, educational institution,
+        public research organization, public safety or health
+        organization, environmental protection organization,
+        or government institution is use for a permitted purpose
+        regardless of the source of funding or obligations resulting
+        from the funding.
+        
+        ## Fair Use
+        
+        You may have "fair use" rights for the software under the
+        law. These terms do not limit them.
+        
+        ## No Other Rights
+        
+        These terms do not allow you to sublicense or transfer any of
+        your licenses to anyone else, or prevent the licensor from
+        granting licenses to anyone else.  These terms do not imply
+        any other licenses.
+        
+        ## Patent Defense
+        
+        If you make any written claim that the software infringes or
+        contributes to infringement of any patent, your patent license
+        for the software granted under these terms ends immediately. If
+        your company makes such a claim, your patent license ends
+        immediately for work on behalf of your company.
+        
+        ## Violations
+        
+        The first time you are notified in writing that you have
+        violated any of these terms, or done anything with the software
+        not covered by your licenses, your licenses can nonetheless
+        continue if you come into full compliance with these terms,
+        and take practical steps to correct past violations, within
+        32 days of receiving notice.  Otherwise, all your licenses
+        end immediately.
+        
+        ## No Liability
+        
+        ***As far as the law allows, the software comes as is, without
+        any warranty or condition, and the licensor will not be liable
+        to you for any damages arising out of these terms or the use
+        or nature of the software, under any kind of legal claim.***
+        
+        ## Definitions
+        
+        The **licensor** is the individual or entity offering these
+        terms, and the **software** is the software the licensor makes
+        available under these terms.
+        
+        **You** refers to the individual or entity agreeing to these
+        terms.
+        
+        **Your company** is any legal entity, sole proprietorship,
+        or other kind of organization that you work for, plus all
+        organizations that have control over, are under the control of,
+        or are under common control with that organization.  **Control**
+        means ownership of substantially all the assets of an entity,
+        or the power to direct its management and policies by vote,
+        contract, or otherwise.  Control can be direct or indirect.
+        
+        **Your licenses** are all the licenses granted to you for the
+        software under these terms.
+        
+        **Use** means anything you do with the software requiring one
+        of your licenses.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.12
+Requires-Dist: fastapi
+Requires-Dist: filelock>=3.13.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rich>=13.7.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: tzdata>=2024.1
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'ml'
+Requires-Dist: torch>=2.0.0; extra == 'ml'
+Description-Content-Type: text/markdown
+
+# fin
+
+A local-first personal finance tool. Syncs with your bank accounts via SimpleFIN or import CSV directly—analyzes spending patterns, detects subscriptions, and keeps your data local with encrypted backups.
+
+## Features
+
+**Security & Privacy**
+- **Local-Only Data**: All data stays on your machine in SQLite. No cloud sync, no tracking.
+- **System Keyring**: Credentials stored in OS secure storage (Keychain, Credential Manager, Secret Service)
+- **Encrypted Backups**: Age encryption for portable, audited backup files
+
+**Accuracy & Trust**
+- **Known Service Detection**: 150+ subscription services recognized instantly (Netflix, Spotify, etc.)
+- **Pattern Validation**: `fin audit-subs` verifies detection accuracy—no false positives
+- **Manual Override**: Correct any miscategorization; your choice persists
+
+**Analysis**
+- **Dashboard**: Visual overview of income, spending, alerts, and subscriptions
+- **Smart Categorization**: Automatic transaction categorization with manual override
+- **Subscription Detection**: Finds recurring charges and separates subscriptions from utility bills
+- **Alerts**: Detects duplicate charges, unusual amounts, price increases
+- **Bundle Detection**: Flags potential duplicate subscriptions (Disney+/Hulu/ESPN+ overlap)
+
+**Interface**
+- **Web Dashboard**: Full-featured UI at localhost
+- **CLI Tools**: Complete command-line interface for automation
+- **Mobile Responsive**: Works on phone, tablet, and desktop
+- **Dark Mode**: Easy on the eyes
+
+## Getting Started
+
+> **Two install paths are in progress.** A guided installer (no Python required, wizard-based setup) is under active development. The manual path below is current and stable.
+
+### Manual Install (Python required)
+
+```bash
+# 1. Create virtual environment
+python -m venv .venv
+.venv\Scripts\activate  # Windows
+# source .venv/bin/activate  # Mac/Linux
+
+# 2. Install
+pip install -e .
+
+# 3. Start the web dashboard
+fin web
+# Browser opens automatically to http://127.0.0.1:8000/dashboard
+# If no data exists, demo data loads with a "Connect your bank" banner
+```
+
+The database is stored automatically at:
+- **Windows**: `%APPDATA%\fin\fin.db`
+- **macOS/Linux**: `~/.local/share/fin/fin.db`
+
+Override with `FIN_DB_PATH` if needed.
+
+### Connecting Your Bank
+
+From the dashboard, click **"Connect your bank"** to open the setup page. Two options:
+
+**Import CSV** (easiest — no account required)
+1. Log into your bank and download a transaction export (CSV)
+2. Drag and drop it onto the import page
+3. fin detects the format automatically for Chase, BofA, Amex, Wells Fargo, and Capital One; shows a preview before importing
+
+**SimpleFIN** (automatic daily sync, ~$1.50/month)
+1. Go to [SimpleFIN Bridge](https://beta-bridge.simplefin.org/), subscribe, and link your bank
+2. Copy your Setup Token
+3. Paste it into the SimpleFIN section on the connect page
+
+See [docs/SIMPLEFIN_SETUP.md](docs/SIMPLEFIN_SETUP.md) for detailed SimpleFIN instructions.
+
+### Docker
+
+```bash
+# 1. Configure
+cp .env.example .env
+# Edit .env with your SimpleFIN access URL
+
+# 2. Build & run
+docker compose build
+docker compose run --rm fin sync
+docker compose run --rm fin web
+```
+
+## Security
+
+Your financial data is sensitive. fin is designed with security as a priority.
+
+### Credential Storage
+
+**Recommended: System Keyring**
+
+```bash
+fin credentials set
+# Prompted for SimpleFIN Access URL, stored securely
+```
+
+Credentials are stored in:
+- **Windows**: Credential Manager
+- **macOS**: Keychain
+- **Linux**: Secret Service (GNOME Keyring, KWallet)
+
+Check status: `fin credentials status`
+
+**Alternative: Environment File**
+
+Create a `.env` file (gitignored):
+
+```bash
+SIMPLEFIN_ACCESS_URL=https://your-access-url-from-simplefin
+```
+
+Keyring takes priority over .env if both are configured.
+
+### Data Protection
+
+**Full-Disk Encryption (Recommended)**
+
+Enable your OS's built-in encryption:
+
+| OS | Solution |
+|----|----------|
+| Windows | BitLocker (Pro/Enterprise) or VeraCrypt |
+| macOS | FileVault |
+| Linux | LUKS |
+
+This protects your database at rest with zero configuration in fin.
+
+**Encrypted Backups**
+
+```bash
+# Create encrypted backup with passphrase
+fin export-backup -p
+
+# Or with age public key (for automated backups)
+fin export-backup -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+# Decrypt later
+age -d -o fin.db fin_backup_20260123.finbak
+```
+
+Requires `age`: `winget install FiloSottile.age` (Windows) / `brew install age` (macOS) / `apt install age` (Linux).
+
+### Why This Architecture?
+
+We chose OS-level encryption + encrypted exports over SQLCipher because:
+1. Zero configuration for users who already have FileVault/BitLocker enabled
+2. No additional dependencies or build complexity
+3. `age` is a modern, audited tool with better key management
+4. You control when encryption happens (backups) vs always-on overhead
+
+## Web Dashboard
+
+The dashboard displays your financial overview in a 5-card responsive layout.
+
+### Card 1: Cash Flow (Hero)
+Shows income vs expenses side-by-side with a big "Kept $X" or "Over $X" number, savings rate, and a 3-month rolling comparison. Mid-month pacing projection appears if you're still in the current month. Pending transactions show a warning if they exceed the typical threshold.
+
+### Card 2: Monthly Commitments
+Lists detected subscriptions and utility bills (using pattern detection over 400 days). Click any item to see all transactions from that merchant. Shows total committed this month as a percentage of income with a color-coded bar (green under 50%, yellow 50-70%, red over 70%). Inline price change alerts flag recent increases. Footer breaks down subscription vs bill totals.
+
+### Card 3: Spending Breakdown
+Top 7 spending categories with horizontal bars and 3-month averages. Click any category to drill down to merchants and transactions. Outlier badges (+X%) highlight categories that exceed their 3-month average. Footer shows total vs 3-month comparison.
+
+### Card 4: Heads Up
+Shows unusual charges with dismiss actions ("Looks fine" / "Flag it"), multi-month spending trends, and bill deviation alerts. When empty, displays "Nothing unusual this month."
+
+### Card 5: Your Trend
+6-month bar chart of net cash flow (kept vs over). Green bars for positive months, red for negative. Current month shown as dashed outline. Click any bar to navigate to that month. Footer shows 6-month average.
+
+### Navigation & Controls
+- **Month navigation**: Previous/next buttons with current month indicator dot
+- **Account filter**: Multi-select dropdown to focus on specific accounts
+- **Transaction search**: Live results dropdown—type a merchant name or amount to find transactions
+- **Keyboard accessible**: Tab navigation, Enter to select, Escape to close dropdowns
+
+### Drilldown System
+Click any number, bar, category, or merchant to open a modal with the full transaction list. Sortable columns, account filtering, and scopes including income, spend, recurring, discretionary, net, merchant, and category.
+
+## Other Pages
+
+**Connect** (`/connect`)
+Import CSV files or connect via SimpleFIN. Drag-and-drop CSV upload with automatic format detection for major banks.
+
+**Recurring Charges** (`/subs`)
+Dedicated page for subscriptions and utility bills. Filter by account, see payment history, toggle between subscription and bill types, and export to CSV.
+
+**Budget** (`/budget`)
+Set spending targets by category. Compare targets vs actual spending with visual indicators.
+
+**Audit** (`/audit`)
+Review and correct transaction categorization. Manages override history for future reference.
+
+## Subscription Detection
+
+fin uses a two-tier approach to find subscriptions:
+
+### Known Services (Instant)
+
+150+ well-known services are recognized immediately, even with just one charge:
+- Streaming: Netflix, Hulu, Disney+, HBO Max, YouTube TV, Spotify
+- Software: Adobe, Microsoft 365, GitHub, ChatGPT, 1Password
+- Fitness: Peloton, Planet Fitness, Strava
+- And many more...
+
+### Pattern Detection (3+ charges)
+
+Unknown merchants are detected via:
+- Consistent amounts (low variance)
+- Regular intervals (weekly, monthly, annual)
+- Recurring payment indicators
+
+### Verifying Accuracy
+
+```bash
+# Audit what's being detected
+fin audit-subs
+
+# Show all detected (including pattern-based)
+fin audit-subs --all
+```
+
+### Bundle Detection
+
+```bash
+fin bundle-check
+```
+
+Flags vendor families where you might be paying twice (Disney+/Hulu/ESPN+, Apple services, etc.)
+
+## CLI Commands
+
+### Everyday Use
+
+| Command | Description |
+|---------|-------------|
+| `fin sync` | Pull latest transactions from bank |
+| `fin web` | Start the web dashboard (browser opens automatically) |
+| `fin web --no-browser` | Start without auto-opening browser |
+| `fin status` | Financial status at a glance (CLI) |
+| `fin trend` | Monthly trend over time |
+
+### Analysis & Audit
+
+| Command | Description |
+|---------|-------------|
+| `fin drill recurring` | All recurring expenses |
+| `fin drill one-offs` | Discretionary spending |
+| `fin drill alerts` | All alerts with details |
+| `fin drill income` | Income sources |
+| `fin audit-subs` | Verify subscription detection accuracy |
+| `fin bundle-check` | Find duplicate/overlapping subscriptions |
+| `fin dashboard-cli` | Full CLI dashboard with alerts |
+
+### Export & Backup
+
+| Command | Description |
+|---------|-------------|
+| `fin export-csv` | Export all data to CSV files |
+| `fin export-backup -p` | Encrypted backup with passphrase |
+| `fin export-backup -r age1...` | Encrypted backup to recipient key |
+| `fin export-summary` | Income vs spend summary with rolling averages |
+| `fin export-duplicates` | Export duplicate subscription groups |
+| `fin import-csv FILE` | Import transactions from CSV (CLI) |
+
+### Credentials & Setup
+
+| Command | Description |
+|---------|-------------|
+| `fin setup TOKEN` | Exchange SimpleFIN setup token for access URL |
+| `fin credentials set` | Store credentials in system keyring |
+| `fin credentials status` | Show credential source (keyring/env/none) |
+| `fin credentials clear` | Remove credentials from keyring |
+
+## Sync Options
+
+```bash
+# Daily sync (14 days) - catches new transactions
+fin sync --quick
+
+# Weekly sync (30 days) - default, covers statement cycle
+fin sync
+
+# After vacation/absence (120 days)
+fin sync --full
+
+# January annual (400 days) - finds yearly subscriptions
+fin sync --annual-bootstrap
+```
+
+## Troubleshooting
+
+### "No transactions found"
+Run `fin sync --full` to pull more history, or import a CSV from `/connect`.
+
+### Categories are wrong
+Click the category in the dashboard, then click the edit icon to override.
+
+### Subscription showing as Bill (or vice versa)
+Click the type badge on the Recurring page to toggle.
+
+### Suspicious subscription detection
+Run `fin audit-subs` to verify what's being detected.
+
+### Alerts not showing expected transactions
+Use the date pickers to select a custom range, or click the month navigation to reset to the current month.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+FIN_DB_PATH=/tmp/test.db pytest
+
+# Type checking
+mypy src/fin
+```
+
+## License
+
+PolyForm Noncommercial 1.0.0