# vatsmanu728/avaranam-agent architecture

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

- Interactive diagram: https://gitdiagram.com/vatsmanu728/avaranam-agent
- Repository: https://github.com/vatsmanu728/avaranam-agent

## Overview

Avaranam Agent is a conversational planning CLI that chooses whether to retrieve scam-related knowledge, ask a clarifying question, escalate, or produce an answer. A chat loads prior conversation state, runs a bounded LangGraph planning cycle, and saves the updated state for later invocations. Decisions use Gemini; retrieval and final judgment are wired to the separate knowledge and core packages. The graph and state contract implement the planning layer. The README and excerpts support the main wiring; external package internals are not shown.

Main entry points: [`src/avaranam_agent/graph.py`](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py) (Planning graph), [`src/avaranam_agent/cli.py`](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/cli.py) (Chat CLI), [`src/avaranam_agent/persistence.py`](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/persistence.py) (State persistence), [`src/avaranam_agent/decision.py`](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/decision.py) (Action decision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and settings"]
  node_cli["Chat CLI<br/>[cli.py]"]
  node_settings["Settings<br/>[config.py]"]
end

subgraph group_planning["Planning workflow"]
  node_agent_state["Agent state<br/>[state.py]"]
  node_actions["Action set<br/>[actions.py]"]
  node_graph["Planning graph<br/>[graph.py]"]
  node_decision["Action decision<br/>[decision.py]"]
  node_search_stage["Knowledge search stage<br/>[graph.py]"]
  node_clarify_stage["Clarification stage<br/>[graph.py]"]
  node_answer_stage["Answer stage<br/>[graph.py]"]
  node_escalate_stage["Escalation stage<br/>[graph.py]"]
end

subgraph group_memory["Conversation memory"]
  node_persistence["State persistence<br/>[persistence.py]"]
  node_saved_state[("Saved conversation<br/>[persistence.py]")]
end

subgraph group_integrations["External capabilities"]
  node_gemini["Gemini API"]
  node_knowledge["Knowledge package"]
  node_core["Core judgment package"]
end

node_user(("User"))
node_human(("Human reviewer"))

node_user -->|"sends message"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"loads and saves"| node_persistence
node_persistence -->|"reads and writes"| node_saved_state
node_persistence -->|"builds state"| node_agent_state
node_cli -->|"runs cycle"| node_graph
node_cli -->|"wires decision"| node_decision
node_graph -->|"reads and updates"| node_agent_state
node_graph -->|"routes actions"| node_actions
node_graph -->|"requests action"| node_decision
node_decision -->|"requests decision"| node_gemini
node_graph -->|"routes search"| node_search_stage
node_search_stage -->|"searches knowledge"| node_knowledge
node_search_stage -->|"returns to decide"| node_graph
node_graph -->|"routes clarification"| node_clarify_stage
node_graph -->|"routes answer"| node_answer_stage
node_answer_stage -->|"requests judgment"| node_core
node_graph -->|"routes escalation"| node_escalate_stage
node_escalate_stage -->|"escalates for review"| node_human
node_cli -->|"shows result"| node_user

click node_cli "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/cli.py"
click node_settings "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/config.py"
click node_persistence "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/persistence.py"
click node_saved_state "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/persistence.py"
click node_agent_state "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/state.py"
click node_actions "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/actions.py"
click node_graph "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py"
click node_decision "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/decision.py"
click node_search_stage "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py"
click node_clarify_stage "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py"
click node_answer_stage "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py"
click node_escalate_stage "https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.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_cli,node_settings,node_user,node_human toneBlue
class node_agent_state,node_actions,node_graph,node_decision,node_search_stage,node_clarify_stage,node_answer_stage,node_escalate_stage toneAmber
class node_persistence,node_saved_state toneMint
class node_gemini,node_knowledge,node_core toneRose
```

## Components

### CLI and settings

- [Chat CLI](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/cli.py): `src/avaranam_agent/cli.py`
- [Settings](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/config.py): `src/avaranam_agent/config.py`

### Planning workflow

- [Agent state](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/state.py): `src/avaranam_agent/state.py`
- [Action set](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/actions.py): `src/avaranam_agent/actions.py`
- [Planning graph](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py): `src/avaranam_agent/graph.py`
- [Action decision](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/decision.py): `src/avaranam_agent/decision.py`
- [Knowledge search stage](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py): `src/avaranam_agent/graph.py`
- [Clarification stage](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py): `src/avaranam_agent/graph.py`
- [Answer stage](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py): `src/avaranam_agent/graph.py`
- [Escalation stage](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/graph.py): `src/avaranam_agent/graph.py`

### Conversation memory

- [State persistence](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/persistence.py): `src/avaranam_agent/persistence.py`
- [Saved conversation](https://github.com/vatsmanu728/avaranam-agent/blob/main/src/avaranam_agent/persistence.py): `src/avaranam_agent/persistence.py`

### External capabilities

- **Gemini API**
- **Knowledge package**
- **Core judgment package**

### Other components

- **User**
- **Human reviewer**

## Connections

- User → Chat CLI: sends message (evidence: `README.md`)
- Chat CLI → Settings: loads settings (evidence: `src/avaranam_agent/cli.py`)
- Chat CLI → State persistence: loads and saves (evidence: `src/avaranam_agent/cli.py`)
- State persistence → Saved conversation: reads and writes (evidence: `src/avaranam_agent/persistence.py`)
- State persistence → Agent state: builds state (evidence: `src/avaranam_agent/persistence.py`)
- Chat CLI → Planning graph: runs cycle (evidence: `src/avaranam_agent/cli.py`)
- Chat CLI → Action decision: wires decision (evidence: `src/avaranam_agent/cli.py`)
- Planning graph → Agent state: reads and updates (evidence: `src/avaranam_agent/graph.py`)
- Planning graph → Action set: routes actions (evidence: `src/avaranam_agent/graph.py`)
- Planning graph → Action decision: requests action (evidence: `README.md`)
- Action decision → Gemini API: requests decision (evidence: `src/avaranam_agent/decision.py`)
- Planning graph → Knowledge search stage: routes search (evidence: `README.md`)
- Knowledge search stage → Knowledge package: searches knowledge
- Knowledge search stage → Planning graph: returns to decide (evidence: `README.md`)
- Planning graph → Clarification stage: routes clarification (evidence: `README.md`)
- Planning graph → Answer stage: routes answer (evidence: `README.md`)
- Answer stage → Core judgment package: requests judgment
- Planning graph → Escalation stage: routes escalation (evidence: `README.md`)
- Escalation stage → Human reviewer: escalates for review (evidence: `README.md`)
- Chat CLI → User: shows result (evidence: `src/avaranam_agent/cli.py`)
