# swordboom/ai-agent-honeypot architecture

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

- Interactive diagram: https://gitdiagram.com/swordboom/ai-agent-honeypot
- Repository: https://github.com/swordboom/ai-agent-honeypot

## Overview

This is a **single Python web service** (“Agentic Honey-Pot API”) that exposes:
- **Core evaluator API**: scam intent detection + multi-persona autonomous engagement + intelligence extraction
- **Protected operator dashboard** (static HTML/JS + server-side JSON endpoints guarded by `x-dashboard-key`)
- **Mandatory final callback** to an external GUVI endpoint (with retries/backoff/workers)

Key architectural traits to reflect:
- **API-first** service with a small built-in web UI
- **In-memory state** (sessions/metrics), TTL cleanup (hackathon speed)
- **LLM-backed** with **failover**: OpenAI → Gemini → rule-based fallback
- “Agentic” pipeline: detection → persona/engagement policy → reply generation → extraction → callbacks

##### App entry + configuration
- `main.py` — web server entrypoint, routing, middleware/auth wiring (likely FastAPI/Flask-style)
- `config.py` — environment variables, feature flags, timeouts, TTLs, keys

##### Agent / AI decisioning pipeline (`agent/`)
- `agent/scam_detector.py` — scam intent detection
- `agent/personas.py` — persona definitions / selection logic
- `agent/engagement_policy.py` (actually under `services/` but conceptually part of agentic behavior) — how/when to engage
- `agent/reply_agent.py` — orchestrates response generation
- `agent/llm_clients.py` — OpenAI/Gemini clients + failover behavior
- `agent/intelligence_extractor.py` — extract actionable intel from conversation (LLM-based when enabled)
- `agent/structured_extractor.py` — structured field extraction (likely schema-driven)
- `agent/notes.py` — internal annotations/summaries persisted into session

##### Services layer (`services/`)
- `services/session_manager.py` — in-memory session store, TTL, cleanup loop
- `services/dashboard_service.py` — aggregates metrics/summaries for dashboard APIs
- `services/callback_service.py` — posts final payload to external GUVI callback (retries/backoff, worker pool)
- `services/engagement_policy.py` — policy gates/logic for engagement style

##### Models / contracts (`models/`)
- `models/api.py` — request/response models for `/api/message`
- `models/dashboard.py` — dashboard DTOs (summary/session views)

##### Dashboard UI (`static/`)
- `static/dashboard.html/.css/.js` — client-side UI calling `/dashboard/api/*`

##### Tests and deployment
- `tests/test_app.py` — smoke/contract tests (good to indicate “test boundary”)
- `Dockerfile`, `runtime.txt`, `requirements.txt` — deployment/runtime dependencies

##### External LLM Providers
- OpenAI API
- Gemini API
##### External Callback Endpoint
- GUVI callback URL (`HONEY_POT_CALLBACK_URL`)

Security boundaries:
- `/api/message` requires `x-api-key` (`HONEY_POT_API_KEY` or `API_KEY`)
- `/dashboard/api/*` requires `x-dashboard-key`

State choice:
- “Sessions/Metrics: **in-memory** (TTL-based)”

##### Component view (inside the Python service)
**Goal:** show the internal pipeline and responsibilities.
- **API Router/Controller layer** (from `main.py`)
- Routes: `/health`, `/api/message`, `/dashboard`, `/dashboard/api/*`
- **Auth middleware/checks** (API key + dashboard key)
- **Session Manager** (`services/session_manager.py`)
- **Agent Orchestrator** (`agent/reply_agent.py`)
- Scam Detector (`agent/scam_detector.py`)
- Engagement Policy (`services/engagement_policy.py`)
- Persona Manager (`agent/personas.py`)
- LLM Clients (`agent/llm_clients.py`) → OpenAI/Gemini
- Fallback logic (rule-based) (called out explicitly)
- Intelligence Extractor (`agent/intelligence_extractor.py`)
- Structured Extractor (`agent/structured_extractor.py`)
- Notes/Summarizer (`agent/notes.py`)
- **Callback Service** (`services/callback_service.py`) → GUVI endpoint
- **Dashboard Service** (`services/dashboard_service.py`) → reads session store, produces summary/session/map data
- **Static Asset Server** (serving `static/*`)

