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:

export OMEGA_API_KEY=oapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Install

pip install omega-api

Quick start

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:

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:

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:

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.