Capstone 1 — Domain C: UCC Filing Lookup Agent

# Run each line on its own — works in bash, zsh, cmd.exe, and PowerShell 5.1+
mkdir capstone-1-ucc-lookup
cd capstone-1-ucc-lookup
python -m venv venv
# macOS/Linux:        source venv/bin/activate
# Windows PowerShell: venv\Scripts\Activate.ps1
# Windows cmd.exe:    venv\Scripts\activate.bat

# Save dependencies — keeps the env reproducible
echo "anthropic>=0.40.0" > requirements.txt
pip install -r requirements.txt

# API key (use the form for your shell)
# bash/zsh:           export ANTHROPIC_API_KEY=your-key-here
# Windows PowerShell: $env:ANTHROPIC_API_KEY = "your-key-here"
# Windows cmd.exe:    set ANTHROPIC_API_KEY=your-key-here

# Run each line on its own — works in bash, zsh, cmd.exe, and PowerShell 5.1+
mkdir capstone-1-ucc-lookup
cd capstone-1-ucc-lookup
npm init -y
npm install @anthropic-ai/sdk typescript ts-node

# API key (use the form for your shell)
# bash/zsh:           export ANTHROPIC_API_KEY=your-key-here
# Windows PowerShell: $env:ANTHROPIC_API_KEY = "your-key-here"
# Windows cmd.exe:    set ANTHROPIC_API_KEY=your-key-here

capstone-1-ucc-lookup/
├── mock_sos.py          # Mock Secretary of State data
├── ucc_agent.py         # Main agent with tool-use loop
├── mock_sos.ts          # TypeScript mock data
├── ucc_agent.ts         # TypeScript agent
└── requirements.txt     # Dependencies

{
  "business_name": "string — the searched entity name",
  "state": "string — 2-letter state code",
  "search_timestamp": "string — ISO 8601 datetime",
  "filings": [
    {
      "filing_number": "string — state filing ID",
      "filing_type": "string — UCC-1 | UCC-3",
      "filing_date": "string — YYYY-MM-DD",
      "lapse_date": "string — YYYY-MM-DD",
      "status": "string — active | lapsed | terminated",
      "secured_party": {
        "name": "string — lender/creditor name",
        "address": "string — full mailing address"
      },
      "debtor": {
        "name": "string — business entity name",
        "address": "string — full mailing address"
      },
      "collateral_description": "string — free-text description",
      "amendments": ["array of amendment objects"]
    }
  ],
  "total_filings": "number — count of filings returned"
}

# mock_sos.py — Mock Secretary of State UCC filing database
# Simulates UCC filing search across multiple states.

VALID_STATES = {"DE", "NY", "CA", "TX", "FL", "IL", "OH", "PA", "NJ", "GA"}

