| --- |
| 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 |
|
|
| ```powershell |
| python -m pip install -r requirements.txt |
| python app.py |
| ``` |
|
|
| Open: |
|
|
| ```text |
| http://127.0.0.1:7860 |
| ``` |
|
|
| ## Deploy Modal Backend |
|
|
| ```powershell |
| 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: |
|
|
| ```powershell |
| python -m modal run modal_app.py::warm_models |
| ``` |
|
|
| If the endpoint changes, set the Hugging Face Space variable: |
|
|
| ```text |
| 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: |
|
|
| ```text |
| 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 |
|
|
| ```powershell |
| python -m pytest |
| ``` |
|
|
| Focused checks used during final prep: |
|
|
| ```powershell |
| 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. |
|
|
