recon-agent 0.1.0__tar.gz

recon_agent-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.env
+exception_report.csv
+.streamlit/
+.venv/
+.pytest_cache/
+web/node_modules/
+web/.next/
+web/build/
+.vscode/
+.idea/

recon_agent-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: recon-agent
+Version: 0.1.0
+Summary: AI-powered reconciliation agent for finance.
+Author-email: Abtimist <abhishek@abtimist.com>
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: backend
+Requires-Dist: cryptography>=42.0; extra == 'backend'
+Requires-Dist: faker>=20.0; extra == 'backend'
+Requires-Dist: fastapi>=0.110; extra == 'backend'
+Requires-Dist: google-genai>=0.2; extra == 'backend'
+Requires-Dist: openai>=1.0; extra == 'backend'
+Requires-Dist: openpyxl>=3.1; extra == 'backend'
+Requires-Dist: pandas>=2.0; extra == 'backend'
+Requires-Dist: psycopg2-binary>=2.9.9; extra == 'backend'
+Requires-Dist: python-dateutil>=2.8; extra == 'backend'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'backend'
+Requires-Dist: python-jose[cryptography]>=3.3; extra == 'backend'
+Requires-Dist: python-multipart>=0.0.9; extra == 'backend'
+Requires-Dist: rapidfuzz>=3.0; extra == 'backend'
+Requires-Dist: reportlab>=4.0; extra == 'backend'
+Requires-Dist: supabase>=2.0; extra == 'backend'
+Requires-Dist: uvicorn>=0.29; extra == 'backend'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Recon Agent — Multi-Tenant SaaS
+
+AI-powered financial reconciliation as a multi-tenant SaaS.
+
+## Architecture
+
+- **Frontend**: Next.js 16 + Clerk auth (App Router)
+- **Backend API**: FastAPI (Python)
+- **Core Engine**: Pure Python reconciliation logic (`core/`)
+- **Database**: Supabase PostgreSQL with RLS
+- **Storage**: Supabase Storage (CSV/XLSX files)
+
+The architecture flows strictly as:
+`Web → FastAPI API → Core Engine → Database`
+
+> [!NOTE]
+> The Command Line Interface (`recon`) is a fully featured CLI that consumes the FastAPI REST API using Personal Access Tokens (PATs).
+
+## Quick Start
+
+### 1. Backend (FastAPI)
+
+```bash
+cd /home/abhishek/PROJECTS/recon-agent
+.venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Health check: `curl http://localhost:8000/health`
+
+### 2. Frontend (Next.js)
+
+```bash
+cd /home/abhishek/PROJECTS/recon-agent/web
+npm run dev
+```
+
+## Command Line Interface (CLI)
+
+Recon Agent includes a powerful CLI that acts as a first-class client to the FastAPI backend. It allows you to automate reconciliations, view history, export reports, and generate AI explanations straight from the terminal.
+
+### Installation
+
+Install locally via pip or uv:
+
+```bash
+pip install -e .
+# or
+uv pip install -e .
+```
+
+This makes the `recon` command globally available. 
+
+```bash
+recon --help
+```
+
+### Usage
+
+1. **Login**: Generate a Personal Access Token in the Web UI, then run:
+   ```bash
+   recon login
+   ```
+2. **Reconcile**:
+   ```bash
+   recon reconcile source.csv target.csv
+   ```
+3. **History**:
+   ```bash
+   recon history
+   ```
+4. **Machine Readable output**:
+   ```bash
+   recon history --json
+   ```
+
+## Documentation
+
+- [Docs Directory](docs/)
+- [Phase 1: Feature 1–7 Audit](docs/platform-integration-audit.md)
+- [Phase 2: Platform Foundations](docs/phase-2-foundations-report.md)
+- [Phase 3: API Authentication](docs/api-authentication.md)
+- [Phase 4: CLI Documentation](docs/cli.md)
+- [Phase 5: Tiers and Roles](docs/tiers-and-roles.md)
+
+## Development
+
+```bash
+uv sync
+```
+Create `.env` (root) and `web/.env.local` with these values.
+
+### Root `.env`
+```
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_SERVICE_KEY=<service_role JWT>      # NOT the publishable key!
+CLERK_SECRET_KEY=sk_test_...
+CLERK_ISSUER=https://<your-app>.clerk.accounts.dev
+ENCRYPTION_KEY=<base64 32 bytes>
+```
+
+### `web/.env.local`
+```
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+```
+
+## Database Setup
+
+Run the SQL in `api/migrations/001_initial_schema.sql` in the Supabase SQL editor.
+
+This creates the tables and enables RLS policies.
+
+## How multi-tenancy works
+
+1. User signs in with Clerk (organizations enabled)
+2. Clerk JWT is sent on every API request
+3. Backend extracts `clerk_org_id` from JWT
+4. Each DB query is scoped to that org — RLS enforces isolation as a backstop
+
+See `api/migrations/001_initial_schema.sql` to `005_usage_quotas.sql` for the full schema.

