Metadata-Version: 2.4
Name: minibot
Version: 0.29.0
Summary: Self-hosted Telegram-first AI assistant with async tooling, memory, and scheduling.
License: MIT
License-File: LICENSE.md
Keywords: telegram,assistant,llm,bot,automation,self-hosted
Author: sonic182
Author-email: johander1822@gmail.com
Requires-Python: >=3.12,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: codex
Provides-Extra: graph
Provides-Extra: http
Provides-Extra: rabbitmq
Provides-Extra: rag
Provides-Extra: stt
Provides-Extra: telegram
Provides-Extra: vault
Requires-Dist: aio-pika (>=9.6.2) ; extra == "rabbitmq"
Requires-Dist: aiogram (>=3.24.0,<4.0.0) ; extra == "telegram"
Requires-Dist: aiopipe (>=0.2.2)
Requires-Dist: aiosonic (>=1.0.7,<2.0.0)
Requires-Dist: aiosqlite (>=0.22.1,<0.23.0)
Requires-Dist: croniter (>=6.2.4,<7.0.0)
Requires-Dist: cryptography (>=50.0.1,<51.0.0) ; extra == "vault"
Requires-Dist: faster-whisper (>=1.0.0,<2.0.0) ; extra == "stt"
Requires-Dist: jinja2 (>=3.1.6,<4.0.0) ; extra == "http"
Requires-Dist: llm-async (>=0.5.3,<0.6.0)
Requires-Dist: llm-async-codex (==0.2.0) ; extra == "codex"
Requires-Dist: logfmter (>=0.0.11,<0.0.12)
Requires-Dist: networkx (>=3.6.1,<4.0.0) ; (python_version >= "3.12" and python_full_version != "3.14.1" and python_version < "3.15") and (extra == "graph")
Requires-Dist: numpy (>=2.0,<3.0) ; extra == "rag"
Requires-Dist: onecache (>=0.8.1,<0.9.0)
Requires-Dist: prompt-toolkit (>=3.0.53,<4.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
Requires-Dist: pypdf (>=6.10.2,<7.0.0) ; extra == "rag"
Requires-Dist: selectolax (>=0.4.11,<0.5.0)
Requires-Dist: sqlalchemy[asyncio] (>=2.0.46,<3.0.0)
Requires-Dist: starlette (>=1.3.1,<2.0.0) ; extra == "http"
Requires-Dist: telegramify-markdown (>=0.5.4,<0.6.0) ; extra == "telegram"
Requires-Dist: textual (>=8.2.8,<9.0.0)
Requires-Dist: tomlkit (>=0.15.1,<0.16.0)
Requires-Dist: uvicorn (>=0.44.0,<0.45.0) ; extra == "http"
Requires-Dist: websockets (>=15.0.1,<16.0.0) ; extra == "http"
Project-URL: Documentation, https://sonic182.github.io/minibot
Project-URL: Homepage, https://github.com/sonic182/minibot
Project-URL: Repository, https://github.com/sonic182/minibot
Description-Content-Type: text/markdown

![MiniBot — Self-hosted, auditable, extensible](docs/_static/minibot-banner.png)

[![PyPI version](https://img.shields.io/pypi/v/minibot)](https://pypi.org/project/minibot/)

Your personal AI assistant for Telegram - self-hosted, auditable, extensible, and intentionally opinionated.

📖 **[Full documentation](https://sonic182.github.io/minibot)**

Top features
------------

- 🤖 Personal assistant, not SaaS: your chats, memory, and scheduled prompts stay in your instance.
- 🎯 Opinionated by design: Telegram-centric flow, small tool surface, and explicit config over hidden magic.
- 🏠 Self-hostable: Dockerfile + docker-compose provided for easy local deployment.
- 🧩 Python extensions: add your own tools, event subscribers, and background services from any importable module — plus channels.
- 💻 Local console channel for development/testing without Telegram.
- 💬 Telegram channel with chat/user allowlists, long-polling or webhook modes, and multimodal inputs.
- 🧠 Provider support via [llm-async]: `openai`, `openai_responses`, `openrouter`, and more.
- 🧰 Configurable tools: chat memory, KV notes, HTTP fetch, calculator, datetime, Python execution, Bash, patch-based editing (`apply_patch`), file storage, grep, speech-to-text, and MCP server bridges.
- 🔎 RAG (optional): index local documents into SQLite (or Qdrant) and retrieve semantically relevant chunks.
- 🕸️ Relation graph (optional): store and traverse typed relationships between entities.
- ⏳ Async task workers: offload long-running jobs to a background queue (SQLite by default, optional RabbitMQ).
- ⏰ Scheduled prompts (one-shot, fixed-interval, and cron recurrence) persisted in SQLite.
- 🤝 Multi-agent orchestration with specialist agent definitions and skill packs.
- ⚙️ `minibot configure`: interactive terminal wizard to create or update `config.toml`.
- 📊 Structured logfmt logs and a focused async test suite.

Make it yours
-------------

MiniBot is built to be extended, and most changes need no Python:

| Level | What you get | Where |
| --- | --- | --- |
| Config | toggle tools, providers, models, limits | `config.toml` |
| No code | rewrite the system prompt, add skills and prompt packs, add specialist agents | `prompts/`, `skills/`, `agents/*.md` |
| External tools | connect any MCP server | `[[tools.mcp.servers]]` |
| Python | your own tools, event subscribers, services, channels | a module + `[extensions].modules` |

Start at the least powerful layer that does the job. The most common asks — a new
capability — usually stop at an MCP server or a ~10-line extension:

Security and trust model
------------------------

MiniBot can execute powerful tools such as shell commands and Python code. It is **not intended to be
a security boundary by itself**. For untrusted workloads, or deployments with sensitive host data,
run MiniBot inside an appropriately isolated environment.

Its job is safe defaults, explicit escape hatches and a documented trust model — not a guarantee the
software cannot make:

- **MiniBot's own responsibility** is safe-by-default config (`bash.pass_parent_env = false`, the
dangerous tools off), keeping secrets out of the LLM's reach (`[vault]`), and gating consequential
actions (`[tools.approval]`). These matter regardless of deployment, because the remote provider sees
whatever reaches a tool call, however isolated the host is.
- **The deployment's responsibility** is OS, filesystem and process isolation for `bash` and
`python_exec`. An owner who already isolates the host can reasonably accept the ambient risk.

Filesystem- and shell-level controls inside MiniBot are advisory. A `bash` tool without a jail, or
`file_storage` with `allow_outside_root = true`, can read and write anything the daemon's OS user
can, including files this documentation says a feature keeps out of reach. Enable those tools only
where the blast radius is acceptable. See
[Security & Sandboxing](https://sonic182.github.io/minibot/security.html).

Every capability is a config switch you own. Multi-agent orchestration, runtime agent reload and
model-authored agents are all opt-in or trivially off; when you turn one on, what it may do is your
decision and your responsibility.

```python
# my_tool.py — add "my_tool" to [extensions].modules
from pydantic import BaseModel, Field
from minibot.app.extensions import ExtensionContext
from minibot.llm.tools.base import ToolContext

class WordCountArgs(BaseModel):
    text: str = Field(description="Text to count words in.")

def register(mb: ExtensionContext) -> None:
    @mb.tool
    async def word_count(args: WordCountArgs, context: ToolContext) -> dict[str, int]:
        """Count the words in a piece of text."""
        return {"words": len(args.text.split())}
```

See the [Extending MiniBot](https://sonic182.github.io/minibot/extending.html) guide
for the full customization ladder. The pluggable surfaces — tools, event subscriptions,
services, channels — are covered in [extensions](https://sonic182.github.io/minibot/extensions.html)
and [events](https://sonic182.github.io/minibot/events.html); external tools arrive via
[MCP](https://sonic182.github.io/minibot/mcp.html).

Quick start
-----------

```bash
pip install minibot
# add extras as needed, e.g.: pip install "minibot[telegram,stt,rag,rabbitmq]"

minibot configure   # interactive wizard, writes config.toml
minibot              # start the daemon
```

Extras: `telegram` (aiogram + Telegram markdown rendering — the daemon needs it only when
`[channels.telegram]` is enabled), `rag` (pypdf, PDF ingestion for the RAG tool), `stt`
(speech-to-text via faster-whisper), `rabbitmq` (RabbitMQ task queue backend — not needed with the
default `sqlite` backend), `graph` (networkx, the optional relation-graph tool). Compact HTML
rendering in `http_request` uses selectolax, which ships with the base install.

MCP needs no extra: the MCP client is a JSON-RPC implementation with no third-party SDK dependency.

No Telegram bot yet? Run `minibot console` instead of `minibot` to chat with it in your terminal.

### Docker

```bash
pipx run minibot configure   # writes config.toml — must run on the host, docker-compose.yml mounts it read-only
# no pipx? `pip install minibot` into a throwaway venv and run `minibot configure` there instead.

docker compose up -d
```

`docker-compose.yml` builds and starts the `minibot` image. The Qdrant and RabbitMQ services are
commented out — `[tools.rag].backend` and `[tasks].backend` both default to `"sqlite"` — and are
only needed if you switch either to `"qdrant"` or `"rabbitmq"`.

Configure it with your AI agent
-------------------------------

**Configure MiniBot with your AI agent** (Claude Code, Codex, OpenCode, pi, ...): paste this prompt.

```text
Configure MiniBot for me:
1. Read the machine-readable docs at
   https://sonic182.github.io/minibot/llms.txt and follow the Getting Started,
   Configuration, Credential vault and Security links it lists.
2. Ask me as little as possible — one short batch of questions, then decide the rest
   yourself with secure defaults:
   - the Telegram allowlist chat/user ids (the bot token goes in the vault);
   - which LLM provider to use. Recommend the ChatGPT Codex subscription
     (`chatgpt_codex`) or OpenCode Go, both with model `gpt-6-luna` and
     `reasoning_effort = "high"`;
   - whether to run in Docker. It is optional: only worth it for isolation if I enable
     the dangerous tools below.
3. Copy `config.example.toml` to `config.toml` and edit it yourself — do not run
   `minibot configure`, that wizard is interactive and meant for humans. The templates
   ship with the repo and with the installed package.
4. Default to a secure install: leave the dangerous tools off — `python_exec`, `bash`,
   `apply_patch`, and `file_storage` with `allow_outside_root = false`. Enable one only
   if I explicitly ask, and say which tools are dangerous when you do.
5. Use the credential vault: enable `[vault]`, keep every credential out of config.toml,
   and write a `${secret:NAME}` placeholder for each (or `auth_secret` for an HTTP MCP
   server). Ask me for the secret *names*, never a secret value, and never write one
   down. Install the `vault` extra (and `codex` for the Codex provider).
6. Walk me through the vault: `minibot vault init`, then `minibot vault edit` to add the
   values, and `minibot vault list` to confirm. For Codex, also run `minibot codex login`.
7. Start MiniBot and confirm the logs are clean.

Stop after that and tell me what you configured and what still needs my input.

For the full reference, run
`curl --silent https://sonic182.github.io/minibot/llms-full.txt`
```

Both machine-readable files are published alongside the site: `llms.txt` is the concise,
curated index, and `llms-full.txt` is a single-file dump of the complete documentation.

Demo
----

Screenshots of Minibot understanding images, summarizing web pages, generating charts, and
transcribing voice messages — see the [demo gallery](https://sonic182.github.io/minibot/demo.html).

[llm-async]: https://github.com/sonic182/llm-async

