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

A worker 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.23.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.23.2
File Size Uploaded Provenance Actions
onejudge-0.23.2.tar.gz 39.1 kB With provenance Details for onejudge-0.23.2.tar.gz

Built distribution (wheel)

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

Total release size: 80.6 kB

Release files / onejudge-0.23.2.tar.gz

Download URL onejudge-0.23.2.tar.gz
Size 39.1 kB
Tags Source
SHA-256 checksum
How to use checksums
bd6143a792a3ccf952f163921ec55b72b163dc5109992bcdc1b7814dadb7d343
BLAKE2b-256 checksum
How to use checksums
8668b66e05be324173f1d217b14e92e5dfc3f4cec3f2f54a7a84773ac60c89ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 13, 2026.

Transparency log

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

Download URL onejudge-0.23.2-py3-none-any.whl
Size 41.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
898de2ec6a239f99b8d58c50a86e8207c67938eeffe30a896b12bd212b4eb544
BLAKE2b-256 checksum
How to use checksums
2e7d08a5c6b4f12b37628a5316c4f9b2838df8a43fd8c70c9631897c13a12368
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 13, 2026.

Transparency log

Security for onejudge 0.23.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.23.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 Nov 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.23.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