Files · 1099-NEC Contractor Classification and W-9 Collection Agent

# 1099-NEC Contractor Classification and W-9 Collection Agent
 
> Automate contractor classification, W-9 requests, and 1099-NEC generation to end the annual scramble.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Overview
 
A CPA firm owner dreads January each year because they must manually classify every contractor as 1099-NEC or non-reportable, chase down missing W-9s via email, and prepare filings. With dozens of clients and hundreds of contractors, the process is error-prone and stressful. This agent automates the entire workflow: classification, W-9 collection, and 1099-NEC generation.
 
## Architecture
 
The agent wires together six `@reaatech/*` packages:
 
- **`@reaatech/agent-handoff`** — retry with exponential backoff + typed event emitter for lifecycle events
- **`@reaatech/agent-memory`** — LLM-powered fact extraction + semantic retrieval for classification audit trail
- **`@reaatech/agent-runbook`** — typed ID generation + input validation at boundaries
- **`@reaatech/agent-eval-harness-suite`** — batch evaluation of classification accuracy
- **`@reaatech/llm-cache`** — SHA-256 exact + cosine-similarity semantic cache for reusing prior classifications
- **`@reaatech/agent-budget-engine`** — pre-flight cost checks + per-scope state machine with auto-downgrade
 
## API Reference
 
| Method | Path | Request Body | Response | Status Codes |
|--------|------|-------------|----------|--------------|
| POST | `/api/classify` | `{ contractorId: string }` | `ClassificationResult` | 200, 400 |
| POST | `/api/classify/batch` | `{ contractorIds: string[] }` | `{ results: ClassificationResult[], count: number }` | 200, 400 |
| POST | `/api/w9/request` | `{ contractorId: string }` | `W9Request` | 200, 400, 404 |
| GET | `/api/w9/status` | Query: `contractorId` | `W9Request \| null` | 200, 400, 404 |
| POST | `/api/w9/receive` | FormData: `contractorId` + `file` (PDF) | `{ extractedTin, extractedName, discrepancies }` | 200, 400, 409, 422 |
| POST | `/api/forms/1099/generate` | `{ contractorId, taxYear }` | `{ documentUrl: string }` | 200, 400, 404, 422 |
| POST | `/api/forms/1099/batch` | `{ taxYear: number }` | `{ generated: number, skipped: number, urls: string[] }` | 200, 400 |
| GET | `/api/forms/report` | Query: `taxYear` (optional, defaults to current) | `{ downloadUrl: string }` | 200 |
| GET | `/api/contractors` | Query: `classification`, `w9Status`, `name` (optional) | `Contractor[]` | 200 |
| POST | `/api/contractors` | `Contractor` (partial fields) | `Contractor` | 201, 400 |
| GET | `/api/contractors/[id]` | Path: `id` | `Contractor` | 200, 404 |
| PUT | `/api/contractors/[id]` | Path: `id`, Body: `Partial<Contractor>` | `Contractor` | 200, 400, 404 |
| DELETE | `/api/contractors/[id]` | Path: `id` | `{ success: true }` | 200, 404 |
| GET | `/api/dashboard` | — | `{ totalContractors, classified, ... }` | 200 |
 
## Environment Variables
 
| Variable | Description |
|----------|-------------|
| `NODE_ENV` | Environment mode (`development` or `production`) |
| `OPENAI_API_KEY` | OpenAI API key for LLM calls |
| `SUPABASE_URL` | Supabase project URL |
| `SUPABASE_ANON_KEY` | Supabase anonymous API key |
| `LANGFUSE_PUBLIC_KEY` | Langfuse tracing public key |
| `LANGFUSE_SECRET_KEY` | Langfuse tracing secret key |
| `LANGFUSE_HOST` | Langfuse host URL |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
| `GOOGLE_REFRESH_TOKEN` | Google OAuth refresh token |
| `GOOGLE_REDIRECT_URL` | Google OAuth redirect URL |
| `W9_REQUEST_EMAIL_FROM` | Sender email address for W-9 requests |
 
## Running locally
 
1. Clone the repo and install dependencies:
   ```bash
   pnpm install
   ```
 
2. Copy the example environment file and fill in your values:
   ```bash
   cp .env.example .env
   ```
   Then edit `.env` with your OpenAI API key, Supabase credentials, Langfuse keys, and Google OAuth credentials.
 
3. Run the tests:
   ```bash
   pnpm test            # vitest run with coverage
   ```
 
4. Start the development server:
   ```bash
   pnpm dev             # next dev
   ```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).