Metadata-Version: 2.4
Name: afkbotio
Version: 1.0.10
Summary: Source-available local AI runtime and CLI for AFKBOT
License-Expression: LicenseRef-AFKBOT-Sustainable-Use-1.0
Project-URL: Homepage, https://afkbot.io
Project-URL: Documentation, https://afkbot.io/docs
Project-URL: Repository, https://github.com/afkbot-io/afkbotio
Project-URL: Issues, https://github.com/afkbot-io/afkbotio/issues
Project-URL: Changelog, https://github.com/afkbot-io/afkbotio/blob/main/CHANGELOG.md
Project-URL: License, https://github.com/afkbot-io/afkbotio/blob/main/LICENSE
Keywords: ai,agent,automation,cli,mcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: greenlet>=3.0
Requires-Dist: aiosqlite>=0.20
Requires-Dist: cryptography>=42.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: qrcode>=8.2
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: socksio>=1.0
Requires-Dist: telethon<2,>=1.42
Requires-Dist: uvicorn>=0.30
Requires-Dist: websockets>=12.0
Requires-Dist: typer>=0.12
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: jsonschema>=4.26
Requires-Dist: mcp<2,>=1.26
Requires-Dist: packaging>=24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# AFKBOT

AFKBOT is a source-available local AI runtime and CLI for chat-driven workflows,
tool calling, automations, and profile-scoped agent environments.

