KEVIN — Autonomous Email Security Agent

Personality: Sarcastic, overconfident, deeply competent Version: 3.0 — Agentic Status: Production Ready

KEVIN is a self-running Python email security agent with a local LLM brain (Ollama), autonomous heartbeat, threat detection, Telegram two-way control, and a REST API for external integration.

He runs on your machine, watches your inbox, quarantines threats, and reports back — no cloud required.

---

What Kevin Does

• Connects to Gmail via IMAP (App Password or OAuth2)
• Scans every new email with a 5-layer pipeline: heuristics + LLM classification + 227 known attacker domains + domain reputation + URL analysis
• Quarantines phishing, deletes spam, archives promos — autonomously
• Adjusts scan frequency based on tension (30s when inbox is hot, 5min when calm)
• Sends Telegram alerts and accepts two-way commands (/scan, /status, /pause, /resume, /summary, /threats)
• Exposes a REST API on port 6010 so other agents (e.g. MAX) can call him
• Sends a morning briefing summarizing what he did overnight

---

Architecture

launcher.py          Boot + wiring
brain.py             Ollama (gemma3:4b) → Gemini fallback
drives.py            Tension/satisfaction loop — drives scan interval
goals.py             inbox_zero / threat_elimination / learning
heartbeat.py         Autonomous tick loop
threat_db.py         227 attacker domains + URL pattern checks
research.py          Domain reputation via Tavily (optional) + HackerTarget (free)
notifications.py     Telegram two-way + Discord + Slack + SMS
personality.py       Dynamic sass levels (low/medium/high)
api.py               Flask REST API — port 6010
kevin_agent.py       IMAP client + action planner
kevin_security.py    Email scoring engine
kevin_setup.py       First-run conversational setup wizard

---

Quick Start

Requirements

• Python 3.10+
• Ollama running locally with gemma3:4b pulled
• Gmail account

Install

git clone https://github.com/unimaginative-artist/KEVIN.git
cd KEVIN
pip install -r requirements.txt

Configure

python kevin_setup.py

Kevin will walk you through Gmail setup, brain config, and notifications. Takes about 2 minutes.

Run

python launcher.py

---

REST API

Kevin exposes a control plane on http://localhost:6010:

Method	Route	Description
GET	/status	tension, mood, threats today, scan count
GET	/goals	active goals and progress
GET	/threats	recent threats list
GET	/summary	brain-generated summary of recent activity
GET	/health	liveness check
POST	/scan	trigger immediate scan
POST	/pause	pause heartbeat
POST	/resume	resume heartbeat
POST	/quarantine	manually quarantine by UID

---

Telegram Commands

Once you configure a Telegram bot token, send commands directly to Kevin:

/scan      Immediate inbox scan
/status    Tension, mood, threat count
/threats   What he found today
/summary   AI-generated briefing
/pause     Stop the heartbeat
/resume    Resume the heartbeat

---

Configuration

Copy kevin_config.json and fill in your values, or run python kevin_setup.py to generate it interactively.

Key fields:

{
  "username": "you@gmail.com",
  "use_oauth": true,
  "brain": {
    "ollama_url": "http://localhost:11434",
    "ollama_model": "gemma3:4b",
    "gemini_api_key": ""
  },
  "notifications": {
    "telegram_token": "",
    "telegram_chat_id": ""
  },
  "tavily_api_key": "",
  "api_port": 6010
}

Note: kevin_config.json is gitignored — it contains your credentials. Never commit it.

---

Ollama Models

Kevin works with any Ollama model. Recommended:

Model	Speed	Quality
gemma3:4b	Fast	Good — default
llama3.2	Medium	Better reasoning
mistral	Medium	Good all-rounder

Pull a model: ollama pull gemma3:4b

---

Optional: Tavily Research

Set tavily_api_key in config to enable live domain reputation lookups. Without it, Kevin falls back to HackerTarget (free) for WHOIS and reverse IP data.

---

Optional: SOMA Federation

Kevin can connect to a SOMA coordinator for federated threat intelligence. Set soma.enabled: true and soma.coordinator_url in config.

---

Test Suite

python test_kevin.py

Verifies all 10 modules, drives math, brain classification, API routes, and more. Should show 33/33 passed with Ollama running.

---

License

MIT