Metadata-Version: 2.4
Name: opalzero-sdk
Version: 1.0.0
Summary: Python SDK for OpalZero — the self-hosted AI kernel. Send an intent, get back structured data.
Project-URL: Homepage, https://albertobarnabo.com/opal-zero/
Project-URL: Documentation, https://albertobarnabo.com/opal-zero/docs
Project-URL: Repository, https://github.com/albertobarnabo/opal-zero-engine
Project-URL: Issues, https://github.com/albertobarnabo/opal-zero-engine/issues
Author-email: Alberto Barnabo <albertobarnabo@gmail.com>
License: MIT
Keywords: agents,ai,anthropic,llm,ollama,openai,sdk,self-hosted,structured-output
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# opalzero-sdk (Python)

Python client for [OpalZero](https://github.com/albertobarnabo/opalzero) — **the self-hosted AI kernel your app delegates to.** Send a plain-English intent and the exact output schema you want; get back finished, structured data. Your app stops writing AI code.

## 🔭 OpalGlimpse — the first product built on OpalZero *(coming soon)*

Autonomous monitoring powered by OpalZero: point it at markets, competitors, or any signal — it runs on a schedule and shows you **exactly what changed**, as structured diffs, not noise. *Watch the world change while you sleep.*

It launches as a hosted SaaS, and **we deploy it once there's enough interest.** Want early access?

- 👍 or comment on the **[OpalGlimpse early-access issue →](https://github.com/albertobarnabo/opal-zero-engine/issues/1)**
- or email **albertobarnabo@gmail.com**

Meanwhile, run the OpalZero engine yourself today — bring your own API key.

---

## Install

```bash
pip install opalzero-sdk
```

## Quick start

```python
import asyncio
from opalzero import OpalZeroClient

async def main():
    async with OpalZeroClient(base_url="http://localhost:8000") as oz:
        async for event in oz.execute("Analyse the EV market in Europe"):
            if event.type == "task_completed":
                print(f"[{event.role}] {event.result[:120]}")
            if event.type == "mission_complete":
                print("Done:", event.mission_state.data_payload)

asyncio.run(main())
```

## Bring your own schema

Pass `schema` — a mapping of field name to type — and the kernel is contractually bound to return exactly that shape. No hallucinated fields, no missing keys, nothing to post-process. To the kernel, every task is the same task: an intent and the shape of its answer.

```python
SCHEMA = {
    "cheapest_model":     "string",
    "cheapest_price_usd": "number",
    "cars":               "array",
}

async with OpalZeroClient(base_url="http://localhost:8000") as oz:
    async for event in oz.execute(
        "Compare the 3 cheapest electric cars on sale today",
        schema=SCHEMA,
    ):
        if event.type == "mission_complete":
            # event.mission_state.data_payload matches SCHEMA exactly
            print(event.mission_state.data_payload)
```

Field types: `string`, `number`, `boolean`, `array`, `object`.

## Self-host

See [docker-compose.yml](../docker-compose.yml) in the monorepo root, or the [full docs](https://albertobarnabo.com/opal-zero/docs).