recon_agent-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Recon Agent — Multi-Tenant SaaS
+
+AI-powered financial reconciliation as a multi-tenant SaaS.
+
+## Architecture
+
+- **Frontend**: Next.js 16 + Clerk auth (App Router)
+- **Backend API**: FastAPI (Python)
+- **Core Engine**: Pure Python reconciliation logic (`core/`)
+- **Database**: Supabase PostgreSQL with RLS
+- **Storage**: Supabase Storage (CSV/XLSX files)
+
+The architecture flows strictly as:
+`Web → FastAPI API → Core Engine → Database`
+
+> [!NOTE]
+> The Command Line Interface (`recon`) is a fully featured CLI that consumes the FastAPI REST API using Personal Access Tokens (PATs).
+
+## Quick Start
+
+### 1. Backend (FastAPI)
+
+```bash
+cd /home/abhishek/PROJECTS/recon-agent
+.venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Health check: `curl http://localhost:8000/health`
+
+### 2. Frontend (Next.js)
+
+```bash
+cd /home/abhishek/PROJECTS/recon-agent/web
+npm run dev
+```
+
+## Command Line Interface (CLI)
+
+Recon Agent includes a powerful CLI that acts as a first-class client to the FastAPI backend. It allows you to automate reconciliations, view history, export reports, and generate AI explanations straight from the terminal.
+
+### Installation
+
+Install locally via pip or uv:
+
+```bash
+pip install -e .
+# or
+uv pip install -e .
+```
+
+This makes the `recon` command globally available. 
+
+```bash
+recon --help
+```
+
+### Usage
+
+1. **Login**: Generate a Personal Access Token in the Web UI, then run:
+   ```bash
+   recon login
+   ```
+2. **Reconcile**:
+   ```bash
+   recon reconcile source.csv target.csv
+   ```
+3. **History**:
+   ```bash
+   recon history
+   ```
+4. **Machine Readable output**:
+   ```bash
+   recon history --json
+   ```
+
+## Documentation
+
+- [Docs Directory](docs/)
+- [Phase 1: Feature 1–7 Audit](docs/platform-integration-audit.md)
+- [Phase 2: Platform Foundations](docs/phase-2-foundations-report.md)
+- [Phase 3: API Authentication](docs/api-authentication.md)
+- [Phase 4: CLI Documentation](docs/cli.md)
+- [Phase 5: Tiers and Roles](docs/tiers-and-roles.md)
+
+## Development
+
+```bash
+uv sync
+```
+Create `.env` (root) and `web/.env.local` with these values.
+
+### Root `.env`
+```
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_SERVICE_KEY=<service_role JWT>      # NOT the publishable key!
+CLERK_SECRET_KEY=sk_test_...
+CLERK_ISSUER=https://<your-app>.clerk.accounts.dev
+ENCRYPTION_KEY=<base64 32 bytes>
+```
+
+### `web/.env.local`
+```
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+```
+
+## Database Setup
+
+Run the SQL in `api/migrations/001_initial_schema.sql` in the Supabase SQL editor.
+
+This creates the tables and enables RLS policies.
+
+## How multi-tenancy works
+
+1. User signs in with Clerk (organizations enabled)
+2. Clerk JWT is sent on every API request
+3. Backend extracts `clerk_org_id` from JWT
+4. Each DB query is scoped to that org — RLS enforces isolation as a backstop
+
+See `api/migrations/001_initial_schema.sql` to `005_usage_quotas.sql` for the full schema.

