Metadata-Version: 2.4
Name: kodeus
Version: 0.3.0rc1
Summary: Declarative SDK for authoring AI agents that run on the Kodeus Runtime
Author: Kodeus
License-Expression: Apache-2.0
Project-URL: Homepage, https://kodeus.ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: httpx>=0.27
Requires-Dist: python-dotenv>=1.0
Requires-Dist: prompt_toolkit>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: detect-secrets==1.5.0; extra == "dev"
Requires-Dist: packaging>=24; extra == "dev"
Provides-Extra: introspect
Requires-Dist: mcp>=1.0; extra == "introspect"
Dynamic: license-file

# Kodeus SDK

Create, publish and invoke AI agents from Python. The SDK provides typed agent
specifications, asynchronous execution clients, event streaming, webhook
verification and a command-line authoring interface.

This version is a **development preview**. Use it with a compatible Kodeus
environment and pin the version in your application's dependency file.

## Install

Requires Python 3.10 or later:

```bash
python -m pip install "kodeus==0.3.0rc1"
```

## Submit a task

Your organization administrator supplies the API base URL, organization ID,
service-account credential and installed agent ID. The application API base URL
must end in `/sdk`. The SDK does not choose a production or test environment for
you.

```python
import asyncio
import os
from uuid import uuid4

from kodeus.client import AsyncKodeus


async def main():
    async with AsyncKodeus(
        base_url=os.environ["KODEUS_BASE_URL"],
        org_id=os.environ["KODEUS_ORG_ID"],
        api_key=os.environ["KODEUS_API_KEY"],
    ) as client:
        agent = client.agents.get(os.environ["KODEUS_AGENT_ID"])
        run = await agent.submit(
            input={"message": "Summarize the available support options."},
            idempotency_key=str(uuid4()),
        )
        print("Run:", run.id)
        print("Session:", run.snapshot.session_id)


asyncio.run(main())
```

Use the input shape required by your agent. Submission returns after durable
acceptance; the agent may still be running. In an application, save the command
UUID and input before submitting, reuse them when retrying that command, and
persist the returned run/session identifiers. Configure credentials through your
environment or secret manager, never in source code.

## CLI and optional integrations

```bash
kodeus --help
kodeus validate --help
```

Hosted agent creation and invocation do not require a local execution engine,
database or message broker. The optional `introspect` extra enables inspection
of local stdio MCP servers:

```bash
python -m pip install "kodeus[introspect]==0.3.0rc1"
```

Local execution, schema provisioning and some administration commands require a
separately authorized Kodeus Runtime distribution. Obtain its installation
instructions from your Kodeus administrator; the public SDK does not download
that private package. The SDK retains the supported BYO database adapter for
existing single-customer installations. Shared hosted environments use the
authenticated API.

Legacy CLI authoring uses `KODEUS_CLOUD_URL`, and its OAuth broker uses
`KODEUS_AI_API_URL`. Set those explicitly for the environment supplied by your
administrator; they are distinct from the application client's API base URL.

## License

The SDK is licensed under Apache-2.0. The separately distributed runtime and
hosted services are not included in this package. Learn more at
[kodeus.ai](https://kodeus.ai).
