docs/PROJECT.md

PROJECT.md — Bug Triage OpenEnv Environment

Round 1 opens: April 1, 2026 | Deadline: April 7, 2026, 11:59 PM IST

---

Problem Statement

Software teams receive hundreds of bug reports daily. Manually triaging each report — classifying the bug type, assigning a priority level, routing to the right developer, and deciding the appropriate action — is slow, error-prone, and a significant cost to engineering velocity.

This environment trains an LLM agent to perform automated bug triage at production scale, simulating real-world issue tracking systems like Jira and GitHub Issues. The agent reads raw bug reports (title, description, stack traces, metadata) and must classify, prioritize, and route each issue accurately.

---

Real-World Relevance

Dimension	Detail
Domain	Software Engineering / DevOps / Issue Tracking
Industry use	Every software company with a bug tracker (GitHub Issues, Jira, Linear, etc.)
Scale	Large teams process 100–500+ bug reports per week
Cost of wrong triage	Critical bugs missed → outages; low-priority spamming senior devs → waste
Current solutions	Manual labels, basic keyword rules, ML classifiers (limited context)
LLM advantage	Can reason over free-text descriptions, logs, and metadata together

---

Users

User	Need
Developers	Only receive bugs relevant to their specialization
QA Engineers	Know which bugs to test first (priority-ordered)
Project Managers	Accurate sprint planning based on classified backlogs
Engineering Leads	Automated triage frees team from manual label overhead

---

Example Scenario

Bug Reported:
  Title:       "App crashes on iOS 17 when uploading files > 50MB"
  Description: "Consistently crashes immediately on upload tap. Blocking 
                3 enterprise customers."
  Logs:        "FATAL: EXC_BAD_ACCESS KERN_INVALID_ADDRESS 0x0000000000000000
                Stack: FileUploadManager.upload(url:size:)"
  Environment: "iOS 17.2, iPhone 15 Pro, App v3.2.1"

Agent Must Output:
  bug_type:           crash          ← Task 1
  priority:           critical       ← Task 2
  assigned_developer: Alice          ← Task 3 (crash specialist)
  suggested_action:   fix_immediately ← Task 3

---

Real-World Constraints the Agent Must Handle

• Ambiguous descriptions — reporters with varying technical skill
• Incomplete logs — stack traces cut off or missing
• Priority inflation — reporters who label everything as "critical"
• Routing uncertainty — cross-cutting bugs (e.g., security + crash)
• Missing environment info — agent must infer from context

---

Tech Stack

Layer	Technology
Environment server	FastAPI + Uvicorn
Containerisation	Docker
Deployment	Hugging Face Spaces
Training	TRL GRPOTrainer + vLLM
Base model	Qwen/Qwen3-1.7B
Package manager	uv
Validation	Pydantic v2
Baseline LLM	OpenAI GPT-4o-mini (via OPENAI_API_KEY)

---

Repository Layout

bug_triage_env/
├── models.py             ← Pydantic-typed Action / Observation / State
├── client.py             ← HTTP client for training code
├── baseline.py           ← OpenAI-backed inference script
├── openenv.yaml          ← Manifest
├── pyproject.toml
├── requirements.txt
├── data/
│   └── bugs.json         ← 15 diverse real-world bug reports
├── graders/
│   ├── task1_grader.py   ← Bug type classification [0.0–1.0]
│   ├── task2_grader.py   ← Priority assignment [0.0–1.0]
│   └── task3_grader.py   ← Full triage [0.0–1.0]
└── server/
    ├── environment.py    ← OpenEnv Environment ABC implementation
    ├── app.py            ← FastAPI (standard + hackathon endpoints)
    └── Dockerfile

---

Hackathon Compliance Checklist

Requirement	Status
HF Space deploys + /reset returns 200	☐
openenv.yaml present	☐
Typed models (Action, Observation, State)	☐
step() / reset() / state() implemented	☐
Dockerfile builds	☐
/tasks — task list + action schema	☐
/grader — score in [0.0, 1.0]	☐
/baseline — OpenAI inference, all 3 tasks	☐
3+ graded tasks with varying scores	☐
baseline.py runs without error	☐