README.md

metadata

title: Judge-GPT
emoji: ⚖️
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 6.17.3
app_file: app.py
pinned: false
license: mit
short_description: AI-native miniature trials under 32B.
tags:
  - track:wood
  - sponsor:openai
  - sponsor:nvidia
  - sponsor:modal
  - achievement:offbrand
  - achievement:fieldnotes

Judge-GPT

Judge-GPT is a cinematic Gradio courtroom for the Build Small Hackathon's Thousand Token Wood track. It turns a compact evidence packet into a two-minute AI-native trial: a clerk opens the docket, two lawyers argue opposite sides, Marcus Aurelius presides, six fixed-perspective jurors vote, and the court seals a verdict.

The point is not legal advice. It is a small-model theater for structured disagreement: evidence is visible, roles are constrained, hidden reasoning is stripped, and every trial leaves a trace of which agent said what.

Submission Links

• Hugging Face Space: https://huggingface.co/spaces/build-small-hackathon/JudgeGPT
• Demo video: https://drive.google.com/drive/folders/10pWJ7NVCsnVV7wOlqm4MGWg4Kmh4rMY2?usp=sharing
• Social post: TODO paste final public social post URL
• GitHub repo: https://github.com/aliiqbal24/BuildSmallfinal
• Field guide validator: https://build-small-hackathon-field-guide.hf.space/submit

What Judges Should Try

1. Open the Space and keep the default Trial of Socrates.
2. Click Begin Trial.
3. Watch the courtroom progress from intake to verdict.
4. Hover the judge, clerk, lawyers, and jurors to inspect model/agent threads.
5. Open the Evidence Drawer and Juror Panel tabs after the verdict.
6. Try Greg Heffley vs Mom for a lighter family-court case.
7. Try Custom to write a short dispute and up to three pieces of evidence per side directly into the docket book.

Why It Fits Build Small

• Thousand Token Wood: the app is whimsical, theatrical, and AI-native rather than a generic chatbot.
• Best Use of Codex: Codex was used throughout implementation, debugging, UI iteration, tests, and commit prep in the connected GitHub repo.
• Nemotron Hardware Prize: Nemotron is a core runtime model for the jury and juror vote generation.
• Best Use of Modal: the Gradio Space delegates live model inference to a Modal GPU streaming endpoint.
• Off-Brand: the UI pushes past stock Gradio with a custom courtroom, animated puppets, docket book, evidence props, audio cues, and verdict staging.
• Field Notes: this README documents the build idea, model choices, runtime architecture, limitations, and submission checklist.

Small-Model Budget

Every named model is under the 32B parameter cap.

Role	Model	Budgeted size	Used for
Presiding advocate	openai/gpt-oss-20b	20B	Judge, claimant lawyer, respondent lawyer, verdict voice
Clerk of style	openbmb/AgentCPM-Explore	4B	Clerk/stage voice
Jury ring	nvidia/Nemotron-Orchestrator-8B	8B	Jury panel and six juror votes

Displayed aggregate budget: 32B. The app does not use a model above 32B.

How It Works

Judge-GPT runs a deterministic courtroom sequence over a CasePacket:

1. Clerk opens the docket.
2. Judge frames the dispute.
3. Mike OSS argues for the claimant.
4. Harvey Vector argues for the respondent.
5. The evidence record is displayed without adding a third lawyer.
6. The judge asks a hinge question.
7. Each lawyer answers from their side.
8. Nemotron Jury retires the panel.
9. Six named jurors vote from distinct worldviews.
10. The judge announces the final verdict.

The shipped demo cases are:

• The Polis v. Socrates
• Greg Heffley v. Mom
• Custom, built from the docket-book fields in the UI

Runtime Architecture

• app.py renders the Gradio UI, courtroom HTML/CSS, audio hooks, case preview book, and live event stream.
• sovereign_bench/engine.py orchestrates trial phases, model calls, evidence events, jury votes, verdict assembly, and trace metadata.
• sovereign_bench/llm.py builds role prompts, calls Hugging Face-compatible chat models, and rejects hidden reasoning or instruction echoes.
• sovereign_bench/cases.py contains the cached demo case packets.
• modal_app.py hosts the GPU-backed streaming endpoint used by the Space.
• tests/ contains engine, case, and rendering regression tests.

The Gradio app uses MODAL_TRIAL_URL when set, otherwise it uses the built-in deployed Modal endpoint. The Modal app owns the Hugging Face token through a Modal secret named huggingface; no real credentials are committed.

Run Locally

python -m pip install -r requirements.txt
python app.py

Open:

http://127.0.0.1:7860

Deploy Modal Backend

python -m modal deploy modal_app.py

After deployment, pre-warm every configured courtroom model in the deployed sovereign-bench app so the first trial does not wait for all GPU containers to cold start. Run this after each deploy because deployments reset Modal autoscaler overrides:

python -m modal run modal_app.py::warm_models

If the endpoint changes, set the Hugging Face Space variable:

MODAL_TRIAL_URL=https://your-modal-endpoint.example

Deploy Hugging Face Space

Create or upload this repo as a Gradio Space inside the official Build Small org:

build-small-hackathon/<your-space-name>

Space settings:

• SDK: Gradio
• App file: app.py
• Python requirements: requirements.txt
• Optional variable: MODAL_TRIAL_URL
• No Space secret is required if using the hosted Modal endpoint.

Verification

python -m pytest

Focused checks used during final prep:

python -m pytest tests/test_engine.py tests/test_ui_rendering.py

Limitations

• Judge-GPT is not legal advice and should not be used for real legal decisions.
• The demo packets are compact, staged evidence packets, not exhaustive source research.
• Model, Modal, or retrieval failures stop the current trial instead of substituting fake dialogue.
• Trial results are not persisted across sessions.
• Custom trials require a short case context and evidence from both sides.

Final Submission Checklist

• Push the repo to the Build Small Hugging Face org as a Gradio Space.
• Confirm the Space launches and can complete Trial of Socrates.
• Record a short demo video showing the trial flow and verdict.
• Replace the Demo video TODO above with the final public URL.
• Publish one social post about the app.
• Replace the Social post TODO above with the final public URL.
• Run the README through the Build Small validator.