Ekklesia¶
Ekklesia is a multi-agent sermon preparation system. You give it a topic; five specialised AI agents collaborate in sequence — each building on the last — to produce a structured sermon brief complete with exegesis, supporting research, and a critical review. The entire pipeline streams live to a React frontend via Server-Sent Events.
At a glance¶
| Layer | Technology | Notes |
|---|---|---|
| LLM backbone | Gemini 2.0 Flash | Configurable via LLM_MODEL env var |
| Embeddings | Gemini gemini-embedding-001 |
768-dim vectors |
| Agent framework | Pydantic AI | Type-safe agents with structured outputs |
| API | FastAPI + SSE | Streaming pipeline events, async throughout |
| Database | PostgreSQL + pgvector | HNSW indexes for ANN search |
| ORM / migrations | SQLAlchemy Core + Alembic | Async engine, asyncpg driver |
| Frontend | React + Vite + Tailwind CSS | Two-pane agentic workspace, tabbed stage outputs, editable sermon canvas |
| Observability | Logfire | OpenTelemetry traces, pipeline spans |
| Deployment | Railway | Docker build, pgvector template |
| Container runtime | Docker / docker compose | Local development stack |
Design principles¶
Streaming first. Every pipeline stage emits start/complete/failed events over SSE. The frontend updates in real time — there is no poll-and-wait pattern anywhere in the stack.
Structured outputs end-to-end. All agent inputs and outputs are validated Pydantic models. This makes the pipeline debuggable and guarantees well-formed data passes between stages.
Hybrid retrieval. The RAG layer combines dense (cosine-similarity vector search) and sparse (PostgreSQL full-text search) results, fused with Reciprocal Rank Fusion. Neither technique alone is sufficient for theological research queries.
Observable by design. Logfire spans wrap every pipeline stage, every retrieval call, and every embedding request. Token usage and tool calls are captured automatically via logfire.instrument_pydantic_ai().
Separation of concerns. Retrieval, agent logic, and HTTP transport are fully decoupled. Each can be tested in isolation and swapped without touching the others.
Documentation¶
| Section | What it covers |
|---|---|
| Architecture | System diagram, component breakdown, key design decisions |
| Agent Pipeline | The five-agent sequence, stage events, error handling |
| Retrieval & RAG | Hybrid search, embedding model, ingestion scripts |
| API Reference | HTTP endpoints, SSE protocol, event schema |
| Frontend | React components, state machine, citation system |
| Deployment | Railway setup, environment variables, Docker, ingestion |