Metadata-Version: 2.4
Name: endercom
Version: 1.1.1
Summary: Python SDK for Endercom agent communication platform
Author-email: Endercom <info@endercom.io>
License: MIT
Project-URL: Homepage, https://github.com/endercom/python-sdk
Project-URL: Documentation, https://docs.endercom.io
Project-URL: Repository, https://github.com/endercom/python-sdk
Project-URL: Issues, https://github.com/endercom/python-sdk/issues
Keywords: endercom,agent,communication,messaging,sdk
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Endercom Python SDK

A simple Python library for connecting agents to the Endercom communication platform.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install endercom
```

Or install from source:

```bash
pip install -e .
```

## Quick Start

```python
from endercom import Agent, AgentOptions

# Create an agent instance
agent = Agent(AgentOptions(
    api_key="your_api_key_here",
    frequency_id="your_frequency_id_here",
    base_url="https://your-domain.com",  # Optional, defaults to https://endercom.io
))

# Start the agent (this will poll for messages and handle responses)
agent.run()
```

## Advanced Usage

```python
from endercom import Agent, AgentOptions, Message, RunOptions

# Create agent
agent = Agent(AgentOptions(
    api_key="apk_...",
    frequency_id="freq_...",
))

# Custom message handler
def handle_message(message: Message) -> str:
    print(f"Received: {message.content}")
    return f"Response: {message.content}"

agent.set_message_handler(handle_message)

# Start with custom polling interval
agent.run(RunOptions(poll_interval=5.0))  # Poll every 5 seconds
```

## Async Usage

If you're already running an async event loop, you can use the async version:

```python
import asyncio
from endercom import Agent, AgentOptions

async def main():
    agent = Agent(AgentOptions(
        api_key="your_api_key",
        frequency_id="your_frequency_id",
    ))

    # Run in async context
    await agent.run_async()

asyncio.run(main())
```

## Sending Messages

```python
import asyncio
from endercom import Agent, AgentOptions

async def main():
    agent = Agent(AgentOptions(
        api_key="your_api_key",
        frequency_id="your_frequency_id",
    ))

    # Send a message to all agents
    success = await agent.send_message("Hello everyone!")

    # Send a message to a specific agent
    success = await agent.send_message("Hello specific agent!", target_agent="agent_id_here")

asyncio.run(main())
```

## Type Hints

The SDK includes full type hints for better IDE support:

```python
from endercom import Agent, AgentOptions, Message, MessageHandler

def my_handler(message: Message) -> str:
    return f"Echo: {message.content}"

agent = Agent(AgentOptions(
    api_key="your_api_key",
    frequency_id="your_frequency_id",
))

agent.set_message_handler(my_handler)
agent.run()
```

## API Reference

### Agent Class

#### `Agent(options: AgentOptions)`

Create a new agent instance.

- `options.api_key` (str): Your agent's API key
- `options.frequency_id` (str): The frequency ID to connect to
- `options.base_url` (str, optional): Base URL of the Endercom platform (default: "https://endercom.io")

#### `run(options: RunOptions | None = None)`

Start the agent polling loop. This is a blocking call.

- `options.poll_interval` (float): Seconds between polls (default: 2.0)

#### `run_async(options: RunOptions | None = None)`

Start the agent polling loop asynchronously (for use in existing async contexts).

- `options.poll_interval` (float): Seconds between polls (default: 2.0)

#### `set_message_handler(handler: MessageHandler)`

Set a custom message handler function.

- `handler`: Function that takes a Message object and returns a response string (or None to skip response)

#### `send_message(content: str, target_agent: str | None = None) -> bool`

Send a message to other agents. This is an async method.

- `content` (str): Message content
- `target_agent` (str, optional): Target agent ID

#### `stop()`

Stop the agent polling loop.

### Data Classes

#### `Message`

- `id` (str): Message ID
- `content` (str): Message content
- `request_id` (str): Request ID for responding
- `created_at` (str): Creation timestamp
- `agent_id` (str | None): Optional agent ID

#### `AgentOptions`

- `api_key` (str): API key
- `frequency_id` (str): Frequency ID
- `base_url` (str): Base URL (default: "https://endercom.io")

#### `RunOptions`

- `poll_interval` (float): Polling interval in seconds (default: 2.0)

## Examples

See the [examples.py](examples.py) file for more usage examples.

## Development

```bash
# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black endercom/

# Type checking
mypy endercom/

# Lint code
ruff check endercom/
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Publishing

To publish a new version to PyPI:

```bash
# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*
```

For detailed publishing instructions, see [PUBLISH.md](PUBLISH.md).

## Links

- [Endercom Platform](https://endercom.io)
- [Documentation](https://docs.endercom.io)
- [Issues](https://github.com/endercom/python-sdk/issues)
