# eblict-sd20/cogopscb architecture

> Architecture diagram of the GitHub repository eblict-sd20/cogopscb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eblict-sd20/cogopscb
- Repository: https://github.com/eblict-sd20/cogopscb

## Overview

1. **Overall shape**
   - This repo is a two-service chatbot system for Bangladesh government services.
   - The main app is a FastAPI-backed chatbot/API + UI service.
   - Retrieval is split out into a separate `jiggasha` search service, so answering is not done in one monolith.

2. **Primary request path**
   - User input enters the chatbot API at `api.py`.
   - The core flow is deterministic: **sanitize → router → retrieval/rerank → composer → verifier**.
   - The system is built to answer only from a fixed government-services corpus and to refuse unsupported claims rather than hallucinate.

3. **Main chatbot service boundary**
   - `govtchat.service` runs the main app on port `9000`.
   - It serves both the API endpoints and the browser UI from `cogops/ui/index.html`.
   - This service owns conversation handling, prompt assembly, streaming responses, verification, and session state.

4. **Search/retrieval service boundary**
   - `jiggasha-search.service` runs independently on port `10000`.
   - It handles passage retrieval for Bengali queries using embeddings, Qdrant, and an LLM-based reranker.
   - The chatbot service calls it over HTTP; it is a hard dependency for the retrieval stage.

5. **Input normalization and routing**
   - `cogops/pipeline/sanitize.py` removes unsafe or malformed input patterns before any LLM call.
   - `cogops/pipeline/router.py` classifies intent and produces Bengali sub-queries.
   - The router can fast-path some pure Bengali domain queries without invoking the LLM.

6. **Retrieval and reranking**
   - The `jiggasha` package is the retrieval subsystem: query expansion, embedding, Qdrant top-K lookup, and rerank.
   - The search service returns vetted passages grouped by sub-query, with a cosine-based fallback if rerank fails.
   - This subsystem is the only place where the corpus is searched; the chatbot does not search directly.

7. **Answer generation**
   - `cogops/agents/pipeline.py` is the composer stage.
   - It builds the final prompt from the retrieved context, optional disambiguation text, and the user query.
   - The primary LLM streams the answer and cites evidence using `[S#]` source tags allocated by the application.

8. **Post-answer verification**
   - `cogops/verifier/nli.py` performs a post-flight NLI check.
   - It is fail-soft and non-blocking at the architecture level, but it can redact or refuse unsupported cited claims depending on policy.
   - This is the final grounding boundary before the answer is returned to the user.

9. **Disambiguation behavior**
   - The system can ask for clarification when a short intent maps to passages from multiple service categories.
   - This prevents the composer from guessing across ambiguous government-service topics.
   - The disambiguation logic is part of the pipeline rather than a separate user-flow service.

10. **Session and conversation state**
   - `cogops/session/*` stores per-user history and query logs.
   - A Redis-backed store is present for persistence and cross-request continuity.
   - This is what allows the test harness and live chatbot sessions to accumulate context server-side.

11. **Eventing and streaming**
   - `cogops/events/*` defines the event types and channels used to stream stage-by-stage progress.
   - The UI debug pane and the test harness consume these events as NDJSON/streamed updates.
   - This event layer exposes internal pipeline boundaries without changing the actual request flow.

12. **LLM integration**
   - `cogops/llm/clients.py` centralizes primary/secondary model access.
   - The repo distinguishes the primary answer model from the secondary reasoning/rerank models.
   - `cogops/llm/reasoning_loop.py` suggests supporting logic for controlled LLM interactions, though the main production path is explicitly non-ReAct.

13. **Prompts, tools, and parsing support**
   - `cogops/prompts/*` contains stage-specific prompt templates for composer, system messages, time reminders, and ReAct-related helpers.
   - `cogops/tools/*` and `cogops/utils/thinking_parser.py` provide supporting abstractions, but the shipped architecture centers on the fixed pipeline rather than free-form tool use.
   - These components mostly define the contract around LLM behavior and output parsing.

14. **Operational and test boundaries**
   - Configuration comes from `configs/config.yml` plus environment files, with separate settings for pipeline, verifier, and Jiggasha.
   - Tests cover normalization, input handling, query expansion, grounding, and end-to-end concurrent sessions.
   - The test harness is architecture-relevant because it validates session isolation, streaming events, retrieval quality, and citation grounding under load.

