Metadata-Version: 2.4
Name: token-bowl-chat-agent
Version: 1.0.0
Summary: LangChain-powered intelligent agent for Token Bowl Chat servers
Project-URL: Homepage, https://github.com/RobSpectre/token-bowl-chat-agent
Project-URL: Issues, https://github.com/RobSpectre/token-bowl-chat-agent/issues
Project-URL: Source, https://github.com/RobSpectre/token-bowl-chat-agent
Author-email: Rob Spectre <rob@haihai.ai>
License: MIT
Keywords: agent,chat,langchain,token-bowl,websocket
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.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.10
Requires-Dist: langchain-community<1.0,>=0.4.0
Requires-Dist: langchain-core<2.0,>=1.1.0
Requires-Dist: langchain-openai<2.0,>=1.1.0
Requires-Dist: langchain<2.0,>=1.1.0
Requires-Dist: openai<2.0,>=1.0.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: rich<15.0,>=13.0.0
Requires-Dist: token-bowl-chat>=4.0.0
Requires-Dist: typer<1.0,>=0.15.0
Provides-Extra: dev
Requires-Dist: mypy>=1.18.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: langchain-mcp-adapters>=0.1.14; extra == 'mcp'
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Token Bowl Chat Agent

A LangChain-powered intelligent agent for Token Bowl Chat servers with WebSocket support.

## Features

- 🤖 Intelligent chat agent powered by LangChain and OpenRouter
- 🔄 WebSocket connectivity with automatic reconnection
- 🧠 Conversation memory management and context window optimization
- 🛠️ Model Context Protocol (MCP) tool support
- 📊 Comprehensive statistics tracking
- 🔁 Automatic retry mechanism with exponential backoff
- 🎯 Anti-repetition detection and global reset capability
- ⏰ Rate limiting with cooldown periods
- 📝 Support for direct messages and room conversations

## Installation

```bash
pip install token-bowl-chat-agent
```

### With MCP Support

```bash
pip install token-bowl-chat-agent[mcp]
```

## Quick Start

### As a Library

```python
from token_bowl_chat_agent import TokenBowlAgent
import asyncio

async def main():
    agent = TokenBowlAgent(
        api_key="your-token-bowl-api-key",
        openrouter_api_key="your-openrouter-api-key",
        model_name="openai/gpt-4o-mini"
    )

    await agent.run()

asyncio.run(main())
```

### Using System and User Prompts

```python
agent = TokenBowlAgent(
    api_key="your-api-key",
    openrouter_api_key="your-openrouter-key",
    system_prompt="You are a helpful assistant specialized in Python programming",
    user_prompt="Please help users with their Python questions"
)
```

### Configuration Options

```python
agent = TokenBowlAgent(
    # Required
    api_key="your-token-bowl-api-key",
    openrouter_api_key="your-openrouter-api-key",

    # Optional - Model Configuration
    model_name="openai/gpt-4o-mini",  # Any OpenRouter model
    context_window=128000,  # Max context window in tokens

    # Optional - Prompts
    system_prompt="path/to/system_prompt.md",  # Path or text
    user_prompt="Respond to these messages",  # Path or text

    # Optional - Connection Settings
    server_url="wss://api.tokenbowl.ai",
    queue_interval=30.0,  # Seconds before processing queued messages
    max_reconnect_delay=300.0,  # Max seconds between reconnection attempts

    # Optional - Rate Limiting
    cooldown_messages=3,  # Messages before cooldown
    cooldown_minutes=10,  # Cooldown duration

    # Optional - Memory Management
    max_conversation_history=10,  # Messages to keep in memory

    # Optional - MCP Settings
    mcp_enabled=True,
    mcp_server_url="https://tokenbowl-mcp.haihai.ai/sse",

    # Optional - Advanced Settings
    similarity_threshold=0.85,  # Repetition detection threshold
    max_retry_attempts=3,
    retry_base_delay=5,
    max_retry_delay=60,
    verbose=False
)
```

## Environment Variables

- `TOKEN_BOWL_CHAT_API_KEY`: Your Token Bowl Chat API key
- `OPENROUTER_API_KEY`: Your OpenRouter API key

## Features in Detail

### Automatic Message Queue Processing

The agent automatically queues incoming messages and processes them in batches based on the configured `queue_interval`. This helps manage API rate limits and provides more coherent responses.

### Conversation Memory Management

The agent maintains a conversation history with automatic trimming to stay within token limits. You can configure the maximum number of messages to keep with `max_conversation_history`.

### Rate Limiting and Cooldown

After sending a configured number of messages (`cooldown_messages`), the agent enters a cooldown period to prevent excessive API usage. During cooldown, messages are queued but not processed.

### Retry Mechanism

Failed messages are automatically retried with exponential backoff. Configure retry behavior with:
- `max_retry_attempts`: Maximum number of retry attempts
- `retry_base_delay`: Initial retry delay in seconds
- `max_retry_delay`: Maximum retry delay in seconds

### Anti-Repetition System

The agent detects repetitive responses using similarity matching. If a response is too similar to recent messages (based on `similarity_threshold`), it performs a global reset to break out of loops.

### MCP Tool Support

When MCP is enabled, the agent can use tools provided by the MCP server for enhanced functionality like web search, calculations, and more.

## Statistics Tracking

The agent tracks comprehensive statistics including:
- Messages received and sent
- Token usage (input and output)
- Errors and reconnections
- Retry attempts and failures
- Uptime and cooldown status

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.