Metadata-Version: 2.4
Name: omega-api
Version: 0.1.0
Summary: Thin, typed Python client for the Omega-API geometric judge.
Project-URL: Homepage, https://omega.dailui.com/integrations.php
Project-URL: Source, https://github.com/DaiLui/omega-api-examples
Author: Davide Lugli
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,conversation,guardrail,judge,omega-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# omega-api · Python client

A thin, typed Python client for the **Omega-API geometric judge**. It sends one turn to the judge over HTTP, reads
the gate, and returns a decision your app can act on.

> This is not a wrapper. It is a comfort layer over one HTTP call.
> Every future SDK is a thin client over the same judge.

Zero dependencies (standard library only). Python 3.9+. Apache-2.0.

## What it does

Omega-API measures whether the **process** in an agent conversation is moving — turn by turn — and returns a decision.
There is no client-side session state to manage: the judge keeps it server-side, per `session_id`. The interface is
open; the judging method is proprietary.

## Before you start: register → key → judge → meter

1. **Register** and create a project at your Omega-API account page.
2. Get an **API key** (`oapi_live_…`).
3. **Judge**: one call per turn.
4. **Meter**: your first 100 judgments are free; after that, billing applies.

There is no anonymous access. Set your key in the environment:

```bash
export OMEGA_API_KEY=oapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Install

```bash
pip install omega-api
```

## Quick start

```python
from omega_api import Omega

omega = Omega()  # reads OMEGA_API_KEY

decision = omega.judge(
    input="customer message",
    output="agent reply",
)

if decision.release:
    show(reply)            # PROCEED or Shadow mode
elif decision.is_clarify:
    regenerate_then_call_again()
elif decision.is_suppress:
    stop_or_escalate()
```

`turn_id` is omitted by default, so the judge assigns a unique one and returns it (`decision.turn_id`). When
`session_id` is omitted, the client mints a fresh one for the call.

## Act on the gate

Read the gate and act **before** you display the agent's response:

| gate action | what your app does                                                          |
| ----------- | --------------------------------------------------------------------------- |
| `release`   | show the original response                                                  |
| `clarify`   | do not release yet — ask the agent to realign / regenerate, then call again |
| `suppress`  | do not release — stop / escalate / fall back per your policy                |
| `none`      | Shadow mode — observe only, show the original                               |

In Shadow mode the gate always returns `none`. Operator mode is opt-in per key. The helpers `decision.release`,
`decision.is_clarify`, and `decision.is_suppress` read the gate directly.

## Real multi-turn conversations

Keep one `session_id` per conversation:

```python
session = omega.session("support-ticket-123")

d1 = session.judge(input="hi", output="hello")
d2 = session.judge(input="my order never arrived", output="let me check that for you")
```

## Fail-open is a policy, not a default

`judge()` raises on every error — auth, bad request, `409 TURN_CONFLICT`, rate limit, server, transport. If you want
to release the original when the judge is unreachable, opt in explicitly:

```python
decision = omega.judge_or_release(input=msg, output=reply)
# on a transport/server failure: decision.release is True, decision.judged is False
```

Only transport and server errors are treated as fail-open. Auth, request-shape, conflict, and rate-limit still raise.

## What Omega-API does not claim

It measures whether the process **moved**. It does **not** promise the agent achieved the user's goal — the two are
independent. Act and bill on the movement; read the outcome separately.

## Errors

`OmegaConfigError` · `OmegaAuthError` · `OmegaRequestError` · `OmegaConflict` · `OmegaRateLimited` ·
`OmegaServerError` · `OmegaTransportError` — all subclasses of `OmegaError`.

## On the roadmap

`observed_event()` — anchoring a real business outcome to a session — is planned for a future release. It requires a
key with the events capability. Most first integrations never send events; that is a legitimate state, not an error.

## Links

- Learn more: <https://omega.dailui.com/integrations.php>
- Examples & HTTP runner: <https://github.com/DaiLui/omega-api-examples>

## License

Apache-2.0.
