Metadata-Version: 2.4
Name: agentos-sdk-python
Version: 0.1.0
Summary: Async Python SDK for AgentOS APIs.
Project-URL: Repository, https://gitlab.litevar.com/litevar/agentos/agentos-sdk-python
Project-URL: Issues, https://gitlab.litevar.com/litevar/agentos/agentos-sdk-python/-/issues
Author: LiteVar
License-Expression: MIT
License-File: LICENSE
Keywords: agentkit,agentos,async,modelkit,sdk,toolkit
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 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.5; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# AgentOS SDK for Python

Async Python SDK for AgentOS APIs. The package is a thin client over AgentOS HTTP and SSE endpoints with small compatibility helpers for bearer tokens, stream callbacks, Pythonic method names, and request defaults.

## Install

```bash
pip install agentos-sdk-python
```

For local development:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
```

## Quickstart

```python
from agentos_sdk import AgentOSSDK


async def main():
    async with AgentOSSDK(base_url="http://localhost:8888") as sdk:
        version = await sdk.agentos.get_version()
        print(version)

        await sdk.agentos.register_bundle(
            {"bundleId": "com.demo.app", "appGroupId": "com.demo.group"}
        )

        tasks = await sdk.cronkit.list_tasks(limit=10)
        print(tasks)
```

`AgentOSSDK` also exposes TS-style camelCase aliases for common migration paths, such as `registerBundle`, `listTasks`, `chatSimple`, `listModels`, and `loadTool`.

## Transport

The SDK uses `httpx.AsyncClient` and defaults to `http://localhost:8888`.

```python
from agentos_sdk import AgentOSSDK

sdk = AgentOSSDK(
    base_url="http://localhost:8888",
    connect_timeout=5.0,
    receive_timeout=10.0,
)
```

Use `async with AgentOSSDK(...)` or call `await sdk.aclose()` when done.

## Token Handling

`sdk.agentos.register_bundle(...)` stores the active app token. Protected facade methods in `sdk.agentkit` and `sdk.cronkit` use that token automatically.

If a protected call fails with HTTP `401`, HTTP `403`, or recognizable invalid-token text, the SDK re-runs registration for the same bundle once and retries the call.

## AgentOS Events

```python
from agentos_sdk import AgentOSEventHandler, AgentOSSDK


class Handler(AgentOSEventHandler):
    async def on_welcome(self, welcome):
        print("welcome", welcome)

    async def on_call_app(self, call):
        print("call app", call)

    async def on_done(self):
        print("subscription ended")

    async def on_error(self, error):
        raise error


async with AgentOSSDK() as sdk:
    await sdk.agentos.register_bundle({"bundleId": "com.demo.app"})
    await sdk.agentos.subscribe(Handler())
```

## AgentKit

```python
from agentos_sdk import AgentMessageHandler, AgentOSSDK, ToolReturn


class ChatHandler(AgentMessageHandler):
    async def on_message(self, session_id, message):
        print("message", session_id, message)

    async def on_chunk(self, session_id, chunk):
        print("chunk", session_id, chunk)

    async def on_function_call(self, session_id, function_call):
        return ToolReturn(function_call["id"], {"ok": True})

    async def on_done(self):
        print("done")

    async def on_error(self, error):
        raise error


async with AgentOSSDK() as sdk:
    await sdk.agentos.register_bundle({"bundleId": "com.demo.app"})
    session = await sdk.agentkit.init_session()
    await sdk.agentkit.chat(
        session,
        {"content": [{"type": "text", "message": "Hello"}]},
        ChatHandler(),
    )
```

Direct AgentKit methods include `get_agent`, `create_agent`, `update_agent`, `delete_agent`, `init_session`, `init_simple`, `chat`, `chat_simple`, `history`, `stop`, `clear`, `callback`, and `stream_callback`.

## CronKit

```python
async with AgentOSSDK() as sdk:
    await sdk.agentos.register_bundle({"bundleId": "com.demo.app"})
    task = await sdk.cronkit.create_task(
        request={
            "name": "Daily summary",
            "schedule": "0 9 * * *",
            "spec": {
                "systemPrompt": "You are a scheduled agent.",
                "content": [{"type": "text", "message": "Summarize today."}],
            },
        }
    )
    await sdk.cronkit.run_task_now(cron_id=task["cronId"])
```

CronKit create requests default `concurrency` to `skipIfRunning`, `enabled` to `True`, and `spec.timeoutSeconds` to `3600`.

## ModelKit

```python
async with AgentOSSDK() as sdk:
    models = await sdk.modelkit.list_models()
    chat_models = await sdk.modelkit.list_models_by_task("chat")

    completion = await sdk.modelkit.chat.create(
        {
            "model": "qwen3-1.7b",
            "messages": [{"role": "user", "content": "Hello"}],
            "maxTokens": 128,
        }
    )

    async for chunk in sdk.modelkit.chat.create_stream(
        {"model": "qwen3-1.7b", "messages": [{"role": "user", "content": "Stream"}]}
    ):
        print(chunk)
```

ModelKit also supports:

- `sdk.modelkit.embedding.create(...)`
- `sdk.modelkit.asr.transcribe(...)`
- `sdk.modelkit.tts.synthesize(...)`
- `sdk.modelkit.tts.list_voices()`

## ToolKit

```python
async with AgentOSSDK() as sdk:
    tools = await sdk.toolkit.list_tool()
    definition = await sdk.toolkit.load_tool("tool-id")
    raw_json = definition.to_json() if definition else None

    async for event in sdk.toolkit.subscribe_tool_events("daemon-api-key"):
        print(event)
```

`load_tool()` returns an `OpenToolDefinition` wrapper that preserves the raw JSON definition. It does not execute tools or implement browser/daemon OpenTool bridging.

## Direct Clients

The low-level clients are available for explicit-token or custom transport usage:

```python
from agentos_sdk.clients import AgentKitClient, CronKitClient, ModelKitClient
from agentos_sdk.transport import ApiClient

api = ApiClient(base_url="http://localhost:8888")
agentkit = AgentKitClient(api)
agent = await agentkit.get_agent("bearer-token", "agent-id")
```

## Development

```bash
.venv/bin/python -m compileall agentos_sdk
.venv/bin/python -m pytest -q
.venv/bin/ruff check .
```
