Capstone 2 — Domain C: UCC Regulatory Reference Agent

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

# Pin dependencies for reproducibility
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

capstone-2-ucc-rag/
├── mock_kb.py           # Mock knowledge base with UCC chunks
├── ucc_rag_agent.py     # RAG agent with tool-use loop
├── mock_kb.ts           # TypeScript mock knowledge base
├── ucc_rag_agent.ts     # TypeScript RAG agent
└── requirements.txt     # Dependencies

{
  "documents": [
    {
      "doc_id": "string — unique document identifier",
      "title": "string — document title",
      "doc_type": "article_9_guide | state_handbook | collateral_guide",
      "sections": [
        {
          "section_id": "string — legal section reference (e.g., 9-301)",
          "title": "string — section heading",
          "content": "string — full section text"
        }
      ]
    }
  ]
}

# mock_kb.py — Mock UCC Knowledge Base with simple similarity search
# In production, replace with ChromaDB / Pinecone / pgvector.

from dataclasses import dataclass

@dataclass
class Chunk:
    chunk_id: str
    doc_id: str
    section_id: str
    doc_type: str  # article_9_guide | state_handbook | collateral_guide
    title: str
    content: str
    state: str | None = None  # for state handbooks

# --- Mock corpus chunked by section ---
CHUNKS = [
    Chunk("c001", "UCC-ART9-GUIDE", "9-301", "article_9_guide",
          "Law Governing Perfection and Priority",
          "The law of the jurisdiction where the debtor is located governs "
          "perfection of a security interest. For registered organizations "
          "(corporations, LLCs), the debtor is located in the state of "
          "organization. For individuals, the debtor is located at their "
          "principal residence. This means a Delaware LLC's filings are "
          "governed by Delaware law, regardless of where the collateral "
          "is physically located."),
    Chunk("c002", "UCC-ART9-GUIDE", "9-310", "article_9_guide",
          "Filing Required to Perfect",
          "A financing statement must be filed to perfect a security "
          "interest in most types of collateral. Exceptions include: "
          "possessory security interests (9-313) where the secured party "
          "takes physical possession, control-based perfection for deposit "
          "accounts (9-314), and automatic perfection for purchase money "
          "security interests in consumer goods (9-309)."),
    Chunk("c003", "UCC-ART9-GUIDE", "9-502", "article_9_guide",
          "Contents of Financing Statement",
          "A financing statement is sufficient if it provides: (1) the "
          "name of the debtor, (2) the name of the secured party or "
          "representative, and (3) an indication of the collateral. "
          "The debtor name must EXACTLY match the name on the state's "
          "public organic record (certificate of formation, articles of "
          "incorporation). A misspelled debtor name can render the filing "
          "seriously misleading and therefore ineffective."),
    Chunk("c004", "STATE-GUIDE-TX", "TX-FILING-01", "state_handbook",
          "Where to File in Texas",
          "In Texas, UCC financing statements are filed with the "
          "Secretary of State. Filing can be done online at SOSDirect "
          "(direct.sos.state.tx.us), by mail to PO Box 13193 Austin TX 78711, "
          "or in person. Filing fee: $15 per page (standard), $5 per page "
          "(online via SOSDirect). Processing time: online filings are "
          "typically processed same-day; mail filings take 5-7 business days.",
          state="TX"),
    Chunk("c005", "STATE-GUIDE-DE", "DE-FILING-01", "state_handbook",
          "Where to File in Delaware",
          "In Delaware, UCC financing statements are filed with the "
          "Division of Corporations under the Secretary of State. Online "
          "filing available at corp.delaware.gov. Filing fee: $50 for a "
          "standard financing statement. Delaware is the most common "
          "filing jurisdiction for registered entities because many "
          "corporations and LLCs are organized in Delaware.",
          state="DE"),
    Chunk("c006", "COLLATERAL-GUIDE", "CC-INVENTORY", "collateral_guide",
          "Inventory Collateral",
          "Inventory includes goods held for sale or lease, raw materials, "
          "work in process, and materials used or consumed in a business. "
          "Key distinction from Equipment: if the debtor holds the goods "
          "for sale to customers, they are inventory; if the debtor uses "
          "the goods in its own operations, they are equipment. This "
          "classification matters because purchase money security interests "
          "in inventory have different priority rules than PMSI in equipment."),
    Chunk("c007", "COLLATERAL-GUIDE", "CC-EQUIPMENT", "collateral_guide",
          "Equipment Collateral",
          "Equipment means goods used or bought for use primarily in a "
          "business. Examples: manufacturing machinery, office computers, "
          "delivery vehicles. If the debtor holds goods for sale, they are "
          "inventory, not equipment. Equipment includes fixtures (goods "
          "that become part of real property) but fixture filings have "
          "special rules under 9-334."),
    Chunk("c008", "UCC-ART9-GUIDE", "9-515", "article_9_guide",
          "Duration and Lapse of Financing Statement",
          "A filed financing statement is effective for 5 years after the "
          "date of filing. To continue effectiveness, a continuation "
          "statement (UCC-3) must be filed within 6 months before lapse. "
          "If the continuation is not filed, the financing statement "
          "lapses and the security interest becomes unperfected. An "
          "unperfected security interest loses priority to subsequent "
          "perfected interests and to a trustee in bankruptcy."),
]


