FastMCP × PydanticAI Research Agent

A conversational ReAct-style research agent using PydanticAI that connects to an MCP HTTP server (FastMCP) for open-web style tools: search, fetch, notes memory, and PII guard. Produces a structured research brief with numeric citations, short quotes, and persistent logs.

Features

• ReAct decision loop with MCP tool calls (search, fetch, notes, guard)
• Cleans & extracts snippets from fetched pages
• Builds 5–8 paragraph brief with inline numeric citations [n]
• Ensures ≥2 short quotes (≤10 words)
• References section mapping [n] to Title + URL (≥3 unique domains)
• PII guard check; creates HITL ticket if flagged
• Logs: search_results.json, selected_urls.json, snippets.json
• Persistent notes SQLite memory (notes.sqlite)

Quick Start

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip
pip install -r requirements.txt
Copy-Item .env.example .env  # then edit OPENAI_API_KEY if you have one

Run (ensure MCP_HTTP_URL points to a running MCP HTTP server fixture or dev server):

python -m student.run --topic "US semiconductor export controls (2024–2025) overview" --out artifacts

Optional: Run Local Dev MCP Stub

Start the stub server (separate terminal):

python -m student.dev_server

Then set in your shell before running the agent:

$env:MCP_HTTP_URL="http://127.0.0.1:8765"

Artifacts written to the output directory:

• brief.md (unless PII flagged)
• report.json (contains pii_flagged boolean)
• search_results.json
• selected_urls.json
• snippets.json
• notes.sqlite (or updated)
• hitl_ticket.json (only if PII flagged)
• reflection.txt (single 600–700 word reflection, generated once)

Environment Variables

• OPENAI_API_KEY (optional in grading if model stubbed)
• OPENAI_MODEL (default: openai:gpt-4o-mini)
• MCP_HTTP_URL (required): base URL of MCP HTTP server
• ASSIGNMENT_MODE (optional): dev or grading

Development Notes

If you lack a real MCP server, we will add a minimal stub later for local testing. The grader supplies its own deterministic MCP.

Reflection: Generated automatically (if absent) after a successful non-PII run as reflection.txt.

Safety

Do NOT commit real API keys (.env is gitignored). Revoke any key you pasted publicly.

License

Educational assignment scaffolding.