finance-cli 1.0.0__tar.gz

finance_cli-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.env
+
+finance_cli/data/finance.db
+finance_cli/data/*.db-shm
+finance_cli/data/*.db-wal
+logs/
+inbox/
+exports/mcp_cache/
+dist/
+build/
+*.egg-info/

finance_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Henry Chien
+
+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.

finance_cli-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: finance-cli
+Version: 1.0.0
+Summary: Personal finance CLI: bank statement import, transaction categorization, budgets, and net worth tracking
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: fastmcp>=2.0; extra == 'all'
+Requires-Dist: plaid-python>=20.0; extra == 'all'
+Requires-Dist: schwab-py>=1.0; extra == 'all'
+Requires-Dist: stripe>=7.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastmcp>=2.0; extra == 'dev'
+Requires-Dist: plaid-python>=20.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: schwab-py>=1.0; extra == 'dev'
+Requires-Dist: stripe>=7.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == 'mcp'
+Provides-Extra: plaid
+Requires-Dist: plaid-python>=20.0; extra == 'plaid'
+Provides-Extra: providers
+Requires-Dist: plaid-python>=20.0; extra == 'providers'
+Requires-Dist: schwab-py>=1.0; extra == 'providers'
+Requires-Dist: stripe>=7.0; extra == 'providers'
+Provides-Extra: schwab
+Requires-Dist: schwab-py>=1.0; extra == 'schwab'
+Provides-Extra: stripe
+Requires-Dist: stripe>=7.0; extra == 'stripe'
+Description-Content-Type: text/markdown
+
+# finance-cli
+
+Personal finance CLI and MCP server for AI-assisted financial management.
+
+Import bank statements (Plaid, CSV, PDF), categorize transactions via rules + AI,
+track budgets, subscriptions, debt, and net worth. SQLite backend, 130 MCP tools
+for Claude Code integration.
+
+## Features
+
+- **Multi-source import**: Plaid API, CSV statements, PDF statements (AI-parsed)
+- **Smart categorization**: Keyword rules → vendor memory → Plaid PFC → AI fallback
+- **Budget tracking**: Per-category budgets with alerts and forecasting
+- **Debt management**: Dashboard, paydown simulator, spending impact analysis
+- **Subscription detection**: Fixed + metered recurring charge detection
+- **Business accounting**: P&L, Schedule C, estimated tax, 1099 tracking
+- **Net worth tracking**: Balance snapshots, investment accounts, projections
+- **130 MCP tools**: Full Claude Code integration for AI-assisted workflows
+
+## Quick Start
+
+```bash
+pip install -e ".[all]"     # Install with all provider extras
+finance-cli setup init       # Initialize database and seed categories
+finance-cli setup connect    # Link bank accounts via Plaid
+finance-cli plaid sync       # Sync transactions
+finance-cli daily            # Today's spending summary
+```
+
+## Installation
+
+```bash
+# Core only (categorization, budgets, reports)
+pip install -e .
+
+# With specific providers
+pip install -e ".[plaid]"       # Plaid bank sync
+pip install -e ".[stripe]"      # Stripe revenue tracking
+pip install -e ".[mcp]"         # Claude Code MCP server
+pip install -e ".[all]"         # Everything
+```
+
+## Configuration
+
+Set environment variables (or use a `.env` file):
+
+```bash
+# Plaid (optional)
+PLAID_CLIENT_ID=...
+PLAID_SECRET=...
+PLAID_ENV=production
+
+# Stripe (optional)
+STRIPE_API_KEY=...
+
+# AI categorization (optional)
+OPENAI_API_KEY=...
+ANTHROPIC_API_KEY=...
+```
+
+## MCP Server (Claude Code)
+
+```bash
+claude mcp add finance-cli -- python3 -m finance_cli.mcp_server
+```
+
+## Documentation
+
+- [How It Works](docs/overview/HOW_IT_WORKS.md) — Architecture overview
+- [Project Guide](docs/overview/PROJECT_GUIDE.md) — Detailed project guide
+- [Agent Workflows](docs/AGENT_WORKFLOWS.md) — AI agent operational playbooks
+- [Import Workflow](docs/ingest/INGEST_WORKFLOW.md) — Bank statement import guide
+- [Adding Institutions](docs/developer/ADD_INSTITUTION_RUNBOOK.md) — CSV normalizer guide
+
+## Requirements
+
+- Python 3.11+
+- SQLite (included with Python)
+
+## License
+
+MIT

finance_cli-1.0.0/README.md

@@ -0,0 +1,82 @@
+# finance-cli
+
+Personal finance CLI and MCP server for AI-assisted financial management.
+
+Import bank statements (Plaid, CSV, PDF), categorize transactions via rules + AI,
+track budgets, subscriptions, debt, and net worth. SQLite backend, 130 MCP tools
+for Claude Code integration.
+
+## Features
+
+- **Multi-source import**: Plaid API, CSV statements, PDF statements (AI-parsed)
+- **Smart categorization**: Keyword rules → vendor memory → Plaid PFC → AI fallback
+- **Budget tracking**: Per-category budgets with alerts and forecasting
+- **Debt management**: Dashboard, paydown simulator, spending impact analysis
+- **Subscription detection**: Fixed + metered recurring charge detection
+- **Business accounting**: P&L, Schedule C, estimated tax, 1099 tracking
+- **Net worth tracking**: Balance snapshots, investment accounts, projections
+- **130 MCP tools**: Full Claude Code integration for AI-assisted workflows
+
+## Quick Start
+
+```bash
+pip install -e ".[all]"     # Install with all provider extras
+finance-cli setup init       # Initialize database and seed categories
+finance-cli setup connect    # Link bank accounts via Plaid
+finance-cli plaid sync       # Sync transactions
+finance-cli daily            # Today's spending summary
+```
+
+## Installation
+
+```bash
+# Core only (categorization, budgets, reports)
+pip install -e .
+
+# With specific providers
+pip install -e ".[plaid]"       # Plaid bank sync
+pip install -e ".[stripe]"      # Stripe revenue tracking
+pip install -e ".[mcp]"         # Claude Code MCP server
+pip install -e ".[all]"         # Everything
+```
+
+## Configuration
+
+Set environment variables (or use a `.env` file):
+
+```bash
+# Plaid (optional)
+PLAID_CLIENT_ID=...
+PLAID_SECRET=...
+PLAID_ENV=production
+
+# Stripe (optional)
+STRIPE_API_KEY=...
+
+# AI categorization (optional)
+OPENAI_API_KEY=...
+ANTHROPIC_API_KEY=...
+```
+
+## MCP Server (Claude Code)
+
+```bash
+claude mcp add finance-cli -- python3 -m finance_cli.mcp_server
+```
+
+## Documentation
+
+- [How It Works](docs/overview/HOW_IT_WORKS.md) — Architecture overview
+- [Project Guide](docs/overview/PROJECT_GUIDE.md) — Detailed project guide
+- [Agent Workflows](docs/AGENT_WORKFLOWS.md) — AI agent operational playbooks
+- [Import Workflow](docs/ingest/INGEST_WORKFLOW.md) — Bank statement import guide
+- [Adding Institutions](docs/developer/ADD_INSTITUTION_RUNBOOK.md) — CSV normalizer guide
+
+## Requirements
+
+- Python 3.11+
+- SQLite (included with Python)
+
+## License
+
+MIT

finance_cli-1.0.0/finance_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Personal finance CLI package."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0"

finance_cli-1.0.0/finance_cli/__main__.py

@@ -0,0 +1,166 @@
+"""CLI entry point for finance_cli."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .commands import (
+    account_cmd,
+    balance_cmd,
+    biz_cmd,
+    budget,
+    cat,
+    daily,
+    debt_cmd,
+    db_cmd,
+    dedup_cmd,
+    export,
+    goal_cmd,
+    ingest,
+    liability_cmd,
+    liquidity_cmd,
+    monthly_cmd,
+    notify_cmd,
+    plaid_cmd,
+    plan,
+    projection_cmd,
+    provider_cmd,
+    rules,
+    setup_cmd,
+    stripe_cmd,
+    schwab_cmd,
+    spending_cmd,
+    subs,
+    summary_cmd,
+    txn,
+    weekly,
+)
+from .commands.common import error_envelope, print_envelope, success_envelope
+from .config import load_dotenv
+from .db import connect, initialize_database
+from .logging_config import setup_logging
+from .migrate_legacy import migrate_legacy_source
+
+
+class CLIParseError(Exception):
+    """Raised when CLI argument parsing fails with non-zero exit status."""
+
+    def __init__(self, message: str, exit_code: int = 2) -> None:
+        super().__init__(message)
+        self.exit_code = int(exit_code)
+
+
+class SafeArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that raises exceptions instead of exiting on parse errors."""
+
+    def error(self, message: str) -> None:
+        raise CLIParseError(message, exit_code=2)
+
+    def exit(self, status: int = 0, message: str | None = None) -> None:
+        if status == 0:
+            super().exit(status=status, message=message)
+            return
+        detail = (message or "").strip() or "Argument parsing failed"
+        raise CLIParseError(detail, exit_code=status)
+
+
+def register_migrate_command(subparsers, format_parent) -> None:
+    parser = subparsers.add_parser("migrate", parents=[format_parent], help="Migrate legacy financial_system CSVs")
+    parser.add_argument("--source", required=True)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.set_defaults(func=handle_migrate, command_name="migrate")
+
+
+def handle_migrate(args, conn):
+    summary = migrate_legacy_source(conn, source_dir=args.source, dry_run=args.dry_run)
+    txn_inserted = sum(item["inserted"] for item in summary.get("transactions", []))
+    cli_report = f"Migrated {len(summary.get('transactions', []))} files, inserted={txn_inserted}"
+    return {
+        "data": summary,
+        "summary": {
+            "total_transactions": txn_inserted,
+            "total_amount": 0,
+        },
+        "cli_report": cli_report,
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = SafeArgumentParser(prog="finance_cli")
+    format_parent = SafeArgumentParser(add_help=False)
+    format_parent.add_argument("--format", choices=["json", "cli"], default="json")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    txn.register(subparsers, format_parent)
+    account_cmd.register(subparsers, format_parent)
+    cat.register(subparsers, format_parent)
+    daily.register(subparsers, format_parent)
+    weekly.register(subparsers, format_parent)
+    budget.register(subparsers, format_parent)
+    export.register(subparsers, format_parent)
+    ingest.register(subparsers, format_parent)
+    db_cmd.register(subparsers, format_parent)
+    dedup_cmd.register(subparsers, format_parent)
+    subs.register(subparsers, format_parent)
+    liquidity_cmd.register(subparsers, format_parent)
+    balance_cmd.register(subparsers, format_parent)
+    liability_cmd.register(subparsers, format_parent)
+    plan.register(subparsers, format_parent)
+    plaid_cmd.register(subparsers, format_parent)
+    stripe_cmd.register(subparsers, format_parent)
+    schwab_cmd.register(subparsers, format_parent)
+    provider_cmd.register(subparsers, format_parent)
+    rules.register(subparsers, format_parent)
+    setup_cmd.register(subparsers, format_parent)
+    monthly_cmd.register(subparsers, format_parent)
+    notify_cmd.register(subparsers, format_parent)
+    debt_cmd.register(subparsers, format_parent)
+    biz_cmd.register(subparsers, format_parent)
+    summary_cmd.register(subparsers, format_parent)
+    spending_cmd.register(subparsers, format_parent)
+    projection_cmd.register(subparsers, format_parent)
+    goal_cmd.register(subparsers, format_parent)
+    register_migrate_command(subparsers, format_parent)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    load_dotenv()
+    setup_logging()
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except CLIParseError as exc:
+        command_name = "unknown"
+        if argv:
+            head = argv[0].strip()
+            if head:
+                command_name = head
+        envelope = error_envelope(command_name, str(exc))
+        print_envelope(envelope, "json")
+        return exc.exit_code
+
+    try:
+        initialize_database()
+        with connect() as conn:
+            result = args.func(args, conn)
+        envelope = success_envelope(
+            command=args.command_name,
+            data=result.get("data", {}),
+            summary=result.get("summary"),
+            cli_report=result.get("cli_report"),
+        )
+        print_envelope(envelope, args.format)
+        return 0
+    except Exception as exc:
+        command_name = getattr(args, "command_name", "unknown")
+        envelope = error_envelope(command_name, str(exc))
+        output_format = getattr(args, "format", "json")
+        print_envelope(envelope, output_format)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())