pawan300/enterprise_bot

Purpose and Entry Points

This is a local, enterprise-style multi-agent Q&A prototype for synthetic consumer-goods data. It answers structured KPI questions, document-based questions, web-search questions, and bounded computations, producing grounded citations and debug metadata. Interactive entry points are scripts/chat_cli.py and app/streamlit_app.py; the latter is an inspection UI rather than a production frontend.

Orchestration and Conversation State

QnaAgent coordinates each turn: it preserves multi-turn context, resolves follow-ups, performs intent/routing decisions, invokes selected agents, and returns formatted answers plus diagnostics. Conversation state and follow-up generation are separate concerns, enabling UI/CLI clients to remain thin.

Paths: src/qna_agent/orchestrator/agent.py, src/qna_agent/orchestrator/conversation.py, src/qna_agent/orchestrator/followups.py.

Deterministic Understanding and Metadata Resolution

Before model-driven decisions, deterministic NLU extracts entities, corrects aliases, interprets temporal language, and detects language. The metadata store supplies KPI/dimension definitions, hierarchy relationships, and document metadata; this supports explicit parent-level fallback (for example, an unavailable sub-region resolving to its parent) and overrides conflicting LLM classifications when entity/KPI resolution is decisive.

Paths: src/qna_agent/nlu/entities.py, src/qna_agent/nlu/temporal.py, src/qna_agent/catalog/metadata_store.py.

Intent Routing and Specialized Execution

The router selects up to four specialized agents based on question intent and evidence requirements. Structured queries target SQLite; unstructured queries retrieve from generated Markdown documents; web search uses live search or an offline corpus; coding handles calculations. Multi-evidence “why” questions can run structured and unstructured paths together.

Paths: src/qna_agent/orchestrator/intent.py, src/qna_agent/orchestrator/router.py, src/qna_agent/subagents/structured_agent.py, src/qna_agent/subagents/unstructured_agent.py, src/qna_agent/subagents/websearch_agent.py, src/qna_agent/subagents/coding_agent.py.

Evidence Stores and Data Boundary

The system’s business corpus is reproducibly generated as a matched structured/unstructured dataset: SQLite warehouse records, Markdown documents, catalog/alias metadata, and an offline web corpus. The shared generator makes document narratives and warehouse events overlap by construction. Agent boundaries should treat retrieved rows, snippets, search results, and computation outputs as evidence passed upstream rather than direct final answers.

Paths: data/generate_data.py, data/warehouse.db, data/documents/, data/catalog.json, data/websearch_corpus.json.

Synthesis, Validation, and Presentation

The synthesizer receives only gathered evidence, drafts a cited response, then deterministically checks that answer numbers are supported. A failed validation triggers retry and ultimately a guaranteed-correct templated fallback. Formatting adds citations, assumptions/fallback notes, and debug fields such as routed agents, SQL, validation retry, latency, and cost.

Paths: src/qna_agent/orchestrator/synthesizer.py, src/qna_agent/orchestrator/formatting.py, src/qna_agent/orchestrator/agent.py.

Runtime, Model, and Security Boundaries

Python 3.11+ runs the application. Ollama hosting local llama3.1:8b is the sole LLM dependency, isolated behind one client wrapper; no cloud model/API key is required. SQL generated for the warehouse is constrained by an introspected allow-list, read-only execution, and timeout. Generated computation code is AST-restricted and runs with minimal builtins.

Paths: src/qna_agent/llm/ollama_client.py, src/qna_agent/security/sql_guard.py, src/qna_agent/security/sandbox.py, requirements.txt.