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.17.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.17.2
File Size Uploaded Provenance Actions
onejudge-0.17.2.tar.gz 37.1 kB With provenance Details for onejudge-0.17.2.tar.gz

Built distribution (wheel)

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

Total release size: 77.4 kB

Release files / onejudge-0.17.2.tar.gz

Download URL onejudge-0.17.2.tar.gz
Size 37.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e86d1aeae81791cec40e754424e9911a76723b073847bb97d336b3481828651e
BLAKE2b-256 checksum
How to use checksums
92528b212dfd709f6407b219e841562b3bf67b970609a43e104f6844f355e55f
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 6, 2026.

Transparency log

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

Download URL onejudge-0.17.2-py3-none-any.whl
Size 40.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
794fa91ccad88bf89fe90f03dc5af4a4f484a7aef98f954ed70c4138e276e948
BLAKE2b-256 checksum
How to use checksums
bbdcaa8ac6d3d864bd8c53adbb2a13a030f82a373743a6aefcc320ac06ffe342
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 6, 2026.

Transparency log

Security for onejudge 0.17.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.17.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 6, 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.17.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