Metadata-Version: 2.4
Name: cerolabs
Version: 0.1.0
Summary: Python SDK for Cero Labs — agent-native expert escalation for AI workflows.
Project-URL: Homepage, https://cerolabs.ai/for-agents
Project-URL: Documentation, https://cerolabs.ai/docs
Project-URL: Repository, https://github.com/os1123/cero-labs
Project-URL: Issues, https://github.com/os1123/cero-labs/issues
Project-URL: Changelog, https://github.com/os1123/cero-labs
Author-email: Cero Labs <contact@cerolabs.ai>
License: MIT
Keywords: agents,ai,expert-escalation,human-in-the-loop,llm,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: jsonschema>=4.23.0
Description-Content-Type: text/markdown

# cerolabs

Python SDK for [Cero Labs](https://cerolabs.ai) — the agent-native API for on-demand domain expertise.

When your agent hits an edge case, `cerolabs` routes the case to a verified domain expert and returns a structured, schema-validated response your workflow can use directly.

## Install

```bash
pip install "git+https://github.com/os1123/cero-labs.git#subdirectory=sdk/python"
```

Requires Python 3.10+.

Package name for PyPI: `cerolabs`. The publish workflow is configured in this repo, but the live PyPI project still needs trusted-publisher setup.

## Quick start

```python
from cerolabs import Cero

cero = Cero(api_key="cero_...")

schema = {
    "type": "object",
    "properties": {
        "appeal_recommended": {"type": "boolean"},
        "reasoning": {"type": "string"},
    },
    "required": ["appeal_recommended", "reasoning"],
}

resolution = cero.escalate_and_wait(
    domain="healthcare.rcm",
    query="Should we appeal this CO-50 denial?",
    context={"cpt": "93015", "payer": "Blue Cross"},
    schema=schema,
)

print(resolution.answer["appeal_recommended"])
print(resolution.answer["reasoning"])
```

## Pydantic models

If you already use Pydantic, pass the model class directly. The SDK will derive `output_schema` for Cero and validate the expert answer on the way back.

```python
from pydantic import BaseModel

from cerolabs import Cero


class CodingDecision(BaseModel):
    cpt_codes: list[str]
    icd10_codes: list[str]
    notes: str | None = None


cero = Cero(api_key="cero_...")
resolution = cero.escalate_and_wait(
    domain="healthcare.coding",
    query="Verify the code set for this operative note.",
    context={"note_id": "OP-123"},
    schema=CodingDecision,
)

assert isinstance(resolution.answer, CodingDecision)
print(resolution.answer.cpt_codes)
```

## Async client

```python
import asyncio

from cerolabs import AsyncCero


async def main() -> None:
    async with AsyncCero(api_key="cero_...") as cero:
        resolution = await cero.escalate_and_wait(
            domain="legal.contract",
            query="Is this indemnity clause outside standard policy?",
        )
        print(resolution.answer)


asyncio.run(main())
```

## API

- `Cero(api_key, base_url?, timeout_s?)`: sync client
- `AsyncCero(api_key, base_url?, timeout_s?)`: async client
- `escalate(...)`: create an escalation and return immediately
- `wait_for_resolution(escalation_id, ...)`: long-poll until resolved
- `escalate_and_wait(...)`: convenience wrapper
- `check_escalation(escalation_id)`: get current status
- `cancel_escalation(escalation_id)`: cancel a pending/routed escalation
- `submit_feedback(escalation_id, score, comment?)`: rate the expert answer
- `list_escalations(...)`: list recent escalations
- `list_domains()`: live supported domains
- `usage()`: tenant credits, tier, and limits

## Machine-readable docs

- [Visual docs](https://cerolabs.ai/docs)
- [Agent docs (`/docs.md`)](https://api.cerolabs.ai/docs.md)
- [Agent discovery (`/llms.txt`)](https://cerolabs.ai/llms.txt)
- [Extended agent guide (`/llms-full.txt`)](https://cerolabs.ai/llms-full.txt)

## Publish locally

```bash
python -m pip install build twine
python -m build
python -m twine check dist/*
```

## License

MIT
