# padmanabhamkiran1234/ai-support-agent architecture

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

- Interactive diagram: https://gitdiagram.com/padmanabhamkiran1234/ai-support-agent
- Repository: https://github.com/padmanabhamkiran1234/ai-support-agent

## Overview

This repository is a small Python multi-agent support automation system, centered on a single orchestration flow that turns a customer message into a classified, research-backed support response and, when needed, a structured ticket.

1. **Top-level architecture**
   - The code is split into four main boundaries: **agents** (decision-making and orchestration), **tools** (data access and side effects), **llm** (model adapter), and **memory** (session state).
   - `utils/` provides cross-cutting concerns such as logging.

2. **Primary entry points**
   - `main.py` is the likely CLI/demo runner for the agent pipeline.
   - `web_app.py` suggests an alternate interactive front end, but the repository is not primarily organized as a web service.
   - `tests/test_demo_flow.py` exercises the end-to-end demo path.

3. **Agent layer**
   - `agents/query_agent.py` handles query interpretation or normalization before downstream processing.
   - `agents/classifier_agent.py` performs intent/category classification, which the README describes as part of a parallelized multi-agent flow.
   - `agents/summary_agent.py` is the final synthesis step that turns the collected evidence and tool outputs into the user-facing answer.

4. **Tool layer**
   - `tools/knowledge_base_tool.py` and `tools/vector_kb_tool.py` are the retrieval side of the system; they represent knowledge-base lookup, with the vector tool likely providing semantic search.
   - `tools/ticket_tool.py` is the action side of the system, generating a structured support ticket when the query cannot be fully resolved from the KB.
   - These tools are the main boundary between reasoning and external data/action workflows.

5. **LLM integration**
   - `llm/gemini_client.py` isolates calls to the Gemini model.
   - This wrapper keeps model-specific behavior out of the agents, so the orchestration layer can stay focused on pipeline logic rather than API details.

6. **Session and memory**
   - `memory/session_service.py` manages in-memory session state.
   - This provides conversational continuity across turns, allowing the system to reuse prior context without relying on a persistent database.

7. **End-to-end data flow**
   - A user query enters through the CLI or web entry point.
   - The query agent prepares the input, the classifier agent determines what kind of support issue it is, and the system consults KB tools in parallel where relevant.
   - If the issue needs escalation or tracking, the ticket tool creates a structured ticket.
   - The summary agent combines the classification, retrieval results, and ticket outcome into the final response, then the session service stores the interaction state.

8. **Execution model**
   - The README explicitly calls out a **multi-agent flow** with **parallel classification** and KB lookup.
   - That implies the core architecture is orchestration-first: one coordinator fans out to specialized workers, then gathers results for a final response.

9. **Observability**
   - `utils/logger.py` provides basic logging across the system.
   - This is likely the main operational visibility layer, since there is no separate monitoring stack in the repository.

10. **Testing and evaluation**
   - `tests/eval_agent.py` appears to support agent-level evaluation.
   - `tests/test_demo_flow.py` validates the integrated demo path, which is important for a system whose behavior depends on orchestration between agents and tools.

11. **Runtime and packaging**
   - `requirements.txt` defines the Python dependencies, and `Dockerfile` packages the app for containerized execution.
   - The README indicates Python 3.9+ as the local runtime baseline.

12. **Architectural summary**
   - This is a modular, LLM-driven support assistant where **agents decide**, **tools retrieve or act**, **memory preserves context**, and **the Gemini client supplies language intelligence**.
   - The cleanest diagram would show a central orchestration path with side branches to KB retrieval, ticket creation, and session storage, all wrapped by logging and exposed through CLI/web entry points.