Main entry points: [`cogops/agents/orchestrator.py`](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/orchestrator.py) (Orchestrator), [`cogops/agents/pipeline.py`](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/pipeline.py) (Composer), [`jiggasha/service.py`](https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/service.py) (Search API), [`api.py`](https://github.com/eblict-sd20/cogopscb/blob/main/api.py) (API entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main_app["Main chatbot"]
  node_api["API entry<br/>FastAPI app<br/>[api.py]"]
  node_ui["Web UI<br/>browser client<br/>[index.html]"]
  node_sanitize["Sanitize<br/>input guard<br/>[sanitize.py]"]
  node_router["Router<br/>[router.py]"]
  node_orchestrator["Orchestrator<br/>pipeline control<br/>[orchestrator.py]"]
  node_composer["Composer<br/>answer builder<br/>[pipeline.py]"]
  node_verifier["Verifier<br/>NLI check<br/>[nli.py]"]
  node_citations["Citations<br/>source tagging<br/>[citations.py]"]
  node_session[("Session store<br/>conversation state<br/>[redis_store.py]")]
  node_events["Events<br/>[types.py]"]
end

subgraph group_search_service["Retrieval service"]
  node_query_expand["Query expand<br/>query normalization<br/>[embedder.py]"]
  node_search_service_node["Search API<br/>retrieval service<br/>[service.py]"]
  node_jiggasha_cfg["Search config<br/>service config<br/>[config.yml]"]
end

subgraph group_support["Shared support"]
  node_llm_clients["LLM clients<br/>model access<br/>[clients.py]"]
  node_prompts["Prompts<br/>prompt templates<br/>[composer.py]"]
  node_thinking["Thinking parser<br/>output parsing<br/>[thinking_parser.py]"]
  node_tools["Tool registry<br/>tooling layer<br/>[registry.py]"]
  node_jiggasha_tool["Jiggasha tool<br/>retrieval client<br/>[jiggasha.py]"]
  node_pipeline_cfg["App config<br/>runtime config<br/>[config.yml]"]
end

node_api -->|"accept input"| node_sanitize
node_sanitize -->|"clean query"| node_router
node_router -->|"route intent"| node_orchestrator
node_orchestrator -->|"retrieve"| node_jiggasha_tool
node_jiggasha_tool -->|"HTTP call"| node_search_service_node
node_search_service_node -->|"expand/search"| node_query_expand
node_query_expand -->|"embed/rerank"| node_llm_clients
node_search_service_node -->|"passages"| node_composer
node_composer -->|"assemble prompt"| node_prompts
node_composer -->|"stream answer"| node_llm_clients
node_composer -->|"tag evidence"| node_citations
node_composer -->|"post-flight check"| node_verifier
node_verifier -->|"validate cites"| node_citations
node_orchestrator -->|"load/save"| node_session
node_orchestrator -->|"emit stages"| node_events
node_ui -->|"consume stream"| node_events
node_api -->|"serve UI"| node_ui
node_orchestrator -.->|"parse output"| node_thinking
node_orchestrator -.->|"use helpers"| node_tools
node_pipeline_cfg -->|"configure"| node_api
node_jiggasha_cfg -->|"configure"| node_search_service_node

click node_api "https://github.com/eblict-sd20/cogopscb/blob/main/api.py"
click node_ui "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/ui/index.html"
click node_sanitize "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/pipeline/sanitize.py"
click node_router "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/pipeline/router.py"
click node_orchestrator "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/orchestrator.py"
click node_composer "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/pipeline.py"
click node_verifier "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/verifier/nli.py"
click node_citations "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/verifier/citations.py"
click node_session "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/session/redis_store.py"
click node_events "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/events/types.py"
click node_llm_clients "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/llm/clients.py"
click node_prompts "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/prompts/composer.py"
click node_thinking "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/utils/thinking_parser.py"
click node_tools "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/tools/registry.py"
click node_jiggasha_tool "https://github.com/eblict-sd20/cogopscb/blob/main/cogops/tools/jiggasha.py"
click node_query_expand "https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/embedder.py"
click node_search_service_node "https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/service.py"
click node_jiggasha_cfg "https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/config.yml"
click node_pipeline_cfg "https://github.com/eblict-sd20/cogopscb/blob/main/configs/config.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_ui,node_sanitize,node_router,node_orchestrator,node_composer,node_verifier,node_citations,node_session,node_events toneBlue
class node_query_expand,node_search_service_node,node_jiggasha_cfg toneAmber
class node_llm_clients,node_prompts,node_thinking,node_tools,node_jiggasha_tool,node_pipeline_cfg toneMint
```

## Components

### Main chatbot

FastAPI chatbot/API service, UI, session handling, prompts, events, and verification.

- [API entry](https://github.com/eblict-sd20/cogopscb/blob/main/api.py): FastAPI app · Main request entrypoint serving chatbot endpoints and the UI. · `api.py`
- [Web UI](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/ui/index.html): browser client · Served static interface for interactive chat and debug streaming. · `cogops/ui/index.html`
- [Sanitize](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/pipeline/sanitize.py): input guard · Removes unsafe or malformed input before any model call. · `cogops/pipeline/sanitize.py`
- [Router](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/pipeline/router.py): intent router · Classifies intent and produces Bengali sub-queries with fast-path handling. · `cogops/pipeline/router.py`
- [Orchestrator](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/orchestrator.py): pipeline control · Coordinates the staged chatbot flow and stage transitions. · `cogops/agents/orchestrator.py`
- [Composer](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/agents/pipeline.py): answer builder · Builds the final prompt and streams grounded responses with citations. · `cogops/agents/pipeline.py`
- [Verifier](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/verifier/nli.py): NLI check · Post-answer grounding check that can redact or refuse unsupported claims. · `cogops/verifier/nli.py`
- [Citations](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/verifier/citations.py): source tagging · Assigns and formats evidence tags used by the generated answer. · `cogops/verifier/citations.py`
- [Session store](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/session/redis_store.py): conversation state · Redis-backed history and query logging for cross-request continuity. · `cogops/session/redis_store.py`
- [Events](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/events/types.py): streaming events · Stage-by-stage event types and channels consumed by UI and tests. · `cogops/events/types.py`

### Retrieval service

Separate Jiggasha search service for query expansion, embedding search, and reranking.

- [Query expand](https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/embedder.py): query normalization · Expands and normalizes user queries before retrieval and routing. · `jiggasha/embedder.py`
- [Search API](https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/service.py): retrieval service · Independent Jiggasha service that exposes passage search and rerank. · `jiggasha/service.py`
- [Search config](https://github.com/eblict-sd20/cogopscb/blob/main/jiggasha/config.yml): service config · Search-service configuration and instruction tuning for retrieval behavior. · `jiggasha/config.yml`

### Shared support

Configuration, LLM access, tools, and utility helpers used across the pipeline.

- [LLM clients](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/llm/clients.py): model access · Centralized primary and secondary model clients. · `cogops/llm/clients.py`
- [Prompts](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/prompts/composer.py): prompt templates · Stage-specific system, composer, and reminder prompts. · `cogops/prompts/composer.py`
- [Thinking parser](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/utils/thinking_parser.py): output parsing · Parses structured reasoning or intermediate LLM output when needed. · `cogops/utils/thinking_parser.py`
- [Tool registry](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/tools/registry.py): tooling layer · Registered helper tools and adapters, including retrieval integration. · `cogops/tools/registry.py`
- [Jiggasha tool](https://github.com/eblict-sd20/cogopscb/blob/main/cogops/tools/jiggasha.py): retrieval client · HTTP client wrapper used by the chatbot to call the search service. · `cogops/tools/jiggasha.py`
- [App config](https://github.com/eblict-sd20/cogopscb/blob/main/configs/config.yml): runtime config · Main application configuration for pipeline, verifier, and service wiring. · `configs/config.yml`

## Connections

- API entry → Sanitize: accept input · Incoming user text is first sanitized.
- Sanitize → Router: clean query · Cleaned input is routed into intent classification and sub-query generation.
- Router → Orchestrator: route intent · Router hands control to the pipeline orchestrator.
- Orchestrator → Jiggasha tool: retrieve · Orchestrator invokes retrieval through the Jiggasha client.
- Jiggasha tool → Search API: HTTP call · Chatbot service depends on the separate search service for retrieval.
- Search API → Query expand: expand/search · Search service expands queries and performs indexed passage lookup.
- Query expand → LLM clients: embed/rerank · Retrieval uses embeddings and LLM-based reranking support.
- Search API → Composer: passages · Retrieved vetted passages are returned to the composer stage.
- Composer → Prompts: assemble prompt · Composer builds the final grounded prompt from templates and context.
- Composer → LLM clients: stream answer · Primary model streams the response back through the application.
- Composer → Citations: tag evidence · Evidence tags are allocated and attached to answer text.
- Composer → Verifier: post-flight check · Generated output is checked for groundedness and policy compliance.
- Verifier → Citations: validate cites · Verifier uses citation state to assess supported claims.
- Orchestrator → Session store: load/save · Conversation history and query logs are persisted per session.
- Orchestrator → Events: emit stages · Pipeline stages are streamed as events for UI and harness consumers.
- Web UI → Events: consume stream · Browser UI listens to streamed pipeline progress updates.
- API entry → Web UI: serve UI · Main service serves the static browser interface.
- Orchestrator → Thinking parser: parse output · Structured reasoning or intermediate outputs can be parsed when used.
- Orchestrator → Tool registry: use helpers · Pipeline can access registered helpers and adapters.
- App config → API entry: configure · Shared configuration drives the main service wiring and policies.
- Search config → Search API: configure · Search-service behavior is controlled by its own configuration.