sinas 0.1.0__py3-none-any.whl

sinas-0.1.0.dist-info/METADATA

@@ -0,0 +1,502 @@
+Metadata-Version: 2.4
+Name: sinas
+Version: 0.1.0
+Summary: Python SDK for SINAS - AI Agent Platform
+Project-URL: Homepage, https://github.com/sinas/sinas-sdk
+Project-URL: Documentation, https://docs.sinas.ai
+Project-URL: Repository, https://github.com/sinas/sinas-sdk
+Author: SINAS Team
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,chatbot,fastapi,llm,mcp,sdk,sinas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+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
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.23.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: email-validator>=2.0.0; extra == 'fastapi'
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# SINAS Python SDK
+
+Python SDK for [SINAS](https://github.com/pulsr-ai/SINAS) - AI Agent & Automation Orchestration Platform.
+
+**Runtime API Client** for executing agents, managing state, running webhooks, and tracking executions.
+
+## Installation
+
+```bash
+pip install sinas
+```
+
+With FastAPI integration:
+```bash
+pip install sinas[fastapi]
+```
+
+## Quick Start
+
+### Authentication
+
+```python
+from sinas import SinasClient
+
+# Initialize client with base URL
+client = SinasClient(base_url="http://localhost:51245")
+
+# Step 1: Login with email (sends OTP)
+login_response = client.auth.login("user@example.com")
+session_id = login_response["session_id"]
+
+# Step 2: Verify OTP and get access + refresh tokens
+response = client.auth.verify_otp(session_id, "123456")
+# Tokens are automatically set on the client
+access_token = response["access_token"]
+refresh_token = response["refresh_token"]
+
+# Or use an API key directly
+client = SinasClient(
+    base_url="http://localhost:51245",
+    api_key="your-api-key"
+)
+```
+
+### Environment Variables
+
+Configure the client using environment variables:
+
+```bash
+export SINAS_BASE_URL="http://localhost:51245"
+export SINAS_API_KEY="your-api-key"
+# or
+export SINAS_TOKEN="your-jwt-token"
+```
+
+```python
+from sinas import SinasClient
+
+# Automatically uses environment variables
+client = SinasClient()
+```
+
+## Core Features
+
+### State Management
+
+Store and retrieve key-value data with namespacing and visibility controls:
+
+```python
+# Create/set a state value
+state = client.state.set(
+    namespace="user_prefs",
+    key="theme",
+    value={"mode": "dark", "accent": "blue"},
+    description="User theme preferences",
+    visibility="private"  # private, group, or public
+)
+
+# Get a specific state
+state = client.state.get(state["id"])
+print(state["value"])  # {"mode": "dark", "accent": "blue"}
+
+# List states with filtering
+states = client.state.list(
+    namespace="user_prefs",
+    visibility="private",
+    tags="settings",
+    search="theme"
+)
+
+# Update state
+updated = client.state.update(
+    state["id"],
+    value={"mode": "light", "accent": "green"}
+)
+
+# Delete state
+client.state.delete(state["id"])
+```
+
+### Agent Chats
+
+Create chats with agents and send messages:
+
+```python
+# Create a chat with an agent
+chat = client.chats.create(
+    namespace="customer-support",
+    agent_name="cs-agent-v1",
+    title="Customer Inquiry",
+    input={"customer_id": "12345"}  # Optional input validated by agent
+)
+
+# Send a message (blocking)
+response = client.chats.send(
+    chat_id=chat["id"],
+    content="What's the status of my order?"
+)
+print(response["content"])
+
+# Stream a message (Server-Sent Events)
+for chunk in client.chats.stream(
+    chat_id=chat["id"],
+    content="Tell me about your services"
+):
+    # Parse SSE data
+    import json
+    try:
+        data = json.loads(chunk)
+        if "content" in data:
+            print(data["content"], end="", flush=True)
+    except:
+        pass
+
+# Get chat with all messages
+chat_data = client.chats.get(chat["id"])
+messages = chat_data["messages"]
+
+# List all chats
+chats = client.chats.list()
+
+# Update chat
+client.chats.update(chat["id"], title="Updated Title")
+
+# Delete chat
+client.chats.delete(chat["id"])
+```
+
+### Webhook Execution
+
+Execute webhooks by path:
+
+```python
+# Execute a webhook
+result = client.webhooks.run(
+    path="process-payment",
+    method="POST",
+    body={"amount": 100, "currency": "USD"},
+    headers={"X-Custom-Header": "value"},
+    query={"idempotency_key": "abc123"}
+)
+
+print(result["execution_id"])  # Track execution
+print(result["result"])  # Function output
+```
+
+### Executions
+
+Track and manage function executions:
+
+```python
+# List recent executions
+executions = client.executions.list(
+    function_name="payment-processor",
+    status="completed",
+    limit=10
+)
+
+# Get execution details
+execution = client.executions.get("execution-id")
+print(execution["status"])  # running, completed, failed, awaiting_input
+print(execution["output_data"])
+
+# Get execution steps
+steps = client.executions.get_steps("execution-id")
+for step in steps:
+    print(f"{step['step_name']}: {step['status']}")
+
+# Continue a paused execution
+result = client.executions.continue_execution(
+    "execution-id",
+    input={"user_choice": "approve"}
+)
+```
+
+### Authentication Methods
+
+```python
+# Refresh access token
+refreshed = client.auth.refresh(refresh_token)
+new_access_token = refreshed["access_token"]
+
+# Exchange external OIDC token
+response = client.auth.external_auth(external_oidc_token)
+
+# Get current user info
+user = client.auth.get_me()
+print(user["email"])
+
+# Logout (revoke refresh token)
+client.auth.logout(refresh_token)
+```
+
+## FastAPI Integration
+
+SINAS provides **two powerful approaches** for FastAPI integration:
+
+### Approach 1: Ready-to-Mount Routers
+
+Mount SINAS Runtime API endpoints directly in your FastAPI app with automatic authentication:
+
+```python
+from fastapi import FastAPI
+from sinas.integrations.routers import create_runtime_router
+
+app = FastAPI()
+
+# Mount ALL runtime endpoints at once
+app.include_router(
+    create_runtime_router("http://localhost:51245", include_auth=False),
+    prefix="/api/runtime"
+)
+
+# This automatically creates endpoints like:
+# - GET    /api/runtime/states
+# - POST   /api/runtime/states
+# - GET    /api/runtime/chats
+# - POST   /api/runtime/agents/{namespace}/{agent}/chats
+# - POST   /api/runtime/webhooks/{path}
+# - GET    /api/runtime/executions
+```
+
+Or mount individual routers:
+
+```python
+from sinas.integrations.routers import (
+    create_state_router,
+    create_chat_router,
+    create_webhook_router,
+    create_executions_router
+)
+
+app.include_router(create_state_router("http://localhost:51245"), prefix="/runtime/states")
+app.include_router(create_chat_router("http://localhost:51245"), prefix="/runtime/chats")
+app.include_router(create_webhook_router("http://localhost:51245"), prefix="/runtime/webhooks")
+app.include_router(create_executions_router("http://localhost:51245"), prefix="/runtime/executions")
+```
+
+### Approach 2: Custom Endpoints with SDK Client
+
+Build custom endpoints with business logic using the authenticated client:
+
+```python
+from fastapi import FastAPI, Depends
+from sinas import SinasClient
+from sinas.integrations.fastapi import SinasAuth
+
+app = FastAPI()
+sinas = SinasAuth(base_url="http://localhost:51245")
+
+# Include auto-generated auth endpoints
+app.include_router(sinas.router, prefix="/auth")
+
+# Custom endpoint with auto-authentication
+@app.get("/my-states")
+async def get_my_states(client: SinasClient = Depends(sinas)):
+    """List user's states with custom filtering."""
+    states = client.state.list(limit=10)
+    return [{"id": s["id"], "key": s["key"]} for s in states]
+
+# Combine multiple SDK calls
+@app.post("/quick-chat")
+async def quick_chat(
+    agent_namespace: str,
+    agent_name: str,
+    message: str,
+    client: SinasClient = Depends(sinas)
+):
+    """Create chat and send message in one request."""
+    chat = client.chats.create(agent_namespace, agent_name)
+    response = client.chats.send(chat["id"], message)
+    return {"chat_id": chat["id"], "response": response}
+
+# Permission-protected endpoint
+@app.post("/admin/cleanup")
+async def cleanup_states(
+    namespace: str,
+    client: SinasClient = Depends(sinas.require("sinas.contexts.delete:all"))
+):
+    """Admin-only: Clean up states (requires permission)."""
+    states = client.state.list(namespace=namespace)
+    for state in states:
+        client.state.delete(state["id"])
+    return {"deleted": len(states)}
+```
+
+### Auto-Generated Auth Endpoints
+
+The `sinas.router` automatically provides:
+
+- `POST /auth/login` - Send OTP to email
+- `POST /auth/verify-otp` - Verify OTP and get tokens
+- `GET /auth/me` - Get current authenticated user
+
+### Permission-Based Access Control
+
+Use `sinas.require()` to protect endpoints:
+
+```python
+# Require specific permission
+@app.delete("/states/{state_id}")
+async def delete_state(
+    state_id: str,
+    client: SinasClient = Depends(sinas.require("sinas.contexts.delete:own"))
+):
+    client.state.delete(state_id)
+    return {"message": "Deleted"}
+
+# Require multiple permissions (OR logic)
+@app.post("/admin-action")
+async def admin_action(
+    client: SinasClient = Depends(
+        sinas.require("sinas.admin:all", "sinas.contexts.write:all")
+    )
+):
+    return {"message": "Admin action completed"}
+```
+
+### Complete Example
+
+See [examples/fastapi_app.py](examples/fastapi_app.py) for a complete working example with both approaches.
+
+Run it with:
+```bash
+uvicorn examples.fastapi_app:app --reload
+```
+
+Then visit `http://localhost:8000/docs` for interactive API documentation.
+
+## Context Manager
+
+The client can be used as a context manager for proper resource cleanup:
+
+```python
+with SinasClient(base_url="http://localhost:51245") as client:
+    states = client.state.list()
+    # Client is automatically closed when exiting
+```
+
+## Error Handling
+
+```python
+from sinas import (
+    SinasClient,
+    SinasAPIError,
+    SinasAuthError,
+    SinasNotFoundError,
+    SinasValidationError
+)
+
+client = SinasClient(base_url="http://localhost:51245")
+
+try:
+    state = client.state.get("non-existent-id")
+except SinasNotFoundError as e:
+    print(f"State not found: {e}")
+except SinasAuthError as e:
+    print(f"Authentication failed: {e}")
+except SinasValidationError as e:
+    print(f"Validation error: {e}")
+except SinasAPIError as e:
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Response: {e.response}")
+```
+
+## API Reference
+
+### SinasClient
+
+#### `auth`
+- `login(email)` - Send OTP to email
+- `verify_otp(session_id, otp_code)` - Verify OTP and get tokens
+- `external_auth(token)` - Exchange external OIDC token
+- `refresh(refresh_token)` - Refresh access token
+- `logout(refresh_token)` - Revoke refresh token
+- `get_me()` - Get current user info
+
+#### `state`
+- `set(namespace, key, value, ...)` - Create/update state
+- `get(state_id)` - Get state by ID
+- `list(namespace?, visibility?, ...)` - List states with filters
+- `update(state_id, value?, ...)` - Update state
+- `delete(state_id)` - Delete state
+
+#### `chats`
+- `create(namespace, agent_name, input?, title?)` - Create chat with agent
+- `send(chat_id, content)` - Send message (blocking)
+- `stream(chat_id, content)` - Send message (streaming SSE)
+- `get(chat_id)` - Get chat with messages
+- `list()` - List user's chats
+- `update(chat_id, title?)` - Update chat
+- `delete(chat_id)` - Delete chat
+
+#### `webhooks`
+- `run(path, method?, body?, headers?, query?)` - Execute webhook
+
+#### `executions`
+- `list(function_name?, status?, skip?, limit?)` - List executions
+- `get(execution_id)` - Get execution details
+- `get_steps(execution_id)` - Get execution steps
+- `continue_execution(execution_id, input)` - Continue paused execution
+
+### FastAPI Integration
+
+#### `SinasAuth(base_url, auto_error=True)`
+FastAPI dependency for authentication and authorization.
+
+#### Router Functions
+- `create_runtime_router(base_url, include_auth=False)` - Complete runtime router
+- `create_state_router(base_url, prefix="")` - State endpoints
+- `create_chat_router(base_url, prefix="")` - Chat endpoints
+- `create_webhook_router(base_url, prefix="")` - Webhook endpoints
+- `create_executions_router(base_url, prefix="")` - Execution endpoints
+
+## Development
+
+### Install Development Dependencies
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Run Examples
+
+```bash
+# Basic usage
+python examples/basic_usage.py
+
+# FastAPI app
+uvicorn examples.fastapi_app:app --reload
+```
+
+### Code Formatting
+
+```bash
+black sinas
+ruff check sinas
+```
+
+## License
+
+MIT

sinas-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+sinas/__init__.py,sha256=nt3SVKS-tSfjDwNirNSFth0xQGOEZYkuEUQQRtX7APQ,398
+sinas/auth.py,sha256=zd78eYhmJ5EhVLvKj3I3d001OYjEsXM0Vieri9NHLH8,3222
+sinas/chats.py,sha256=zgQpY7rlveREuwjFXLhLHGxt3YnTBU9aLbaB50ZfVl4,3371
+sinas/client.py,sha256=1i2l5KFsTrKb_tLWg4y9vBXUKOyxo4R_yY5U_5Ww56M,5964
+sinas/exceptions.py,sha256=ERTw8uPaGtkroAQhxDij7p5EY_-YiKJmGnuvjWBBNZI,815
+sinas/executions.py,sha256=wB4tS57zFpt149oIxO2B-bnY2t_DiZP3sTteiHHAR5A,2323
+sinas/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sinas/state.py,sha256=J7Ol6QFu08WPnYQI0uroOnq7pEt6htArDT3Xjz88o8o,5315
+sinas/webhooks.py,sha256=mz1IXBSYjc8B_n3dPbhmMcT0ItrvQ-zuyr3PrqStsfE,1665
+sinas/integrations/__init__.py,sha256=pMVqIo30O0LQaWK7qtspgxsI0QUpxxYGTpz87_ShuTo,480
+sinas/integrations/fastapi.py,sha256=yNLez_OP-eef7Nr-2j2v09RdukU0DarHj58jmXWk5YE,9419
+sinas/integrations/routers.py,sha256=H60DpU1n-GPNcm2qPKP0P0pFXgcRmqxvVcLaF8FM-rE,9908
+sinas-0.1.0.dist-info/METADATA,sha256=PPGwuYC0tv93qy7Q83W_v0kqaodUOcUFgYaxhVGe8Yk,13156
+sinas-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sinas-0.1.0.dist-info/licenses/LICENSE,sha256=rxZIwhvDtoCgD8-unmNYMBi2HelS5mkblOffT9hhiXQ,1062
+sinas-0.1.0.dist-info/RECORD,,

sinas-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sinas-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SINAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.