Skip to content

architecture.md

Latest commit

 

History

History
94 lines (76 loc) · 5.45 KB

architecture.md

File metadata and controls

94 lines (76 loc) · 5.45 KB
Raw

Architecture — TXLookup

This is the codified version of the kickoff whiteboard sketch.

Layers

                 ┌─────────────┐
                 │   Models    │  Codex / GPT-4o / Featherless / local Ollama
                 └──────┬──────┘
                        │
┌─────────┐   ┌────────▼─────────┐   ┌─────────┐
│ Dataset │──▶│      Ingest      │──▶│   DB    │  (Supabase, optional)
│Socrata  │   │ httpx + pandas   │   └────┬────┘
└─────────┘   └──────────────────┘        │
                                          │
            ┌─────────────────────────────┼─────────────────────────────┐
            │                             │                             │
       ┌────▼────┐                  ┌─────▼─────┐                  ┌────▼────┐
       │ Agents  │                  │   APIs    │                  │   MCP   │
       │         │                  │           │                  │  Server │
       │ Reason  │                  │ Socrata   │                  │ FastMCP │
       │  Plan   │                  │ Census    │                  │         │
       │ Tool Use│                  │ Geo       │                  │ tools:  │
       │Complete │                  │           │                  │ discover│
       │         │                  │           │                  │ describe│
       │         │                  │           │                  │ query   │
       │         │                  │           │                  │summarize│
       │         │                  │           │                  │ cite    │
       └────┬────┘                  └─────┬─────┘                  └────┬────┘
            │                             │                             │
            └─────────────────────────────┼─────────────────────────────┘
                                          │
                                  ┌───────▼────────┐
                                  │       UI       │  Next.js (search / map / chart)
                                  │      Miro      │  Visual data board (bounty)
                                  └────────────────┘

Layer responsibilities

Models

LLM provider routing. Codex/GPT-4o for the planner; Featherless or local Ollama for cheap iteration; structured-output mode for plans + summaries. Config in config/models.yaml.

Dataset

Public data sources. SODA-based Texas city portals + state portal + Census. Catalog lives in config/datasets.yaml.

Ingest

agent/tools/data.py — Socrata SODA client. httpx async, pandas for transforms. Bounded by skill rules (max limit, timeout, backoff).

DB

Supabase. Optional for v1 — we go direct portal-to-agent live. Becomes load-bearing in Step 1 for caching repeat queries.

Agents

agent/main.py orchestrator. Reason → Plan → Execute → Complete loop with doom-loop detection (3+ identical tool calls or [A,B,A,B] repeating sequences trigger a corrective system prompt) and context compaction at ~150k tokens.

APIs

Direct API clients (Socrata, Census, geocoding). Used by both the agent (when it needs raw data) and the MCP server (when it serves a tool call).

MCP Server

mcp/server.py — FastMCP. Exposes the five core tools: discover, describe, query, summarize, cite. This is the surface that external agents (Claude Code, Cursor, Codex) bind to.

UI

  • Next.js app (app/) — search, map, table, chart views per persona
  • Miro board — generated by the Miro-MCP integration for the wow demo

Data flow — one query end-to-end

1. User (persona) types or speaks question into UI
2. UI POSTs to /api/agent
3. Orchestrator calls planner → plan = ["discover", "describe", "query", "summarize", "cite"]
4. Executor dispatches each step:
   - discover → MCP server → catalog lookup
   - describe → MCP server → schema + sample rows
   - query/summarize → MCP server → Socrata API → records
   - cite → MCP server → citation block
5. Orchestrator composes answer + (optionally) writes Miro board
6. UI renders answer with citations

What's NOT in scope for v1

  • Bulk data warehousing (we hit the portal live)
  • Multi-tenant auth (single-user demo)
  • Write-back to portals (read-only)
  • Realtime streams (this is reporting data)

Why MCP server + skill doc, both

Track rules (Brainforge/Vicinity): ship at least one of MCP server OR agent skill. Teams that ship both are "especially competitive." We ship both because:

  • The MCP server is the machine interface — any agent runtime can bind to it
  • The skill doc is the policy + invocation guide — tells the agent when and how to use the tools safely
  • Together they make TXLookup re-usable beyond the demo