Surplus Funds Recovery Service

AI-powered service that identifies properties with surplus funds after foreclosure sales, locates rightful claimants, and generates legal paperwork packets. The memory layer tracks every case across sessions so the agent gets smarter with every recovery.

Revenue Model

Metric	Value
Price	25-35% of recovered surplus
Typical recovery	$5K-$50K per case
Target	3-5 closings/month
Cost	Filing fees + API costs
Net	$10K-$25K/month
Moat	Compounding case memory

Architecture

surplus_funds/
  models/          # SQLAlchemy models: Case, Property, Claimant, Document
  services/
    research_engine.py     # County surplus list scraping + lead qualification
    claimant_locator.py    # Ownership chain + skip tracing
    document_generator.py  # Claim forms, affidavits, fee agreements
    ai_agent.py            # Claude-powered analysis + strategy
  memory/
    case_memory.py         # Per-case + cross-case memory layer
  api/
    routes.py              # FastAPI REST endpoints
    schemas.py             # Pydantic request/response models
  templates/               # Jinja2 document templates
  config.py                # Settings from environment
  database.py              # Async SQLAlchemy engine

backend.py                 # FastAPI application entry point
main.py                    # CLI agent interface (Typer + Rich)

Setup

# Clone and install
pip install -r requirements.txt

# Configure
cp .env.example .env
# Edit .env with your Anthropic API key

# Initialize database
python main.py init

CLI Usage

# Create a new case
python main.py new-case \
  --county "Hillsborough" \
  --state "FL" \
  --address "123 Main St, Tampa, FL 33601" \
  --owner "John Smith" \
  --surplus 15000

# View all cases
python main.py cases

# View case details
python main.py case-detail <case_id>

# Run claimant identification + skip tracing
python main.py locate <case_id>

# Generate filing packet
python main.py generate-docs <case_id>

# AI case analysis
python main.py analyze <case_id>

# Get next recommended action
python main.py next-action <case_id>

# Daily briefing
python main.py briefing

# Ask the agent anything
python main.py ask "Which cases should I prioritize this week?"

# View pipeline dashboard
python main.py dashboard

# View case memory
python main.py memory <case_id>

# View lessons learned
python main.py lessons

# Update case status
python main.py update-status <case_id> signed --notes "Agreement signed 2/10"

API Usage

# Start the API server
uvicorn backend:app --reload

# Docs at http://localhost:8000/docs

Key Endpoints

Method	Path	Description
POST	/api/v1/cases	Create new case
GET	/api/v1/cases	List cases (filter by status, county, state)
GET	/api/v1/cases/{id}	Case detail
PATCH	/api/v1/cases/{id}	Update case
POST	/api/v1/cases/{id}/claimants/locate	Run skip tracing
POST	/api/v1/cases/{id}/documents/generate	Generate filing packet
GET	/api/v1/dashboard/stats	Pipeline statistics
GET	/api/v1/memory/lessons	Cross-case lessons learned
GET	/api/v1/memory/playbook/{county}/{state}	County playbook

Case Lifecycle

LEAD -> CONTACTED -> SIGNED -> DOCUMENTS_PREPARED -> FILED -> UNDER_REVIEW -> APPROVED -> FUNDS_RECEIVED -> FEE_COLLECTED -> CLOSED

Each status transition is tracked in memory. The AI agent uses this history across all cases to improve recommendations over time.

Memory System

The memory layer operates at two levels:

1. Case Memory — Per-case notes organized by category (research, contact, legal, strategy, filing, outcome, lesson). Attached directly to the case record.

2. Agent Session Memory — Global learnings persisted in JSON. Survives across agent sessions and informs every new case with accumulated wisdom.

3. County Playbook — Auto-generated from past cases in the same jurisdiction. Filing quirks, contact strategies, and success patterns specific to each county.

Document Generation

The filing packet includes:

• Claim Form — County-specific surplus funds claim
• Affidavit of Entitlement — Sworn statement with notary block
• Fee Agreement — Contingency-based recovery fee contract

Documents are rendered as HTML (printable) with all case-specific data populated. Templates are extensible via the templates/ directory.