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

# Judge-GPT

Judge-GPT is a cinematic Gradio Space for the Build Small Hackathon's Thousand Token Wood track. It runs two-minute AI-native miniature trials where small-model agents act as advocates, judge, jurors, clerk, and evidence auditor.

The app is built to stay under the 32B named-model budget:

- `openai/gpt-oss-20b` for primary legal reasoning.
- `openbmb/AgentCPM-Explore` for clerk/stage/verdict style.
- `nvidia/Nemotron-Orchestrator-8B` for juror and evidence-auditor review.

Total named budget: 32B parameters.

## What the app can do

- Run cached trials for the Socrates and Barnaby demo cases without network search.
- Run the Live Search Tribunal path, which builds a search packet from a user query and stops if live material is too weak to support a trial.
- Add a hypothetical sidebar to shift the framing of a trial without editing cached case files.
- Switch trial pacing between swift, measured, and ceremonial speeds.
- Stage the courtroom with phase-specific visuals, agent puppets, evidence props, captions, and browser audio cues.
- Show the Mind Layer as a compact JSON trace of agent turns and phase metadata.
- Call a Modal streaming endpoint when `MODAL_TRIAL_URL` is configured. Endpoint or model failures stop the trial instead of substituting cached dialogue.
- Retain decree and agent-trace export helpers in `sovereign_bench/export.py` for future UI restoration.

## Limitations

- Judge-GPT is not legal advice and should not be used for real legal decisions.
- Live search snippets are not independently verified by the app.
- Output quality depends on Modal GPU availability, token limits, and the configured Hugging Face models.
- Model, Modal, or live retrieval failures stop the current trial rather than returning substitute courtroom dialogue.
- Trial results are not persisted across sessions.
- Export generation remains in the codebase, but the visible download UI is currently hidden.

## Run locally

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

## Modal backend

The Gradio app works locally without Modal. If `MODAL_TRIAL_URL` is set, the Space calls the Modal streaming endpoint and stops the trial if the endpoint is unavailable.

The deployed Modal endpoint runs each role prompt through a GPU-backed vLLM class on H100 by default. Traces mark successful GPU calls with `runtime: modal-gpu-vllm`, `provider: modal-gpu-vllm`, and `gpu: H100`. If a GPU/model load fails, the trial stops; the app does not substitute provider or cached dialogue.

```powershell
python -m modal deploy modal_app.py
```

Keep the deployed endpoint URL as a Hugging Face Space variable named `MODAL_TRIAL_URL`.

## Project targets

Workspace connected to:

- GitHub: `https://github.com/aliiqbal24/BuildSmallfinal.git`
- Modal profile: `ali-j-iqbal24`
- Hugging Face user: `AliIqbal05`

## Secrets

Credentials are not committed to this repo.

- Local Hugging Face CLI auth is stored in the Hugging Face cache.
- Modal auth is stored in the local Modal profile.
- Modal has a secret named `huggingface` with `HF_TOKEN`.

Use the Modal secret in functions like this:

```python
@app.function(secrets=[modal.Secret.from_name("huggingface")])
def run_model():
    token = os.getenv("HF_TOKEN")
```

## Developer guide

- `app.py`: Gradio UI, CSS, JavaScript audio hooks, HTML renderers, and Modal/local streaming switch.
- `sovereign_bench/engine.py`: trial phases, agent orchestration, verdict assembly, and trace construction.
- `sovereign_bench/llm.py`: Hugging Face calls, strict model error handling, and prompt building.
- `sovereign_bench/retrieval.py`: live search packet construction.
- `sovereign_bench/models.py`: Pydantic schemas for cases, evidence, events, turns, votes, and verdicts.
- `sovereign_bench/cases.py`: cached demo case packets.
- `sovereign_bench/export.py`: dormant decree and trace writers.
- `modal_app.py`: Modal deployment and GPU-backed streaming endpoint.
- `tests/`: engine, case, and rendering regression coverage.

## Verify Modal to Hugging Face

```powershell
python -m modal run modal_app.py
```