How piyush30007/nexa-ai works
Nexa AI is an enterprise policy assistant combining a React client, authenticated FastAPI endpoints, document ingestion, and an agentic RAG workflow. Users upload knowledge-base documents, then ask questions; the agent plans retrieval, evaluates evidence, and returns grounded answers with sources. The product also supports conversation history, usage reporting, and evaluation. The README documents several guardrail and infrastructure behaviors beyond the sampled implementation; those links are cited to the README. The tree and excerpts also show an older, separate RAG API, which is represented without assuming it participates in the current agent workflow.
Main entry points: main.py Enterprise API · processor.py Document Ingestion · graph.py Agent State Graph · client.js API Client
Components 31
User Experience
- React Application
frontend/src/App.jsx - Assistant Chat
frontend/src/pages/AIAssistant.jsx - Knowledge Base UI
frontend/src/pages/KnowledgeBase.jsx - API Client
frontend/src/api/client.js - Evaluation UI
frontend/src/pages/Evaluation.jsx - Usage Dashboard
frontend/src/pages/Usage.jsx
API and Identity
- Enterprise API
backend/app/main.py - Clerk Authentication
backend/app/auth/clerk_auth.py
Knowledge and Retrieval
- Document Ingestion
backend/app/ingestion/processor.py - Format Loaders
backend/app/ingestion/Loader - Text Cleaning
backend/app/ingestion/Preprocessing/cleaner.py - Chunking
backend/app/ingestion/Chunking/splitter.py - Embedding Service
backend/app/services/embedding.py - Qdrant Store
backend/app/services/retrieval/qdrant_service.py - Hybrid Retrieval
backend/app/services/retrieval/hybrid_service.py - Result Reranking
backend/app/services/retrieval/ranking_services.py - Legacy RAG API
backend/rag.py
Agent and Safety
- Agent State Graph
backend/app/agents/graph.py - Query Planner
backend/app/agents/nodes/planner.py - Agent Retriever
backend/app/agents/nodes/retriever.py - Evidence Evaluator
backend/app/agents/nodes/sufficiency.py - Answer Responder
backend/app/agents/nodes/responder.py - Guardrails
backend/app/guardrails - Model Gateway
backend/app/gateway/client.py
Persistence and Services
- Conversation Service
backend/app/services/conversation_service.py - PostgreSQL Models
backend/database.py - Embedding and Response Cache
backend/app/services/cache.py - Evaluation Service
backend/evaluation.py
Other components
- User
- Portkey AI Gateway
- Gemini Embeddings
Connections 36
- User → React Application: uses
- React Application → Assistant Chat: routes to
frontend/src/App.jsx - React Application → Knowledge Base UI: routes to
frontend/src/App.jsx - Assistant Chat → API Client: requests
frontend/src/pages/AIAssistant.jsx - Knowledge Base UI → API Client: requests
frontend/src/api/client.js - API Client → Enterprise API: calls endpoints
frontend/src/api/client.js - Enterprise API → Clerk Authentication: authenticates
backend/app/main.py - Enterprise API → Guardrails: applies
backend/app/main.py - Enterprise API → Agent State Graph: invokes
backend/app/main.py - Enterprise API → Conversation Service: persists turns
backend/app/main.py - Conversation Service → PostgreSQL Models: reads and writes
backend/app/services/conversation_service.py - Enterprise API → Document Ingestion: uploads documents
backend/app/main.py - Document Ingestion → Format Loaders: extracts formats
backend/app/ingestion/processor.py - Document Ingestion → Text Cleaning: cleans text
backend/app/ingestion/processor.py - Document Ingestion → Chunking: chunks text
backend/app/ingestion/processor.py - Document Ingestion → Embedding Service: embeds chunks
backend/app/ingestion/processor.py - Embedding Service → Embedding and Response Cache: checks cache
backend/app/services/embedding.py - Embedding Service → Gemini Embeddings: embeds text
- Agent State Graph → Query Planner: dispatches
backend/app/agents/graph.py - Agent State Graph → Agent Retriever: dispatches
backend/app/agents/graph.py - Agent State Graph → Evidence Evaluator: dispatches
backend/app/agents/graph.py - Agent State Graph → Answer Responder: dispatches
backend/app/agents/graph.py - Query Planner → Agent Retriever: routes retrieval
- Query Planner → Answer Responder: routes conversation
- Agent Retriever → Hybrid Retrieval: searches
backend/app/agents/nodes/retriever.py - Hybrid Retrieval → Qdrant Store: queries vectors
backend/app/services/retrieval/hybrid_service.py - Hybrid Retrieval → Result Reranking: reranks candidates
- Agent Retriever → Evidence Evaluator: submits evidence
- Evidence Evaluator → Query Planner: retries query
- Evidence Evaluator → Answer Responder: routes answer
- Answer Responder → Model Gateway: generates answer
- Model Gateway → Portkey AI Gateway: routes inference
- Enterprise API → Evaluation Service: runs evaluation
backend/app/main.py - Evaluation UI → API Client: requests evaluation
frontend/src/pages/Evaluation.jsx - Usage Dashboard → API Client: requests usage
- Legacy RAG API → PostgreSQL Models: reads and writes
backend/rag.py