# Mothership - Python Edition

A minimalist framework for building Telegram bots rapidly with clean abstractions and zero boilerplate.

## Features

- **Simple Bot Definition**: Define bots with minimal code
- **Storage Abstraction**: Automatic fallback between Firestore and in-memory storage
- **Flexible Deployment**: Support for local (polling), webhooks, and serverless platforms
- **Type-Safe**: Full type hints support
- **Structured Logging**: Built-in colored, leveled logging
- **Firebase Integration**: Optional Firestore persistence

## Installation

```bash
# Using uv (recommended)
uv pip install mothership-bot

# Or using pip
pip install mothership-bot
```

## Quick Start

### 1. Create a bot file (bot.py)

```python
from mothership import BotDefinition, Update, ContextTypes, create_logger

logger = create_logger('my-bot')

async def handle_start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('Hello! I am your bot.')

bot: BotDefinition = {
    'config': {
        'name': 'my-bot',
        'description': 'My awesome bot'
    },
    'commands': [
        {
            'command': 'start',
            'description': 'Start the bot',
            'handler': handle_start
        }
    ]
}
```

### 2. Set your bot token

```bash
export BOT_TOKEN=your_token_here
```

### 3. Run your bot

```bash
# Using the CLI
mothership run bot.py

# Or using Python directly
python -c "from mothership.cli import run_bot; import asyncio; asyncio.run(run_bot('bot.py'))"
```

## CLI Usage

The `mothership` CLI provides an easy way to run and manage your bots:

```bash
# Run a bot from a file
mothership run bot.py

# Run a bot from bots directory (looks for bots/ping_bot/__init__.py)
mothership run ping_bot

# Run on a custom port
mothership run ping_bot --port 8080

# List available bots in bots/ directory
mothership list

# Get help
mothership --help
```

## Requirements

- Python >= 3.8
- Telegram Bot Token (from @BotFather)

## Environment Variables

- `BOT_TOKEN` - Required: Telegram bot token
- `FIREBASE_PROJECT_ID` - Optional: Enable persistent storage
- `LOG_LEVEL` - Optional: Logging level (debug|info|warn|error)

## Documentation

See the main Mothership repository for full documentation.
