42 is a local-first decision-support studio. Not a chatbot in a toga: its LangGraph workflow combines local retrieval, structured outputs, citation validation, parallel future-letter subgraphs, and human review. Bring a dilemma; the council debates it, and you keep the final word.
AI-generated voices are interpretations, not quotations. The future letters are fictional narratives and not predictions or professional advice.
Watch the full 4:24 demo video
- A multi-stage agent system: Conditional routing, subgraphs, parallel future generation, structured outputs, interruptions, and resumable state.
- Grounded, citation-aware responses: Searches a local library first, validates that generated excerpts appear in retrieved passages, and falls back to web research only when local evidence is insufficient.
- Human control by design: Pauses for clarification, lets users revise or approve the final exhibit, supports follow-up questions, and persists session state across API restarts.
- Privacy-conscious architecture: Dilemmas and source passages stay local through Ollama. Tavily is used only for fixed topic research queries and selected web extraction.
- Built for observable reasoning: Streams node progress and trace events to the interface so users can see where the workflow is moving and which sources informed the result.
- Tested agent contracts: Unit and integration coverage exercises routing, citations, checkpoints, follow-ups, restart recovery, local retrieval, and API file-safety behavior.
- Share a question — enter an open reflection or a choice with two paths.
- Clarify when necessary — the graph pauses if the question needs more context.
- Research the topic — search curated local PDFs first, then use web fallback when warranted.
- Stage an interpretation — multiple AI perspectives respond sequentially and a moderator distills tensions and agreements.
- Explore possible futures — for a clear decision, generate two independent, fictional letters grounded in the gathered evidence.
- Review, revise, or approve — submit critique before the exhibit is saved.
- Continue the conversation — ask follow-ups without rewriting the original future letters.
flowchart TD
U[User dilemma] --> API[FastAPI session API]
API --> G[LangGraph controller]
G --> C{Classify the question}
C -->|Needs context| I[Human clarification interrupt]
I --> G
C -->|Clear| R[Topic and evidence research]
R --> L[Local PDF library]
R --> W[Tavily web fallback]
L --> V[Citation validation]
W --> V
V --> RT[Sequential philosopher roundtable]
RT --> D{Decision or open question}
D -->|Decision| F[Parallel future subgraphs]
D -->|Open question| CR[Critique]
F --> CR
CR --> EX[Curated exhibit]
EX --> HR{Human review}
HR -->|Revise| G
HR -->|Approve| S[(SQLite checkpoints + saved exhibit)]
HR -->|Follow-up| FU[Focused follow-up research and discussion]
FU --> S
| Component | Responsibility |
|---|---|
fortytwo/graph.py |
Main LangGraph workflow, routing, review interrupts, and exhibit creation |
fortytwo/research.py |
Local-author discovery, relevance checks, Tavily search, and extraction |
fortytwo/library.py |
PDF extraction, chunking, embeddings, Chroma index, and passage retrieval |
fortytwo/roundtable.py |
Sequential interpretations and moderator distillation |
fortytwo/futures.py |
Parallel fictional future-letter subgraphs |
fortytwo/retrieval.py |
Citation and source-grounding validation |
api.py |
Durable FastAPI sessions, trace events, follow-ups, and exhibit storage |
frontend/ |
React interface for live progress, review, follow-ups, and source browsing |
The workflow is not a linear chatbot loop. LangGraph coordinates research, clarification, roundtable discussion, critic review, revision, exhibit curation, human approval, and follow-up branches. SQLite checkpointers preserve state, allowing paused conversations to resume after a restart.
- Local passages are prioritized over web search.
- Evidence is filtered for topical relevance and author diversity.
- Structured Pydantic outputs constrain routing and model-generated artifacts.
- A critic checks unsupported claims and citation validity.
- Generated citations must resolve to exact retrieved passage text.
The API exposes session status and ordered trace events. The frontend renders workflow stages as they complete, making the system understandable and easier to debug than an opaque chat response.
| Area | Technology |
|---|---|
| Agent orchestration | LangGraph |
| Model integration | LangChain Ollama |
| Structured outputs | Pydantic |
| Local language model | Ollama with qwen3.5:4b |
| Local embeddings | nomic-embed-text |
| Vector search | ChromaDB |
| PDF processing | PyPDF |
| Web research fallback | Tavily Search and Extract |
| API | FastAPI, Uvicorn |
| State and sessions | SQLite |
| Frontend | React 19, Vite |
ollama serve
ollama pull qwen3.5:4b
ollama pull nomic-embed-textuv syncCreate .env if it does not exist, then add your key:
TAVILY_API_KEY=your_api_keyThe repository includes philosophical PDFs. With Ollama running, build or rebuild the local index:
uv run python -m fortytwo.libraryTerminal 1 — API:
uv run --env-file .env uvicorn api:app --host 127.0.0.1 --port 8000Terminal 2 — frontend:
cd frontend
npm install
npm run devOpen http://127.0.0.1:5173.
Run the Python suite:
uv run python -m unittest -v \
test_api test_graph test_library test_local_research test_futuresCheck the frontend:
cd frontend
npm run lint
npm run buildThe test_api suite uses an isolated temporary SQLite database. Core graph
tests replace external models and services with deterministic fakes, so they
validate orchestration and contracts without making a live model call.
Passing unit tests establish software behavior; they do not establish quality of local model output. Use the small human-review set in evaluation/README.md to inspect relevance, citation accuracy, interpretation quality, latency, and failures.
The evaluation explicitly treats its scoring set as a manual review aid, not a validated quality benchmark.
- Personal prompts and local Ollama responses are processed locally.
- Tavily receives fixed topic queries, catalogued thinker names, and selected URLs. Prompt details may still be disclosed through topic routing.
- Checkpoints, trace events, source text, drafts, and exhibits are stored
under
.data/andexhibits/; they are not encrypted by the application. - Do not enter sensitive personal information or commit personal sessions, questions, or reviewer notes.
- The philosophical voices are AI interpretations and may be inaccurate or unbalanced.
- The system is for reflection and exploration, not legal, medical, financial, or psychological advice.
- CPU-only local inference may be slow; output quality varies by model and source.
fortytwo/ Agent graphs, prompts, retrieval, and evidence validation
frontend/ React interface
library/ Source PDFs and the source catalog
evaluation/ Human-scored scenarios and result template
test_*.py API, graph, retrieval, and library tests
api.py FastAPI application
This repository started as a guided systems-building exercise and grew into a complete reference application. Its core engineering lesson is that a useful agentic product should combine four things:
- A model for flexible interpretation
- Determinable workflows and validation
- Persistent state and human checkpoints
- Sources and limitations that users can inspect
Add a license file before publishing or accepting contributions. Until a license is included, the repository should be treated as source-available for portfolio review, not as a grant of reuse rights.
Built to make AI agents inspectable, grounded, interruptible, and human-reviewed.