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.4

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.4
File Size Uploaded Provenance Actions
onejudge-0.23.4.tar.gz 39.1 kB With provenance Details for onejudge-0.23.4.tar.gz

Built distribution (wheel)

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

Total release size: 80.6 kB

Release files / onejudge-0.23.4.tar.gz

Download URL onejudge-0.23.4.tar.gz
Size 39.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6ac37cd8d99b538fcaf0aa89e5efedb06fd8f26d8cea50a50392908a32a1f580
BLAKE2b-256 checksum
How to use checksums
9725a898c0f640cdda35fad7c6da67b318c1e26527b22d9fc97740d4ee7329b1
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 16, 2026.

Transparency log

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

Download URL onejudge-0.23.4-py3-none-any.whl
Size 41.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ed44a78fc67417bc3928dc11c5d8bf63726e0a05a2010df9ff9fa119e777a83
BLAKE2b-256 checksum
How to use checksums
93403373251ae8d5da9a2f74676f021c236632d8d413929a8a889423189ed1e5
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 16, 2026.

Transparency log

Security for onejudge 0.23.4

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.4.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 16, 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.4 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