Documentation lives at [afkbot.io/docs](https://afkbot.io/docs). The project site is [afkbot.io](https://afkbot.io).
Use the docs site for setup, configuration, MCP, automations, and command reference.

## What AFKBOT does

- Runs local chat sessions with tool access, planning, and configurable reasoning.
- Supports multiple LLM providers in setup/profile runtime (`openrouter`, `openai`, `claude`, `moonshot`, `deepseek`, `xai`, `qwen`, and `custom`).
- Provides a CLI-first workflow for setup, chat, health checks, and runtime control.
- Supports profile-scoped configuration, secrets, permissions, and tool exposure.
- Includes browser, web, app, MCP, automation, and channel integration surfaces.
- Exposes a local runtime and API layer for longer-running workflows.

## License Model

- AFKBOT source code is available under the `Sustainable Use License 1.0`.
- Personal use, non-commercial use, and internal business use are allowed.
- Forking and modifying AFKBOT are allowed, but redistribution must stay free of charge and non-commercial.
- You may not sell AFKBOT, sell copies of AFKBOT, resell the source code, or offer AFKBOT as a paid hosted or white-label service without separate permission.
- The repository license does not grant any trademark rights to the AFKBOT name, logo, or branding.

## Requirements

- Python 3.12 or newer for manual source installs
- `uv` recommended for local development
- SQLite is the default runtime database for AFKBOT
- The hosted installers bootstrap `uv`, install AFKBOT as an isolated uv tool, and keep runtime state outside the app source tree

## Install

Hosted installer for macOS/Linux:

```bash
curl -fsSL https://afkbot.io/install.sh | bash
# open a new terminal after install
afk setup
afk doctor
afk chat
```

Hosted installer for Windows PowerShell:

```powershell
powershell -c "irm https://afkbot.io/install.ps1 | iex"
# open a new terminal after install
afk setup
afk doctor
afk chat
```

Local installer from a source checkout:

```bash
bash scripts/install.sh --repo-url "file://$PWD"
# open a new terminal after install
afk setup
afk doctor
afk chat
```

Common installer flags:

```bash
# installer and setup prompts in Russian
curl -fsSL https://afkbot.io/install.sh | bash -s -- --lang ru

# install from a specific Git ref
curl -fsSL https://afkbot.io/install.sh | bash -s -- --git-ref v1.0.10

# install from a local checkout
bash scripts/install.sh --repo-url "file://$PWD"

# show actions without mutating the machine
bash scripts/install.sh --dry-run

# skip bootstrap-only setup seeding during install
bash scripts/install.sh --skip-setup
```

What the installer does:

- bootstraps `uv` into the user-local bin directory if needed
- installs AFKBOT as an isolated `uv tool`
- updates shell integration so `afk` is available in new terminals
- seeds the runtime root with bootstrap-only setup metadata
- remembers the install source so `afk update` can refresh the same source later

The installer is idempotent. Rerun it to refresh the installed tool in place, or use `afk update`.

## First Run

For normal usage, the first-run flow is:

```bash
afk setup
afk doctor
afk chat
```

- `afk setup` configures the default profile, provider, policy, locale, and runtime defaults
- `afk setup` also asks whether `afk chat` should check for AFKBOT updates before opening chat
- `afk doctor` prints the effective runtime/chat ports and checks local readiness
- `afk chat` is the main entrypoint for real work

If update notices are enabled in setup, interactive `afk chat` checks for a newer AFKBOT build before opening the session and asks:

- `Yes`
- `No`
- `Remind in a week`

`No` continues into chat immediately and does not save a permanent skip. `Remind in a week` suppresses all update prompts for seven days. If you disable update notices in setup, chat will not ask at startup.

The runtime chooses and persists a non-default local port automatically for fresh installs, so use `afk doctor` when you need the actual `runtime_port` or `api_port`.

Manual local source setup with `uv`:

```bash
uv sync --extra dev
uv run afk setup
uv run afk doctor
uv run afk chat
```

Manual local source setup with `pip`:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
afk setup
afk doctor
afk chat
```

## Local Runtime

AFKBOT uses one local SQLite database by default for runtime state, semantic memory, and chat metadata:

```bash
export AFKBOT_DB_URL='sqlite+aiosqlite:///./afkbot.db'
```

Start the local runtime/API:

```bash
uv run afk start
uv run afk doctor
# doctor prints the effective runtime_port and api_port for this install
```

Webhook trigger example:

```bash
curl -X POST http://127.0.0.1:<runtime_port>/v1/automations/<profile_id>/webhook/<token> \
  -H 'Content-Type: application/json' \
  -d '{"event_id":"manual-test-1"}'
```

Useful commands:

```bash
uv run afk version
uv run afk doctor
uv run afk setup
uv run afk chat --message "Summarize this project"
uv run afk automation list --profile default
uv run afk plugin list
uv run afk mcp list
uv run afk profile show default
uv run afk update
```

## Plugins

AFKBOT supports installable embedded plugins that extend the local platform with:

- API routers
- static web apps
- tool factories
- skill directories
- app registrars
- optional startup and shutdown hooks

Current curated plugins:

- `afkbotui`: unified AFKBOT web workspace for automations today and future operator surfaces

Typical operator flow:

```bash
uv run afk plugin list
uv run afk plugin install
uv run afk plugin inspect afkbotui
uv run afk plugin config-get afkbotui
uv run afk plugin update afkbotui
```

`afk plugin install` now works as a small wizard:

- it shows curated plugins that are not installed yet
- today the curated list contains only `afkbotui`
- the last option is a custom GitHub source, where you can paste a GitHub URL or `github:owner/repo@ref`

You can still install directly without the wizard:

```bash
uv run afk plugin install github:afkbot-io/afkbotuiplugin@main
```

Direct `afk plugin install <source>` also still accepts a local path when you want to install a plugin from a checkout on disk.

The current curated external plugin is AFKBOT UI. Today it provides the web workspace for automations and is intended to expand into the main operator surface for Task Flow, subagents, MCP, AI settings, and profile management. The older kanban-specific example is no longer the curated plugin path. After installation and `afk start`, it mounts:

- API: `/v1/plugins/afkbotui/...`
- UI: `/plugins/afkbotui`

Plugin install state lives under the AFKBOT runtime root in `/plugins/...` and is treated as local machine state, not repository content.

## Channels Quickstart

AFKBOT can attach chat transports to a profile for inbound routing and operator workflows.
Use the docs site for the full command reference; the examples below cover the common setup paths.

Telegram bot polling channel:

```bash
# guided wizard; omit channel_id to let AFKBOT suggest one
afk channel telegram add

# fully explicit example
afk channel telegram add support-bot --profile default --credential-profile support-bot
afk channel telegram status
afk channel telegram show support-bot
```

Telethon user-account channel:

```bash
# guided wizard; omit channel_id to let AFKBOT suggest one
afk channel telethon add

# fully explicit example
afk channel telethon add personal-user --profile default --credential-profile personal-user
afk channel telethon status --probe
afk channel telethon show personal-user
```

Notes:

- Interactive channel setup explains required credentials inline: Telegram bot token comes from `@BotFather`; Telethon `api_id` and `api_hash` come from `my.telegram.org`.
- If you skip the Telethon session string during setup, finish login later with `afk channel telethon authorize <channel_id>`.
- Interactive prompt language follows this order: explicit `--lang` or `--ru`, then the project's saved `prompt_language`, then the current system locale.

## MCP Quickstart

AFKBOT supports profile-local MCP configuration plus runtime MCP tool discovery.

Manual CLI flow:

```bash
# connect one MCP endpoint URL to the default profile
afk mcp connect https://example.com/mcp --profile default --secret-ref mcp_example_token

# inspect the saved config
afk mcp get example --profile default

# validate effective MCP files for the profile
afk mcp validate --profile default

# list all saved MCP servers, including disabled entries
afk mcp list --profile default --show-disabled
```

You can still use the explicit form:

```bash
afk mcp add --profile default --url https://example.com/mcp --secret-ref mcp_example_token
```

Chat-driven flow:

```text
Connect this MCP endpoint to my default profile: https://example.com/mcp
Show me what was saved and validate it.
```

Notes:

- Use the actual MCP endpoint URL, not a generic product homepage.
- `afk mcp` and `mcp.profile.*` manage profile config.
- `mcp.tools.list` and `mcp.tools.call` are the runtime bridge used after a compatible remote MCP server is configured and exposed.
- If the MCP server needs auth, store only refs in MCP config such as `secret_refs` or `env_refs`; do not hardcode plaintext secrets into MCP JSON.

Managed-install maintenance:

```bash
afk update
bash scripts/uninstall.sh --yes
```

```powershell
afk update
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1 -Yes
```

Hosted installers use `uv tool install` under the hood. Advanced equivalents:

```bash
uv tool install --python 3.12 --reinstall https://github.com/afkbot-io/afkbotio/archive/main.tar.gz
afk update
uv tool uninstall afkbotio
```

## Configuration

- Environment-based configuration examples live in [`.env.example`](https://github.com/afkbot-io/afkbotio/blob/main/.env.example).
- Setup/provider selection supports OpenRouter, OpenAI, Claude, Moonshot (Kimi), DeepSeek, xAI, Qwen, and custom OpenAI-compatible endpoints.
- Runtime secrets should be configured through `afk setup`, `afk profile`, or credential commands, not committed into the repository.
- Manual source setups use a local SQLite database and a local AFKBOT runtime.
- New installs create the current SQLite schema directly; no legacy migration chain is required.
- Full setup guidance and user documentation are published at [afkbot.io/docs](https://afkbot.io/docs).

## Development

Install the development environment and run the standard checks:

```bash
uv sync --extra dev
uv run ruff check afkbot tests
uv run mypy afkbot tests
uv run pytest -q
```

## PyPI Release

The project builds clean Python distributions and passes `twine check`:

```bash
uv build
uvx twine check dist/*
```

For a safe dry run, upload to TestPyPI first:

```bash
uvx twine upload --repository testpypi dist/*
```

This repository also includes a GitHub Actions publish workflow prepared for trusted publishing:

- `workflow_dispatch`: builds distributions and publishes to `testpypi`
- `push` on `v*` tags: builds distributions, attaches them to the GitHub release, and publishes to `pypi`

Before using the workflow, create matching trusted publishing environments in PyPI:

- `testpypi` for `https://test.pypi.org/p/afkbotio`
- `pypi` for `https://pypi.org/project/afkbotio/`

## License

AFKBOT is distributed under the `Sustainable Use License 1.0`.

- See [`LICENSE`](https://github.com/afkbot-io/afkbotio/blob/main/LICENSE) for the full license text.
- See [`LICENSE_FAQ.md`](https://github.com/afkbot-io/afkbotio/blob/main/LICENSE_FAQ.md) for practical allowed/not-allowed examples.
- See [`COMMERCIAL_LICENSE.md`](https://github.com/afkbot-io/afkbotio/blob/main/COMMERCIAL_LICENSE.md) for commercial-use guidance.
- See [`TRADEMARKS.md`](https://github.com/afkbot-io/afkbotio/blob/main/TRADEMARKS.md) for brand and name usage rules.
