Metadata-Version: 2.4
Name: seraph-agent
Version: 0.5.4
Summary: The AI agent that audits itself. 27 providers, 45 tools, 23 channels, self-improving.
Author: bosskalash
License: MIT
Project-URL: Homepage, https://github.com/bosskalash/seraph
Project-URL: Documentation, https://github.com/bosskalash/seraph#readme
Project-URL: Repository, https://github.com/bosskalash/seraph
Project-URL: Issues, https://github.com/bosskalash/seraph/issues
Keywords: ai,agent,self-improving,telegram,discord,llm,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: flask>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.30
Requires-Dist: websockets>=12.0
Requires-Dist: rich>=13.0
Requires-Dist: questionary>=2.0
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: google-generativeai>=0.5; extra == "all"
Requires-Dist: boto3>=1.34; extra == "all"
Requires-Dist: openwakeword>=0.6; extra == "all"
Requires-Dist: pyaudio>=0.2; extra == "all"
Requires-Dist: qrcode>=7.0; extra == "all"
Requires-Dist: websocket-client>=1.7; extra == "all"
Requires-Dist: opentelemetry-api>=1.20; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pyflakes>=3.0; extra == "dev"
Dynamic: license-file

# Seraph

**The AI agent that audits itself.**

**v0.5.4** — Gateway feature completion: streaming, dynamic provider plugins, hot-reload, remote-device nodes, OAuth PKCE, sandbox execution, canvas surfaces, companion pairing.

Self-improving, self-auditing, multi-channel AI agent platform. 45 tools, 23 channels, runs everywhere.

---

## Fastest path to first message — local CLI (60 seconds)

No bot tokens. No platform setup. Just clone, install, run, type.

```bash
git clone https://github.com/bosskalash/seraph.git
cd seraph
pip install -e .
python seraph_cli.py
```

You land at a `>` prompt. Type a message, press Enter, and Seraph replies in
the same terminal — routed through the full shared V2 reasoning core (tools,
failover, verifier, memory, outcome recording). Exit with `/exit`, `quit`,
`Ctrl+C`, or `Ctrl+D`.

Slash commands inside the CLI:

```
/help       — show this help
/status     — show channel/session/model status
/new        — clear the current conversation
/model      — view or change the active LLM model
/channels   — list registered channels in the registry
/exit       — exit the REPL (also: /quit, exit, quit)
```

