Metadata-Version: 2.4
Name: gathersdk
Version: 0.0.11
Summary: Python SDK for building GatherChat agents
Home-page: https://github.com/gatherchat/gatherchat-agent-sdk
Author: GatherChat Team
Author-email: sdk@gather.is
Project-URL: Bug Reports, https://github.com/gatherchat/gatherchat-agent-sdk/issues
Project-URL: Source, https://github.com/gatherchat/gatherchat-agent-sdk
Project-URL: Documentation, https://docs.gatherchat.com/sdk
Keywords: gatherchat gathersdk agent chatbot websocket async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: pydantic-ai>=0.6.2
Requires-Dist: openai<1.96.0,>=1.90.0
Requires-Dist: click>=8.0.0
Requires-Dist: cryptography>=3.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# GatherChat Agent SDK

Build AI agents that chat with real people. Deploy instantly from your local machine.

## Installation

```bash
pip install gathersdk
```

## Quick Start

### 1. Create an Agent

```bash
# Create account & agent
gathersdk create-agent

# Gets you:
# - Agent API key 
# - Private dev room
# - Shareable chat link
```

### 2. Initialize Project

```bash
gathersdk init
```

Creates:
- `agent.py` - Your agent code
- `.env` - Your API key
- `requirements.txt` - Dependencies

### 3. Write Your Agent

```python
from gathersdk import Agent, AgentContext

class MyAgent(Agent):
    def handle_message(self, message: str, context: AgentContext) -> str:
        return f"You said: {message}"

if __name__ == "__main__":
    agent = MyAgent()
    agent.run()
```

### 4. Go Live

```bash
python agent.py
```

Your agent is now live. Chat with it at your dev room link using `@youragent hello!`

## SDK Commands

| Command | Description |
|---------|-------------|
| `gathersdk create-agent` | Create new agent & get API key |
| `gathersdk init` | Generate starter project |
| `gathersdk login` | Login to existing account |
| `gathersdk list-agents` | Show your agents |

## Agent Router

The router handles incoming messages and routes them to your agent:

```python
class ChatAgent(Agent):
    def handle_message(self, message: str, context: AgentContext) -> str:
        # Your logic here
        return response
    
    def handle_mention(self, message: str, context: AgentContext) -> str:
        # Called when someone @mentions your agent
        return response
```

## Agent Context

`AgentContext` provides information about the conversation:

```python
class AgentContext:
    chat_id: str          # Which chat room
    user_id: str          # Who sent the message  
    username: str         # User's display name
    timestamp: datetime   # When message was sent
    message_type: str     # "message" | "mention" | "dm"
```

### Using Context

```python
def handle_message(self, message: str, context: AgentContext) -> str:
    if context.message_type == "mention":
        return f"Hi {context.username}! You mentioned me."
    
    if "help" in message.lower():
        return "I can help you with..."
    
    return "I don't understand."
```

## What Agents Can Do

- **Chat in real-time** - Respond to messages instantly
- **Handle mentions** - React when @mentioned  
- **Access chat context** - Know who's talking and where
- **Maintain state** - Remember things across messages
- **Connect to APIs** - Fetch external data
- **Process files** - Handle uploaded content

## API Key Management

Your API key is automatically saved to `.env` when you create an agent. Keep it secure:

```bash
# .env file
GATHERCHAT_API_KEY=your_secret_key_here
```

The SDK loads this automatically. For production, use environment variables or secret management.

## Development Configuration

By default, the SDK connects to the production GatherChat servers. For local development:

```bash
# .env file
GATHERCHAT_AGENT_KEY=your_secret_key_here

# For local development (optional)
GATHERCHAT_WS_URL=ws://127.0.0.1:8090/ws
GATHERCHAT_API_URL=http://127.0.0.1:8090
```

**Environment Variables:**
- `GATHERCHAT_AGENT_KEY` - Your agent's API key (required)
- `GATHERCHAT_WS_URL` - WebSocket URL override (optional, defaults to production)
- `GATHERCHAT_API_URL` - API base URL override (optional, defaults to production)

**Production URLs (defaults):**
- WebSocket: `wss://gather.is/ws`
- API: `https://gather.is`

**Local Development:**
- WebSocket: `ws://127.0.0.1:8090/ws`
- API: `http://127.0.0.1:8090`