##### API Layer
- validates `x-api-key`
- parses request into `models/api.py`
##### Session Manager
- load/create session (`models/session.py`)
- append incoming message/history
##### Scam Detector
- compute scam intent / risk
##### Engagement Policy + Personas
- decide whether/how to engage
- pick persona / response style
##### Reply Agent
- call LLM via `llm_clients.py`
- **first OpenAI**, on timeout/error **fallback to Gemini**, then **rule-based**
- produce reply text
##### Extraction (optional, flag-driven)
- if `ENABLE_LLM_EXTRACTION=true` and interval reached:
- run intelligence extraction / structured extraction
- store results in session
##### Persist updates
- session updated in-memory + timestamps for TTL
##### Callback Service (conditional/limited)
- send final evaluator-compatible payload to GUVI
- retries/backoff/worker pool (`CALLBACK_MAX_*`, `CALLBACK_MAX_WORKERS`)
##### Response
- minimal by default: `{"status":"success","reply":"..."}`
- optionally extended debug fields if `HONEY_POT_EXTENDED_RESPONSE=true`

- synchronous request path vs. callback work (often best drawn as async/background even if implemented inline)
- external calls (LLMs, callback endpoint) with timeout annotations (`LLM_TIMEOUT_SECONDS`, `CALLBACK_TIMEOUT_SECONDS`)

##### API Layer validates `x-dashboard-key`
4. **Dashboard Service** queries **Session Manager** (in-memory) and returns DTOs (`models/dashboard.py`)

##### Labels
- Use module-level labels in parentheses for traceability:
- “Session Manager (services/session_manager.py)”
- “LLM Clients (agent/llm_clients.py)”
- etc.

Examples:
- `POST /api/message {sessionId, message, history, metadata}`
- `LLM prompt/response`
- `Callback payload (evaluator-compatible)`

