Metadata-Version: 2.3
Name: shikigami-bot
Version: 20260302.165807
Summary: Multi-agent Telegram bot with semantic routing and OS-level security
Author: Malte Sussdorff
Author-email: Malte Sussdorff <malte.sussdorff@cognovis.de>
Requires-Dist: aiogram>=3.25.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anthropic>=0.83.0
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: cryptography>=46.0.5
Requires-Dist: httpx>=0.28.1
Requires-Dist: pillow>=12.1.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pyotp>=2.9.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: qrcode>=8.2
Requires-Dist: slack-bolt>=1.22.0
Requires-Dist: structlog>=25.5.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Shikigami Bot

Shikigami Bot is a personal AI agent platform built on Telegram. It routes your messages to specialized AI agents — each with its own personality, tools, and skills — using semantic classification. Agents run as Claude Code CLI subprocesses, keeping tool access and trust boundaries explicit. The platform is designed for single-operator use: you control which Telegram users can interact with it, which agents exist, and what each agent can do.

## Architecture

```
Telegram
   |
   v
+-------------+
| Transport   |  aiogram adapter — raw Telegram message -> domain model
+-------------+
   |
   v
+-------------+
| Guardrails  |  Fail-closed allowlist — deny by default
+-------------+
   |
   v
+-------------+
|    Relay    |  Claude Haiku — semantic classification, session routing
|   Router    |  Returns: agent, session, confidence
+-------------+
   |
   v
+-------------+
|   Session   |  SQLite (dev) / Postgres (prod) — create or resume
|    Store    |
+-------------+
   |
   v
+-------------+
| Claude CLI  |  Subprocess with env allowlist and tool restriction
|  (adapter)  |  --append-system-prompt (trusted) / -p (untrusted input)
+-------------+
   |
   v
+-------------+
|  Response   |  Extract intent tags [REMEMBER:], [GOAL:], etc.
|   Parser    |
+-------------+
   |
   v
Telegram
```

## Key Features

- **Semantic routing**: Messages are classified by topic and routed to the right agent automatically. Session continuity is determined by topic similarity, not timeouts.
- **Confidence-gated HITL**: When routing confidence falls below the configured threshold, the user is asked to confirm via inline keyboard before the agent responds.
- **Structured trust zones**: Agent definitions are immutable at runtime. Skills are append-only. Only session state is mutable.
- **Prompt separation**: Agent system prompts are passed via `--append-system-prompt`; user input via `-p`. They are never concatenated.
- **Environment allowlist**: The Claude CLI subprocess receives only `PATH`, `HOME`, and `ANTHROPIC_API_KEY` — never the full parent environment.
- **Per-agent tool restriction**: Each agent declares its `tools` in `agent.yml`. The adapter enforces this via `--allowedTools`.
- **Fail-closed defaults**: Empty allowlist denies all users. Missing API key triggers safe fallback routing. Required config fails at startup.
- **Observability**: Optional Langfuse integration for tracing (self-hosted or cloud).

## Prerequisites

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) for dependency management
- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude`) on `PATH`
- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
- An Anthropic API key (for relay classification and agent invocations)

## Quick Start

```bash
git clone https://github.com/your-org/shikigami-bot.git
cd shikigami-bot
cp .env.example .env
# Edit .env with your tokens and allowed user IDs
uv run python -m shikigami_bot
```

The bot starts polling Telegram immediately. Send it a message from an allowed user ID to verify.

## Configuration

All configuration is read from environment variables (or a `.env` file in the project root). See `.env.example` for a template with all fields.

| Variable | Required | Default | Description |
|---|---|---|---|
| `TELEGRAM_BOT_TOKEN` | Yes | — | Bot token from @BotFather |
| `ALLOWED_USER_IDS` | Yes | `""` (deny all) | Comma-separated Telegram user IDs |
| `ANTHROPIC_API_KEY` | Yes | — | Used by relay router and Claude CLI adapter |
| `DATABASE_URL` | No | SQLite | Postgres connection string for production |
| `RELAY_CONFIDENCE_THRESHOLD` | No | `0.8` | Below this, routing asks for confirmation |
| `LANGFUSE_PUBLIC_KEY` | No | — | Langfuse tracing public key |
| `LANGFUSE_SECRET_KEY` | No | — | Langfuse tracing secret key |
| `LANGFUSE_HOST` | No | `https://cloud.langfuse.com` | Langfuse host URL |

**Important:** If `ALLOWED_USER_IDS` is empty, all users are denied. There is no "allow all" fallback.

To find your Telegram user ID, send a message to [@userinfobot](https://t.me/userinfobot).

## Agent Configuration

Agents live under the `agents/` directory. Each agent is a subdirectory containing `agent.yml` and `prompt.md`.

### Directory Structure

```
agents/
  general/
    agent.yml         # Required — config: name, model, tools, skills
    prompt.md         # Required — full system prompt
  research/
    agent.yml
    prompt.md
    skills/           # Optional — skill definitions
      briefing.md
      research.md
```

### agent.yml

The `agent.yml` file is the agent's configuration.

```yaml
name: research
description: Market intelligence, competitor analysis, deep research
model: opus            # haiku | sonnet | opus
orchestrator: false
tools:
  - WebSearch
  - WebFetch
  - Read
skills:
  - briefing
  - research
```

Fields:

| Field | Required | Description |
|---|---|---|
| `name` | Yes | Unique agent identifier (matches directory name) |
| `description` | Yes | One-line description used in relay routing table |
| `model` | No | `haiku`, `sonnet`, or `opus` (default: `sonnet`) |
| `orchestrator` | No | Whether this agent orchestrates others (default: `false`) |
| `tools` | No | List of Claude CLI tool names the agent may use |
| `skills` | No | List of skill names (matching files in `skills/`) |

### prompt.md

The system prompt for the agent. Injected as trusted content via `--append-system-prompt`. If it contains a `# Soul` or `## Personality` heading, the content after that heading is extracted as the personality block.

### Skills

Skills are markdown files under `agents/<name>/skills/`. Each skill provides additional context or capability description that is loaded into the relay routing table. Skill content format is free-form markdown.

### Minimal Agent Example

The simplest possible agent:

```
agents/
  myagent/
    agent.yml
    prompt.md
```

`agent.yml`:
```yaml
name: myagent
description: Handles calendar and scheduling tasks
model: sonnet
tools:
  - Read
  - Write
skills: []
```

`prompt.md`:
```markdown
You are a scheduling assistant. Help the user manage their calendar.
Be concise. Confirm before making changes.
```

## Security Model

Shikigami Bot operates across three trust zones. The **immutable zone** contains agent definitions and source code — these are frozen at runtime and require a redeploy to change. The **append-only zone** contains skills that can be installed once but not modified from within the running system. The **mutable zone** is session state in the database, which is fully runtime-managed.

The platform is fail-closed: an empty user allowlist denies everyone, a missing API key triggers safe fallback routing, and required configuration missing at startup raises an exception rather than silently degrading. User input and agent system prompts are structurally separated at the CLI level and never concatenated. When routing confidence is low, the user must confirm the routing decision via an inline keyboard before the agent is invoked.

## License

MIT
