Metadata-Version: 2.4
Name: turborg
Version: 0.7.0
Summary: An open-source modular AI agent framework. Plug in IRC, Discord, Telegram, web — power it with Claude or any LLM.
Project-URL: Homepage, https://github.com/turborg/turborg
Project-URL: Repository, https://github.com/turborg/turborg
Project-URL: Issues, https://github.com/turborg/turborg/issues
Project-URL: Changelog, https://github.com/turborg/turborg/blob/main/CHANGELOG.md
Author-email: The turborg Authors <hello@xshellz.com>
Maintainer-email: xshellz <hello@xshellz.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,anthropic,chatbot,claude,discord,framework,irc,llm,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.40
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'all'
Requires-Dist: websockets>=13; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-randomly>=3.15; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Provides-Extra: web
Requires-Dist: fastapi>=0.115; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'web'
Requires-Dist: websockets>=13; extra == 'web'
Description-Content-Type: text/markdown

# turborg

**A Python framework for chat-network agents — an IRC bouncer + browser UI + bot orchestrator in one process. Optional LLM hookup for AI features.**

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/turborg/turborg/actions/workflows/ci.yml/badge.svg)](https://github.com/turborg/turborg/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A595%25-brightgreen.svg)](#testing)

```python
from turborg.core import Agent, OutboundEnvelope
from turborg.connectors.irc import IRCConnector, IRCSettings

agent = Agent()
agent.add_connector(IRCConnector(IRCSettings(hostname="irc.libera.chat", nick="myturborg")))

@agent.on_command("ping")
async def ping(envelope):
    return OutboundEnvelope.reply(envelope, "pong")

agent.run()
```

That's a working IRC bot — no LLM required. Add a `WebGateway` and a `Bouncer` and you've also got a browser-side IRC client and a HexChat/irssi tunnel through the same process.

---

## What turborg gives you

- **A real IRC connector**, not a toy — TLS, SASL PLAIN, NickServ identify, IRCv3 `server-time`, full WHOIS / NAMES / MODE handling, and tracking of every channel you're in. See [docs/connectors/irc.md](docs/connectors/irc.md).
- **A built-in IRC bouncer.** Local clients (HexChat, irssi, mIRC) connect to the bot's loopback port, authenticate with a password, and tunnel through the bot's upstream session. The bot stays in control while a human can lurk and chat from their own client.
- **A WebSocket gateway + reference web UI.** A vanilla-JS single-page client at `/` with channel sidebar, member list, slash commands, autocomplete, IndexedDB-backed per-channel scrollback that survives reloads, browser notifications, and clear UX for kicks/bans. SaaS deployments can swap in their own polished UI; the protocol is documented and stable.
- **A normalized `Envelope`** so the same handler that runs on IRC will also run on Discord / Telegram / Web when those connectors land.
- **Optional LLM**, not the centerpiece. If you set an API key, `!ask` is wired in. If you don't, the rest of the bot doesn't care.

The design separates **how the bot talks to a network** (the connector) from **how it thinks** (any LLM, or none) from **what it does** (your handlers).

For the long-term vision — **hive.xshellz.com**, a shared-intelligence cloud any turborg instance can attach to — see [docs/hive.md](docs/hive.md).

## Status

**v0.6.0** — alpha. The IRC connector, the bouncer, and the WebSocket gateway with reference UI are production-grade and well-tested (≥95% coverage gate enforced in CI). Other connectors are roadmap.

| Connector  | Status     | Install                                |
|------------|------------|----------------------------------------|
| IRC        | Stable     | `pip install turborg`                  |
| Web        | Stable     | `pip install turborg[web]`             |
| Discord    | Roadmap    | `pip install turborg[discord]` (TBD)   |
| Telegram   | Roadmap    | `pip install turborg[telegram]` (TBD)  |
| WhatsApp   | Roadmap    | `pip install turborg[whatsapp]` (TBD)  |

LLM providers are **optional**. turborg runs perfectly fine as a pure command-driven bot without any LLM. When you do want one, both Anthropic (default, with prompt caching) and OpenAI ship as extras — see [docs/llm-providers.md](docs/llm-providers.md).

## Install

```bash
pip install turborg          # or: uv add turborg
pip install turborg[web]     # if you want the WebSocket gateway / reference UI
```

Configure via environment variables (everything is `TURBORG_*`-prefixed) or a `.env` file. The most common minimum:

```bash
TURBORG_IRC_HOSTNAME=irc.libera.chat
TURBORG_IRC_NICK=myturborg
TURBORG_IRC_CHANNELS='["#turborg-test"]'
```

See [docs/configuration.md](docs/configuration.md) for the full list — including SASL, NickServ identify, the bouncer, the web gateway, idle-shutdown, rate limits, logging.

## Quickstart

The full 5-minute tutorial is at [docs/quickstart.md](docs/quickstart.md). The 30-second version:

```bash
pip install turborg
export TURBORG_IRC_HOSTNAME=irc.libera.chat
export TURBORG_IRC_NICK=myturborg
export TURBORG_IRC_CHANNELS='["#turborg-test"]'
turborg run
```

You're online. To enable the AI command, also set `TURBORG_ANTHROPIC_API_KEY` (or use the OpenAI extra). To attach HexChat through the built-in bouncer, set `TURBORG_IRC_BOUNCER_PASSWORD`. To open the reference web UI at `http://127.0.0.1:8765/`, set `TURBORG_WEB_PASSWORD`. Each is independent — pick what you need.

## Run with Docker

```bash
cp .env.example .env       # fill in TURBORG_IRC_* (and optionally LLM / web / bouncer)
docker compose up
```

Or without compose:

```bash
docker run --env-file .env turborg/turborg:latest
```

Mount your own bot script with `-v "$PWD/mybot.py:/app/mybot.py"`. The image is multi-stage, ~150 MB, and runs as a non-root user.

## Documentation

- [Quickstart](docs/quickstart.md) — get a bot online in 5 minutes
- [Architecture](docs/architecture.md) — the agent / connector / LLM / Envelope model
- [IRC connector](docs/connectors/irc.md) — bouncer, SASL, web gateway, channel state, and every IRC-specific design decision
- [Configuration](docs/configuration.md) — every environment variable, every default
- [LLM providers (optional)](docs/llm-providers.md) — Anthropic (default), OpenAI, custom
- [Writing a connector](docs/writing-a-connector.md) — add Discord, Telegram, your own
- [Hive](docs/hive.md) — the future shared-intelligence cloud

## Examples

- [`examples/minimal_irc_bot.py`](examples/minimal_irc_bot.py) — the smallest possible bot (`!ping` → `pong`), no LLM
- [`examples/claude_powered_irc.py`](examples/claude_powered_irc.py) — `!ask <question>` proxies to Claude

## Project layout

```
turborg/
├── src/turborg/
│   ├── core/          Agent, envelope, event bus, command registry
│   ├── connectors/    Connector ABC + per-protocol implementations
│   │   └── irc/       IRC connector + bouncer + protocol parser
│   ├── web/           WebSocket gateway + reference HTML/JS UI
│   ├── llm/           LLM provider ABC + Anthropic / OpenAI adapters
│   ├── hive/          Hive client extension hook (noop default)
│   ├── config/        pydantic-settings config
│   └── cli.py         turborg CLI entry point
├── tests/             unit + integration suites (≥95% coverage gate)
├── examples/          runnable example bots
└── docs/              full documentation
```

## Testing

```bash
uv sync --extra dev
uv run pytest                                    # tests + coverage gate
uv run ruff check . && uv run ruff format --check .
uv run mypy src/turborg                          # strict mode
```

CI runs the same four gates and enforces ≥95% branch coverage.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, branching strategy, and PR rules. By submitting a contribution you agree to the [Contributor License Agreement](CLA.md) — the cla-assistant bot will guide you on first PR.

## License

[Apache License 2.0](LICENSE) — see [TRADEMARKS.md](TRADEMARKS.md) for the trademark policy on the names "turborg" and "xshellz".

## Security

Found a vulnerability? Please **do not** open a public issue. See [SECURITY.md](SECURITY.md) for the responsible-disclosure process.

## Style

- Conventional Commits for PR titles (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`)
- Squash-merge to `main`; linear history
- 100-char line limit, ruff-formatted, mypy-strict
- pytest with branch coverage; **fail under 95%**

---

*Part of the [**xshellz**](https://www.xshellz.com) ecosystem. The future hosted hive lives at [hive.xshellz.com](https://hive.xshellz.com).*
