How swordboom/ai-agent-honeypot works
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