Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=adhd_env
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check (use Python - curl may not be in base image)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,101 @@
 ---
-title: Adhd Env
-emoji: 🔥
-colorFrom: purple
-colorTo: gray
+title: ADHD Task Initiation Coaching Environment
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+app_port: 8000
+tags:
+  - openenv
+  - reinforcement-learning
+  - adhd
+  - executive-function
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ADHD Task Initiation Coaching Environment
+
+An OpenEnv environment that evaluates ADHD coaching response quality. It scores AI coaching responses for task initiation paralysis based on tool calling and response quality.
+
+**Innovation**: State tracking ("knobs") + tool calling evaluation - not just text scoring.
+
+## Quick Start
+
+```python
+from adhd_env import ADHDAction, ADHDEnv
+
+# Connect to deployed environment
+with ADHDEnv(base_url="https://YOUR-SPACE.hf.space") as env:
+    # Get an ADHD scenario
+    result = env.reset()
+    print(f"Scenario: {result.observation.scenario}")
+
+    # Submit a coaching response for scoring
+    result = env.step(ADHDAction(
+        tool_calls=["adhd_task_initiation_coach"],
+        message="Open email and type just the recipient name. Stop there."
+    ))
+    print(f"Reward: {result.reward}")  # 1.0
+```
+
+## How Scoring Works
+
+The environment evaluates coaching responses on tool calling (V1):
+
+| Action | Reward | Why |
+|--------|--------|-----|
+| Called `adhd_task_initiation_coach` | **1.0** | Used the primary coaching tool |
+| Called `set_timer` or `break_down_task` | **0.5** | Valid tool, but not the primary one |
+| No tools called | **0.0** | No tool engagement |
+
+### Available Tools
+- `adhd_task_initiation_coach` - Primary coaching tool for task initiation
+- `set_timer` - Focus timers for task boxing
+- `break_down_task` - Decompose large tasks into micro-steps
+
+## API
+
+### POST /reset
+Returns a new ADHD scenario with user state.
+
+### POST /step
+Scores a coaching response. Body: `{"action": {"tool_calls": [...], "message": "..."}}`
+
+### GET /health
+Health check endpoint.
+
+### GET /schema
+JSON schemas for action and observation models.
+
+## Environment Details
+
+### ADHDAction
+- `tool_calls` (list[str]) - Tools the model would call
+- `message` (str) - The coaching response text
+
+### ADHDObservation
+- `scenario` (str) - The ADHD task initiation scenario
+- `state` (dict) - User state tracking (sitting time, energy, etc.)
+- `scoring` (dict) - Detailed scoring breakdown with explanations
+- `reward` (float) - Score 0.0-1.0
+- `done` (bool) - Episode complete flag
+
+## Development
+
+```bash
+# Install dependencies
+cd adhd_env && uv sync
+
+# Run locally
+uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+# Test
+python test_environment.py        # Direct test
+python test_environment.py --http  # HTTP test (server must be running)
+
+# Validate structure
+openenv validate --verbose
+
+# Deploy to HF Spaces
+openenv push --repo-id USERNAME/adhd-env
+```

TODO_movement_first_rubric.md