##### Quick “component checklist” to ensure you captured the essentials
- [ ] Two client types: evaluator client + operator browser
- [ ] Web app container with both API + dashboard routes
- [ ] Two auth gates (API key vs dashboard key)
- [ ] In-memory session store + TTL cleanup loop
- [ ] LLM providers + explicit failover ordering
- [ ] Callback service + retry/backoff/worker pool + external callback endpoint
- [ ] Dashboard static assets + dashboard APIs → dashboard service → session store

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% VIEW A: C4 CONTAINER VIEW
  %% =========================
  subgraph "View A — C4 Container (Top-level)"
    direction TB

    EC["Client: Evaluator / Scammer Simulator"]:::client
    OB["Client: Operator Browser"]:::client

    SVC["Agentic Honey-Pot API\n(Python Web App)"]:::container

    subgraph "External Services"
      direction TB
      OAI{{"OpenAI API"}}:::external
      GEM{{"Gemini API"}}:::external
      GUVI{{"GUVI Callback Endpoint\n(HONEY_POT_CALLBACK_URL)"}}:::external
    end

    EC -->|"POST /api/message"| SVC
    OB -->|"GET /dashboard"| SVC
    OB -->|"GET /dashboard/api/*"| SVC

    SVC -->|"LLM requests (timeout: LLM_TIMEOUT_SECONDS)"| OAI
    SVC -->|"LLM failover (OpenAI→Gemini)"| GEM
    SVC -.->|"Final callback payload\n(retries/backoff/workers,\nCALLBACK_TIMEOUT_SECONDS)"| GUVI

    APIKEY["Auth Gate: x-api-key\n(HONEY_POT_API_KEY / API_KEY)"]:::auth
    DKEY["Auth Gate: x-dashboard-key"]:::auth

    EC -->|"requires"| APIKEY
    OB -->|"requires (dashboard APIs)"| DKEY
    APIKEY -->|"guards /api/message"| SVC
    DKEY -->|"guards /dashboard/api/*"| SVC

    MEM["Sessions/Metrics Store\nIn-memory (TTL-based)"]:::store
    SVC -->|"reads/writes"| MEM
  end

  %% ===========================
  %% VIEW B: INTERNAL COMPONENTS
  %% ===========================
  subgraph "View B — Component View (Inside Python Web App)"
    direction TB

    subgraph "App Entry + Configuration"
      direction TB
      MAIN["API Router/Controller\n(main.py)\nRoutes: /health, /api/message, /dashboard, /dashboard/api/*"]:::component
      CFG["Configuration / Feature Flags\n(config.py)"]:::config
      AUTH["Auth Checks\n(x-api-key, x-dashboard-key)"]:::auth
      STATIC["Static Asset Server\n(serves static/*)"]:::frontend
    end

    subgraph "Models / Contracts"
      direction TB
      M_API["API Contracts\n(models/api.py)"]:::model
      M_SESS["Session State Model\n(models/session.py)"]:::model
      M_DASH["Dashboard DTOs\n(models/dashboard.py)"]:::model
    end

    subgraph "State & Services"
      direction TB
      SM["Session Manager\n(services/session_manager.py)\nIn-memory + TTL cleanup loop"]:::component
      DASH["Dashboard Service\n(services/dashboard_service.py)\nAggregations/metrics"]:::component
      CB["Callback Service\n(services/callback_service.py)\nRetries/Backoff/Worker Pool"]:::component
      EP["Engagement Policy\n(services/engagement_policy.py)"]:::component
      STORE[("In-memory Sessions/Metrics\n(TTL-based)")]:::store
    end

    subgraph "Agentic Pipeline (Orchestrator Pattern)"
      direction TB
      RA["Agent Orchestrator / Reply Agent\n(agent/reply_agent.py)"]:::orchestrator
      SD["Scam Detector\n(agent/scam_detector.py)"]:::component
      PM["Persona Manager\n(agent/personas.py)"]:::component
      LLM["LLM Clients + Failover\n(agent/llm_clients.py)\nOpenAI → Gemini → Rule-based"]:::component
      RB["Rule-based Fallback"]:::fallback
      IE["Intelligence Extractor (optional)\n(agent/intelligence_extractor.py)\nENABLE_LLM_EXTRACTION"]:::component
      SE["Structured Extractor\n(agent/structured_extractor.py)"]:::component
      NOTES["Notes / Summaries\n(agent/notes.py)"]:::component
    end

    %% Wiring inside service
    MAIN -->|"routes to"| AUTH
    AUTH -->|"dispatch /api/message"| RA
    AUTH -->|"dispatch /dashboard/api/*"| DASH
    MAIN -->|"serves /dashboard"| STATIC

    MAIN -->|"parse/validate"| M_API
    SM -->|"stores shape"| M_SESS
    DASH -->|"responds with"| M_DASH

    RA -->|"load/create session"| SM
    SM <-->|"read/write"| STORE

    RA -->|"detect"| SD
    RA -->|"policy gate"| EP
    RA -->|"select persona"| PM
    RA -->|"generate reply"| LLM
    LLM -->|"primary"| OAI
    LLM -->|"failover"| GEM
    LLM -->|"final fallback"| RB

    RA -->|"extract (interval/flag)"| IE
    RA -->|"extract structured fields"| SE
    RA -->|"annotate/summarize"| NOTES

    IE -->|"persist intel"| SM
    SE -->|"persist fields"| SM
    NOTES -->|"persist notes"| SM

    DASH -->|"read-only aggregation"| SM

    RA -.->|"enqueue/trigger final callback\n(evaluator-compatible payload)"| CB
    CB -.->|"POST with retries/backoff\nCALLBACK_MAX_* / CALLBACK_MAX_WORKERS"| GUVI

    %% Config influences (feature flags, TTLs, timeouts, keys)
    CFG -.->|"keys/timeouts/flags"| AUTH
    CFG -.->|"TTL/history limits"| SM
    CFG -.->|"LLM timeouts/enablement"| LLM
    CFG -.->|"ENABLE_LLM_EXTRACTION"| IE
    CFG -.->|"callback enablement/timeouts"| CB
  end

  %% ==================================
  %% VIEW C: REQUEST FLOW (API MESSAGE)
  %% ==================================
  subgraph "View C — Core Flow: POST /api/message (Synchronous vs Async)"
    direction TB

    F1["1) Evaluator Client\nPOST /api/message\n{sessionId,message,history,metadata}"]:::client
    F2["2) API Layer validates x-api-key\nparses models/api.py"]:::auth
    F3["3) Session Manager load/create\nappend message/history"]:::component
    F4["4) Scam intent detection"]:::component
    F5["5) Engagement policy + persona selection"]:::component
    F6["6) Reply generation via LLM\n(OpenAI→Gemini→Rule-based)"]:::component
    F7["7) Optional extraction\n(intel + structured + notes)\nflag/interval driven"]:::component
    F8["8) Persist session updates\n(in-memory + TTL timestamps)"]:::store
    F9["9) Final callback to GUVI\n(retries/backoff/workers)"]:::external
    F10["10) API response\n{status:'success', reply}\n(+optional extended fields)"]:::component

    F1 --> F2 --> F3 --> F4 --> F5 --> F6 --> F7 --> F8 --> F10
    F8 -.-> F9
  end

  %% Connect views lightly (keep vertical)
  EC -->|"drives"| F1
  F2 -->|"implemented by"| MAIN
  F3 -->|"implemented by"| SM
  F6 -->|"implemented by"| LLM
  F9 -->|"implemented by"| CB

  %% =========================
  %% Click events (file paths)
  %% =========================
  click MAIN "https://github.com/swordboom/ai-agent-honeypot/blob/main/main.py"
  click CFG "https://github.com/swordboom/ai-agent-honeypot/blob/main/config.py"

  click RA "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/reply_agent.py"
  click SD "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/scam_detector.py"
  click PM "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/personas.py"
  click LLM "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/llm_clients.py"
  click IE "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/intelligence_extractor.py"
  click SE "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/structured_extractor.py"
  click NOTES "https://github.com/swordboom/ai-agent-honeypot/blob/main/agent/notes.py"

  click EP "https://github.com/swordboom/ai-agent-honeypot/blob/main/services/engagement_policy.py"
  click SM "https://github.com/swordboom/ai-agent-honeypot/blob/main/services/session_manager.py"
  click DASH "https://github.com/swordboom/ai-agent-honeypot/blob/main/services/dashboard_service.py"
  click CB "https://github.com/swordboom/ai-agent-honeypot/blob/main/services/callback_service.py"

  click M_API "https://github.com/swordboom/ai-agent-honeypot/blob/main/models/api.py"
  click M_SESS "https://github.com/swordboom/ai-agent-honeypot/blob/main/models/session.py"
  click M_DASH "https://github.com/swordboom/ai-agent-honeypot/blob/main/models/dashboard.py"

  click STATIC "https://github.com/swordboom/ai-agent-honeypot/blob/main/static/dashboard.html"
  click F10 "https://github.com/swordboom/ai-agent-honeypot/blob/main/static/dashboard.js"

  %% Additional mapped assets (as standalone clickable nodes)
  AS_HTML["Dashboard UI (static/dashboard.html)"]:::frontend
  AS_CSS["Dashboard Styles (static/dashboard.css)"]:::frontend
  AS_JS["Dashboard Logic (static/dashboard.js)"]:::frontend
  TESTS["Tests Boundary (tests/test_app.py)"]:::test
  DOCKER["Deployment (Dockerfile)"]:::ops
  REQS["Dependencies (requirements.txt)"]:::ops
  RUNTIME["Runtime Pin (runtime.txt)"]:::ops
  ENVEX["Env Template (.env.example)"]:::ops

  STATIC -->|"serves"| AS_HTML
  STATIC -->|"serves"| AS_CSS
  STATIC -->|"serves"| AS_JS

  click AS_HTML "https://github.com/swordboom/ai-agent-honeypot/blob/main/static/dashboard.html"
  click AS_CSS "https://github.com/swordboom/ai-agent-honeypot/blob/main/static/dashboard.css"
  click AS_JS "https://github.com/swordboom/ai-agent-honeypot/blob/main/static/dashboard.js"
  click TESTS "https://github.com/swordboom/ai-agent-honeypot/blob/main/tests/test_app.py"
  click DOCKER "https://github.com/swordboom/ai-agent-honeypot/tree/main/Dockerfile"
  click REQS "https://github.com/swordboom/ai-agent-honeypot/blob/main/requirements.txt"
  click RUNTIME "https://github.com/swordboom/ai-agent-honeypot/blob/main/runtime.txt"
  click ENVEX "https://github.com/swordboom/ai-agent-honeypot/blob/main/.env.example"

  %% ==============
  %% Styling/Colors
  %% ==============
  classDef client fill:#E8F1FF,stroke:#2F5FB3,stroke-width:1.5px,color:#0B1B3A;
  classDef container fill:#E9FFF3,stroke:#1C8B4A,stroke-width:2px,color:#08301A;
  classDef component fill:#FFF7E6,stroke:#B7791F,stroke-width:1.5px,color:#3A2507;
  classDef orchestrator fill:#FFE4E6,stroke:#C53030,stroke-width:2px,color:#3B0A0A;
  classDef auth fill:#FFECEC,stroke:#B91C1C,stroke-width:2px,color:#3B0A0A;
  classDef store fill:#F2F4F7,stroke:#344054,stroke-width:1.5px,color:#101828;
  classDef external fill:#F3E8FF,stroke:#6B21A8,stroke-width:2px,color:#2B0B3F;
  classDef frontend fill:#E6FFFB,stroke:#0F766E,stroke-width:1.5px,color:#042F2E;
  classDef model fill:#F0FDF4,stroke:#15803D,stroke-width:1.5px,color:#052E16;
  classDef fallback fill:#FFF1F2,stroke:#9F1239,stroke-width:1.5px,color:#3B0A0A;
  classDef config fill:#ECFDF3,stroke:#16A34A,stroke-width:2px,color:#052E16;
  classDef test fill:#EEF2FF,stroke:#4338CA,stroke-width:1.5px,color:#111827;
  classDef ops fill:#FAFAFA,stroke:#525252,stroke-width:1.5px,color:#111827;
```
