README.md

metadata

title: Smart Sprint Planner
emoji: 🗂️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860

Smart Sprint Planner

Real-world OpenEnv environment for agile sprint planning and dynamic replanning.

Core pipeline: audio or transcript -> extraction -> JIRA-style tickets -> developer assignments -> dynamic disruptions -> reward and grading

This repository is aligned to the Round 1 competition requirements captured in context_scaler.txt.

Environment Summary

The environment simulates a real planning workflow an engineering manager, scrum lead, or delivery lead would actually perform:

• convert planning discussion into structured tasks
• assign work under team capacity constraints
• respond to urgent work, capacity loss, and dependency changes
• maximize completion, timeliness, workload balance, and adaptability

This is intended as a real-world planning and replanning environment, not a toy game.

Tasks And Difficulty

There are 3 graded tasks:

• easy Static sprint planning. Fixed backlog, fixed capacity, fixed deadlines.
• medium One disruption event. Usually urgent work or a developer capacity loss.
• hard Multiple disruptions over time. New work, dependency shifts, and changing capacity.

Difficulty represents volatility, not just more tickets.

Project Flow

1. env/transcription.py Handles audio-to-text or accepts provided transcript text.
2. env/extraction.py Extracts structured work items with an LLM or deterministic fallback logic.
3. env/jira.py Converts extracted items into JIRA-style sprint tickets.
4. env/environment.py Implements reset(), step(), and state() with dynamic event handling.
5. env/graders.py Computes dense rewards and final deterministic grading in [0.0, 1.0].
6. planner.py Runs the full end-to-end pipeline and returns assignment recommendations.

Observation And Action Space

Observation includes:

• meeting text
• extracted work items
• active JIRA tickets
• developer pool
• completed task ids
• sprint day
• metrics and event history
• pending and recent disruption signals

Action is one assignment:

{
  "task_id": "T001",
  "developer_id": "D1"
}

Extraction Schema

Each extracted item can include:

• task
• description
• deadline
• priority
• category
• tags
• acceptance_criteria
• dependency_hints
• owner_hint
• urgency_reason
• raw_text

LLM extraction uses the OpenAI client when credentials are available. Otherwise the system uses a deterministic rule-based fallback for offline reproducibility.

Reward And Grading

Dense step rewards include:

• on-time completion
• specialization or skill-match reward
• priority-aware completion reward
• penalties for invalid, blocked, and over-capacity actions
• adaptation reward for disruption-created work
• future-feasibility shaping for preserving replanning options

Final grading combines:

• completion rate
• on-time rate
• extraction quality
• workload balance
• efficiency
• adaptability

All final scores are normalized to [0.0, 1.0].

Baseline Inference

The required root-level baseline script is inference.py.

It:

• uses the OpenAI client for LLM calls
• reads API_BASE_URL, MODEL_NAME, and HF_TOKEN
• also supports OPENAI_API_KEY locally
• falls back deterministically when no key is configured
• emits strict competition stdout lines:
  • [START]
  • [STEP]
  • [END]

Run one task:

python inference.py medium

Run all tasks:

python inference.py --all

Current local reproducible baseline from python inference.py --all:

• easy: 0.83
• medium: 0.73
• hard: 0.76

These are the submission-safe heuristic fallback scores in the current environment.

Learned Planner

The learned planner is trained separately and is not required for the baseline script.

• training entrypoint: train.py
• evaluation entrypoint: eval.py
• strongest checkpoint: checkpoints/best

Current held-out dataset-eval comparison for the strongest checkpoint:

• Heuristic: 0.893
• DDQN: 0.897

On the richer held-out split, the learned DDQN now slightly outperforms the heuristic overall and on hard.

Train:

python train.py --episodes 400

Evaluate:

python eval.py --checkpoint checkpoints/best --scenario-source dataset-eval

Full Pipeline

The full product-facing path is exposed through planner.py and POST /plan.

Run locally from transcript:

python planner.py --transcript "Fix the checkout bug today, then finish analytics after auth." --difficulty medium --strategy auto

auto prefers the trained DDQN checkpoint when checkpoints/best exists, and falls back to heuristic otherwise.

API Server

Start the server:

uvicorn server.app:app --reload --port 7860

Endpoints:

• GET /health
• POST /reset
• POST /step
• GET /state
• GET /render
• GET /grade
• POST /plan

Setup

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Windows:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Validation And Tests

Run tests:

pytest tests -v

Run OpenEnv validation:

.\whisper_env\Scripts\openenv.exe validate

Current local status:

• 25 tests passing
• openenv validate previously passing in the project environment
• baseline inference reproducing all 3 tasks

Docker

Build:

docker build -t smart-sprint-planner .

Run:

docker run -p 7860:7860 smart-sprint-planner

Metadata

Environment metadata lives in openenv.yaml.

Before final submission, the remaining non-code checklist is:

1. verify Docker builds on the target machine
2. verify the Hugging Face Space responds with 200
3. keep the root inference.py output unchanged
4. submit with checkpoints/best included if you want auto to use DDQN