Agentic AI (Python)
Python full rebuild · ReAct · FastAPI

Your Library Knowledge Base

A conversational AI assistant that answers from your own PDFs, the live web, or its own knowledge — you decide, with two toggles. Built in Python as three FastAPI services, styled after python.org, and honest about where every answer came from.

3 FastAPI services ReAct agent loop Pinecone + Ollama embeddings MongoDB memory + MCP Tavily web search 72 pytest tests Ollama → Claude backend
3
Python services
2
source toggles
5
agent tools
72
passing tests
What it does

Pick your source. Trust the answer.

Every answer carries an honest provenance label, so you always know whether it came from your library, the web, the database, or the model itself.

Web toggle

Flip on 🌐 Web and the agent may call Tavily. Source URLs are captured, rendered as clickable citations, and persisted with the conversation.

My Library toggle

Flip on 📚 My Library for your ingested PDFs (Pinecone vector search) and the MongoDB MCP CRUD tools. Both toggles off = the model's own knowledge.

Conversation memory

History lives in MongoDB via motor. A past-conversations sidebar reopens any chat, and a read-only recall_history tool gives the model exact deep recall.

Drag-and-drop ingestion

The retrieval service has a modern upload page: extract → chunk → embed (Ollama) → upsert to Pinecone, plus a Mongo books catalog for per-book narrowing.

Clarify-back

When a topic can't be pinned to a specific book, the agent asks "do you mean Game of Thrones or…?" instead of guessing — backed by the catalog.

Tiered context token-budgeted

Recent turns verbatim, older folded into a rolling summary, raw tool observations never replayed — so prompts stay cheap even on local Ollama.

Architecture

Three Python services, one assistant

A clean separation: the agent reasons, the retrieval service owns PDFs and vectors, and the MCP server exposes MongoDB as model tools over SSE.

:8082

agent/

The conversational ReAct agent and chat UI.

  • FastAPI + static chat UI
  • ReAct loop, tool gating by toggle
  • Conversation store (motor)
  • LLM backend: Ollama or Claude
:8081

retrieval/

PDF ingestion + vector search.

  • Drag-drop upload UI
  • extract → chunk → embed → upsert
  • Pinecone store + books catalog
  • POST /api/search streams SSE
:8083

mcp_server/

MongoDB as MCP tools over SSE.

  • Official Python mcp SDK
  • list / query / insert / update / delete
  • Discovered at runtime by the agent
  • Plain CRUD — no vectors here
Browser chat UI · ingest UI agent :8082 toggles gate tools memory · summary web_search Tavily · citations search_pdf retrieval :8081 (SSE) mcp (umbrella) mcp_server :8083 (SSE) recall_history read-only · scoped Web Tavily · live search Pinecone vector search MongoDB books · convos Mongo (memory) recall_history store

The agent exposes only the tools its toggles allow: recall_history is always on; My Library adds search_pdf + mcp; Web adds web_search. Backend is Ollama by default, Claude when a key, model, and credit flag are all set.

How it works

One turn, end to end

Ask

You type a question and choose Web, My Library, both, or neither.

Assemble

The agent builds a budgeted prompt: branched system + rolling summary + last K turns.

Reason & act

A ReAct loop calls only the allowed tools — vector search, web, MCP, recall.

Answer

Final text is persisted with provenance + citations; raw observations are dropped.

In action

A step-by-step walkthrough

The real UIs, in python.org light theme. (Screenshots are generated by docs/capture_screenshots.py against the running apps.)

01

The chat hero

Open the agent at :8082. A blue gradient hero over a clean chat column, with the past-conversations sidebar on the right — all in the python.org palette.

Agent chat landing page with hero band and sidebar
agent/app/static — chat landing
02

Source toggles

Two pills — 🌐 Web and 📚 My Library. Active = filled blue, inactive = blue outline. They gate which tools the agent may use this turn.

Web and My Library toggles, both active
Both toggles active
03

Answer with provenance + clickable web sources

Every answer carries an honest source chip — from Web, from My Library, from Database, or model's own knowledge — and web answers list clickable Tavily citations.

Assistant answer with provenance chip and clickable web citations
Provenance + Tavily citations
04

Drag-and-drop ingestion

The retrieval service at :8081 has a modern drop zone. Drop a PDF, give it a title, and the pipeline extracts, chunks, embeds, and upserts to Pinecone + the catalog.

PDF drag-and-drop ingestion page
retrieval/app/static — upload
Ingestion status console reporting pages, chunks, and vectors upserted
Real ingestion — pages, chunks, and vectors upserted
05

The search-test panel

A built-in panel hits Pinecone directly (the raw vectors the agent uses), so you can confirm a freshly-ingested PDF is findable without going through the LLM.

Vector search test panel with dark console output
Direct vector search test
06

Past-conversations sidebar

Every conversation is saved. Click any item to reopen it; the agent reloads the thread and keeps reasoning with full token-budgeted memory.

Past conversations sidebar with saved chats
Reopen any prior chat
Setup

One command to get running

macOS one-shot setup: installs/verifies Python 3.12+, MongoDB, and Ollama; creates the venv; pulls models; and prepares config.json. Idempotent — safe to re-run.

# from the repo root $ ./setup.sh # then launch all three services $ ./run.sh
API keys can't be auto-provisioned. setup.sh reads TAVILY_API_KEY, PINECONE_API_KEY, and the Anthropic vars from your environment if set; otherwise it writes placeholders into config.json (gitignored) and prints exactly which keys to fill in. Ollama-only and library/web features degrade gracefully without them.

What it automates

Toolchain

Verifies Homebrew, installs Python 3.12+, creates .venv, and runs pip install -e ".[dev]".

Services & models

Installs & starts MongoDB and Ollama, pulls nomic-embed-text (embeddings) and a chat model (e.g. gemma2:2b).

Config

Copies config.example.json → config.json if missing, injecting any keys found in the environment.

Launcher

Writes run.sh to start all three uvicorn services (agent, retrieval, mcp_server) together.

Run services manually

$ source .venv/bin/activate $ uvicorn retrieval.app.main:app --port 8081 # PDF ingest + search $ uvicorn agent.app.main:app --port 8082 # chat UI $ uvicorn mcp_server.app.server:app --port 8083 # Mongo MCP (SSE)
Reference

Technical docs