Main entry points: [`agents/classifier_agent.py`](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/classifier_agent.py) (Classifier), [`agents/summary_agent.py`](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/summary_agent.py) (Summary agent), [`agents/query_agent.py`](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/query_agent.py) (Query agent), [`utils/logger.py`](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/utils/logger.py) (Logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry Points"]
  node_main_py["CLI runner<br/>entrypoint<br/>[main.py]"]
  node_web_app_py["Web app<br/>entrypoint<br/>[web_app.py]"]
end

subgraph group_agents["Agents"]
  node_query_agent_py["Query agent<br/>[query_agent.py]"]
  node_classifier_agent_py["Classifier<br/>agent"]
  node_summary_agent_py["Summary agent<br/>[summary_agent.py]"]
end

subgraph group_tools["Tools"]
  node_kb_tool_py["KB lookup<br/>retrieval tool"]
  node_vector_kb_tool_py["Vector search<br/>retrieval tool<br/>[vector_kb_tool.py]"]
  node_ticket_tool_py["Ticket tool<br/>action tool<br/>[ticket_tool.py]"]
end

subgraph group_core["Core Services"]
  node_gemini_client_py["Gemini client<br/>llm adapter<br/>[gemini_client.py]"]
  node_session_service_py["Session service<br/>memory service<br/>[session_service.py]"]
end

subgraph group_ops["Ops"]
  node_logger_py["Logger<br/>observability<br/>[logger.py]"]
  node_test_demo_flow_py["Demo flow test<br/>integration test<br/>[test_demo_flow.py]"]
  node_eval_agent_py["Agent eval<br/>evaluation<br/>[eval_agent.py]"]
end

node_main_py -->|"starts"| node_query_agent_py
node_web_app_py -->|"starts"| node_query_agent_py
node_query_agent_py -->|"normalizes for"| node_classifier_agent_py
node_classifier_agent_py -->|"looks up"| node_kb_tool_py
node_classifier_agent_py -->|"semantic search"| node_vector_kb_tool_py
node_classifier_agent_py -->|"escalates to"| node_ticket_tool_py
node_kb_tool_py -->|"provides evidence"| node_summary_agent_py
node_vector_kb_tool_py -->|"provides evidence"| node_summary_agent_py
node_ticket_tool_py -->|"returns status"| node_summary_agent_py
node_classifier_agent_py -->|"hands off"| node_summary_agent_py
node_query_agent_py -->|"uses"| node_gemini_client_py
node_classifier_agent_py -->|"uses"| node_gemini_client_py
node_summary_agent_py -->|"uses"| node_gemini_client_py
node_main_py -->|"stores state"| node_session_service_py
node_web_app_py -->|"stores state"| node_session_service_py
node_query_agent_py -->|"reads context"| node_session_service_py
node_summary_agent_py -->|"updates context"| node_session_service_py
node_main_py -->|"logs"| node_logger_py
node_web_app_py -->|"logs"| node_logger_py
node_query_agent_py -->|"logs"| node_logger_py
node_classifier_agent_py -->|"logs"| node_logger_py
node_summary_agent_py -->|"logs"| node_logger_py
node_test_demo_flow_py -->|"exercises"| node_main_py
node_eval_agent_py -->|"evaluates"| node_classifier_agent_py

click node_main_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/main.py"
click node_web_app_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/web_app.py"
click node_query_agent_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/query_agent.py"
click node_classifier_agent_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/classifier_agent.py"
click node_summary_agent_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/summary_agent.py"
click node_kb_tool_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/knowledge_base_tool.py"
click node_vector_kb_tool_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/vector_kb_tool.py"
click node_ticket_tool_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/ticket_tool.py"
click node_gemini_client_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/llm/gemini_client.py"
click node_session_service_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/memory/session_service.py"
click node_logger_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/utils/logger.py"
click node_test_demo_flow_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tests/test_demo_flow.py"
click node_eval_agent_py "https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tests/eval_agent.py"

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_main_py,node_web_app_py toneBlue
class node_query_agent_py,node_classifier_agent_py,node_summary_agent_py toneAmber
class node_kb_tool_py,node_vector_kb_tool_py,node_ticket_tool_py toneMint
class node_gemini_client_py,node_session_service_py toneRose
class node_logger_py,node_test_demo_flow_py,node_eval_agent_py toneIndigo
```

## Components

### Entry Points

Ways to invoke the support pipeline.

- [CLI runner](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/main.py): entrypoint · Primary command-line/demo entry for the support flow. · `main.py`
- [Web app](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/web_app.py): entrypoint · Alternate interactive front end for the same orchestration flow. · `web_app.py`

### Agents

Decision and orchestration components.

- [Query agent](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/query_agent.py): agent · Normalizes or interprets incoming customer queries. · `agents/query_agent.py`
- [Classifier](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/classifier_agent.py): agent · Determines intent and support category. · `agents/classifier_agent.py`
- [Summary agent](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/agents/summary_agent.py): agent · Synthesizes evidence into the final response. · `agents/summary_agent.py`

### Tools

Knowledge retrieval and ticketing actions.

- [KB lookup](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/knowledge_base_tool.py): retrieval tool · Knowledge-base access for direct lookups. · `tools/knowledge_base_tool.py`
- [Vector search](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/vector_kb_tool.py): retrieval tool · Semantic retrieval against the knowledge base. · `tools/vector_kb_tool.py`
- [Ticket tool](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tools/ticket_tool.py): action tool · Creates structured support tickets when escalation is needed. · `tools/ticket_tool.py`

### Core Services

Shared runtime services and model access.

- [Gemini client](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/llm/gemini_client.py): llm adapter · Isolates model calls and prompt execution. · `llm/gemini_client.py`
- [Session service](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/memory/session_service.py): memory service · Stores in-memory conversation state across turns. · `memory/session_service.py`

### Ops

Cross-cutting support and validation.

- [Logger](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/utils/logger.py): observability · Shared logging for the pipeline. · `utils/logger.py`
- [Demo flow test](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tests/test_demo_flow.py): integration test · Validates the end-to-end orchestration path. · `tests/test_demo_flow.py`
- [Agent eval](https://github.com/padmanabhamkiran1234/ai-support-agent/blob/main/tests/eval_agent.py): evaluation · Supports agent-level evaluation and benchmarking. · `tests/eval_agent.py`

## Connections

- CLI runner → Query agent: starts · CLI/demo execution enters the agent pipeline.
- Web app → Query agent: starts · Web interaction routes into the same orchestration flow.
- Query agent → Classifier: normalizes for · Prepared query is handed to classification.
- Classifier → KB lookup: looks up · Classification can trigger knowledge-base retrieval.
- Classifier → Vector search: semantic search · Parallel retrieval path for relevant support content.
- Classifier → Ticket tool: escalates to · Unresolved or actionable issues can become tickets.
- KB lookup → Summary agent: provides evidence · KB results feed the final synthesis step.
- Vector search → Summary agent: provides evidence · Semantic search results are merged into the response.
- Ticket tool → Summary agent: returns status · Ticket creation outcome is included in the final answer.
- Classifier → Summary agent: hands off · Classification output is part of the final synthesis context.
- Query agent → Gemini client: uses · Agent logic relies on the LLM adapter for language tasks.
- Classifier → Gemini client: uses · Classification is driven through the model wrapper.
- Summary agent → Gemini client: uses · Final response generation uses the model wrapper.
- CLI runner → Session service: stores state · CLI run updates session continuity.
- Web app → Session service: stores state · Interactive sessions persist conversation context in memory.
- Query agent → Session service: reads context · Current query can be interpreted using prior turns.
- Summary agent → Session service: updates context · Final response and interaction state are stored.
- CLI runner → Logger: logs · Pipeline execution is logged.
- Web app → Logger: logs · Interactive execution is logged.
- Query agent → Logger: logs · Agent activity is observed through shared logging.
- Classifier → Logger: logs · Classification steps emit logs.
- Summary agent → Logger: logs · Synthesis and response generation emit logs.
- Demo flow test → CLI runner: exercises · Integration test validates the demo entry path.
- Agent eval → Classifier: evaluates · Evaluation focuses on agent behavior and outputs.