recon_agent-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "recon-agent"
+version = "0.1.0"
+description = "AI-powered reconciliation agent for finance."
+authors = [{name = "Abtimist", email = "abhishek@abtimist.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "typer>=0.12",
+    "rich>=13.7",
+    "keyring>=25.0"
+]
+
+[project.optional-dependencies]
+backend = [
+    "pandas>=2.0",
+    "rapidfuzz>=3.0",
+    "faker>=20.0",
+    "google-genai>=0.2",
+    "python-dateutil>=2.8",
+    "openai>=1.0",
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+    "supabase>=2.0",
+    "python-jose[cryptography]>=3.3",
+    "cryptography>=42.0",
+    "python-multipart>=0.0.9",
+    "openpyxl>=3.1",
+    "reportlab>=4.0",
+    "psycopg2-binary>=2.9.9",
+    "python-dotenv>=1.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["recon_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["recon_cli", "README.md", "pyproject.toml"]
+
+[project.scripts]
+recon = "recon_cli.main:app"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

recon_agent-0.1.0/recon_cli/auth.py

@@ -0,0 +1,127 @@
+import os
+import json
+import keyring
+import stat
+from typing import Optional
+from pathlib import Path
+from recon_cli.config import CREDENTIALS_FILE, CONFIG_DIR
+
+SERVICE_NAME = "recon-agent"
+TOKEN_KEY = "pat"
+
+def _is_keyring_available() -> bool:
+    try:
+        # Check if the active keyring is just the failing ChrootKeyring or similar empty ones
+        kr = keyring.get_keyring()
+        # Non-viable keyrings typically have "fail" in their name or class name, or it throws on get/set
+        if "fail" in str(kr).lower():
+            return False
+        return True
+    except Exception:
+        return False
+
+def _read_fallback_token() -> Optional[str]:
+    if not CREDENTIALS_FILE.exists():
+        return None
+    try:
+        # Ensure strict permissions before trusting it
+        st = os.stat(CREDENTIALS_FILE)
+        if st.st_mode & stat.S_IRWXO or st.st_mode & stat.S_IRWXG:
+            # File is accessible to group or others, which is insecure
+            print("Warning: ~/.recon/credentials.json has insecure permissions. It should be 600.")
+        
+        with open(CREDENTIALS_FILE, "r") as f:
+            data = json.load(f)
+            return data.get(TOKEN_KEY)
+    except Exception:
+        return None
+
+def _write_fallback_token(token: str):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Touch the file securely if it doesn't exist
+    if not CREDENTIALS_FILE.exists():
+        open(CREDENTIALS_FILE, 'w').close()
+        
+    # Force 600 permissions
+    os.chmod(CREDENTIALS_FILE, stat.S_IRUSR | stat.S_IWUSR)
+    
+    data = {}
+    if CREDENTIALS_FILE.exists() and os.path.getsize(CREDENTIALS_FILE) > 0:
+        try:
+            with open(CREDENTIALS_FILE, "r") as f:
+                data = json.load(f)
+        except Exception:
+            pass
+            
+    data[TOKEN_KEY] = token
+    with open(CREDENTIALS_FILE, "w") as f:
+        json.dump(data, f)
+
+def _delete_fallback_token():
+    if not CREDENTIALS_FILE.exists():
+        return
+    try:
+        with open(CREDENTIALS_FILE, "r") as f:
+            data = json.load(f)
+        if TOKEN_KEY in data:
+            del data[TOKEN_KEY]
+        with open(CREDENTIALS_FILE, "w") as f:
+            json.dump(data, f)
+    except Exception:
+        pass
+
+def get_token() -> Optional[str]:
+    """
+    Get the Personal Access Token.
+    Checks environment variable first, then keyring, then fallback file.
+    """
+    # 1. Environment Variable
+    env_token = os.environ.get("RECON_API_TOKEN")
+    if env_token:
+        return env_token
+
+    # 2. Keyring
+    if _is_keyring_available():
+        try:
+            token = keyring.get_password(SERVICE_NAME, "default_user")
+            if token:
+                return token
+        except Exception:
+            pass
+
+    # 3. Fallback file
+    return _read_fallback_token()
+
+def save_token(token: str) -> bool:
+    """
+    Save the Personal Access Token.
+    Prefers keyring, falls back to secure file.
+    Returns True if keyring was used, False if fallback was used.
+    """
+    if _is_keyring_available():
+        try:
+            keyring.set_password(SERVICE_NAME, "default_user", token)
+            # Make sure we clean up the fallback file if we successfully used keyring
+            _delete_fallback_token()
+            return True
+        except Exception:
+            pass
+            
+    # Fallback
+    _write_fallback_token(token)
+    return False
+
+def clear_token():
+    """
+    Clear the saved Personal Access Token.
+    """
+    if _is_keyring_available():
+        try:
+            keyring.delete_password(SERVICE_NAME, "default_user")
+        except keyring.errors.PasswordDeleteError:
+            pass
+        except Exception:
+            pass
+            
+    _delete_fallback_token()

recon_agent-0.1.0/recon_cli/client.py

@@ -0,0 +1,107 @@
+import httpx
+from typing import Optional, Any, Dict
+from recon_cli.config import get_api_url
+from recon_cli.auth import get_token
+
+class ReconAPIError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None, data: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.data = data
+
+def _get_headers() -> Dict[str, str]:
+    token = get_token()
+    if not token:
+        raise ReconAPIError("Not authenticated. Please run 'recon login' first.")
+    return {
+        "Authorization": f"Bearer {token}"
+    }
+
+def _handle_response(response: httpx.Response) -> Any:
+    try:
+        response.raise_for_status()
+        if response.status_code == 204:
+            return None
+        return response.json()
+    except httpx.HTTPStatusError as e:
+        detail = "Unknown error"
+        try:
+            data = e.response.json()
+            if isinstance(data, dict) and "detail" in data:
+                detail = data["detail"]
+        except Exception:
+            detail = e.response.text
+            
+        if e.response.status_code == 401:
+            raise ReconAPIError(
+                f"Authentication failed (401). Your token may be invalid or revoked. Detail: {detail}",
+                status_code=401
+            )
+        elif e.response.status_code == 403:
+            raise ReconAPIError(
+                f"Permission denied (403). You do not have access to this feature or role. Detail: {detail}",
+                status_code=403
+            )
+        elif e.response.status_code == 429:
+            raise ReconAPIError(
+                f"Quota Exceeded (429). Please upgrade your plan. Detail: {detail}",
+                status_code=429
+            )
+        elif e.response.status_code == 404:
+            raise ReconAPIError(
+                f"Not found (404). Detail: {detail}",
+                status_code=404
+            )
+        else:
+            raise ReconAPIError(
+                f"API Error ({e.response.status_code}): {detail}",
+                status_code=e.response.status_code
+            )
+    except httpx.RequestError as e:
+        raise ReconAPIError(f"Network error while connecting to API: {str(e)}")
+
+def get_client() -> httpx.Client:
+    """Returns an authenticated httpx client configured with the base URL."""
+    base_url = get_api_url()
+    try:
+        headers = _get_headers()
+    except ReconAPIError:
+        # If we just want a client without auth (e.g. for login check), 
+        # we can handle that separately, but for now most commands need auth.
+        headers = {}
+    
+    return httpx.Client(
+        base_url=base_url,
+        headers=headers,
+        timeout=30.0
+    )
+
+def api_get(endpoint: str, params: Optional[Dict] = None) -> Any:
+    base_url = get_api_url()
+    headers = _get_headers()
+    try:
+        with httpx.Client(base_url=base_url, headers=headers, timeout=30.0) as client:
+            response = client.get(endpoint, params=params)
+            return _handle_response(response)
+    except httpx.RequestError as e:
+        raise ReconAPIError(f"Network error while connecting to API: {str(e)}")
+
+def api_post(endpoint: str, json: Optional[Dict] = None, data: Optional[Dict] = None, files: Optional[Dict] = None, timeout: float = 30.0) -> Any:
+    base_url = get_api_url()
+    headers = _get_headers()
+    try:
+        with httpx.Client(base_url=base_url, headers=headers, timeout=timeout) as client:
+            response = client.post(endpoint, json=json, data=data, files=files)
+            return _handle_response(response)
+    except httpx.RequestError as e:
+        raise ReconAPIError(f"Network error while connecting to API: {str(e)}")
+
+def api_delete(endpoint: str) -> Any:
+    base_url = get_api_url()
+    headers = _get_headers()
+    try:
+        with httpx.Client(base_url=base_url, headers=headers, timeout=30.0) as client:
+            response = client.delete(endpoint)
+            return _handle_response(response)
+    except httpx.RequestError as e:
+        raise ReconAPIError(f"Network error while connecting to API: {str(e)}")

recon_agent-0.1.0/recon_cli/commands/auth.py

@@ -0,0 +1,100 @@
+import typer
+import httpx
+from rich.prompt import Prompt
+from recon_cli.auth import save_token, clear_token, get_token
+from recon_cli.config import save_config, get_api_url
+from recon_cli.client import ReconAPIError, api_get
+from recon_cli.output import print_error, print_success, print_info, print_json
+
+app = typer.Typer(help="Authentication and session management.")
+
+@app.command()
+def login(
+    base_url: str = typer.Option(None, "--url", help="API Base URL"),
+    token: str = typer.Option(None, "--token", help="Personal Access Token")
+):
+    """
+    Log in to a Recon Agent instance using a Personal Access Token.
+    """
+    if not base_url:
+        current_url = get_api_url()
+        base_url = Prompt.ask("API Base URL", default=current_url)
+    
+    if not token:
+        token = Prompt.ask("Personal Access Token (ra_live_...)", password=True)
+
+    if not token.startswith("ra_live_"):
+        print_error("Invalid token format. It should start with 'ra_live_'")
+        raise typer.Exit(1)
+
+    # Save the config
+    save_config({"api_base_url": base_url.rstrip("/")})
+    
+    # Save the token
+    used_keyring = save_token(token)
+    
+    if used_keyring:
+        print_info("Token saved securely in OS keychain.")
+    else:
+        print_info("Token saved in ~/.recon/credentials.json (OS keychain unavailable).")
+
+    # Validate the token
+    try:
+        response = api_get("/auth/status")
+        print_success(f"Logged in successfully as {response.get('clerk_user_id', 'unknown')}")
+    except ReconAPIError as e:
+        print_error(f"Login failed: {e}")
+        clear_token()
+        raise typer.Exit(1)
+    except Exception as e:
+        print_error(f"Connection failed: {e}")
+        clear_token()
+        raise typer.Exit(1)
+
+
+@app.command()
+def logout():
+    """
+    Log out and clear the stored token.
+    """
+    clear_token()
+    print_success("Logged out successfully.")
+
+@app.command()
+def whoami(
+    ctx: typer.Context,
+):
+    """
+    Check current authentication status.
+    """
+    token = get_token()
+    if not token:
+        if ctx.obj.get("json", False):
+            print_json({"authenticated": False, "error": "No token found"})
+        else:
+            print_error("Not logged in. Run 'recon auth login' first.")
+        raise typer.Exit(1)
+
+    try:
+        data = api_get("/auth/status")
+        if ctx.obj.get("json", False):
+            print_json({"authenticated": True, "data": data})
+        else:
+            print_info(f"Authenticated as User ID: {data.get('clerk_user_id')}")
+            if data.get("org_id"):
+                print_info(f"Organization ID: {data.get('org_id')}")
+            print_info(f"Scopes: {', '.join(data.get('scopes', []))}")
+            if not data.get("is_pat"):
+                print_info("Note: Authenticated via Clerk JWT (browser token) instead of PAT.")
+    except ReconAPIError as e:
+        if ctx.obj.get("json", False):
+            print_json({"authenticated": False, "error": str(e)})
+        else:
+            print_error(f"Authentication check failed: {e}")
+        raise typer.Exit(1)
+
+# Alias status to whoami
+@app.command()
+def status(ctx: typer.Context):
+    """Alias for whoami."""
+    whoami(ctx)

recon_agent-0.1.0/recon_cli/commands/explain.py

@@ -0,0 +1,101 @@
+import typer
+from recon_cli.client import api_post, ReconAPIError
+from recon_cli.output import print_error, print_json, print_markdown, console
+
+app = typer.Typer(help="Generate an AI-powered CFO Explanation for a reconciliation result.")
+
+@app.callback(invoke_without_command=True)
+def explain(
+    ctx: typer.Context,
+    run_id: str = typer.Argument(..., help="Run ID to explain")
+):
+    is_json = ctx.obj.get("json", False)
+    
+    try:
+        from recon_cli.client import api_get
+        import time
+
+        if not is_json:
+            console.print(f"Fetching run {run_id} details...")
+            
+        run_data = api_get(f"/runs/{run_id}")
+        
+        payload = {
+            "type": "single",
+            "result": run_data
+        }
+        
+        if not is_json:
+            with console.status("[bold cyan]Requesting CFO Explanation...[/bold cyan]") as status:
+                job_accepted = api_post("/explain/", json=payload, timeout=120.0)
+                job_id = job_accepted.get("job_id")
+                
+                status.update("[bold cyan]Job queued. Waiting for worker to process...[/bold cyan]")
+                
+                while True:
+                    time.sleep(2)
+                    job_status = api_get(f"/explain/{job_id}/status")
+                    s = job_status.get("status")
+                    
+                    if s == "processing":
+                        status.update("[bold cyan]Worker is processing the job...[/bold cyan]")
+                    elif s == "completed":
+                        status.update("[bold cyan]Explanation generated![/bold cyan]")
+                        data = job_status.get("response_data")
+                        break
+                    elif s == "failed":
+                        raise ReconAPIError(500, job_status.get("error_message") or "Explain job failed")
+        else:
+            job_accepted = api_post("/explain/", json=payload, timeout=120.0)
+            job_id = job_accepted.get("job_id")
+            while True:
+                time.sleep(2)
+                job_status = api_get(f"/explain/{job_id}/status")
+                s = job_status.get("status")
+                if s == "completed":
+                    data = job_status.get("response_data")
+                    break
+                elif s == "failed":
+                    raise ReconAPIError(500, job_status.get("error_message") or "Explain job failed")
+        
+        if is_json:
+            print_json(data)
+            return
+            
+        # Format the markdown output
+        md = f"""# {data.get('headline')}
+
+**Status:** {data.get('status')}
+
+## Summary
+{data.get('summary')}
+
+## Key Findings
+"""
+        for finding in data.get('key_findings', []):
+            md += f"- {finding}\n"
+            
+        md += f"\n## Financial Impact\n{data.get('financial_impact')}\n"
+        
+        md += "\n## Attention Items\n"
+        for item in data.get('attention_items', []):
+            md += f"- {item}\n"
+            
+        md += "\n## Recommended Actions\n"
+        for action in data.get('recommended_actions', []):
+            md += f"- {action}\n"
+            
+        print_markdown(md)
+        
+    except ReconAPIError as e:
+        if is_json:
+            print_json({"error": str(e)})
+        else:
+            print_error(str(e))
+        raise typer.Exit(1)
+    except Exception as e:
+        if is_json:
+            print_json({"error": str(e)})
+        else:
+            print_error(f"Failed to generate explanation: {e}")
+        raise typer.Exit(1)

recon_agent-0.1.0/recon_cli/commands/export.py

@@ -0,0 +1,89 @@
+import typer
+import httpx
+from pathlib import Path
+from recon_cli.client import get_client, get_api_url, _get_headers
+from recon_cli.output import print_error, print_success, print_json, console
+
+app = typer.Typer(help="Export reconciliation results to a file.")
+
+@app.callback(invoke_without_command=True)
+def export(
+    ctx: typer.Context,
+    run_id: str = typer.Argument(..., help="Run ID or Batch ID to export"),
+    format: str = typer.Option("excel", "--format", "-f", help="Format to export (excel or pdf)"),
+    out: Path = typer.Option(None, "--out", "-o", help="Output file path")
+):
+    if format not in ["excel", "pdf"]:
+        print_error("Format must be 'excel' or 'pdf'.")
+        raise typer.Exit(1)
+        
+    is_json = ctx.obj.get("json", False)
+    
+    # First we need to know if it's a batch or single. We can just try one, then the other,
+    # or just assume it's single first. Let's try single.
+    
+    base_url = get_api_url()
+    try:
+        headers = _get_headers()
+    except Exception as e:
+        if is_json:
+            print_json({"error": str(e)})
+        else:
+            print_error(str(e))
+        raise typer.Exit(1)
+        
+    payload = {"run_id": run_id}
+    endpoint = f"{base_url}/export/single/{format}"
+    
+    # Try single first
+    try:
+        with httpx.Client(headers=headers, timeout=60.0) as client:
+            if not is_json:
+                console.print(f"Requesting {format.upper()} export for run {run_id}...")
+            
+            response = client.post(endpoint, json=payload)
+            
+            if response.status_code == 404:
+                # Try batch
+                payload = {"batch_id": run_id}
+                endpoint = f"{base_url}/export/batch/{format}"
+                response = client.post(endpoint, json=payload)
+                
+            response.raise_for_status()
+            
+            # Determine output filename if not provided
+            if not out:
+                content_disp = response.headers.get("Content-Disposition", "")
+                if "filename=" in content_disp:
+                    filename = content_disp.split("filename=")[-1].strip('"\'')
+                else:
+                    ext = "xlsx" if format == "excel" else "pdf"
+                    filename = f"recon_export_{run_id}.{ext}"
+                out = Path(filename)
+            
+            with open(out, "wb") as f:
+                f.write(response.content)
+                
+            if is_json:
+                print_json({"success": True, "file": str(out.absolute())})
+            else:
+                print_success(f"Export saved to [bold]{out}[/bold]")
+                
+    except httpx.HTTPStatusError as e:
+        detail = "Unknown error"
+        try:
+            detail = e.response.json().get("detail", detail)
+        except:
+            pass
+        err_msg = f"API Error ({e.response.status_code}): {detail}"
+        if is_json:
+            print_json({"error": err_msg})
+        else:
+            print_error(err_msg)
+        raise typer.Exit(1)
+    except Exception as e:
+        if is_json:
+            print_json({"error": str(e)})
+        else:
+            print_error(f"Failed to export: {e}")
+        raise typer.Exit(1)

recon_agent-0.1.0/recon_cli/commands/history.py

@@ -0,0 +1,112 @@
+import typer
+from recon_cli.client import api_get, ReconAPIError
+from recon_cli.output import print_error, print_json, print_table, print_panel, console
+
+app = typer.Typer(help="View past reconciliation runs.")
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    run_id: str = typer.Argument(None, help="Specific Run ID to fetch details for"),
+    limit: int = typer.Option(20, help="Number of recent runs to show when listing")
+):
+    if ctx.invoked_subcommand is not None:
+        return
+        
+    is_json = ctx.obj.get("json", False)
+
+    if run_id:
+        # Fetch specific run
+        try:
+            # First try as a single run
+            try:
+                data = api_get(f"/runs/{run_id}")
+            except ReconAPIError as e:
+                if e.status_code == 404:
+                    # Maybe it's a batch run?
+                    data = api_get(f"/runs/batch/{run_id}")
+                else:
+                    raise e
+                    
+            if is_json:
+                print_json(data)
+                return
+                
+            # Formatting details
+            if "batch_id" in data and "files" not in data:
+                # Single run
+                print_panel(
+                    f"ID: {data.get('id')}\n"
+                    f"Status: {data.get('status')}\n"
+                    f"Match Rate: {data.get('match_rate', 0)}%\n"
+                    f"Exceptions: {data.get('exceptions_count', 0)}\n"
+                    f"Completed: {data.get('completed_at')}",
+                    title="Single Run Details"
+                )
+            else:
+                # Batch run
+                print_panel(
+                    f"Batch ID: {data.get('batch_id')}\n"
+                    f"Status: {data.get('status')}\n"
+                    f"Total Match Rate: {data.get('overall_match_rate', 0)}%\n"
+                    f"Total Exceptions: {data.get('total_exceptions', 0)}\n"
+                    f"Files processed: {len(data.get('files', []))}",
+                    title="Batch Run Details"
+                )
+                
+        except ReconAPIError as e:
+            if is_json:
+                print_json({"error": str(e)})
+            else:
+                print_error(str(e))
+            raise typer.Exit(1)
+            
+    else:
+        # List runs
+        try:
+            data = api_get("/runs/", params={"limit": limit})
+            if is_json:
+                print_json(data)
+                return
+                
+            if not data:
+                console.print("No history found.")
+                return
+                
+            rows = []
+            for item in data:
+                run_type = item.get("type", "single")
+                run_ident = item.get("id") or item.get("batch_id")
+                completed = item.get("completed_at", "N/A")
+                if completed != "N/A":
+                    completed = completed[:16].replace("T", " ")
+                    
+                if run_type == "single":
+                    rate = f"{item.get('match_rate', 0)}%"
+                    exc = str(item.get('exceptions_count', 0))
+                else:
+                    rate = f"{item.get('overall_match_rate', 0)}%"
+                    exc = str(item.get('total_exceptions', 0))
+                    
+                rows.append([
+                    run_type.upper(),
+                    run_ident[:8] + "...",
+                    item.get("status", ""),
+                    rate,
+                    exc,
+                    completed
+                ])
+                
+            print_table(
+                title=f"Recent Runs (Showing up to {limit})",
+                columns=["Type", "ID", "Status", "Match Rate", "Exceptions", "Completed"],
+                rows=rows
+            )
+            console.print("\nRun [cyan]recon history <id>[/cyan] to see details.")
+            
+        except ReconAPIError as e:
+            if is_json:
+                print_json({"error": str(e)})
+            else:
+                print_error(str(e))
+            raise typer.Exit(1)

recon_agent-0.1.0/recon_cli/commands/reconcile.py

@@ -0,0 +1,129 @@
+import typer
+from pathlib import Path
+from recon_cli.client import api_post, ReconAPIError
+from recon_cli.output import print_error, print_success, print_info, print_json, print_table, console
+
+app = typer.Typer(help="Execute reconciliation between source and target datasets.")
+
+@app.command("run")
+def run_reconcile(
+    ctx: typer.Context,
+    source: Path = typer.Argument(..., help="Path to the source CSV/XLSX file", exists=True, dir_okay=False),
+    target: Path = typer.Argument(..., help="Path to the target CSV/XLSX file", exists=True, dir_okay=False),
+    amount_tolerance: float = typer.Option(0.0, "--tolerance", "-t", help="Allowable difference in amounts"),
+    date_window: int = typer.Option(0, "--date-window", "-d", help="Allowable difference in days for dates"),
+    ai_provider: str = typer.Option("none", "--provider", help="AI provider for fuzzy matching (groq, openai, none)"),
+    mapping_id: str = typer.Option(None, "--mapping", "-m", help="Mapping preset ID to use"),
+):
+    """
+    Reconcile two files against each other.
+    """
+    is_json = ctx.obj.get("json", False)
+
+    try:
+        with open(source, "rb") as s_file, open(target, "rb") as t_file:
+            files = {
+                "source_file": (source.name, s_file),
+                "target_file": (target.name, t_file),
+            }
+            data = {
+                "source_mapping_json": "{}",
+                "target_mapping_json": "{}",
+                "source_amount_mode": "single",
+                "target_amount_mode": "single",
+                "amount_tolerance": amount_tolerance,
+                "date_window_days": date_window
+            }
+
+            from recon_cli.client import api_get
+            import time
+
+            if not is_json:
+                with console.status("[bold cyan]Uploading and queueing reconciliation job...[/bold cyan]") as status:
+                    job_accepted = api_post("/reconcile/", data=data, files=files, timeout=300.0)
+                    run_id = job_accepted.get("run_id")
+                    
+                    if not run_id:
+                        raise ReconAPIError(500, "Failed to get run_id from API")
+                        
+                    status.update("[bold cyan]Job queued. Waiting for worker to process...[/bold cyan]")
+                    
+                    # Poll for completion
+                    while True:
+                        time.sleep(2)
+                        job_status = api_get(f"/runs/{run_id}/status")
+                        s = job_status.get("status")
+                        
+                        if s == "processing":
+                            status.update("[bold cyan]Worker is processing the job...[/bold cyan]")
+                        elif s == "completed":
+                            status.update("[bold cyan]Job completed! Fetching results...[/bold cyan]")
+                            break
+                        elif s == "failed":
+                            raise ReconAPIError(500, job_status.get("error_message") or "Job failed")
+                    
+                    result = api_get(f"/runs/{run_id}")
+            else:
+                job_accepted = api_post("/reconcile/", data=data, files=files, timeout=300.0)
+                run_id = job_accepted.get("run_id")
+                while True:
+                    time.sleep(2)
+                    job_status = api_get(f"/runs/{run_id}/status")
+                    if job_status.get("status") in ("completed", "failed"):
+                        if job_status.get("status") == "failed":
+                            raise ReconAPIError(500, job_status.get("error_message") or "Job failed")
+                        break
+                result = api_get(f"/runs/{run_id}")
+
+    except ReconAPIError as e:
+        if is_json:
+            print_json({"error": str(e), "status_code": e.status_code})
+        else:
+            print_error(str(e))
+        raise typer.Exit(1)
+    except Exception as e:
+        if is_json:
+            print_json({"error": str(e)})
+        else:
+            print_error(f"Failed to upload and reconcile: {e}")
+        raise typer.Exit(1)
+
+    if is_json:
+        print_json(result)
+        return
+
+    # Render summary nicely
+    print_success(f"Reconciliation Run Completed (ID: {result.get('run_id', 'N/A')})")
+    
+    summary = result.get("summary", {})
+    
+    table = [
+        ["Total Source Rows", str(result.get("total_source_rows", 0))],
+        ["Matched Rows", str(result.get("total_matched", 0))],
+        ["Match Rate", f"{result.get('match_rate', 0)}%"],
+        ["Exceptions", str(result.get("exceptions_count", 0))],
+    ]
+    
+    print_table("Reconciliation Summary", ["Metric", "Value"], table)
+    
+    matches = [
+        ["Exact Matches", str(result.get("exact_matches", 0))],
+        ["Fuzzy Matches", str(result.get("fuzzy_matches", 0))],
+        ["AI Matches", str(result.get("ai_matches", 0))],
+    ]
+    
+    print_table("Match Breakdown", ["Type", "Count"], matches)
+
+@app.callback(invoke_without_command=True)
+def default_reconcile(
+    ctx: typer.Context,
+    source: Path = typer.Argument(..., help="Path to the source CSV/XLSX file", exists=True, dir_okay=False),
+    target: Path = typer.Argument(..., help="Path to the target CSV/XLSX file", exists=True, dir_okay=False),
+    amount_tolerance: float = typer.Option(0.0, "--tolerance", "-t", help="Allowable difference in amounts"),
+    date_window: int = typer.Option(0, "--date-window", "-d", help="Allowable difference in days for dates"),
+    ai_provider: str = typer.Option("none", "--provider", help="AI provider for fuzzy matching (groq, openai, none)"),
+    mapping_id: str = typer.Option(None, "--mapping", "-m", help="Mapping preset ID to use"),
+):
+    if ctx.invoked_subcommand is None:
+        # Pass directly to run
+        run_reconcile(ctx, source, target, amount_tolerance, date_window, ai_provider, mapping_id)

recon_agent-0.1.0/recon_cli/config.py

@@ -0,0 +1,35 @@
+import json
+import os
+from pathlib import Path
+
+# The base configuration path
+CONFIG_DIR = Path.home() / ".recon"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+
+DEFAULT_CONFIG = {
+    "api_base_url": "https://api.recon-agent.com"
+}
+
+def load_config() -> dict:
+    if not CONFIG_FILE.exists():
+        return DEFAULT_CONFIG.copy()
+    try:
+        with open(CONFIG_FILE, "r") as f:
+            data = json.load(f)
+            # Merge with defaults
+            return {**DEFAULT_CONFIG, **data}
+    except Exception:
+        return DEFAULT_CONFIG.copy()
+
+def save_config(config: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(config, f, indent=2)
+
+def get_api_url() -> str:
+    """Return the API URL, allowing env var override."""
+    env_url = os.environ.get("RECON_API_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    return load_config().get("api_base_url", DEFAULT_CONFIG["api_base_url"]).rstrip("/")

recon_agent-0.1.0/recon_cli/main.py

@@ -0,0 +1,37 @@
+import typer
+
+app = typer.Typer(
+    name="recon",
+    help="Recon Agent CLI - Multi-tenant financial reconciliation from your terminal.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+from recon_cli.commands import auth, reconcile, history, export, explain
+
+app.add_typer(auth.app, name="auth")
+app.add_typer(reconcile.app, name="reconcile")
+app.add_typer(history.app, name="history")
+app.add_typer(export.app, name="export")
+app.add_typer(explain.app, name="explain")
+
+# Add some top-level aliases for convenience
+app.command(name="login")(auth.login)
+app.command(name="logout")(auth.logout)
+app.command(name="whoami")(auth.whoami)
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json: bool = typer.Option(False, "--json", help="Output machine-readable JSON instead of human-readable text"),
+    debug: bool = typer.Option(False, "--debug", help="Enable debug mode with full tracebacks"),
+):
+    """
+    Global options for Recon Agent CLI.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["json"] = json
+    ctx.obj["debug"] = debug
+
+if __name__ == "__main__":
+    app()

recon_agent-0.1.0/recon_cli/output.py

@@ -0,0 +1,38 @@
+import json
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich import print as rprint
+from rich.markdown import Markdown
+
+# Global console instance
+console = Console()
+
+def print_error(msg: str):
+    console.print(f"[bold red]Error:[/bold red] {msg}")
+
+def print_success(msg: str):
+    console.print(f"[bold green]Success:[/bold green] {msg}")
+
+def print_info(msg: str):
+    console.print(f"[cyan]{msg}[/cyan]")
+
+def print_json(data: dict | list):
+    """Prints raw JSON to stdout. Bypasses rich formatting for standard out pipes."""
+    print(json.dumps(data, indent=2))
+
+def print_table(title: str, columns: list[str], rows: list[list[str]]):
+    table = Table(title=title, show_header=True, header_style="bold magenta")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[str(item) if item is not None else "" for item in row])
+    console.print(table)
+
+def print_panel(content: str, title: str = "", border_style: str = "blue"):
+    panel = Panel(content, title=title, border_style=border_style, expand=False)
+    console.print(panel)
+
+def print_markdown(content: str):
+    md = Markdown(content)
+    console.print(md)

recon_agent-0.1.0/web/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.