Skip to main content

onejudge

Typed async Python access to the onejudge CLI. The distribution is onejudge, the import is onejudge_sdk, and each release depends on the exact same onejudge-cli version.

pip install onejudge
import asyncio

from onejudge_sdk import OneJudge


async def main() -> None:
    result = await OneJudge().run(
        {"provider": {"kind": "oneharness"}},
        "Review this repository",
        cwd="/path/to/repository",
        timeout=3600,
    )
    print(result.completed, result.assistant_turns, result.verdicts)


asyncio.run(main())

run validates the config before starting the CLI, writes a temporary effective JSON config (JSON is valid YAML), and always sends the task over stdin with --task -. It accepts a provider override, subprocess cwd, additional env (including ONEHARNESS_HISTORY_LABELS and ONEHARNESS_TIMEOUT), and a timeout. Executable resolution is the constructor's executable, then ONEJUDGE_BIN, then onejudge on PATH.

Exit 0 and 1 return RunResult: exit_code and stderr remain available, and raw, completed, verdicts, usage, assistant_turns, and agent_turns cover ai-orchestrator's dispatch needs. Exit 2 (bad config or provider/runtime failure) and unexpected nonzero exits raise OneJudgeProcessError without discarding the exit code or stderr. A caller timeout raises OneJudgeTimeoutError.

Watching a run as it happens

An agent turn can take 600–2000 seconds. Pass on_event to see its tool activity while it is still running: the SDK runs the CLI under --stream, reads the NDJSON as it arrives, and calls back once per event before returning the same RunResult.

from onejudge_sdk import OneJudge, StreamEvent


def watch(event: StreamEvent) -> None:
    print(event["turn"], event["event"].get("name"))


result = await OneJudge().run(config, "Review this repository", on_event=watch)

Every line is validated against the same generated contract the buffered path uses, so an unreadable line, an envelope this SDK does not model, or a stream that stops before its terminal result line raises ContractError — never a partial run that looks finished. Events arrive live from a provider that streams (provider.stream: true) and are replayed at the end of the turn from one that does not, so on_event works either way. The protocol is documented in docs/streaming.md.

The Rust JSON Schemas generate the SDK's complete public type surface. Besides RunConfig and RunReport, nested contracts such as ProviderConfig, EvalConfig, Transcript, Usage, and JudgeVerdict are importable from onejudge_sdk; StreamEvent is one live event's payload and EventHandler the on_event signature.

The JSONL interface in docs/protocol.md is a different thing: the internal CommandProvider request/response protocol, not a CLI result stream.

Metadata

Release files for onejudge 0.19.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onejudge 0.19.2
File Size Uploaded Provenance Actions
onejudge-0.19.2.tar.gz 38.2 kB With provenance Details for onejudge-0.19.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onejudge 0.19.2
File Interpreter ABI Platform Actions
onejudge-0.19.2-py3-none-any.whl Python 3 none any Details for onejudge-0.19.2-py3-none-any.whl

Total release size: 78.7 kB

Release files / onejudge-0.19.2.tar.gz

Download URL onejudge-0.19.2.tar.gz
Size 38.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e2469c5f6193d75534d74671198669025da358c6b23216e89d4f03edf48eb940
BLAKE2b-256 checksum
How to use checksums
7c32115c48e97e55d64c103cd0cccf929d45f1006be259369377e8ada4c4682d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Release files / onejudge-0.19.2-py3-none-any.whl

Download URL onejudge-0.19.2-py3-none-any.whl
Size 40.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
651c276253a26c64927fa1f97ffd68b92ba9c4290a630dafc72f3b6bc4e80706
BLAKE2b-256 checksum
How to use checksums
ba997bc979922efb8dc0ad3bb51f94432a74d327ae2c7734b58f2ddab520e34e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Security for onejudge 0.19.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for onejudge-0.19.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.19.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page