HPCL-Configurable-Agentic-Chatbot

HPCL-Configurable-Agentic-Chatbot is a configurable, template-scoped agentic chatbot for HPCL-style employee and business-data workflows. It combines a FastAPI backend, a static browser UI, governed SQL/RAG/API tools, and optional framework adapters while keeping deterministic Python code in control of routing, privacy, verification, and tool execution.

This repository is being prepared for a future open-source release. The public release target is source code plus safe documentation only. Local secrets, generated evidence, logs, test caches, screenshots, virtual environments, runtime databases, and large model assets must stay out of the published repository.

What It Does

• Serves a browser chatbot UI from FastAPI.
• Supports template/workspace-scoped routing across SQL, RAG, and read-only API sources.
• Uses YAML template packages to describe datasource ownership, readiness, query policy, and evaluation requirements.
• Preserves deterministic safeguards: read-only SQL, no raw model-authored SQL execution, scoped RAG evidence, privacy checks, and bounded repair/clarification.
• Provides optional framework adapters for LangChain/LangGraph, DSPy, Haystack, LlamaIndex, CrewAI, AutoGen, MCP, and Temporal behind admission controls and feature flags.

Current Runtime Shape

Browser UI
  -> FastAPI app
  -> template/source catalog
  -> scoped family planner
  -> SQL | RAG | read-only API tools
  -> verification and privacy guardrails
  -> response synthesis with source labels

The project still contains local development artifacts and phase evidence that are intentionally excluded from the future public repository. See:

• Project overview
• Core file manifest
• Excluded artifacts
• Runtime recreation
• Cleanup decision matrix
• Security publication checklist

Local Quick Start

Prerequisites

• Python 3.10+
• Docker, when using Qdrant or local PostgreSQL helpers
• Local environment variables copied from .env.example
• Optional Groq API credentials for Groq-backed agentic model calls

Setup

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env.local

Edit .env.local locally. Do not commit .env.local.

Start

docker start qdrant
.\run_servers.ps1 -Restart -AppPort 8010

Open:

http://127.0.0.1:8010/

Health Checks

Invoke-RestMethod http://127.0.0.1:8010/health
Invoke-RestMethod http://127.0.0.1:8010/health/ready -TimeoutSec 60
Invoke-RestMethod http://127.0.0.1:8010/config/sources

Verification

Use the strongest applicable checks before publishing or claiming release readiness:

python -m compileall app tests -q
python -m pytest tests/unit/test_config_runtime.py -q
python -m pytest tests/unit/test_template_source_catalog.py -q
python -m pytest tests/unit/test_template_runtime_readiness.py -q

Browser-visible behavior should be verified through the real UI at http://127.0.0.1:8010/ before release claims.

Repository Boundary

The future public repository should include source code, safe tests, safe template packages, safe docs, and placeholder-only configuration examples. It should not include:

• .git/ history from this local working folder
• venv/
• .env.local
• local SQLite databases
• vector databases
• generated phase evidence
• browser screenshots and traces
• logs and terminal captures
• pytest temp directories
• large ONNX/model files unless a dedicated distribution decision is made

License

MIT. See LICENSE.

Security

Do not paste secrets, credentials, internal screenshots, employee data, database dumps, or private vector payloads into public issues or pull requests. See SECURITY.md.