How manishkumarsingh41/contextengine works
1. Purpose and Runtime Entry Points
ContextEngine is an enterprise AI workspace combining authenticated chat, RAG document/repository intelligence, multi-agent reasoning, and pluggable LLM providers. The backend runs as FastAPI via backend/app.py; the Streamlit client starts at frontend/app.py. Container deployment is defined by docker-compose.yml and Dockerfile.
2. API, Security, and Persistent Application State
FastAPI route modules expose chat, streaming, uploads, sessions, provider selection, authentication, admin, and health endpoints. Authentication supports JWT user sessions and hashed API keys; service-level managers handle auth/session lifecycle and audit concerns. SQLAlchemy models/sessions form the transactional persistence boundary, backed by PostgreSQL or SQLite depending on DATABASE_URL.
• backend/routes/chat.py
• backend/dependencies/auth.py
• backend/db/models.py
3. Chat and Streaming Boundary
Chat requests enter through backend routes, validate into Pydantic request/response schemas, select an LLM path, and can return streamed events. Session state persists resumable conversations; the frontend maintains UI/session state and renders messages, agent activity, documents, and workflow output.
• backend/routes/chat.py
• backend/routes/stream.py
• frontend/state.py
4. Provider Abstraction and Resilient Routing
Providers are isolated behind common types/base interfaces and instantiated by a factory. Implementations target OpenAI, Anthropic Claude, Gemini, Cohere, Groq, NVIDIA NIM, Together, Ollama, and OpenRouter. The router adds provider policy selection, health assessment, metrics, and circuit-breaker behavior before calls leave the application boundary for external model APIs.
• providers/base.py
• providers/factory.py
• router/router.py
5. RAG Ingestion and Retrieval
Upload/GitHub ingestion is a distinct pipeline: files or repositories are loaded and parsed, metadata is extracted, content is chunked, embeddings are generated, then vectors are persisted. Query-time retrieval embeds the prompt, searches the vector store, can rerank results, and supplies grounded context to generation. ChromaDB is the vector persistence/search boundary; embedding and store factories make implementations replaceable.
• rag/ingestion_pipeline.py
• rag/retrieval.py
• rag/chroma_store.py
6. Multi-Agent Orchestration
Complex prompts are processed as a workflow with shared state: Planner decomposes work; Retriever obtains relevant context; Generator creates a response; Critic evaluates it; Reflection refines it until the workflow stops. Orchestration owns stage sequencing/state transitions, while individual agents encapsulate role-specific LLM prompting and evaluation.
• orchestration/workflow.py
• orchestration/state.py
• agents/planner.py
7. Frontend and Operational Infrastructure
The Streamlit frontend is a separate client over the backend API, organized into chat/login/upload/settings pages and reusable UI components. Production concerns are embedded in backend observability middleware: structured logging, metrics/Prometheus export, tracing/OpenTelemetry, and health probes. Docker Compose supplies the production-like multi-service runtime; GitHub Actions provides CI, Docker, and release workflows.
• frontend/pages/chat.py
• backend/observability/middleware.py
• docker-compose.yml
Main entry points: workflow.py Agent workflow · app.py FastAPI application · chat.py Chat and stream routes · factory.py Provider factory
Components 19
Client
- Streamlit workspace · Chat, login, upload, and settings UI.
frontend/app.py - UI session state
frontend/state.py - Chat UI
frontend/pages/chat.py
Backend API
- FastAPI application · Authenticated application boundary.
backend/app.py - Chat and stream routes · Validates chat requests and emits streaming events.
backend/routes/chat.py - Auth dependency · JWT sessions and API-key authentication.
backend/dependencies/auth.py
AI Processing
- Agent workflow · Sequences shared-state reasoning stages.
orchestration/workflow.py - Workflow state
orchestration/state.py - Planner agent · Decomposes complex prompts.
agents/planner.py - Retrieval service · Embeds queries, searches, and can rerank context.
rag/retrieval.py - Ingestion pipeline · Parses sources, extracts metadata, chunks, and embeds content.
rag/ingestion_pipeline.py - Provider factory · Instantiates common-interface LLM providers.
providers/factory.py - Provider interface · Common provider types and base interface.
providers/base.py - LLM router · Applies policy, health checks, metrics, and circuit breaking.
router/router.py
Persistence
- Application database · Transactional users, sessions, and audit state.
backend/db/models.py - Chroma vector store · Vector persistence and similarity search boundary.
rag/chroma_store.py
Operations
- Observability middleware · Logging, metrics, tracing, and health probes.
backend/observability/middleware.py - Container runtime · Production-like multi-service deployment.
docker-compose.yml
Other components
- External LLM APIs · OpenAI, Claude, Gemini, Cohere, Groq, NIM, Together, Ollama, and OpenRouter.
Connections 21
- Streamlit workspace → UI session state: maintains
- Streamlit workspace → Chat UI: renders
- Chat UI → FastAPI application: backend API calls
- FastAPI application → Chat and stream routes: mounts
- FastAPI application → Auth dependency: enforces
- Auth dependency → Application database: loads sessions and keys
- Chat and stream routes → Application database: persists conversations
- Chat and stream routes → Agent workflow: complex prompts
- Chat and stream routes → LLM router: direct generation
- Agent workflow → Workflow state: transitions
- Agent workflow → Planner agent: plans with
- Agent workflow → Retrieval service: grounds with
- Agent workflow → LLM router: generates via
- Ingestion pipeline → Chroma vector store: indexes vectors
- Retrieval service → Chroma vector store: searches
- LLM router → Provider factory: selects provider
- Provider factory → Provider interface: implements
- Provider factory → External LLM APIs: calls
- FastAPI application → Observability middleware: instrumented by
- Container runtime → FastAPI application: runs
- Container runtime → Streamlit workspace: runs