Metadata-Version: 2.4
Name: shannon-sdk
Version: 0.1.0a1
Summary: Python SDK for Shannon multi-agent AI platform
Author-email: Shannon Team <dev@ptmind.com>
License: MIT
Project-URL: Homepage, https://github.com/Kocoro-lab/Shannon
Project-URL: Documentation, https://github.com/Kocoro-lab/Shannon/blob/main/clients/python/README.md
Project-URL: Repository, https://github.com/Kocoro-lab/Shannon
Project-URL: Issues, https://github.com/Kocoro-lab/Shannon/issues
Keywords: ai,agents,llm,orchestration,multi-agent,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: grpcio>=1.60.0
Requires-Dist: protobuf>=4.25.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.60.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# Shannon Python SDK

Python client for Shannon multi-agent AI platform.

## Installation

```bash
# Development installation (from this directory)
pip install -e .

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

## Quick Start

```python
from shannon import ShannonClient

# Initialize client
client = ShannonClient(
    grpc_endpoint="localhost:50052",
    http_endpoint="http://localhost:8081",
    api_key="your-api-key"  # or use bearer_token
)

# Submit a task
handle = client.submit_task(
    "Analyze market trends for Q4 2024",
    session_id="my-session",
    user_id="alice"
)

print(f"Task submitted: {handle.task_id}")
print(f"Workflow ID: {handle.workflow_id}")

# Get status
status = client.get_status(handle.task_id)
print(f"Status: {status.status}")
print(f"Progress: {status.progress:.1%}")

# Cancel if needed
# client.cancel(handle.task_id, reason="User requested")

client.close()
```

## Async Usage

```python
import asyncio
from shannon import AsyncShannonClient

async def main():
    async with AsyncShannonClient(
        grpc_endpoint="localhost:50052",
        api_key="your-api-key"
    ) as client:
        # Submit task
        handle = await client.submit_task(
            "What is 2+2?",
            user_id="test-user"
        )

        # Poll for completion
        while True:
            status = await client.get_status(handle.task_id)
            if status.status in ["COMPLETED", "FAILED", "CANCELLED"]:
                break
            await asyncio.sleep(1)

        print(f"Result: {status.result}")

asyncio.run(main())
```

## Features

- ✅ Task submission with metadata and context
- ✅ Task status polling with detailed metrics
- ✅ Task cancellation
- ✅ Async-first design with sync wrapper
- ✅ Session management (multi-turn conversations)
- ✅ Template support
- ⏳ Event streaming (gRPC + SSE fallback)
- ⏳ Approval handling
- ⏳ CLI tool

## Development

```bash
# Generate proto stubs
make proto

# Run tests
make test

# Lint
make lint

# Format
make format
```

## Project Structure

```
clients/python/
├── src/shannon/
│   ├── __init__.py      # Public API
│   ├── client.py        # AsyncShannonClient, ShannonClient
│   ├── models.py        # Data models (TaskHandle, TaskStatus, Event, etc.)
│   ├── errors.py        # Exception hierarchy
│   └── generated/       # Generated proto stubs
├── tests/               # Integration tests
├── examples/            # Usage examples
└── pyproject.toml       # Package metadata
```

## License

MIT