def search_ucc_knowledge_base(
    query: str,
    top_k: int = 5,
    filters: dict | None = None,
) -> dict:
    """
    Search the mock UCC knowledge base using keyword matching.
    In production, replace with vector similarity search.
    """
    try:
        if not query or not query.strip():
            return {"is_error": True, "error_category": "EMPTY_QUERY",
                    "is_retryable": False, "context": "Query cannot be empty."}

        query_lower = query.lower()
        query_terms = query_lower.split()

        # Filter chunks
        candidates = CHUNKS
        if filters:
            if filters.get("doc_type"):
                candidates = [c for c in candidates if c.doc_type == filters["doc_type"]]
            if filters.get("state"):
                candidates = [c for c in candidates if c.state == filters["state"].upper()]
            if filters.get("section_id"):
                candidates = [c for c in candidates if c.section_id == filters["section_id"]]

        # Score by keyword overlap (mock similarity)
        scored = []
        for chunk in candidates:
            text = (chunk.title + " " + chunk.content).lower()
            score = sum(1 for term in query_terms if term in text) / max(len(query_terms), 1)
            if score > 0:
                scored.append((chunk, round(score, 3)))

        scored.sort(key=lambda x: x[1], reverse=True)
        top = scored[:top_k]

        results = []
        for chunk, score in top:
            results.append({
                "chunk_id": chunk.chunk_id,
                "doc_id": chunk.doc_id,
                "section_id": chunk.section_id,
                "title": chunk.title,
                "content": chunk.content,
                "similarity_score": score,
                "metadata": {
                    "doc_type": chunk.doc_type,
                    "state": chunk.state,
                },
            })

        return {"is_error": False, "results": results, "total": len(results)}

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

# Quick sanity test — run from the project directory:
python -c "from mock_kb import search_ucc_knowledge_base; print(search_ucc_knowledge_base('filing Texas'))"

# ucc_rag_agent.py — RAG-Powered UCC Reference Agent
import anthropic
import json
from mock_kb import search_ucc_knowledge_base

SYSTEM_PROMPT = """You are a UCC Article 9 Reference Agent for commercial
lending professionals. You answer questions about UCC filing requirements,
collateral classifications, perfection rules, and state-specific procedures.

You have access to a knowledge base of UCC reference materials via the
search_ucc_knowledge_base tool. ALWAYS search before answering.

CITATION RULES (critical):
- Every factual claim MUST cite a specific section: (Section 9-310)
- If a claim comes from a state handbook, cite it: (TX-FILING-01)
- If you cannot find relevant information, say so explicitly.
  Do NOT guess or make up legal information.
- You provide REFERENCE INFORMATION only. You do NOT provide legal advice.
- Always recommend consulting counsel for specific legal questions.

RESPONSE FORMAT:
- Use clear headings and bullet points for multi-part answers
- Cite sources inline: "Filing is required to perfect (Section 9-310)"
- End with a "Sources" list showing all cited sections
"""

TOOLS = [
    {
        "name": "search_ucc_knowledge_base",
        "description": (
            "Search the UCC reference knowledge base for information about "
            "Article 9 filing requirements, collateral classifications, "
            "perfection rules, and state-specific procedures. Returns "
            "relevant document sections with citation references."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Natural language search query",
                },
                "top_k": {
                    "type": "integer",
                    "description": "Number of results to return (default 5)",
                },
                "filters": {
                    "type": "object",
                    "description": "Optional filters",
                    "properties": {
                        "doc_type": {
                            "type": "string",
                            "enum": ["article_9_guide", "state_handbook", "collateral_guide"],
                        },
                        "state": {"type": "string"},
                        "section_id": {"type": "string"},
                    },
                },
            },
            "required": ["query"],
        },
    },
]

TOOL_HANDLERS = {
    "search_ucc_knowledge_base": lambda args: search_ucc_knowledge_base(
        query=args["query"],
        top_k=args.get("top_k", 5),
        filters=args.get("filters"),
    ),
}


def run_rag_agent(user_message: str, history: list | None = None) -> tuple[str, list]:
    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY env var
    messages = history or []
    messages.append({"role": "user", "content": user_message})

    for _ in range(5):
        try:
            response = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=2048,
                system=SYSTEM_PROMPT,
                tools=TOOLS,
                messages=messages,
            )
        except anthropic.APIError as e:
            return f"Technical issue: {e}", messages

        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    handler = TOOL_HANDLERS.get(block.name)
                    result = handler(block.input) if handler else {
                        "is_error": True, "error_category": "UNKNOWN_TOOL",
                    }
                    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 "Unable to complete your request.", messages


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

python ucc_rag_agent.py

python ucc_rag_agent.py

# verify.py — End-to-end smoke test
from ucc_rag_agent import run_rag_agent

test_queries = [
    ("Where do I file a UCC-1 in Delaware?", ["DE-FILING-01"]),
    ("What is the difference between inventory and equipment?", ["CC-INVENTORY", "CC-EQUIPMENT"]),
    ("How long is a financing statement effective?", ["9-515"]),
]

print("=== End-to-End Verification ===\n")
passed = 0
for query, expected_citations in test_queries:
    response, _ = run_rag_agent(query)
    found = [cit for cit in expected_citations if cit in response]
    status = "PASS" if len(found) == len(expected_citations) else "FAIL"
    if status == "PASS":
        passed += 1
    print(f"[{status}] Query: {query}")
    print(f"       Expected citations: {expected_citations}")
    print(f"       Found: {found}\n")

print(f"Result: {passed}/{len(test_queries)} tests passed.")
if passed == len(test_queries):
    print("All tests passed — your RAG agent is working correctly!")

python verify.py