MOCK_FILINGS = {
    ("acme logistics llc", "DE"): {
        "business_name": "Acme Logistics LLC",
        "state": "DE",
        "search_timestamp": "2024-03-10T14:30:00Z",
        "filings": [
            {
                "filing_number": "2023-1234567",
                "filing_type": "UCC-1",
                "filing_date": "2023-06-15",
                "lapse_date": "2028-06-15",
                "status": "active",
                "secured_party": {"name": "First National Bank", "address": "123 Main St, Wilmington, DE 19801"},
                "debtor": {"name": "Acme Logistics LLC", "address": "456 Commerce Blvd, Dover, DE 19901"},
                "collateral_description": "All inventory, accounts receivable, and equipment now owned or hereafter acquired.",
                "amendments": [],
            },
            {
                "filing_number": "2022-9876543",
                "filing_type": "UCC-1",
                "filing_date": "2022-01-20",
                "lapse_date": "2027-01-20",
                "status": "active",
                "secured_party": {"name": "Delaware Capital Partners", "address": "789 Finance Row, Wilmington, DE 19801"},
                "debtor": {"name": "Acme Logistics LLC", "address": "456 Commerce Blvd, Dover, DE 19901"},
                "collateral_description": "All vehicles and transportation equipment.",
                "amendments": [],
            },
        ],
        "total_filings": 2,
    },
    ("buildright construction", "NY"): {
        "business_name": "BuildRight Construction",
        "state": "NY",
        "search_timestamp": "2024-03-10T14:31:00Z",
        "filings": [
            {
                "filing_number": "NY-2024-0055123",
                "filing_type": "UCC-1",
                "filing_date": "2024-01-10",
                "lapse_date": "2029-01-10",
                "status": "active",
                "secured_party": {"name": "Empire State Lending Corp", "address": "100 Wall St, New York, NY 10005"},
                "debtor": {"name": "BuildRight Construction", "address": "88 Builder Ave, Albany, NY 12207"},
                "collateral_description": "All construction equipment, heavy machinery, and related parts inventory.",
                "amendments": [],
            },
        ],
        "total_filings": 1,
    },
    ("metro holdings inc", "CA"): {
        "business_name": "Metro Holdings Inc",
        "state": "CA",
        "search_timestamp": "2024-03-10T14:32:00Z",
        "filings": [],
        "total_filings": 0,
    },
    ("riverside trucking llc", "TX"): {
        "business_name": "Riverside Trucking LLC",
        "state": "TX",
        "search_timestamp": "2024-03-10T14:32:00Z",
        "filings": [
            {
                "filing_number": "TX-2023-89441",
                "filing_type": "UCC-1",
                "filing_date": "2023-09-12",
                "lapse_date": "2028-09-12",
                "status": "active",
                "secured_party": {"name": "First National Bank", "address": "123 Main St, Dallas, TX 75201"},
                "debtor": {"name": "Riverside Trucking LLC", "address": "200 River Rd, Houston, TX 77002"},
                "collateral_description": "All trucks, trailers, and titled rolling stock; specifically 6 Peterbilt 579 model year 2022.",
                "amendments": [],
            },
        ],
        "total_filings": 1,
    },
    ("metalworks incorporated", "DE"): {
        "business_name": "MetalWorks Incorporated",
        "state": "DE",
        "search_timestamp": "2024-03-10T14:32:00Z",
        "filings": [
            {
                "filing_number": "DE-2022-44102",
                "filing_type": "UCC-1",
                "filing_date": "2022-04-18",
                "lapse_date": "2029-04-18",
                "status": "active",
                "secured_party": {"name": "Industrial Lenders LLC", "address": "55 Capital Way, Wilmington, DE 19801"},
                "debtor": {"name": "MetalWorks Incorporated", "address": "12 Foundry Ln, Newark, DE 19711"},
                "collateral_description": "Equipment, inventory, and accounts receivable now owned or hereafter acquired.",
                "amendments": [
                    {"filing_number": "DE-2024-00811", "amendment_type": "continuation", "filing_date": "2024-01-22", "new_lapse_date": "2029-04-18"},
                ],
            },
        ],
        "total_filings": 1,
    },
}


def search_ucc_filings(business_name: str, state: str) -> dict:
    """Search UCC filings for a business in a specific state."""
    try:
        # Validate state code
        if not state or len(state) != 2:
            return {
                "is_error": True,
                "error_category": "INVALID_STATE",
                "is_retryable": False,
                "context": f"Invalid state code: '{state}'. Provide a 2-letter US state code.",
            }
        state_upper = state.upper()
        if state_upper not in VALID_STATES:
            return {
                "is_error": True,
                "error_category": "INVALID_STATE",
                "is_retryable": False,
                "context": f"State '{state_upper}' not in supported states: {', '.join(sorted(VALID_STATES))}",
            }

        # Simulate timeout for TX (for testing)
        if state_upper == "TX" and business_name.lower() == "timeout test":
            return {
                "is_error": True,
                "error_category": "SERVICE_TIMEOUT",
                "is_retryable": True,
                "context": "Texas SOS service timed out after 30 seconds.",
            }

        # Look up filings
        key = (business_name.lower().strip(), state_upper)
        result = MOCK_FILINGS.get(key)

        if result:
            return {"is_error": False, **result}

        # No results found (valid search, just no matches)
        return {
            "is_error": False,
            "business_name": business_name,
            "state": state_upper,
            "search_timestamp": "2024-03-10T14:35:00Z",
            "filings": [],
            "total_filings": 0,
        }

    except Exception as e:
        return {
            "is_error": True,
            "error_category": "INTERNAL_ERROR",
            "is_retryable": True,
            "context": str(e),
        }

