# Shannon Python SDK
Python client for Shannon multi-agent AI platform.
**Version:** 0.1.0a2 (Alpha)
## 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
- ✅ Event streaming (gRPC + SSE fallback with auto-reconnect)
- ✅ Approval workflows (approve, get_pending_approvals)
- ✅ Session management (7 RPCs for multi-turn conversations)
- ✅ Template support (pass template names to server)
- ✅ Workflow routing via custom labels
- ✅ CLI tool (13 commands: submit, status, stream, approve, sessions, etc.)
- ✅ Async-first design with sync wrapper
- ✅ Type-safe enums (EventType, TaskStatusEnum)
- ✅ Comprehensive error handling
## Examples
The SDK includes comprehensive examples demonstrating key features:
- **`simple_task.py`** - Basic task submission and status polling
- **`simple_streaming.py`** - Event streaming with filtering
- **`streaming_with_approvals.py`** - Approval workflow handling
- **`workflow_routing.py`** - Using labels for workflow routing and task categorization
- **`session_continuity.py`** - Multi-turn conversations with session management
- **`template_usage.py`** - Template-based task execution with versioning
Run any example:
```bash
cd clients/python
python examples/simple_task.py
```
## 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
Raw data
{
"_id": null,
"home_page": null,
"name": "shannon-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, agents, llm, orchestration, multi-agent, workflow",
"author": null,
"author_email": "Shannon Team <dev@ptmind.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/72/1a82e28d180d34b0c2a25d57ef95f5085c9b02b1209ceaf83f613c9bf93f/shannon_sdk-0.1.0a2.tar.gz",
"platform": null,
"description": "# Shannon Python SDK\n\nPython client for Shannon multi-agent AI platform.\n\n**Version:** 0.1.0a2 (Alpha)\n\n## Installation\n\n```bash\n# Development installation (from this directory)\npip install -e .\n\n# With dev dependencies\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n```python\nfrom shannon import ShannonClient\n\n# Initialize client\nclient = ShannonClient(\n grpc_endpoint=\"localhost:50052\",\n http_endpoint=\"http://localhost:8081\",\n api_key=\"your-api-key\" # or use bearer_token\n)\n\n# Submit a task\nhandle = client.submit_task(\n \"Analyze market trends for Q4 2024\",\n session_id=\"my-session\",\n user_id=\"alice\"\n)\n\nprint(f\"Task submitted: {handle.task_id}\")\nprint(f\"Workflow ID: {handle.workflow_id}\")\n\n# Get status\nstatus = client.get_status(handle.task_id)\nprint(f\"Status: {status.status}\")\nprint(f\"Progress: {status.progress:.1%}\")\n\n# Cancel if needed\n# client.cancel(handle.task_id, reason=\"User requested\")\n\nclient.close()\n```\n\n## Async Usage\n\n```python\nimport asyncio\nfrom shannon import AsyncShannonClient\n\nasync def main():\n async with AsyncShannonClient(\n grpc_endpoint=\"localhost:50052\",\n api_key=\"your-api-key\"\n ) as client:\n # Submit task\n handle = await client.submit_task(\n \"What is 2+2?\",\n user_id=\"test-user\"\n )\n\n # Poll for completion\n while True:\n status = await client.get_status(handle.task_id)\n if status.status in [\"COMPLETED\", \"FAILED\", \"CANCELLED\"]:\n break\n await asyncio.sleep(1)\n\n print(f\"Result: {status.result}\")\n\nasyncio.run(main())\n```\n\n## Features\n\n- \u2705 Task submission with metadata and context\n- \u2705 Task status polling with detailed metrics\n- \u2705 Task cancellation\n- \u2705 Event streaming (gRPC + SSE fallback with auto-reconnect)\n- \u2705 Approval workflows (approve, get_pending_approvals)\n- \u2705 Session management (7 RPCs for multi-turn conversations)\n- \u2705 Template support (pass template names to server)\n- \u2705 Workflow routing via custom labels\n- \u2705 CLI tool (13 commands: submit, status, stream, approve, sessions, etc.)\n- \u2705 Async-first design with sync wrapper\n- \u2705 Type-safe enums (EventType, TaskStatusEnum)\n- \u2705 Comprehensive error handling\n\n## Examples\n\nThe SDK includes comprehensive examples demonstrating key features:\n\n- **`simple_task.py`** - Basic task submission and status polling\n- **`simple_streaming.py`** - Event streaming with filtering\n- **`streaming_with_approvals.py`** - Approval workflow handling\n- **`workflow_routing.py`** - Using labels for workflow routing and task categorization\n- **`session_continuity.py`** - Multi-turn conversations with session management\n- **`template_usage.py`** - Template-based task execution with versioning\n\nRun any example:\n```bash\ncd clients/python\npython examples/simple_task.py\n```\n\n## Development\n\n```bash\n# Generate proto stubs\nmake proto\n\n# Run tests\nmake test\n\n# Lint\nmake lint\n\n# Format\nmake format\n```\n\n## Project Structure\n\n```\nclients/python/\n\u251c\u2500\u2500 src/shannon/\n\u2502 \u251c\u2500\u2500 __init__.py # Public API\n\u2502 \u251c\u2500\u2500 client.py # AsyncShannonClient, ShannonClient\n\u2502 \u251c\u2500\u2500 models.py # Data models (TaskHandle, TaskStatus, Event, etc.)\n\u2502 \u251c\u2500\u2500 errors.py # Exception hierarchy\n\u2502 \u2514\u2500\u2500 generated/ # Generated proto stubs\n\u251c\u2500\u2500 tests/ # Integration tests\n\u251c\u2500\u2500 examples/ # Usage examples\n\u2514\u2500\u2500 pyproject.toml # Package metadata\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Shannon multi-agent AI platform",
"version": "0.1.0a2",
"project_urls": {
"Documentation": "https://github.com/Kocoro-lab/Shannon/blob/main/clients/python/README.md",
"Homepage": "https://github.com/Kocoro-lab/Shannon",
"Issues": "https://github.com/Kocoro-lab/Shannon/issues",
"Repository": "https://github.com/Kocoro-lab/Shannon"
},
"split_keywords": [
"ai",
" agents",
" llm",
" orchestration",
" multi-agent",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a12201cb97f6ba697716383344a74fe8d8c5433d8ec353859fbccd906f62cad",
"md5": "e7a410ad9fe495923f3d4fdd503b5b92",
"sha256": "ff1ea87d77e5e1205a0285252b5d1ff7415fe754b07b02a3eaa37097c5376252"
},
"downloads": -1,
"filename": "shannon_sdk-0.1.0a2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7a410ad9fe495923f3d4fdd503b5b92",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 40383,
"upload_time": "2025-10-07T07:34:25",
"upload_time_iso_8601": "2025-10-07T07:34:25.713796Z",
"url": "https://files.pythonhosted.org/packages/5a/12/201cb97f6ba697716383344a74fe8d8c5433d8ec353859fbccd906f62cad/shannon_sdk-0.1.0a2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d721a82e28d180d34b0c2a25d57ef95f5085c9b02b1209ceaf83f613c9bf93f",
"md5": "b04e209c7d95c41351063d5612200ef4",
"sha256": "771557654acb2e7ecb9cccfbbb63d5655c78239a72fbc0ad1dfe93aa25936b77"
},
"downloads": -1,
"filename": "shannon_sdk-0.1.0a2.tar.gz",
"has_sig": false,
"md5_digest": "b04e209c7d95c41351063d5612200ef4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 34059,
"upload_time": "2025-10-07T07:34:26",
"upload_time_iso_8601": "2025-10-07T07:34:26.916890Z",
"url": "https://files.pythonhosted.org/packages/4d/72/1a82e28d180d34b0c2a25d57ef95f5085c9b02b1209ceaf83f613c9bf93f/shannon_sdk-0.1.0a2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 07:34:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kocoro-lab",
"github_project": "Shannon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shannon-sdk"
}
JSON
