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.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| onejudge-0.19.4.tar.gz | 38.2 kB | With provenance | Details for onejudge-0.19.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| onejudge-0.19.4-py3-none-any.whl | Python 3 | none | any | Details for onejudge-0.19.4-py3-none-any.whl |
Total release size: 78.7 kB
Release files / onejudge-0.19.4.tar.gz
| Download URL | onejudge-0.19.4.tar.gz |
|---|---|
| Size | 38.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fde2ae0764c6270c4a0e48f45c06c888830f15e852d1cc27f0d91d1c73857fbd
|
|
BLAKE2b-256 checksum How to use checksums |
a1756bf16b9d58633085724fbeb0250e75f63d672d21a47ec2f3870879f9f30e
|
| 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 15, 2026.
Transparency logRelease files / onejudge-0.19.4-py3-none-any.whl
| Download URL | onejudge-0.19.4-py3-none-any.whl |
|---|---|
| Size | 40.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92e34afadd651143d683559ba8adb40355748ba99ded4ac94b8f6312dd3e5cff
|
|
BLAKE2b-256 checksum How to use checksums |
8012551e341b3fea36758235a5dc63a69d5b52c51591018c96730de8bda9461b
|
| 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 15, 2026.
Transparency logSecurity for onejudge 0.19.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.
Attestation for onejudge-0.19.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 Oct 15, 2026.
Transparency logA 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.