python -c "from mock_sos import search_ucc_filings; print(search_ucc_filings('Acme Logistics LLC', 'DE'))"

# ucc_agent.py — UCC Filing Lookup Agent (Capstone 1, Domain C)
# A single-tool conversational agent that searches UCC filings
# and summarizes lien exposure in plain English.

import anthropic
import json
from mock_sos import search_ucc_filings

SYSTEM_PROMPT = """You are a UCC Filing Lookup Agent for commercial lenders.
Your job is to help credit analysts assess lien exposure on prospective
borrowers by searching Secretary of State UCC filing records.

You have access to one tool:
- search_ucc_filings: Search UCC filings by business name and state

Rules:
- Always ask for the state if the user doesn't provide one.
- Summarize filings in plain English — not raw JSON.
- For each active filing, clearly state: secured party, collateral,
  filing date, and lapse date.
- If there are no filings, report a clean lien status.
- Warn the user that results may be incomplete (name variations,
  filings in other states).
- You can ONLY search filings. You cannot file, modify, or delete them.
- Never reveal raw error details to the user.
"""

TOOLS = [
    {
        "name": "search_ucc_filings",
        "description": (
            "Search the Secretary of State UCC filing database for a "
            "business entity in a specific state. Returns all active "
            "and lapsed filings with secured party, collateral, and dates."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "business_name": {
                    "type": "string",
                    "description": "The business entity name to search for",
                },
                "state": {
                    "type": "string",
                    "description": "2-letter US state code (e.g., DE, NY, CA)",
                },
            },
            "required": ["business_name", "state"],
        },
    },
]

TOOL_HANDLERS = {
    "search_ucc_filings": lambda args: search_ucc_filings(
        args["business_name"], args["state"]
    ),
}


def run_agent(user_message: str, history: list | None = None) -> tuple[str, list]:
    """
    Run the UCC lookup agent. Supports multi-turn conversation
    by accepting and returning message history.
    """
    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY env var
    messages = history or []
    messages.append({"role": "user", "content": user_message})
    tools_called = []

    for _ in range(5):  # safety net
        try:
            response = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                system=SYSTEM_PROMPT,
                tools=TOOLS,
                messages=messages,
            )
        except anthropic.APIError as e:
            return f"Sorry, I encountered a technical issue: {e}", messages

        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    tools_called.append(block.name)
                    handler = TOOL_HANDLERS.get(block.name)
                    result = handler(block.input) if handler else {
                        "is_error": True,
                        "error_category": "UNKNOWN_TOOL",
                        "context": block.name,
                    }
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": json.dumps(result),
                    })
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})

        elif response.stop_reason == "end_turn":
            text = " ".join(
                b.text for b in response.content if hasattr(b, "text")
            )
            messages.append({"role": "assistant", "content": response.content})
            return text, messages

    return "I was unable to complete your request.", messages


if __name__ == "__main__":
    print("UCC Filing Lookup Agent — Type 'quit' to exit.\n")
    history = []
    while True:
        query = input("You: ").strip()
        if query.lower() in ("quit", "exit", "q"):
            break
        response, history = run_agent(query, history)
        print(f"\nAgent: {response}\n")

python ucc_agent.py

python -c "
from ucc_agent import run_agent
response, _ = run_agent('Search for Acme Logistics LLC in Delaware')
print(response)
assert 'First National Bank' in response, 'Missing secured party'
assert 'active' in response.lower(), 'Missing filing status'
print('\n--- ALL CHECKS PASSED ---')
"