Metadata-Version: 2.4
Name: talocode-botlane
Version: 0.1.0
Summary: Telegram bridge for Grok/xAI-powered bots — run a Grok bot from Telegram with session memory, groups, and an allowlist
Project-URL: Homepage, https://github.com/talocode/botlane
Project-URL: Documentation, https://docs.talocode.site
Project-URL: Repository, https://github.com/talocode/botlane
Project-URL: Issues, https://github.com/talocode/botlane/issues
Author: Talocode
License-Expression: MIT
Keywords: agent,bot,bridge,chat,cli,grok,mcp,sdk,talocode,telegram,xai
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# BotLane

**Run a Grok-powered bot from Telegram.**

[![PyPI version](https://badge.fury.io/py/talocode-botlane.svg)](https://pypi.org/project/talocode-botlane/)
[![npm version](https://img.shields.io/npm/v/@talocode/botlane)](https://www.npmjs.com/package/@talocode/botlane)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Open-source bridge that connects a Grok (xAI) bot to Telegram and lets you
drive it straight from chat — one-to-one, in groups, or with scheduled tasks.
No server to babysit, no webhooks to configure.

## Why it exists

People who run agent bots on X want to reach them from Telegram too — the same
bot, the same memory, no extra setup. BotLane is that bridge:

- **Dependency-free** — the Python SDK and local bridge use only the standard
  library. No pip installs beyond `talocode-botlane`.
- **1:1 and group mode** — private chats work out of the box; in groups the
  bot responds only to `@mention`, `/commands`, and replies.
- **Session memory** — per-chat conversation history persisted to disk.
- **Secure by default** — an allowlist gates who can talk to the bot so your
  credits don't get drained by strangers.
- **Hosted path available** — use the open tool locally, or run it on Talocode
  Cloud under `/v1/botlane/*` for managed power.

Part of [Talocode](https://talocode.site): open tools people trust, hosted
power behind them.

## Install

```bash
pip install talocode-botlane
```

Node version (CLI, SDK, MCP server, HTTP API):

```bash
npm install -g @talocode/botlane
```

## Quickstart

### Talk to a hosted BotLane instance

```python
from botlane import BotLaneClient

client = BotLaneClient()          # uses TALOCODE_API_KEY + TALOCODE_BASE_URL
print(client.health())
client.send(chat_id=123456789, text="Hello from the bot")
reply = client.chat("Summarize the last 3 messages")
print(reply)
```

### Run a local bridge from Python

```python
from botlane import BotLaneBridge

bridge = BotLaneBridge()          # uses TELEGRAM_BOT_TOKEN + XAI_API_KEY
bridge.run()                      # long-polls Telegram and replies with Grok
```

## Auth / env

The Python SDK reads the same environment the hosted path uses:

| Env var | Default | Purpose |
|---------|---------|---------|
| `TALOCODE_API_KEY` | — | API key for hosted/self-hosted BotLane API. |
| `TALOCODE_BASE_URL` | `https://api.talocode.site` | Hosted API base URL. |
| `TELEGRAM_BOT_TOKEN` | — | Required for the local bridge. Bot token from @BotFather. |
| `XAI_API_KEY` | — | Required for the local bridge. xAI (Grok) key. |
| `BOTLANE_MODEL` | `grok-3-mini` | Model used for completions. |

## API surface

### Hosted routes (Talocode Cloud)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/botlane/health` | Liveness + config summary. |
| POST | `/v1/botlane/chat` | One-off Grok completion. |
| POST | `/v1/botlane/send` | Send a message from the bot. |
| GET | `/v1/botlane/history` | Per-chat conversation history. |
| POST | `/v1/botlane/reset` | Clear a chat's history. |

Auth:

```
Authorization: Bearer $TALOCODE_API_KEY
# or
X-Api-Key: $TALOCODE_API_KEY
```

### SDK methods

| Method | Description |
|--------|-------------|
| `BotLaneClient.health()` | Check instance health. |
| `BotLaneClient.chat(prompt, ...)` | One-off Grok completion. |
| `BotLaneClient.send(chat_id, text)` | Send a message from the bot. |
| `BotLaneClient.history(chat_id)` | Read per-chat history. |
| `BotLaneClient.reset(chat_id)` | Clear a chat's history. |
| `BotLaneBridge.run()` | Start the local long-polling bridge. |

## CLI

```bash
botlane check                          # validate config, print bot identity
botlane run --model grok-3-mini        # start the local bridge
botlane send 123456789 "Hello"         # one-off message from the bot
botlane chat "What is 2+2?"            # one-off completion via hosted API
botlane health                         # check a hosted instance
```

## MCP server

The npm package ships a dependency-free [Model Context Protocol](https://modelcontextprotocol.io)
server (`botlane-mcp`) so agent runtimes (Cursor, Claude Code, OpenCode,
Codra) can drive the bot directly. Tools: `botlane_check`, `botlane_send`,
`botlane_history`, `botlane_reset`, `botlane_chat`.

## Develop

```bash
git clone https://github.com/talocode/botlane
cd botlane/python
pip install -e .
python -m botlane.cli check
```

## Related packages

| Package | Install |
|---------|---------|
| BotLane (this package) | `pip install talocode-botlane` |
| Tera | `pip install talocode-tera` |
| Codra | `pip install talocode-codra` |
| SearchLane | `pip install talocode-searchlane` |
| StackLane | `pip install talocode` |
| ContextLane | `pip install contextlane` |
| ScreenLane | `pip install talocode-screenlane` |
| Tradia | `pip install tradia` |
| DevTool | `pip install talocode-devtool` |
| XProLane | `pip install talocode-xprolane` |

## Talocode ecosystem

| Product | Repo | Notes |
|---------|------|-------|
| [BotLane](https://github.com/talocode/botlane) | `talocode/botlane` | **(this package)** Telegram bridge for Grok bots |
| [Tera](https://github.com/talocode/tera) | `talocode/tera` | Hosted writing/coding capability API |
| [Codra](https://github.com/talocode/codra) | `talocode/codra` | Coding agent runtime |
| [SearchLane](https://github.com/talocode/searchlane) | `talocode/searchlane` | Agent web search & research |
| [StackLane](https://github.com/talocode/stacklane) | `talocode/stacklane` | Cloud control plane, keys, wallet |
| [GateLane](https://github.com/talocode/gatelane) | `talocode/gatelane` | Policy / gate tooling |
| [ContextLane](https://github.com/talocode/contextlane) | `talocode/contextlane` | Context infrastructure |
| [ScreenLane](https://github.com/talocode/screenlane) | `talocode/screenlane` | Screen/agent UI tooling |
| [MemoryLane](https://github.com/talocode/memorylane) | `talocode/memorylane` | Memory for agents |
| [Tradia](https://github.com/talocode/tradia) | `talocode/tradia` | Trading tooling |
| [DevTool](https://github.com/talocode/devtool) | `talocode/devtool` | Developer utilities |
| [XProLane](https://github.com/talocode/xprolane) | `talocode/xprolane` | X Pro setup & signal dashboard |
| [XSearchLane](https://github.com/talocode/xsearchlane) | `talocode/xsearchlane` | Realtime X search MCP/API |
| [Agent Browser](https://github.com/talocode/agent-browser) | `talocode/agent-browser` | Browser automation API |
| [InvoiceLane](https://github.com/talocode/invoicelane) | `talocode/invoicelane` | Invoicing |
| [GeoLane](https://github.com/talocode/geolane) | `talocode/geolane` | Geo visibility |
| [ClipLoop](https://github.com/talocode/cliploop) | `talocode/cliploop` | Short-form video loop |

More: [github.com/talocode](https://github.com/talocode) · [talocode.site](https://talocode.site) · [docs.talocode.site](https://docs.talocode.site)

## Links

- GitHub: https://github.com/talocode/botlane
- npm: https://www.npmjs.com/package/@talocode/botlane
- PyPI: https://pypi.org/project/talocode-botlane
- Docs: https://docs.talocode.site
- API base: `https://api.talocode.site`

## License

MIT © Talocode
