Metadata-Version: 2.5
Name: recon-agent
Version: 0.1.2
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.
