# nithyasahasra/agentapi architecture

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

- Interactive diagram: https://gitdiagram.com/nithyasahasra/agentapi
- Repository: https://github.com/nithyasahasra/agentapi

## Overview

This is a real-time, multi-agent scam honeypot: an incoming scam message is classified, a persona engages the sender over multiple turns, intelligence is extracted, and results are reported to GUVI. The graph preserves the documented workflow and major capabilities, plus conversation direction, LLM response generation, and session/RL state. Several implementation links are documented only at product level; those edges cite the README. The supplied excerpts do not show endpoint internals, extraction wiring, or GUVI callback invocation.

Main entry points: [`endpoints.py`](https://github.com/nithyasahasra/agentapi/blob/main/endpoints.py) (API endpoints), [`agent_orchestrator.py`](https://github.com/nithyasahasra/agentapi/blob/main/agent_orchestrator.py) (Agent orchestrator), [`base_agent.py`](https://github.com/nithyasahasra/agentapi/blob/main/base_agent.py) (Persona agent base), [`session_manager_enhanced.py`](https://github.com/nithyasahasra/agentapi/blob/main/session_manager_enhanced.py) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_api["API endpoints<br/>[endpoints.py]"]
  node_auth["API key auth<br/>[auth.py]"]
  node_sessions["Session manager"]
  node_database[("Session database")]
end

subgraph group_conversation["Scam engagement"]
  node_classifier["Scam classification"]
  node_orchestrator["Agent orchestrator"]
  node_director["Conversation director"]
  node_base["Persona agent base<br/>[base_agent.py]"]
  node_personas["Five engagement personas<br/>[aunty_agent.py]"]
  node_generator["Response generator"]
  node_templates["Persona templates<br/>[templates.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_extractor["Intelligence extraction"]
  node_analyst["Intelligence analyst"]
  node_callback["GUVI callback<br/>[guvi_callback.py]"]
end

subgraph group_learning["Learning and models"]
  node_rl["RL agent<br/>[rl_agent.py]"]
  node_state["State encoder<br/>[state_encoder.py]"]
  node_reward["Reward calculator"]
end

node_caller(("Scammer"))
node_llm_service{{"LLM providers"}}

node_caller -->|"sends message"| node_api
node_api -.->|"authenticates"| node_auth
node_api -->|"classifies scam"| node_classifier
node_api -.->|"tracks session"| node_sessions
node_classifier -->|"selects engagement"| node_orchestrator
node_orchestrator -->|"requests strategy"| node_director
node_orchestrator -->|"creates persona"| node_personas
node_orchestrator -->|"generates turn"| node_base
node_personas -.->|"extends"| node_base
node_base -->|"requests response"| node_generator
node_base -->|"invokes fallback"| node_llm
node_generator -.->|"uses persona prompts"| node_templates
node_llm -->|"calls provider"| node_llm_service
node_api -->|"extracts intelligence"| node_extractor
node_extractor -.->|"analyzes findings"| node_analyst
node_api -->|"reports findings"| node_callback
node_sessions -->|"persists sessions"| node_database
node_sessions -->|"uses RL"| node_rl
node_rl -.->|"encodes state"| node_state
node_rl -.->|"calculates reward"| node_reward

click node_api "https://github.com/nithyasahasra/agentapi/blob/main/endpoints.py"
click node_auth "https://github.com/nithyasahasra/agentapi/blob/main/auth.py"
click node_sessions "https://github.com/nithyasahasra/agentapi/blob/main/session_manager_enhanced.py"
click node_classifier "https://github.com/nithyasahasra/agentapi/blob/main/scam_classifier_enhanced.py"
click node_orchestrator "https://github.com/nithyasahasra/agentapi/blob/main/agent_orchestrator.py"
click node_director "https://github.com/nithyasahasra/agentapi/blob/main/conversation_director_agent.py"
click node_base "https://github.com/nithyasahasra/agentapi/blob/main/base_agent.py"
click node_personas "https://github.com/nithyasahasra/agentapi/blob/main/aunty_agent.py"
click node_generator "https://github.com/nithyasahasra/agentapi/blob/main/response_generator.py"
click node_templates "https://github.com/nithyasahasra/agentapi/blob/main/templates.py"
click node_llm "https://github.com/nithyasahasra/agentapi/blob/main/llm_client.py"
click node_extractor "https://github.com/nithyasahasra/agentapi/blob/main/intelligence_extractor.py"
click node_analyst "https://github.com/nithyasahasra/agentapi/blob/main/intelligence_analyst_agent.py"
click node_callback "https://github.com/nithyasahasra/agentapi/blob/main/guvi_callback.py"
click node_rl "https://github.com/nithyasahasra/agentapi/blob/main/rl_agent.py"
click node_state "https://github.com/nithyasahasra/agentapi/blob/main/state_encoder.py"
click node_reward "https://github.com/nithyasahasra/agentapi/blob/main/reward_calculator.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_api,node_auth,node_sessions,node_database toneBlue
class node_classifier,node_orchestrator,node_director,node_base,node_personas,node_generator,node_templates,node_llm toneAmber
class node_extractor,node_analyst,node_callback toneMint
class node_rl,node_state,node_reward toneRose
class node_caller,node_llm_service toneIndigo
```

## Components

### API and sessions

- [API endpoints](https://github.com/nithyasahasra/agentapi/blob/main/endpoints.py): `endpoints.py`
- [API key auth](https://github.com/nithyasahasra/agentapi/blob/main/auth.py): `auth.py`
- [Session manager](https://github.com/nithyasahasra/agentapi/blob/main/session_manager_enhanced.py): `session_manager_enhanced.py`
- **Session database**

### Scam engagement

- [Scam classification](https://github.com/nithyasahasra/agentapi/blob/main/scam_classifier_enhanced.py): `scam_classifier_enhanced.py`
- [Agent orchestrator](https://github.com/nithyasahasra/agentapi/blob/main/agent_orchestrator.py): `agent_orchestrator.py`
- [Conversation director](https://github.com/nithyasahasra/agentapi/blob/main/conversation_director_agent.py): `conversation_director_agent.py`
- [Persona agent base](https://github.com/nithyasahasra/agentapi/blob/main/base_agent.py): `base_agent.py`
- [Five engagement personas](https://github.com/nithyasahasra/agentapi/blob/main/aunty_agent.py): `aunty_agent.py`
- [Response generator](https://github.com/nithyasahasra/agentapi/blob/main/response_generator.py): `response_generator.py`
- [Persona templates](https://github.com/nithyasahasra/agentapi/blob/main/templates.py): `templates.py`
- [LLM client](https://github.com/nithyasahasra/agentapi/blob/main/llm_client.py): `llm_client.py`

### Intelligence

- [Intelligence extraction](https://github.com/nithyasahasra/agentapi/blob/main/intelligence_extractor.py): `intelligence_extractor.py`
- [Intelligence analyst](https://github.com/nithyasahasra/agentapi/blob/main/intelligence_analyst_agent.py): `intelligence_analyst_agent.py`
- [GUVI callback](https://github.com/nithyasahasra/agentapi/blob/main/guvi_callback.py): `guvi_callback.py`

### Learning and models

- [RL agent](https://github.com/nithyasahasra/agentapi/blob/main/rl_agent.py): `rl_agent.py`
- [State encoder](https://github.com/nithyasahasra/agentapi/blob/main/state_encoder.py): `state_encoder.py`
- [Reward calculator](https://github.com/nithyasahasra/agentapi/blob/main/reward_calculator.py): `reward_calculator.py`

### Other components

- **Scammer**
- **LLM providers**

## Connections

- Scammer → API endpoints: sends message
- API endpoints → API key auth: authenticates
- API endpoints → Scam classification: classifies scam
- API endpoints → Session manager: tracks session
- Scam classification → Agent orchestrator: selects engagement
- Agent orchestrator → Conversation director: requests strategy (evidence: `agent_orchestrator.py`)
- Agent orchestrator → Five engagement personas: creates persona (evidence: `agent_orchestrator.py`)
- Agent orchestrator → Persona agent base: generates turn (evidence: `agent_orchestrator.py`)
- Five engagement personas → Persona agent base: extends
- Persona agent base → Response generator: requests response (evidence: `base_agent.py`)
- Persona agent base → LLM client: invokes fallback (evidence: `base_agent.py`)
- Response generator → Persona templates: uses persona prompts
- LLM client → LLM providers: calls provider (evidence: `llm_client.py`)
- API endpoints → Intelligence extraction: extracts intelligence
- Intelligence extraction → Intelligence analyst: analyzes findings
- API endpoints → GUVI callback: reports findings
- Session manager → Session database: persists sessions (evidence: `session_manager_enhanced.py`)
- Session manager → RL agent: uses RL (evidence: `session_manager_enhanced.py`)
- RL agent → State encoder: encodes state
- RL agent → Reward calculator: calculates reward