@@ -0,0 +1,101 @@
+# TODO: "Movement First" Rubric Criterion
+
+## The Ideal Response Pattern
+
+When user state indicates physical distress (slouching, long sitting, late evening),
+the OPTIMAL coaching response prioritizes body movement BEFORE task work:
+
+> "Before you do anything else, get up and move your body. Maybe get a drink of water,
+> go outside and touch grass, go split some wood. When you come back I will have some
+> questions for you."
+
+Then it calls `adhd_coach_tool` to set up the follow-up interaction for when they return.
+
+This should be rewarded very heavily — it's the best possible ADHD coaching response
+for these states.
+
+## State Triggers (any of these)
+
+- `position_in_chair == "slouching"`
+- `minutes_since_last_stood >= 60`
+- Late evening: hour >= 20
+
+## What Makes This Response Pattern Unique
+
+It has THREE parts, all present together:
+1. **Movement-first priority** — "before anything else", "first", "before you start"
+2. **Physical activity suggestions** — water, outside, walk, fresh air, move your body, stretch
+3. **Promise of return/continuation** — "when you come back", "after that we'll", "then I'll help"
+
+Plus: calls `adhd_coach_tool` (to prepare the follow-up)
+
+## Brainstorm: First-Cut Keyword Approach
+
+Could score this without an LLM judge by checking for all 3 categories:
+
+```python
+def score_movement_first(action, user_state) -> float:
+    """Heavy bonus when response prioritizes movement before task work."""
+    # Only triggers when state warrants it
+    needs_movement = (
+        user_state.get("position_in_chair") == "slouching"
+        or user_state.get("minutes_since_last_stood", 0) >= 60
+        or int(user_state.get("time_of_day", "12:00").split(":")[0]) >= 20
+    )
+    if not needs_movement:
+        return 0.0  # not applicable, no bonus
+
+    msg = action.message.lower()
+
+    # Category 1: Prioritizes movement BEFORE task
+    priority_words = ["before", "first", "before anything", "step away", "stop"]
+
+    # Category 2: Physical activity
+    activity_words = ["water", "outside", "walk", "fresh air", "move", "body",
+                      "stretch", "drink", "grass", "sunshine", "exercise"]
+
+    # Category 3: Promise to continue after
+    return_words = ["come back", "when you return", "after that", "then we",
+                    "then i", "ready", "waiting", "here for you"]
+
+    has_priority = any(w in msg for w in priority_words)
+    has_activity = any(w in msg for w in activity_words)
+    has_return = any(w in msg for w in return_words)
+
+    if has_priority and has_activity and has_return:
+        return 1.0   # full bonus — all 3 parts present
+    elif has_priority and has_activity:
+        return 0.6   # good — movement first but no return promise
+    elif has_activity:
+        return 0.3   # mentions movement but doesn't prioritize it
+    return 0.0
+```
+
+### How to integrate into rubric weights
+
+Option A: Add as 4th criterion, rebalance weights:
+- tool_calling: 30%, state_awareness: 20%, adhd_relevance: 20%, movement_first: 30%
+
+Option B: Make it a multiplier/bonus on top of existing score:
+- If movement_first triggers fully, multiply final score by 1.5 (before clamp)
+
+Option C: Replace state_awareness with this (it's a superset):
+- This IS state awareness, just the most important kind
+
+## Limitations of Keyword Approach
+
+- Can't tell if the response ACTUALLY prioritizes movement vs just mentioning it
+- "Don't walk away from your task" would false-positive on "walk" and "away"
+- Can't evaluate the QUALITY or tone of the suggestion
+- Can't tell if the return promise is genuine coaching setup vs throwaway
+
+## Future: LLM-as-Judge
+
+For a proper implementation, we'd want an LLM judge that evaluates:
+1. Does the response prioritize physical wellbeing over task completion?
+2. Does it give concrete physical activity suggestions (not just "take a break")?
+3. Does it promise meaningful follow-up (not just dismissing the user)?
+4. Is the tone encouraging rather than prescriptive?
+
+Could use a small model (SmolLM3-3B) as judge with a rubric prompt.
+Trade-off: slower scoring, but much more accurate for this nuanced criterion.

__init__.py

@@ -0,0 +1,10 @@
+"""ADHD Task Initiation Coaching Evaluation Environment."""
+
+from .client import ADHDEnv
+from .models import ADHDAction, ADHDObservation
+
+__all__ = [
+    "ADHDAction",
+    "ADHDObservation",
+    "ADHDEnv",
+]

client.py

@@ -0,0 +1,59 @@
+"""ADHD Environment Client.
+
+Connects to an ADHD coaching evaluation environment server via WebSocket.
+"""
+
+from typing import Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+from openenv.core import EnvClient
+
+from .models import ADHDAction, ADHDObservation
+
+
+class ADHDEnv(EnvClient[ADHDAction, ADHDObservation]):
+    """Client for the ADHD Task Initiation Coaching Environment.
+
+    Example:
+        >>> with ADHDEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.scenario)
+        ...
+        ...     result = client.step(ADHDAction(
+        ...         tool_calls=["adhd_task_initiation_coach"],
+        ...         message="Open email and type just the recipient name."
+        ...     ))
+        ...     print(f"Reward: {result.reward}")
+    """
+
+    def _step_payload(self, action: ADHDAction) -> Dict:
+        """Convert ADHDAction to JSON payload."""
+        return {
+            "tool_calls": action.tool_calls,
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[ADHDObservation]:
+        """Parse server response into StepResult."""
+        obs_data = payload.get("observation", {})
+        observation = ADHDObservation(
+            scenario=obs_data.get("scenario", ""),
+            state=obs_data.get("state", {}),
+            scoring=obs_data.get("scoring", {}),
+            done=payload.get("done", False),
+            reward=payload.get("reward", 0.0),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", 0.0),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """Parse server response into State object."""
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

models.py

@@ -0,0 +1,47 @@
+"""Data models for the ADHD Task Initiation Coaching Environment."""
+
+from pydantic import Field
+from typing import List, Dict, Any
+
+from openenv.core.env_server.types import Action, Observation
+
+
+class ADHDAction(Action):
+    """Action: Tool calls + coaching response to evaluate.
+
+    Models submit tool_calls (which tools they'd invoke) and a message
+    (the coaching response text) for scoring.
+    """
+
+    tool_calls: List[str] = Field(
+        default_factory=list,
+        description="Tools called by the model (e.g., ['adhd_task_initiation_coach'])",
+    )
+    message: str = Field(
+        default="",
+        description="The coaching response text",
+    )
+
+
+class ADHDObservation(Observation):
+    """Observation: ADHD scenario + user state.
+
+    Returned from reset() with the scenario and state.
+    Returned from step() with the scored reward and scoring details.
+    Note: done, reward, metadata are inherited from Observation base class.
+    Note: OpenEnv's serialize_observation excludes 'metadata' from HTTP responses,
+    so we use a custom 'scoring' field for scoring details.
+    """
+
+    scenario: str = Field(
+        default="",
+        description="The task initiation scenario (user utterance)",
+    )
+    state: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="User state tracking (sitting time, energy, etc.)",
+    )
+    scoring: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Scoring breakdown and explanation (visible in HTTP responses)",
+    )

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: adhd_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_adhd_env.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: openenv-adhd_env
+Version: 0.1.0
+Summary: Adhd Env environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_adhd_env.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+./reward.py
+openenv_adhd_env.egg-info/PKG-INFO
+openenv_adhd_env.egg-info/SOURCES.txt
+openenv_adhd_env.egg-info/dependency_links.txt
+openenv_adhd_env.egg-info/entry_points.txt
+openenv_adhd_env.egg-info/requires.txt
+openenv_adhd_env.egg-info/top_level.txt
+server/__init__.py
+server/adhd_env_environment.py
+server/app.py

openenv_adhd_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_adhd_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = adhd_env.server.app:main

openenv_adhd_env.egg-info/requires.txt

@@ -0,0 +1,5 @@
+openenv-core[core]>=0.2.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_adhd_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+adhd_env

pyproject.toml

@@ -0,0 +1,46 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-adhd_env"
+version = "0.1.0"
+description = "Adhd Env environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.0",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m adhd_env.server.app
+server = "adhd_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["adhd_env", "adhd_env.server"]
+package-dir = { "adhd_env" = ".", "adhd_env.server" = "server" }

reward.py

@@ -0,0 +1,164 @@
+"""Reward scoring for ADHD coaching environment.
+
+V2: Rubric-based scoring with tool calling + state awareness.
+- Tool calling: 40% weight - penalizes wrong-domain tools
+- State awareness: 30% weight - rewards state-responsive coaching
+- ADHD relevance: 30% weight - rewards directive, low-cognitive-load responses
+"""
+
+from typing import Dict, Any, Optional
+from models import ADHDAction
+
+
+# ADHD-domain tools
+ADHD_TOOLS = {"adhd_coach_tool"}
+
+
+def score_tool_calling(
+    action: ADHDAction,
+    is_adhd_scenario: bool,
+    expected_tool: Optional[str] = None,
+) -> float:
+    """Score tool selection based on scenario type.
+
+    ADHD scenario:
+        1.0  - called adhd_coach_tool
+        0.0  - no tools called
+       -0.5  - called a non-ADHD tool (wrong domain)
+
+    Non-ADHD scenario:
+       -0.5  - called adhd_coach_tool (wrong domain)
+        0.7  - called the expected non-ADHD tool
+        0.5  - no tools called (neutral)
+        0.5  - called some other non-ADHD tool (neutral)
+    """
+    called = set(action.tool_calls)
+
+    if is_adhd_scenario:
+        if "adhd_coach_tool" in called:
+            return 1.0
+        if not called:
+            return 0.0
+        # Called non-ADHD tool on ADHD scenario
+        return -0.5
+    else:
+        # Non-ADHD scenario
+        if "adhd_coach_tool" in called:
+            return -0.5
+        if expected_tool and expected_tool in called:
+            return 0.7
+        # No tool or some other non-ADHD tool - neutral
+        return 0.5
+
+
+def score_state_awareness(action: ADHDAction, user_state: dict) -> float:
+    """Score whether response accounts for user state.
+
+    1.0 - mentions movement/stretching when sitting 60+ min or slouching
+    1.0 - suggests simpler tasks when evening (hour >= 20)
+    0.5 - generic response (default, neutral)
+    """
+    msg = action.message.lower()
+    score = 0.5  # default neutral
+
+    minutes_sitting = user_state.get("minutes_since_last_stood", 0)
+    position = user_state.get("position_in_chair", "normal")
+    time_str = user_state.get("time_of_day", "12:00")
+    hour = int(time_str.split(":")[0])
+
+    movement_keywords = [
+        "stand", "stretch", "walk", "move", "get up", "posture",
+        "take a break", "step away", "physical",
+    ]
+
+    # Reward movement suggestions when sitting too long or slouching
+    if minutes_sitting >= 60 or position == "slouching":
+        if any(kw in msg for kw in movement_keywords):
+            score = 1.0
+
+    # Reward simpler task suggestions in the evening
+    evening_keywords = [
+        "simple", "small", "easy", "quick", "short", "wind down",
+        "rest", "tomorrow", "lighter",
+    ]
+    if hour >= 20:
+        if any(kw in msg for kw in evening_keywords):
+            score = 1.0
+
+    return score
+
+
+def score_adhd_relevance(action: ADHDAction, is_adhd_scenario: bool) -> float:
+    """Score ADHD-specific response quality.
+
+    For ADHD scenarios: rewards concise responses and reflective questions.
+    For non-ADHD: returns neutral 0.5.
+    """
+    if not is_adhd_scenario:
+        return 0.5
+
+    msg = action.message.strip()
+    if not msg:
+        return 0.0
+
+    score = 0.5  # baseline
+    msg_lower = msg.lower()
+
+    # Reward reflective/clarifying questions that prompt self-reflection
+    if "?" in msg:
+        question_words = ("what", "how")
+        reflective_words = ("specific", "detail", "details", "feeling", "think", "reflect", "explain")
+        if any(qw in msg_lower for qw in question_words) and any(rw in msg_lower for rw in reflective_words):
+            score += 0.15
+
+    # Reward concise responses (under 100 words = lower cognitive load)
+    word_count = len(msg.split())
+    if 5 <= word_count <= 50:
+        score += 0.25
+    elif word_count > 100:
+        score -= 0.25  # too long, high cognitive load
+
+    return max(0.0, min(1.0, score))
+
+
+def score_rubric(
+    action: ADHDAction,
+    scenario: str,
+    user_state: dict,
+    is_adhd_scenario: bool,
+    expected_tool: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Combined rubric score with per-criterion breakdown.
+
+    Weights: tool_calling 40% + state_awareness 30% + adhd_relevance 30%
+    Total clamped to 0.0-1.0.
+    """
+    tool_score = score_tool_calling(action, is_adhd_scenario, expected_tool)
+    state_score = score_state_awareness(action, user_state)
+    relevance_score = score_adhd_relevance(action, is_adhd_scenario)
+
+    raw_total = (tool_score * 0.4) + (state_score * 0.3) + (relevance_score * 0.3)
+    total = max(0.0, min(1.0, raw_total))
+
+    return {
+        "version": "v2.1",
+        "total_score": round(total, 3),
+        "criteria": {
+            "tool_calling": {
+                "score": tool_score,
+                "weight": 0.4,
+                "is_adhd_scenario": is_adhd_scenario,
+                "expected_tool": expected_tool,
+                "tools_called": action.tool_calls,
+            },
+            "state_awareness": {
+                "score": state_score,
+                "weight": 0.3,
+                "user_state": user_state,
+            },
+            "adhd_relevance": {
+                "score": relevance_score,
+                "weight": 0.3,
+            },
+        },
+    }

server/__init__.py

@@ -0,0 +1,5 @@
+"""ADHD environment server components."""
+
+from .adhd_env_environment import ADHDEnvironment
+
+__all__ = ["ADHDEnvironment"]

server/adhd_env_environment.py

@@ -0,0 +1,135 @@
+"""ADHD Task Initiation Coaching Evaluation Environment.
+
+Evaluates ADHD coaching responses by scoring tool calling and response quality.
+V2: Multiple scenarios, state tracking, rubric-based scoring.
+"""
+
+import random
+from typing import Optional
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+from models import ADHDAction, ADHDObservation
+from reward import score_rubric
+
+
+# ADHD task initiation scenarios
+ADHD_SCENARIOS = [
+    "I can't start writing the email to my manager",
+    "I've been staring at this blank document for 30 minutes",
+    "I need to make a phone call but I keep putting it off",
+    "I'm stuck on starting this presentation",
+    "I've been avoiding this report all day",
+    "I don't know how to begin this project proposal",
+    "I keep switching tabs instead of starting my work",
+    "I'm overwhelmed by this task list",
+    "I can't focus on writing this code review",
+    "I've been procrastinating on this assignment for hours",
+]
+
+# Non-ADHD scenarios: (prompt, expected_tool or None)
+NON_ADHD_SCENARIOS = [
+    ("What's the weather like today?", "web_search_tool"),
+    ("What is the latest revenue for IBM?", "web_search_tool"),
+    ("What is the capital of France?", "web_search_tool"),
+    ("Write me a poem about cats", None),
+    ("Translate this sentence to Spanish", None),
+]
+
+
+def generate_user_state() -> dict:
+    """Generate randomized user state (the 'knobs')."""
+    hour = random.randint(6, 22)
+    minute = random.randint(0, 59)
+    return {
+        "time_of_day": f"{hour:02d}:{minute:02d}",
+        "position_in_chair": random.choice(["normal", "slouching", "standing"]),
+        "minutes_since_last_stood": random.randint(0, 240),
+    }
+
+
+class ADHDEnvironment(Environment):
+    """ADHD Task Initiation Coaching Evaluation Environment.
+
+    Evaluates coaching responses for ADHD task initiation paralysis.
+    Innovation: state tracking + tool calling evaluation.
+
+    V2: Multiple scenarios, state tracking, rubric-based scoring.
+    - 10 ADHD scenarios + 5 non-ADHD scenarios
+    - 3 state variables (time_of_day, position_in_chair, minutes_since_last_stood)
+    - Rubric with tool calling + state awareness scoring
+
+    Single-turn: reset() -> step() -> done=True
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.current_scenario: str = ""
+        self.current_user_state: dict = {}
+        self.is_adhd_scenario: bool = True
+        self.expected_tool: Optional[str] = None
+
+    def reset(self) -> ADHDObservation:
+        """Generate new episode with randomized scenario and user state."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.current_user_state = generate_user_state()
+
+        # Pick ADHD 80% / non-ADHD 20%
+        if random.random() < 0.7:
+            self.current_scenario = random.choice(ADHD_SCENARIOS)
+            self.is_adhd_scenario = True
+            self.expected_tool = "adhd_coach_tool"
+        else:
+            scenario_tuple = random.choice(NON_ADHD_SCENARIOS)
+            self.current_scenario = scenario_tuple[0]
+            self.is_adhd_scenario = False
+            self.expected_tool = scenario_tuple[1]
+
+        return ADHDObservation(
+            scenario=self.current_scenario,
+            state=self.current_user_state,
+            done=False,
+            reward=0.0,
+            scoring={
+                "version": "v2.1",
+                "available_tools": [
+                    "adhd_coach_tool",
+                    "web_search_tool",
+                ],
+            },
+        )
+
+    def step(self, action: ADHDAction) -> ADHDObservation:  # type: ignore[override]
+        """Score a coaching response.
+
+        Single-turn: returns done=True after scoring.
+        """
+        self._state.step_count += 1
+
+        scoring = score_rubric(
+            action,
+            self.current_scenario,
+            self.current_user_state,
+            self.is_adhd_scenario,
+            self.expected_tool,
+        )
+        scoring["action"] = {
+            "tool_calls": action.tool_calls,
+            "message": action.message,
+        }
+
+        return ADHDObservation(
+            scenario=self.current_scenario,
+            state=self.current_user_state,
+            done=True,
+            reward=scoring["total_score"],
+            scoring=scoring,
+        )
+
+    @property
+    def state(self) -> State:
+        return self._state

server/app.py

@@ -0,0 +1,33 @@
+"""FastAPI application for the ADHD Coaching Environment.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000
+"""
+
+from openenv.core.env_server.http_server import create_app
+
+from models import ADHDAction, ADHDObservation
+from .adhd_env_environment import ADHDEnvironment
+
+app = create_app(
+    ADHDEnvironment,
+    ADHDAction,
+    ADHDObservation,
+    env_name="adhd_env",
+    max_concurrent_envs=1,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """Entry point for: uv run --project . server"""
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

test_environment.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Test script for the ADHD coaching environment.
+
+Tests the environment directly (no server needed) and via HTTP if a server is running.
+
+Usage:
+    # Direct test (no server):
+    cd adhd_env && .venv/bin/python test_environment.py
+
+    # With server running:
+    cd adhd_env && .venv/bin/uvicorn server.app:app --host 0.0.0.0 --port 8000 &
+    cd adhd_env && .venv/bin/python test_environment.py --http
+"""
+
+import sys
+
+
+def test_direct():
+    """Test environment directly without HTTP server."""
+    from server.adhd_env_environment import ADHDEnvironment
+    from models import ADHDAction
+
+    env = ADHDEnvironment()
+    print("=" * 60)
+    print("DIRECT ENVIRONMENT TEST")
+    print("=" * 60)
+
+    # Test reset returns valid state
+    obs = env.reset()
+    print(f"\n--- Reset ---")
+    print(f"Scenario: {obs.scenario}")
+    print(f"State: {obs.state}")
+    print(f"Done: {obs.done}")
+    print(f"Reward: {obs.reward}")
+
+    assert obs.scenario, "Scenario should not be empty"
+    assert obs.done is False
+    assert obs.reward == 0.0
+
+    # Validate state has all 3 keys
+    assert "time_of_day" in obs.state, "Missing time_of_day"
+    assert "position_in_chair" in obs.state, "Missing position_in_chair"
+    assert "minutes_since_last_stood" in obs.state, "Missing minutes_since_last_stood"
+    assert obs.state["position_in_chair"] in ("normal", "slouching", "standing")
+    assert 0 <= obs.state["minutes_since_last_stood"] <= 240
+    print("State validation: PASS")
+
+    # Variety check: reset 10x and verify we get at least 2 distinct states
+    states = []
+    for _ in range(10):
+        o = env.reset()
+        states.append(
+            (o.state["time_of_day"], o.state["position_in_chair"], o.state["minutes_since_last_stood"])
+        )
+    unique_states = len(set(states))
+    assert unique_states >= 2, f"Expected at least 2 distinct states, got {unique_states}"
+    print(f"State variety check ({unique_states} unique in 10 resets): PASS")
+
+    print(f"\n{'=' * 60}")
+    print("ALL DIRECT TESTS PASSED")
+    print(f"{'=' * 60}")
+
+
+def test_rubric():
+    """Test rubric scoring with positive and negative cases."""
+    from server.adhd_env_environment import ADHDEnvironment
+    from models import ADHDAction
+    from reward import score_rubric
+
+    print(f"\n{'=' * 60}")
+    print("RUBRIC TEST")
+    print(f"{'=' * 60}")
+
+    # State where user has been sitting a long time and is slouching
+    tired_state = {
+        "time_of_day": "14:00",
+        "position_in_chair": "slouching",
+        "minutes_since_last_stood": 90,
+    }
+
+    evening_state = {
+        "time_of_day": "21:00",
+        "position_in_chair": "normal",
+        "minutes_since_last_stood": 30,
+    }
+
+    # POSITIVE: ADHD scenario + primary tool + state-aware message
+    action_good = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="Stand up and stretch for 30 seconds, then type just the recipient name.",
+    )
+    result = score_rubric(action_good, "I can't start the email", tired_state, True, None)
+    print(f"\nPOSITIVE (ADHD + primary tool + state-aware): {result['total_score']}")
+    assert result["total_score"] >= 0.7, f"Expected >= 0.7, got {result['total_score']}"
+    print("PASS")
+
+    # NEGATIVE: ADHD scenario + wrong-domain tool
+    action_wrong_tool = ADHDAction(
+        tool_calls=["web_search_tool"],
+        message="Let me search for tips on email writing.",
+    )
+    result = score_rubric(action_wrong_tool, "I can't start the email", tired_state, True, None)
+    print(f"\nNEGATIVE (ADHD + web_search_tool): {result['total_score']}")
+    assert result["total_score"] < 0.3, f"Expected < 0.3, got {result['total_score']}"
+    print("PASS")
+
+    # NEGATIVE: Non-ADHD scenario + ADHD tool
+    action_adhd_on_non = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="Let me help you initiate that task.",
+    )
+    result = score_rubric(action_adhd_on_non, "What's the weather?", tired_state, False, "web_search_tool")
+    print(f"\nNEGATIVE (non-ADHD + ADHD tool): {result['total_score']}")
+    assert result["total_score"] < 0.3, f"Expected < 0.3, got {result['total_score']}"
+    print("PASS")
+
+    # SLIGHTLY POSITIVE: Non-ADHD factual + correct tool
+    action_correct_non_adhd = ADHDAction(
+        tool_calls=["web_search_tool"],
+        message="Let me look that up for you.",
+    )
+    result = score_rubric(action_correct_non_adhd, "What is the capital of France?", tired_state, False, "web_search_tool")
+    print(f"\nSLIGHTLY POSITIVE (non-ADHD + correct tool): {result['total_score']}")
+    assert result["total_score"] >= 0.5, f"Expected >= 0.5, got {result['total_score']}"
+    print("PASS")
+
+    # NEUTRAL: Non-ADHD creative + no tool
+    action_no_tool_creative = ADHDAction(
+        tool_calls=[],
+        message="Here is a poem about cats.",
+    )
+    result = score_rubric(action_no_tool_creative, "Write me a poem about cats", tired_state, False, None)
+    print(f"\nNEUTRAL (non-ADHD creative + no tool): {result['total_score']}")
+    assert 0.3 <= result["total_score"] <= 0.7, f"Expected 0.3-0.7, got {result['total_score']}"
+    print("PASS")
+
+    # MEDIUM: ADHD + primary tool + generic message (no state awareness)
+    action_generic = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="Try breaking this task into smaller pieces.",
+    )
+    result = score_rubric(action_generic, "I'm stuck on this report", tired_state, True, None)
+    print(f"\nMEDIUM (ADHD + primary tool + generic): {result['total_score']}")
+    assert 0.4 <= result["total_score"] <= 0.85, f"Expected 0.4-0.85, got {result['total_score']}"
+    print("PASS")
+
+    # EVENING: ADHD + primary tool + evening-aware message
+    action_evening = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="It's late. Pick a small easy task to finish tonight, save the rest for tomorrow.",
+    )
+    result = score_rubric(action_evening, "I can't focus on this", evening_state, True, None)
+    print(f"\nEVENING AWARE (ADHD + primary tool + evening tips): {result['total_score']}")
+    assert result["total_score"] >= 0.7, f"Expected >= 0.7, got {result['total_score']}"
+    print("PASS")
+
+    # REFLECTIVE QUESTION: ADHD + primary tool + clarifying question
+    action_reflective = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="What are you specifically stuck on? Explain the first step you think you need to take.",
+    )
+    result_reflective = score_rubric(action_reflective, "I've been stuck for 30 minutes", tired_state, True, None)
+    # Compare against same scenario with generic non-reflective message
+    action_plain = ADHDAction(
+        tool_calls=["adhd_coach_tool"],
+        message="Just try to get started on it.",
+    )
+    result_plain = score_rubric(action_plain, "I've been stuck for 30 minutes", tired_state, True, None)
+    print(f"\nREFLECTIVE Q (ADHD + primary tool + clarifying question): {result_reflective['total_score']}")
+    print(f"  vs PLAIN (ADHD + primary tool + generic): {result_plain['total_score']}")
+    assert result_reflective["total_score"] > result_plain["total_score"], \
+        f"Reflective question should score higher than plain: {result_reflective['total_score']} vs {result_plain['total_score']}"
+    print("PASS")
+
+    print(f"\n{'=' * 60}")
+    print("ALL RUBRIC TESTS PASSED")
+    print(f"{'=' * 60}")
+
+
+def test_http(base_url="http://localhost:8000"):
+    """Test environment via HTTP endpoints."""
+    import requests
+
+    print(f"\n{'=' * 60}")
+    print(f"HTTP TEST ({base_url})")
+    print(f"{'=' * 60}")
+
+    # Health check
+    r = requests.get(f"{base_url}/health")
+    assert r.status_code == 200
+    print(f"\nHealth: {r.json()}")
+
+    # Schema
+    r = requests.get(f"{base_url}/schema")
+    assert r.status_code == 200
+    schema = r.json()
+    assert "action" in schema
+    assert "observation" in schema
+    print(f"Schema: action has {list(schema['action']['properties'].keys())}")
+    print(f"Schema: observation has {list(schema['observation']['properties'].keys())}")
+
+    # Reset
+    r = requests.post(f"{base_url}/reset")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["done"] is False
+    assert data["reward"] == 0.0
+    assert "scenario" in data["observation"]
+    obs = data["observation"]
+    assert "state" in obs
+    assert "time_of_day" in obs["state"]
+    assert "position_in_chair" in obs["state"]
+    assert "minutes_since_last_stood" in obs["state"]
+    print(f"\nReset: scenario='{obs['scenario']}'")
+    print(f"  state={obs['state']}")
+    print(f"  State keys present: PASS")
+
+    # Good action (ADHD scenario + primary tool)
+    r = requests.post(f"{base_url}/step", json={
+        "action": {
+            "tool_calls": ["adhd_coach_tool"],
+            "message": "Stand up and stretch, then type just the recipient name.",
+        }
+    })
+    assert r.status_code == 200
+    data = r.json()
+    assert data["done"] is True
+    assert data["reward"] > 0
+    print(f"Good action: reward={data['reward']} PASS")
+
+    # Bad action (no tools on presumed ADHD scenario)
+    r = requests.post(f"{base_url}/step", json={
+        "action": {
+            "tool_calls": [],
+            "message": "What do you want to work on?",
+        }
+    })
+    assert r.status_code == 200
+    data = r.json()
+    print(f"No-tool action: reward={data['reward']}")
+
+    # Verify scoring details in response
+    assert "scoring" in data["observation"]
+    assert "total_score" in data["observation"]["scoring"]
+    assert "criteria" in data["observation"]["scoring"]
+    print(f"Scoring details present: PASS")
+
+    print(f"\n{'=' * 60}")
+    print("ALL HTTP TESTS PASSED")
+    print(f"{'=' * 60}")
+
+
+if __name__ == "__main__":
+    test_direct()
+    test_rubric()
+
+    if "--http" in sys.argv:
+        url = "http://localhost:8000"
+        for arg in sys.argv:
+            if arg.startswith("http"):
+                url = arg
+        test_http(url)

test_with_model.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""End-to-end test: LLM with tool calling -> ADHD environment scoring.
+
+Tests whether LLMs pick the correct tools for ADHD vs non-ADHD scenarios,
+and scores their responses using the environment's rubric.
+
+Usage:
+    cd adhd_env && .venv/bin/python test_with_model.py
+    cd adhd_env && .venv/bin/python test_with_model.py --model Qwen/Qwen3.5-9B
+    cd adhd_env && .venv/bin/python test_with_model.py --all
+
+Requires HF_TOKEN environment variable.
+"""
+
+import argparse
+import os
+import sys
+
+from openai import OpenAI
+
+from models import ADHDAction
+from reward import score_rubric
+
+MODELS = [
+    "HuggingFaceTB/SmolLM3-3B",
+    "Qwen/Qwen3.5-9B",
+    "allenai/OLMo-3-7B-Instruct",
+]
+
+# Tool definitions the LLM sees
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "adhd_assist_tool",
+            "description": (
+                "Help a user with ADHD task initiation paralysis. "
+                "Use when someone is stuck starting a task, procrastinating, "
+                "or overwhelmed by executive function challenges."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "coaching_message": {
+                        "type": "string",
+                        "description": "The coaching response to help the user start their task.",
+                    }
+                },
+                "required": ["coaching_message"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "web_search_tool",
+            "description": (
+                "Search the web for information. Use for general knowledge questions, "
+                "weather, facts, latest news, etc."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "The search query.",
+                    }
+                },
+                "required": ["query"],
+            },
+        },
+    },
+]
+
+# LLM tool name -> environment tool name
+TOOL_NAME_MAP = {
+    "adhd_assist_tool": "adhd_coach_tool",
+    "web_search_tool": "web_search_tool",
+}
+
+# Test cases: (scenario, user_state, is_adhd, expected_tool, expected_llm_tool, description)
+TEST_CASES = [
+    {
+        "scenario": "I can't start writing the email to my manager",
+        "user_state": {"time_of_day": "10:00", "position_in_chair": "normal", "minutes_since_last_stood": 30},
+        "is_adhd": True,
+        "expected_tool": None,
+        "expected_llm_tool": "adhd_assist_tool",
+        "description": "ADHD task initiation - should use adhd_assist_tool",
+    },
+    {
+        "scenario": "What's the weather like today?",
+        "user_state": {"time_of_day": "12:00", "position_in_chair": "normal", "minutes_since_last_stood": 15},
+        "is_adhd": False,
+        "expected_tool": "web_search_tool",
+        "expected_llm_tool": "web_search_tool",
+        "description": "Weather question - should use web_search_tool",
+    },
+    {
+        "scenario": "I've been procrastinating on this assignment for hours and I'm exhausted",
+        "user_state": {"time_of_day": "21:30", "position_in_chair": "slouching", "minutes_since_last_stood": 120},
+        "is_adhd": True,
+        "expected_tool": None,
+        "expected_llm_tool": "adhd_assist_tool",
+        "description": "Evening ADHD with fatigue - should use adhd_assist_tool",
+    },
+    {
+        "scenario": "Write me a poem about cats",
+        "user_state": {"time_of_day": "14:00", "position_in_chair": "normal", "minutes_since_last_stood": 20},
+        "is_adhd": False,
+        "expected_tool": None,
+        "expected_llm_tool": None,
+        "description": "Creative request - should NOT use adhd_assist_tool",
+    },
+]
+
+
+def call_model(client: OpenAI, model: str, scenario: str, user_state: dict) -> dict:
+    """Send scenario to LLM and parse tool call response."""
+    system_prompt = (
+        "You are a helpful assistant. You have access to tools. "
+        "Use the appropriate tool when the user's request matches a tool's purpose. "
+        "If no tool is appropriate, respond directly without calling any tool.\n\n"
+        f"User context: time={user_state['time_of_day']}, "
+        f"position={user_state['position_in_chair']}, "
+        f"minutes since last stood={user_state['minutes_since_last_stood']}"
+    )
+
+    try:
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": scenario},
+            ],
+            tools=TOOLS,
+            tool_choice="auto",
+            max_tokens=256,
+        )
+    except Exception as e:
+        return {"error": str(e), "tool_calls": [], "message": ""}
+
+    msg = response.choices[0].message
+    tool_calls_raw = msg.tool_calls or []
+
+    # Map LLM tool names to environment tool names
+    env_tool_calls = []
+    llm_tool_names = []
+    for tc in tool_calls_raw:
+        llm_tool_names.append(tc.function.name)
+        env_name = TOOL_NAME_MAP.get(tc.function.name, tc.function.name)
+        env_tool_calls.append(env_name)
+
+    # Extract message from tool args or content
+    message = msg.content or ""
+    if not message and tool_calls_raw:
+        import json
+        try:
+            args = json.loads(tool_calls_raw[0].function.arguments)
+            message = args.get("coaching_message", args.get("query", ""))
+        except (json.JSONDecodeError, IndexError):
+            pass
+
+    return {
+        "tool_calls": env_tool_calls,
+        "llm_tool_names": llm_tool_names,
+        "message": message,
+        "error": None,
+    }
+
+
+def run_model_tests(client: OpenAI, model: str) -> dict:
+    """Run all test cases against a model and return results."""
+    print(f"\n{'=' * 60}")
+    print(f"MODEL: {model}")
+    print(f"{'=' * 60}")
+
+    correct = 0
+    total = len(TEST_CASES)
+    total_reward = 0.0
+    results = []
+
+    for i, tc in enumerate(TEST_CASES):
+        print(f"\n--- Test {i+1}: {tc['description']} ---")
+        print(f"  Scenario: {tc['scenario']}")
+
+        resp = call_model(client, model, tc["scenario"], tc["user_state"])
+
+        if resp.get("error"):
+            print(f"  ERROR: {resp['error']}")
+            results.append({"test": i+1, "error": resp["error"]})
+            continue
+
+        print(f"  LLM tools: {resp['llm_tool_names']}")
+        print(f"  Message: {resp['message'][:80]}...")
+
+        # Score with environment rubric
+        action = ADHDAction(tool_calls=resp["tool_calls"], message=resp["message"])
+        scoring = score_rubric(
+            action, tc["scenario"], tc["user_state"],
+            tc["is_adhd"], tc["expected_tool"],
+        )
+        reward = scoring["total_score"]
+        total_reward += reward
+
+        # Check if LLM picked the right tool
+        llm_picked = resp["llm_tool_names"][0] if resp["llm_tool_names"] else None
+        expected = tc["expected_llm_tool"]
+
+        if expected is None:
+            # For "no tool expected", correct if didn't pick adhd_assist_tool
+            tool_correct = llm_picked != "adhd_assist_tool"
+        else:
+            tool_correct = llm_picked == expected
+
+        if tool_correct:
+            correct += 1
+
+        status = "CORRECT" if tool_correct else "WRONG"
+        print(f"  Tool choice: {status} (picked={llm_picked}, expected={expected})")
+        print(f"  Reward: {reward}")
+        results.append({
+            "test": i+1,
+            "tool_correct": tool_correct,
+            "reward": reward,
+            "picked": llm_picked,
+            "expected": expected,
+        })
+
+    avg_reward = total_reward / total if total > 0 else 0
+    print(f"\n--- Summary for {model} ---")
+    print(f"  Tool accuracy: {correct}/{total}")
+    print(f"  Avg reward: {avg_reward:.3f}")
+
+    return {
+        "model": model,
+        "correct": correct,
+        "total": total,
+        "avg_reward": avg_reward,
+        "results": results,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Test LLM tool calling with ADHD environment")
+    parser.add_argument("--model", type=str, help="Model to test (default: first in list)")
+    parser.add_argument("--all", action="store_true", help="Test all models and show leaderboard")
+    args = parser.parse_args()
+
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        print("ERROR: HF_TOKEN environment variable not set.")
+        print("Run: export HF_TOKEN=hf_...")
+        sys.exit(1)
+
+    client = OpenAI(
+        base_url="https://router.huggingface.co/v1",
+        api_key=token,
+    )
+
+    if args.all:
+        models = MODELS
+    elif args.model:
+        models = [args.model]
+    else:
+        models = [MODELS[0]]
+
+    all_results = []
+    for model in models:
+        result = run_model_tests(client, model)
+        all_results.append(result)
+
+    if len(all_results) > 1:
+        print(f"\n{'=' * 60}")
+        print("MODEL LEADERBOARD")
+        print(f"{'=' * 60}")
+        print(f"{'Model':<40} {'Accuracy':>10} {'Avg Reward':>12}")
+        print("-" * 62)
+
+        for r in sorted(all_results, key=lambda x: x["avg_reward"], reverse=True):
+            print(f"{r['model']:<40} {r['correct']}/{r['total']:>8} {r['avg_reward']:>11.3f}")
+
+
+if __name__ == "__main__":
+    main()