**What you need first:** an LLM API key in `~/.seraph/.env` (or your shell
environment). See [Configuration](#configuration). If you want a richer
setup — Telegram, Discord, Slack, and 19 other channels — see
[Other channels](#other-channels).

> **Why this is the recommended path:** the CLI is a first-class
> `IChannelAdapter` on the shared V2 core — the exact same reasoning pipeline
> Telegram and Discord use. See
> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and
> [docs/PLUGIN_QUICKSTART.md](docs/PLUGIN_QUICKSTART.md).

---

## Why Seraph?

| | Legacy Agent | Hermes | Seraph |
|--|----------|--------|--------|
| Self-improving | No | Yes | **Yes** |
| Self-auditing | No | No | **Yes** |
| Anti-dilution | No | No | **Yes** |
| Windows native | Clunky | No (WSL) | **Yes** |
| Channels | 22 | 16 | **23** |
| Tools | ~30 | 48 | **45** |
| Models | ~10 | 200+ | **200+** |
| Memory | SQLite | SQLite+FTS5 | **SQLite+FTS5** |
| Skills guard | No | Regex | **Regex + trust scoring** |
| Smart routing | No | Yes | **Yes + failover + pool** |
| Canvas | Electron | No | **Web (any browser)** |
| Companion app | Native | No | **PWA (all platforms)** |

---

## Install

**From PyPI:**
```bash
pip install seraph-agent
seraph configure   # interactive setup wizard
seraph run         # foreground
# or: seraph start   # background
```

**From source (for development):**
```bash
git clone https://github.com/bosskalash/seraph.git
cd seraph
pip install -e .
python seraph_cli.py
```

**Docker (for running the full multi-channel deployment):**
```bash
git clone https://github.com/bosskalash/seraph.git
cd seraph
cp .env.example .env  # edit with your keys
docker compose up -d
```

---

## Configuration

Seraph reads config from `~/.seraph/.env` (and your process environment). The
CLI launcher loads this file automatically on startup.

Minimum for the CLI path:

```env
SERAPH_PROVIDER=openai
SERAPH_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-key-here
```

Or any provider Seraph supports — Anthropic, Google, OpenRouter, MiniMax,
Mistral, DeepSeek, Groq, Fireworks, Together, xAI, Cerebras, etc.

### Supported Models
- OpenAI: gpt-5.4, gpt-4.1, gpt-4o, gpt-4o-mini
- Anthropic: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
- OpenRouter: 200+ models via one API key

### YAML config (`~/.seraph/config.yaml`)
```yaml
model: gpt-5.4
provider: openai
memory:
  enabled: true
skills:
  auto_generate: true
audit:
  enabled: true
  max_rounds: 5
```

### Identity (`~/.seraph/SOUL.md`)
Customize who your agent is. Injected into every prompt.

### MCP Servers (`~/.seraph/mcp.json`)
```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}
```

---

## Other channels

The CLI is the fastest local path. For real-world deployments you can run
any of the other 22 channels instead — they all share the same reasoning
core.

**Telegram** (the historic default):

1. Get a bot token from [@BotFather](https://t.me/BotFather).
2. Add to `~/.seraph/.env`:
   ```env
   SERAPH_TELEGRAM_TOKEN=your-bot-token
   SERAPH_ALLOWED_USERS=your-telegram-id
   ```
3. Run `python run.py` — this boots the full multi-channel stack
   (Telegram + Discord + Slack + WhatsApp + any channel with credentials).
4. Message your bot on Telegram.

**Discord, Slack, WhatsApp, Signal, Matrix, ...** — set the matching env vars
in `~/.seraph/.env` and they start automatically when `run.py` boots. See
the [full channel list](#23-channels) below, and
[docs/PLUGIN_QUICKSTART.md](docs/PLUGIN_QUICKSTART.md) for how to add a
new one.

---

## 45 Built-in Tools

| Category | Tools |
|----------|-------|
| **Core** | terminal, read_file, write_file, list_files, clipboard |
| **Web** | web_search, web_fetch, browse (headless) |
| **Code** | run_code (sandbox), apply_patch, audit_file, audit_directory |
| **AI** | describe_image (vision), mixture_of_agents, delegate_task, verify_claim |
| **Media** | generate_image (DALL-E), text_to_speech, transcribe, voice_respond |
| **Comms** | send_email, notify, manage_webhook, send_notification |
| **Data** | query_sqlite, export_conversation, export_html, search_sessions |
| **DevOps** | ssh, git, git_clone, import_api (OpenAPI), health_check |
| **Smart Home** | homeassistant |
| **Workflow** | todo, checkpoint, clarify, request_approval, interrupt, progress |
| **Skills** | skills_hub (install/search/sync), fuzzy_find, mcp (Model Context Protocol) |
| **Meta** | canvas (visual workspace), qr_code, usage_stats |

## 23 Channels

| Channel | Protocol | Status |
|---------|----------|--------|
| **CLI** | **stdin/stdout** | **Production — fastest local path** |
| Telegram | Bot API | Production |
| Discord | Gateway WS | Ready |
| Slack | Socket Mode | Ready |
| WhatsApp | Cloud API | Ready |
| Signal | signal-cli REST | Ready |
| Matrix | Client-Server | Ready |
| Email | IMAP + SMTP | Ready |
| SMS | Twilio | Ready |
| IRC | Raw socket | Ready |
| MS Teams | Bot Framework | Ready |
| Google Chat | Webhook API | Ready |
| LINE | Messaging API | Ready |
| Mattermost | REST API | Ready |
| Twitch | IRC over SSL | Ready |
| Nostr | Relay protocol | Ready |
| DingTalk | Robot API | Ready |
| Feishu/Lark | Open API | Ready |
| iMessage | BlueBubbles | Ready |
| WebChat | HTTP server | Ready |
| Canvas | Visual workspace | Ready |
| Voice Wake | Mic + wake word | Ready |
| PWA | Progressive Web App | Ready |

## 40+ Slash Commands (Telegram/Discord/Slack)

```
/new         Fresh conversation         /improve     Self-improvement cycle
/model       View or change model       /cron        Manage scheduled jobs
/status      System status              /heartbeat   Health monitor
/tools       List available tools       /doctor      Run diagnostics
/exec        Run a shell command        /approve     DM pairing approval
/search      Search the web             /think       Set reasoning level
/read        Read a file                /insights    Conversation analytics
/files       List workspace files       /update      Pull latest from git
/memory      Memory status              /restart     Restart the bot
/remember    Save a fact                /backup      Backup all data
/forget      Remove a fact              /logs        View recent logs
/recall      Search past conversations  /budget      Daily spending limit
/persona     Switch personality         /template    Prompt templates
/raw         Direct LLM (zero overhead) /config      View/change settings
/sandbox     Run Python code            /compress    Smart compress
/branch      Fork conversation          /retry       Retry last response
/undo        Undo last exchange         /send        Send a file
/checkpoint  Save conversation state    /id          Show Telegram ID
/restore     Restore a checkpoint       /help        Show all commands
```

The CLI channel supports a smaller built-in set (`/help`, `/status`,
`/channels`, `/exit`); other slash commands still dispatch through to the
shared core when typed.

## Architecture

```
User (on one of 23 channels: CLI, Telegram, Discord, Slack, ...)
  |
  v
Channel adapter (IChannelAdapter — thin, delivery-only)
  |
  v
seraph_core/orchestrator.py  — shared V2 reasoning core
  |  ProviderRegistry | ToolRegistry | SeraphSettings
  |  FailoverEngine | ToolLoop | ResponseDiscipline
  |  OutcomeRecorder | ShadowEvalRunner | PromptBuilder
  |
  v
LLM provider (OpenAI / Anthropic / Google / OpenRouter / ...)
  |
  v
SQLite — memory (FTS5), sessions, skills, rules
```

Every channel — CLI included — goes through the same core. See
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## What Makes Seraph Different

### Anti-Dilution Engine
Other platforms waste 30-50% of context on bloated system prompts. Seraph has:
- **Smart tool filtering** -- only sends relevant tools per message
- **Prompt compiler** -- minifies, deduplicates, strips decorations
- **Context budget** -- system overhead capped at 20%
- **Lazy injection** -- memory only loaded when conversation needs it
- **`/raw` mode** -- zero injection, direct LLM access

### Self-Improvement Loop
The agent improves itself over time:
- Reviews conversations for user corrections
- Stores lessons in active memory
- Auto-generates reusable skills from complex tasks
- Self-audits its own code for bugs
- Runs on cron (every 6h) or manual (`/improve`)

### Skills Guard
Every external skill is security-scanned before installation:
- 30+ threat patterns (exfiltration, injection, destructive, credential theft)
- Trust scoring (0-100)
- Install policy by source (builtin/trusted/community)

### Canvas
Live visual workspace at `http://localhost:18803/canvas`. The agent can push HTML, code, tables, charts, and run JavaScript in your browser.

### Model Router
- **Smart routing** -- simple questions use cheap model, complex use strong
- **Failover chain** -- auto-switch when a model is down
- **Credential pool** -- rotate API keys with exponential backoff

## Testing

```bash
pip install -e ".[dev]"
python -m pytest tests/ -v
```

## Report a bug / Ask for help

- **Bug?** Open an issue — the form asks for `seraph doctor`
  output, version, and repro steps so we can act on it:
  [github.com/bosskalash/seraph/issues/new/choose](https://github.com/bosskalash/seraph/issues/new/choose).
- **Security vulnerability?** Do NOT file a public issue. Use
  GitHub's private advisory flow —
  [github.com/bosskalash/seraph/security/advisories/new](https://github.com/bosskalash/seraph/security/advisories/new) —
  and see [SECURITY.md](SECURITY.md) for scope and disclosure
  timeline.
- **Setup question?** Run `seraph doctor` first — it prints
  actionable next-step hints for every failed check.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and
[docs/PLUGIN_QUICKSTART.md](docs/PLUGIN_QUICKSTART.md) for the 5-minute guide
to writing a tool, provider, channel, or memory backend.

## License

MIT — see [LICENSE](LICENSE).
