Apppublic

hugging2021/json-repair-env

sourceHugging Faceupdated 6mo agoView on Hugging Face

0likes

App README

![OpenEnv](https://github.com/preethamjain275/json-repair-env) ![Docker](https://hub.docker.com) ![HuggingFace](https://huggingface.co/spaces/preethamjain275/json-repair-env) ![FastAPI](https://fastapi.tiangolo.com) ![Python](https://python.org) ![License](LICENSE)

<br/>

![Meta](https://meta.com) ![HuggingFace Engineers](https://huggingface.co) ![Hackathon](https://huggingface.co)

</div>

💡 "Every LLM-powered product breaks JSON. This environment trains agents to fix it — automatically."

</div>

🔥 What Is This?

🚨 The Problem

json

{
  "name": "Alice",
  "age": "30",        ← wrong type
  "active": "true",   ← wrong type
                      ← missing field!
}                     ← trailing comma

</td> <td width="50%">

✅ The Solution

json

{
  "name": "Alice",
  "age": 30,
  "active": true,
  "role": "user"
}

</td> </tr> </table>

This OpenEnv RL environment rewards agents for transforming broken JSON into valid, schema-compliant, semantically correct output. It models a real production problem faced by every team deploying LLMs at scale.

🎮 Environment Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    JSON REPAIR ENVIRONMENT                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   🤖 Agent                    🌐 OpenEnv Server                 │
│   ┌─────────┐   reset()       ┌──────────────────────┐         │
│   │         │ ──────────────► │  Initial Observation  │         │
│   │         │ ◄────────────── │  • broken JSON        │         │
│   │         │                 │  • target schema      │         │
│   │  BRAIN  │   step(action)  │  • hint               │         │
│   │         │ ──────────────► ├──────────────────────┤         │
│   │         │ ◄────────────── │  Reward + Next Obs    │         │
│   │         │                 │  0.0 ──────────► 1.0  │         │
│   └─────────┘   state()       └──────────────────────┘         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🎯 Three Tasks — Easy → Medium → Hard

	Task	Difficulty	Challenge	Reward Ceiling
🟢	`easy_syntax_fix`	Easy	Remove trailing commas	`1.00`
🟡	`medium_type_repair`	Medium	Fix types + add missing fields	`1.00`
🔴	`hard_nested_reconstruction`	Hard	Reconstruct corrupted nested JSON	`1.00`

</div>

Task 1 — 🟢 Easy: Syntax Fix

python

# Input (broken)
'{"name": "Alice", "age": 30, "email": "alice@example.com",}'
#                                                           ↑ trailing comma

# Expected output (fixed)
'{"name": "Alice", "age": 30, "email": "alice@example.com"}'

Task 2 — 🟡 Medium: Type Repair

python

# Input (broken)
'{"user": "Bob", "score": "95", "active": "true"}'
#                          ↑ str     ↑ str  missing "role" field ↑

# Expected output (fixed)
'{"user": "Bob", "score": 95, "active": true, "role": "user"}'

Task 3 — 🔴 Hard: Nested Reconstruction

python

# Input (broken)
"{product: 'Laptop', price: '999.99', specs: {ram: '16gb', storage: 512}}"
# ↑ unquoted keys  ↑ wrong type   ↑ missing field  ↑ needs normalization

# Expected output (fixed)
'{"product": "Laptop", "price": 999.99, "specs": {"ram": "16GB", "storage": 512}, "available": true}'

🏆 Reward Function — Partial Progress Signals

Reward = f(syntax, schema, semantics)

  ┌─────────────────────────────────────────────┐
  │  ✅  Valid JSON syntax      →   +0.40        │
  │  ✅  Schema compliance      →   +0.40        │
  │  ✅  Exact semantic match   →   +0.20        │
  │                              ───────         │
  │  🏅  Maximum per task       =   1.00         │
  │                                              │
  │  💡  Partial credit awarded for partially    │
  │      correct fixes — not binary pass/fail    │
  └─────────────────────────────────────────────┘

📊 Baseline Performance

Task	Mistral-7B	GPT-4o-mini	Notes
🟢 `easy_syntax_fix`	0.95	1.00	Straightforward for most LLMs
🟡 `medium_type_repair`	0.75	0.90	Requires type inference
🔴 `hard_nested_reconstruction`	0.55	0.75	Genuinely challenges frontier models
📈 Overall Score	0.75	0.88	Out of 1.0

</div>

🟢 Easy       ████████████████████░░ 95%
🟡 Medium     ███████████████░░░░░░░ 75%
🔴 Hard       ███████████░░░░░░░░░░░ 55%

🧩 OpenEnv Spec Compliance

▶ Action Space

python

class Action(BaseModel):
    repaired_json: str    # Agent's fixed JSON string
    explanation:  str     # Brief description of changes (optional)

👁 Observation Space

python

class Observation(BaseModel):
    broken_json:   str        # The malformed JSON to repair
    target_schema: dict       # JSON Schema output must comply with
    hint:          str        # What type of error to look for
    task_name:     str        # Current task identifier
    step_number:   int        # Current step in episode
    total_tasks:   int        # Total tasks in episode

🔁 API Endpoints

Method	Endpoint	Description
`POST`	`/reset`	Start new episode, get first observation
`POST`	`/step`	Submit action, get reward + next observation
`GET`	`/state`	Get current environment state
`GET`	`/health`	Health check ping
`GET`	`/tasks`	List all available tasks

🚀 Quick Start

1️⃣ Clone & Run Locally

bash

git clone https://huggingface.co/spaces/preethamjain275/json-repair-env
cd json-repair-env
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 7860

2️⃣ Test the API

bash

# ✅ Health check
curl http://localhost:7860/health

# 🔄 Reset environment
curl -X POST http://localhost:7860/reset | python -m json.tool

# 📤 Submit a repair action
curl -X POST http://localhost:7860/step \
  -H "Content-Type: application/json" \
  -d '{"repaired_json": "{\"name\": \"Alice\", \"age\": 30, \"email\": \"alice@example.com\"}", "explanation": "removed trailing comma"}'

3️⃣ Run Baseline Inference

bash

export HF_TOKEN=hf_your_token_here
export API_BASE_URL=https://api-inference.huggingface.co/v1
export MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.3
export ENV_URL=http://localhost:7860

python inference.py
# {"type": "START", "task": "json_repair_all_tasks", ...}
# {"type": "STEP",  "step": 1, "reward": 0.95, "done": false, ...}
# {"type": "END",   "success": true, "score": 0.75, ...}

4️⃣ Docker

bash

docker build -t json-repair-env .
docker run -p 7860:7860 \
  -e HF_TOKEN=hf_xxx \
  -e API_BASE_URL=https://api-inference.huggingface.co/v1 \
  -e MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.3 \
  json-repair-env

5️⃣ OpenEnv Validate

bash

pip install openenv-core
openenv validate .
# ✓ openenv.yaml valid
# ✓ /reset responds correctly
# ✓ /step responds correctly
# ✓ /state responds correctly
# ✓ All checks passed!

📁 Project Structure

json-repair-env/
│
├── 🐍 main.py          ← FastAPI server (OpenEnv endpoints)
├── 🎯 tasks.py         ← Task definitions: easy / medium / hard
├── ⚖️  grader.py        ← Deterministic reward & scoring logic
├── 🤖 inference.py     ← Baseline inference script (REQUIRED)
├── 📋 openenv.yaml     ← OpenEnv spec metadata
├── 📦 requirements.txt ← Python dependencies
├── 🐳 Dockerfile       ← Container configuration
└── 📖 README.md        ← This file

🌍 Real-World Impact

🏭  Production LLM Apps        → Self-healing JSON parsing
🔌  Function Calling Pipelines  → Reliable structured outputs
📊  Data Extraction Workflows   → Automatic error correction
🤖  Agentic Systems             → Resilient tool-call parsing

⚙️ Environment Variables

Variable	Description	Example
`API_BASE_URL`	LLM API endpoint	`https://api-inference.huggingface.co/v1`
`MODEL_NAME`	Model identifier	`mistralai/Mistral-7B-Instruct-v0.3`
`HF_TOKEN`	HuggingFace API key	`hf_xxxxxxxxxxxx`
`ENV_URL`	Environment server URL	`http://localhost:7860`

🏅 Built For

<br/>

Scaler × HuggingFace — OpenEnv Hackathon 2026

Reviewed by engineers from Meta & HuggingFace 🤗

<br/>

![GitHub](https://github.com/preethamjain275) ![HuggingFace](https://huggingface.co/preethamjain275)

<br/>

⭐ Star this repo if it helped you!

</div>