How arjun-57561/ufac works
1. This repo is a two-tier application: a Python backend that performs PM-KISAN eligibility assessment and a Next.js frontend that presents the assessment flow, results, and system status. The backend is the source of truth for eligibility logic; the UI is primarily a client for submitting user data and visualizing outputs.
2. Primary request path starts at the frontend’s assessment forms/pages, which call the backend’s POST /check endpoint. The backend returns a structured UFAC assessment containing the answer, confidence, known facts, assumptions, unknowns, risk level, and next steps. The UI also has pages for the overall agent flow, eligibility checking, and backend health/status.
3. Backend entrypoints are split between API and CLI. api/app.py exposes the FastAPI application, while main.py and core/ufac_engine.py support direct programmatic/command-line execution of the same assessment engine. This makes the core logic reusable outside the HTTP layer.
4. The core architecture is a multi-agent orchestration layer in core/. The engine coordinates five specialized agents: Fact, Assumption, Unknown, Confidence, and Decision. The assessment is intentionally decomposed into these stages so each agent produces a distinct part of the final response rather than one monolithic model call.
5. Agent execution is optimized and partially parallelized. The README describes a two-batch execution model: the first batch handles fact/assumption/unknown extraction, and the second batch handles confidence and decision generation. That means the engine is not just routing; it is also coordinating concurrency and merging results into a unified schema.
6. LLM access is isolated behind utility and resilience layers. core/llm_utils.py centralizes calls to the Groq API, while core/circuit_breaker.py, retry logic, and timeout configuration protect the system from upstream failures. This boundary matters: the rest of the app should not depend directly on provider-specific behavior.
7. Eligibility reasoning combines LLM output with rules and RAG. The data/ package contains PM-KISAN rule definitions plus a RAG pipeline backed by data/chroma_db/ and PDF source documents. If the retrieval pipeline is unavailable, the system degrades to hardcoded rules, so there is a clear fallback path from knowledge retrieval to deterministic policy logic.
8. Stateful subsystems are separated from request handling. core/cache.py provides in-memory caching with TTLs for assessments, RAG, and LLM calls; core/database.py persists assessment history to SQLite/PostgreSQL via async SQLAlchemy; and core/metrics.py tracks latency, request counts, and agent performance. These are supporting planes around the main inference path, not part of the core decision logic.
9. The API layer is also a control and observability surface. Besides /check, it exposes health, RAG status, circuit breaker state, cache stats, metrics, history lookup, and cache/metrics reset endpoints. The presence of these endpoints shows the backend is designed for operational transparency, not just request/response handling.
10. Security is enforced at the boundary in the FastAPI app: environment-driven CORS allowlists, rate limiting on assessment requests, input sanitization, and security headers. This means the HTTP layer is responsible for abuse prevention before data reaches the UFAC engine.
11. The frontend is a fairly rich presentation layer, not a thin form. Under UI/app/ and UI/components/, it includes the eligibility form, agent flow visualization, result panels, confidence/consensus indicators, backend status indicators, theme controls, and animated UI scaffolding. The hooks suggest a client-side integration model for polling backend status and submitting assessments.
12. The app uses modern web tooling but remains architecture-light on the client side. The frontend is built with Next.js 14 App Router, React, TypeScript, and component primitives in UI/components/ui/. The important boundary is that the UI depends on backend APIs for assessment logic and system state; it does not embed the PM-KISAN rules itself.
13. Testing is focused on the backend’s reliability surface. The tests/ folder covers API behavior, caching, and error handling, which matches the repo’s emphasis on resilience, fallback behavior, and operational endpoints. This indicates the critical architectural risk is not just correctness of eligibility results, but failure handling under real API/LLM conditions.
14. There is a separate research/prototyping area in research/ with scripts for Groq, Gemini, and Llama API testing. This appears to be exploratory tooling rather than production flow, and it sits outside the main runtime path.
15. For an architecture diagram, the key data flow is: user inputs enter the UI, go to the FastAPI /check endpoint, pass through security/rate limiting/cache, then into the UFAC engine, which consults LLM/RAG/rules through resilience wrappers, and finally returns a structured assessment that may also be persisted to the database and reflected back in metrics/history/status endpoints.
Main entry points: ufac_engine.py UFAC engine · app.py API app · llm_utils.py LLM utils · rag_pipeline.py RAG pipeline
Components 22
Frontend
Next.js presentation layer for assessment, flow visualization, and status views.
- UI app · App Router pages for home, eligibility, check, flow, agent flow, and about.
UI/app - UI components · Reusable form, results, visualization, status, and layout components.
UI/components - UI hooks · Browser-side hooks for backend status, counts, and assessment submission.
UI/hooks
Backend
FastAPI API and reusable UFAC engine that perform eligibility assessment.
- API app · HTTP surface exposing /check plus health, status, metrics, cache, and history endpoints.
api/app.py - UFAC engine · Coordinates the multi-agent assessment pipeline and assembles the final UFAC response.
core/ufac_engine.py - Fact agent · Derives known facts from the submitted assessment data.
core/fact_agent.py - Assumption agent · Produces assumptions needed to complete the assessment.
core/assumption_agent.py - Unknown agent · Identifies missing information and unresolved unknowns.
core/unknown_agent.py - Confidence agent · Estimates confidence and uncertainty for the assessment result.
core/confidence_agent.py - Decision agent · Determines the final eligibility answer and next steps.
core/decision_agent.py - LLM utils · Centralized provider access for LLM calls and prompt execution.
core/llm_utils.py - Resilience · Protects LLM and external calls with retries, timeouts, and circuit breaking.
core/circuit_breaker.py - Schema · Structured response model for answer, confidence, facts, assumptions, unknowns, risk, and next steps.
core/schema.py
Knowledge
Rules, retrieved documents, and persisted RAG store used by the backend.
- PM-KISAN rules · Hardcoded eligibility rules used when retrieval is unavailable or as policy grounding.
data/pm_kisan_rules.py - RAG pipeline · Retrieves guideline context from embedded PM-KISAN documents.
data/rag_pipeline.py - Chroma store · Persistent embedded document index backing retrieval.
data/chroma_db - Guidelines docs · Operational and scheme guideline documents used to build retrieval context.
data
Support
State, observability, tests, and exploratory tooling around the main runtime.
- Cache · In-memory caching for assessments, RAG results, and LLM responses.
core/cache.py - Database · Persists assessment history through async SQLAlchemy to SQLite/PostgreSQL.
core/database.py - Metrics · Tracks request counts, latency, and agent performance.
core/metrics.py - API tests · Coverage for API behavior, caching, and error handling.
tests/test_api.py - Research tools · Ad hoc Groq, Gemini, and Llama API experiments outside the production path.
research
Connections 27
- UI app → API app: submit /check · Frontend submits assessment data and reads backend state.
- UI components → UI app: render pages · Shared components power the assessment and status views.
- UI hooks → API app: poll/call · Client hooks fetch backend status and assessment results.
- API app → Cache: read/write · API consults cache for repeated assessments and status data.
- API app → Resilience: protect calls · HTTP requests are guarded by throttling and failure controls.
- API app → UFAC engine: invoke engine · The /check endpoint delegates assessment to the core engine.
- UFAC engine → Fact agent: batch 1 · First execution batch extracts known facts.
- UFAC engine → Assumption agent: batch 1 · First execution batch derives assumptions.
- UFAC engine → Unknown agent: batch 1 · First execution batch identifies unknowns.
- UFAC engine → Confidence agent: batch 2 · Second batch computes confidence after extraction.
- UFAC engine → Decision agent: batch 2 · Second batch determines final eligibility outcome.
- Fact agent → LLM utils: LLM call · Agent uses centralized model access.
- Assumption agent → LLM utils: LLM call · Agent uses centralized model access.
- Unknown agent → LLM utils: LLM call · Agent uses centralized model access.
- Confidence agent → LLM utils: LLM call · Agent uses centralized model access.
- Decision agent → LLM utils: LLM call · Agent uses centralized model access.
- LLM utils → Resilience: wrap provider · Provider calls pass through retry and circuit-breaking controls.
- UFAC engine → Schema: assemble · Engine merges agent outputs into the structured UFAC contract.
- API app → Schema: serialize · API returns the unified assessment schema to clients.
- UFAC engine → RAG pipeline: retrieve context · Engine can pull scheme context for grounding and fallback.
- RAG pipeline → Chroma store: query index · Retrieval reads the persistent vector store.
- RAG pipeline → Guidelines docs: built from · The vector store is derived from scheme guideline PDFs.
- UFAC engine → PM-KISAN rules: fallback rules · Deterministic rules are used when retrieval is unavailable.
- API app → Database: persist history · Assessment results and lookup history are stored.
- API app → Metrics: observe · Operational endpoints expose request and latency metrics.
- API app → API tests: validated by · Backend behavior is exercised by automated tests.
- Research tools → LLM utils: prototype · Experimental scripts exercise provider integrations.