b10fbreez/claudestack

Surplus Funds Recovery Service — Skill Reference

What This Does

This is an AI-powered surplus funds recovery business built as a Python service. After a property is sold at a foreclosure auction for more than what was owed, the excess (surplus) goes into a court-held account. The former owner is entitled to that money but often doesn't know it exists. This service finds those cases, locates the claimants, generates the legal paperwork, and files the claims — charging a percentage of recovered funds.

Core Skills

1. Lead Research

• Scrapes county surplus fund lists
• Parses sale records (HTML tables, APIs)
• Calculates surplus amounts (sale price - judgment)
• Qualifies leads (minimum threshold, deadline check, dedup)
• Converts qualified leads into tracked cases

2. Claimant Location

• Builds ownership chains from property records
• Identifies potential claimants (former owners, heirs, lienholders)
• Runs skip tracing (structured for API integration)
• Manages multiple contact records per claimant
• Verifies identity and claim basis

3. Document Generation

• Claim forms (county-specific, court-ready)
• Affidavits of entitlement (with notary block)
• Fee/assignment agreements (contingency-based)
• Full filing packets in one command
• HTML output, extensible templates

4. AI Agent

• Case viability analysis (1-10 scoring)
• Next action recommendations per status
• Outreach letter drafting
• Daily pipeline briefing
• General-purpose Q&A about the pipeline

5. Memory System

• Per-case notes by category (research, contact, legal, strategy, filing, outcome, lesson)
• Cross-case lessons learned (the agent gets smarter)
• County-specific playbooks (auto-built from case history)
• Agent session memory (persists between sessions)

Case Status Flow

lead -> contacted -> signed -> documents_prepared -> filed -> under_review -> approved -> funds_received -> fee_collected -> closed

Side exits: rejected, abandoned

Fee Structure

• Default: 30% of recovered surplus (configurable 25-35%)
• Alternative: flat fee option available
• Contingency-based: no recovery = no fee
• Fee calculated automatically from case data

Tech Stack

• Python 3.11+ with async/await throughout
• FastAPI for REST API
• SQLAlchemy 2.0 async ORM
• SQLite (default) / PostgreSQL (production)
• Typer + Rich for CLI
• Jinja2 for document templates
• Anthropic Claude for AI agent
• httpx + BeautifulSoup for web scraping

Key Files

| File | Purpose | |------|---------| | main.py | CLI entry point — all commands | | backend.py | FastAPI server | | surplus_funds/config.py | Settings from .env | | surplus_funds/database.py | DB engine + session | | surplus_funds/models/case.py | Case model (central entity) | | surplus_funds/models/property.py | Property + foreclosure sale | | surplus_funds/models/claimant.py | Claimant + contact info | | surplus_funds/models/document.py | Generated documents | | surplus_funds/services/research_engine.py | Lead scraping + qualification | | surplus_funds/services/claimant_locator.py | Skip tracing + ownership chain | | surplus_funds/services/document_generator.py | Legal document rendering | | surplus_funds/services/ai_agent.py | Claude-powered analysis | | surplus_funds/memory/case_memory.py | Memory layer | | surplus_funds/api/routes.py | API endpoints | | surplus_funds/api/schemas.py | Request/response schemas | | outreach_templates.yaml | Claimant contact templates (mail, phone, email) |

Outreach Templates

outreach_templates.yaml contains ready-to-use templates for every stage of claimant contact:

| Template | Channel | When | |----------|---------|------| | initial_contact | Mail | First letter — within 48h of lead qualification | | follow_up | Mail | 10-14 days after initial contact, no response | | phone_script | Phone | Warm/cold call with objection handling | | email_outreach | Email | Supplemental or preferred channel | | agreement_cover | Mail | Sent with fee agreement packet | | filing_confirmation | Mail | Within 48h of filing claim | | recovery_notification | Mail | Funds approved/received |

Templates use {{mustache}} variables populated from case data. State-specific compliance notes included for FL, TX, CA, and GA.

Extending

Add a New County Source

Edit surplus_funds/services/research_engine.py and add to COUNTY_SOURCES:

CountySource(
    county="Your County",
    state="FL",
    url="https://clerk.yourcounty.gov/surplus",
    source_type="html_table",
    selectors={...},
)

Add a New Document Template

Drop an HTML template in surplus_funds/templates/ and add a generator method in document_generator.py.

Integrate Skip Tracing API

Replace the placeholder in claimant_locator.py skip_trace() method with your TLO/Accurint/BeenVerified API calls.

Switch to PostgreSQL

Update .env:

SF_DATABASE_URL=postgresql+asyncpg://user:pass@localhost/surplus_funds