Add OpenEnv server integration and deployment checks

.dockerignore

@@ -0,0 +1,8 @@
+OpenEnv/
+__pycache__/
+*.pyc
+*.pyo
+*.log
+.git/
+.venv/
+venv/

README.md

@@ -1,3 +1,18 @@
+---
+title: Shopping Agent OpenEnv
+emoji: 🛍️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+tags:
+  - openenv
+  - reinforcement-learning
+  - fastapi
+license: bsd-3-clause
+---
+
 # 🧠 Personality-Driven Shopping Agent — OpenEnv Environment
 
 A **real-world shopping simulation** where an AI agent must learn a specific user's shopping personality from persistent memory and make purchase decisions aligned with their style — not just pick the "globally best" product.
@@ -174,6 +189,32 @@ docker run -p 7860:7860 shopping-agent-env:latest
 curl http://localhost:7860/health
 ```
 
+Verified locally:
+- `docker build -t shopping-agent-env:local .`
+- `docker run -p 7860:7860 shopping-agent-env:local`
+- `GET /health` returns `{"status":"healthy"}`
+
+### Hugging Face Space Deployment
+
+This repository is ready to run as a Docker-based Hugging Face Space and is tagged for OpenEnv in the README frontmatter above.
+
+```bash
+# Create a Docker Space, then push this repo to it
+git remote add hf https://huggingface.co/spaces/<username>/shopping-agent-openenv
+git push hf main
+```
+
+Space settings:
+- SDK: `Docker`
+- App port: `7860`
+- Tag: `openenv`
+
+After deployment, verify:
+
+```bash
+curl https://<username>-shopping-agent-openenv.hf.space/health
+```
+
 ### API Endpoints
 
 | Endpoint | Method | Description |

client.py

@@ -0,0 +1,49 @@
+"""
+OpenEnv Client for the Shopping Agent Environment.
+
+Connects to the shopping environment server via WebSocket (OpenEnv protocol).
+"""
+
+from typing import Any, Dict
+
+from openenv.core.env_client import EnvClient
+from openenv.core.client_types import StepResult
+
+from openenv_models import ShoppingAction, ShoppingObservation, ShoppingState
+
+
+class ShoppingEnvClient(EnvClient[ShoppingAction, ShoppingObservation, ShoppingState]):
+    """
+    WebSocket client for the Shopping Agent Environment.
+
+    Usage (async):
+        async with ShoppingEnvClient(base_url="http://localhost:8000") as env:
+            result = await env.reset(query="lip balm", product_count=4)
+            result = await env.step(ShoppingAction(action_type="view_item", item_ids=["p1"]))
+
+    Usage (sync):
+        with ShoppingEnvClient(base_url="http://localhost:8000").sync() as env:
+            result = env.reset(query="earbuds")
+            result = env.step(ShoppingAction(action_type="buy", item_ids=["p1"]))
+    """
+
+    def _step_payload(self, action: ShoppingAction) -> Dict[str, Any]:
+        """Convert ShoppingAction to the JSON payload expected by the server."""
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ShoppingObservation]:
+        """Parse server response into StepResult[ShoppingObservation]."""
+        obs_data = payload.get("observation", payload)
+        reward = payload.get("reward") or obs_data.get("reward", 0.0)
+        done = payload.get("done", obs_data.get("done", False))
+
+        observation = ShoppingObservation(**obs_data)
+        return StepResult(
+            observation=observation,
+            reward=reward,
+            done=done,
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> ShoppingState:
+        """Parse server state response into ShoppingState."""
+        return ShoppingState(**payload)

openenv_models.py

@@ -0,0 +1,90 @@
+"""
+OpenEnv-compatible models for the Shopping Agent Environment.
+
+These models inherit from openenv's base Action/Observation/State types
+so they can be used with create_app() and EnvClient.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+from openenv.core.env_server.types import (
+    Action as OpenEnvAction,
+    Observation as OpenEnvObservation,
+    State as OpenEnvState,
+)
+
+
+# ---------------------------------------------------------------------------
+# Action: what the agent sends (OpenEnv-compatible)
+# ---------------------------------------------------------------------------
+class ShoppingAction(OpenEnvAction):
+    """
+    An action the agent can take in the shopping environment.
+
+    Supported action_types:
+      search, view_item, compare, shortlist, add_to_cart,
+      remove_from_cart, buy, skip, ask_more
+    """
+
+    action_type: str = Field(
+        ...,
+        description="One of: search, view_item, compare, shortlist, "
+                    "add_to_cart, remove_from_cart, buy, skip, ask_more",
+    )
+    item_ids: List[str] = Field(
+        default_factory=list,
+        description="Product IDs involved in the action",
+    )
+    search_query: Optional[str] = Field(
+        default=None,
+        description="Query string when action_type is 'search'",
+    )
+
+    model_config = {"extra": "allow"}
+
+
+# ---------------------------------------------------------------------------
+# Observation: what the environment returns (OpenEnv-compatible)
+# ---------------------------------------------------------------------------
+class ShoppingObservation(OpenEnvObservation):
+    """What the agent observes after each step — OpenEnv Observation subclass."""
+
+    query: str = Field("", description="Current search query")
+    category: str = Field("", description="Current product category")
+    candidate_products: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Products currently visible to the agent",
+    )
+    memory_profile: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="User personality traits and semantic memory",
+    )
+    cart: List[str] = Field(default_factory=list, description="Product IDs in cart")
+    shortlisted: List[str] = Field(default_factory=list, description="Shortlisted IDs")
+    viewed_items: List[str] = Field(default_factory=list, description="Viewed IDs")
+    compared_sets: List[List[str]] = Field(
+        default_factory=list, description="Compared product ID sets"
+    )
+    history_summary: str = Field("", description="Recent actions summary")
+    feedback: str = Field("", description="Environment feedback")
+    step_number: int = Field(0, description="Current step")
+    max_steps: int = Field(15, description="Max steps")
+
+    model_config = {"extra": "allow"}
+
+
+# ---------------------------------------------------------------------------
+# State: episode metadata (OpenEnv-compatible)
+# ---------------------------------------------------------------------------
+class ShoppingState(OpenEnvState):
+    """Episode-level metadata — OpenEnv State subclass."""
+
+    task_name: str = ""
+    difficulty: str = ""
+    done: bool = False
+    cumulative_reward: float = 0.0
+    cart: List[str] = Field(default_factory=list)
+    shortlisted: List[str] = Field(default_factory=list)
+    product_query: str = Field(default="", description="Current product query")

product_generator.py

@@ -251,7 +251,7 @@ def _get_template(category: str) -> Dict[str, Any]:
     return DEFAULT_TEMPLATE
 
 
-def _make_seller(brand: str, seller_type: str) -> str:
+def _make_seller(brand: str, seller_type: str, rng: random.Random) -> str:
     """Generate a seller name based on the brand and seller type."""
     if seller_type == "official":
         return f"{brand} Official"
@@ -262,7 +262,7 @@ def _make_seller(brand: str, seller_type: str) -> str:
             "Unknown Marketplace", "Quick Deals", "Flash Sales",
             "Random Seller", "Budget Bazaar",
         ]
-        return random.choice(unknown_sellers)
+        return rng.choice(unknown_sellers)
 
 
 def _deterministic_seed(query: str, salt: str = "") -> int:
@@ -297,8 +297,15 @@ def generate_products(
     price_min, price_max = template["price_range"]
     price_span = price_max - price_min
 
-    # Use up to `count` archetypes
-    archetypes = ARCHETYPES[:count]
+    # Reuse the base archetypes with deterministic variants when a task
+    # requests more products than the archetype library size.
+    archetypes: List[Dict[str, Any]] = []
+    for i in range(count):
+        base = dict(ARCHETYPES[i % len(ARCHETYPES)])
+        variant_index = i // len(ARCHETYPES)
+        if variant_index:
+            base["variant_index"] = variant_index
+        archetypes.append(base)
     products: List[Dict[str, Any]] = []
 
     # Clean up the query for product naming
@@ -312,13 +319,16 @@ def generate_products(
         # Calculate price
         base_price = price_min + (price_span * arch["price_pct"])
         price_jitter = rng.uniform(-0.05, 0.05) * price_span
-        price = round(max(price_min, base_price + price_jitter), 2)
+        variant_index = arch.get("variant_index", 0)
+        variant_multiplier = 1.0 + (0.04 * variant_index)
+        price = round(max(price_min, (base_price + price_jitter) * variant_multiplier), 2)
 
         # Rating
-        rating = round(rng.uniform(*arch["rating"]), 1)
+        rating = round(max(1.0, min(5.0, rng.uniform(*arch["rating"]) - (0.1 * variant_index))), 1)
 
         # Reviews
-        reviews = rng.randint(*arch["reviews"])
+        review_floor, review_ceiling = arch["reviews"]
+        reviews = rng.randint(review_floor, max(review_floor, int(review_ceiling * (0.9 ** variant_index))))
 
         # Features
         n_features = rng.randint(*arch["feature_count"])
@@ -326,12 +336,14 @@ def generate_products(
         features = features_pool[:n_features]
 
         # Seller
-        seller = _make_seller(brand, arch["seller_type"])
+        seller = _make_seller(brand, arch["seller_type"], rng)
 
         # Build product name
         name = f"{arch['name_prefix']} {category_name}"
         if arch["key"] == "discounted":
             name = f"{category_name} (Was ${round(price * 1.8, 2)}, Now Sale!)"
+        elif variant_index:
+            name = f"{name} {variant_index + 1}"
 
         product = {
             "id": f"p{i + 1}",

requirements.txt

@@ -4,3 +4,4 @@ pydantic>=2.0.0
 python-dotenv>=1.0.0
 openai>=1.0.0
 pyyaml>=6.0
+openenv-core>=0.2.3

run_openenv.py

@@ -0,0 +1,350 @@
+"""
+OpenEnv Inference Runner — Personality-Driven Shopping Agent
+=============================================================
+Runs the shopping agent through the OpenEnv protocol:
+  1. Starts the server (ShoppingEnvironment via create_app)
+  2. Connects via ShoppingEnvClient (WebSocket)
+  3. Runs 3 tasks (easy → medium → hard) using an LLM or fallback heuristic
+  4. Prints results in OpenEnv STDOUT format
+
+STDOUT FORMAT:
+  [START] task=<task_name> env=<benchmark> model=<model_name>
+  [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+  [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+
+Usage:
+  python run_openenv.py
+"""
+
+import asyncio
+import json
+import os
+import sys
+import textwrap
+import time
+from pathlib import Path
+from typing import List, Optional
+
+from dotenv import load_dotenv
+
+# Ensure project root is importable
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+load_dotenv()
+
+from openai import OpenAI
+from openenv_models import ShoppingAction
+from server.shopping_environment import ShoppingEnvironment
+from memory_engine import load_profile
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+
+BENCHMARK = "shopping_agent"
+TEMPERATURE = 0.7
+MAX_TOKENS = 300
+
+TASKS = [
+    {"name": "quick_pick",  "query": "lip balm",       "difficulty": "easy",   "max_steps": 8,  "product_count": 4},
+    {"name": "smart_shop",  "query": "earbuds",         "difficulty": "medium", "max_steps": 12, "product_count": 8},
+    {"name": "expert_deal", "query": "laptop backpack", "difficulty": "hard",   "max_steps": 15, "product_count": 12},
+]
+
+
+# ---------------------------------------------------------------------------
+# Logging (strict OpenEnv format)
+# ---------------------------------------------------------------------------
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} "
+        f"score={score:.2f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# System prompt builder
+# ---------------------------------------------------------------------------
+def build_system_prompt(profile_text: str) -> str:
+    return textwrap.dedent(f"""\
+You are a shopping agent acting on behalf of a specific user.
+Your goal is to buy the product that THIS USER would choose.
+
+{profile_text}
+
+## Your Task
+Given the observation (products, personality profile, cart, history),
+decide the BEST next action for THIS user. Think about:
+- Would this user research more before buying? (check research_depth)
+- Would this user pick the cheapest option? (check price_sensitivity)
+- Would this user avoid risky products? (check risk_aversion)
+- Would this user trust this brand? (check brand_trust)
+- Would this user care about reviews? (check review_dependence)
+
+Reply with **only valid JSON**:
+
+{{
+  "action_type": "search" | "view_item" | "compare" | "shortlist" |
+                 "add_to_cart" | "remove_from_cart" | "buy" | "skip" | "ask_more",
+  "item_ids": ["p1", ...],
+  "search_query": "query text"
+}}
+
+Rules:
+- research_depth > 0.7: view 3+ items and compare before buying.
+- risk_aversion > 0.7: avoid products with <50 reviews or unknown sellers.
+- Do NOT output anything besides the JSON object.
+""").strip()
+
+
+# ---------------------------------------------------------------------------
+# LLM interaction
+# ---------------------------------------------------------------------------
+def build_user_prompt(step: int, obs_dict: dict, last_reward: float, history: List[str]) -> str:
+    history_block = "\n".join(history[-5:]) if history else "None"
+    mem_profile = obs_dict.get("memory_profile", {})
+    obs_summary = {
+        "query": obs_dict.get("query", ""),
+        "personality_preferences": {
+            k: v for k, v in mem_profile.items()
+            if isinstance(v, (int, float)) and 0 <= v <= 1
+        },
+        "personality_conclusions": mem_profile.get("semantic_conclusions", [])[:4],
+        "products": [
+            {
+                "id": p["id"],
+                "name": p["name"],
+                "price": p["price"],
+                "rating": p["rating"],
+                "brand": p["brand"],
+                "reviews": p["reviews"],
+                "refundable": p["refundable"],
+                "seller": p.get("seller", ""),
+            }
+            for p in obs_dict.get("candidate_products", [])
+        ],
+        "cart": obs_dict.get("cart", []),
+        "shortlisted": obs_dict.get("shortlisted", []),
+        "viewed": obs_dict.get("viewed_items", []),
+        "feedback": obs_dict.get("feedback", ""),
+        "step": obs_dict.get("step_number", step),
+        "max_steps": obs_dict.get("max_steps", 15),
+    }
+    return textwrap.dedent(f"""\
+Step {step} | Last reward: {last_reward:.2f}
+
+Observation:
+{json.dumps(obs_summary, indent=2)}
+
+Recent history:
+{history_block}
+
+Reply with the next action as JSON.""")
+
+
+def get_agent_action(
+    client: OpenAI,
+    system_prompt: str,
+    step: int,
+    obs_dict: dict,
+    last_reward: float,
+    history: List[str],
+) -> ShoppingAction:
+    user_prompt = build_user_prompt(step, obs_dict, last_reward, history)
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        text = (completion.choices[0].message.content or "").strip()
+        if text.startswith("```"):
+            text = text.split("\n", 1)[-1]
+        if text.endswith("```"):
+            text = text.rsplit("```", 1)[0]
+        text = text.strip()
+        data = json.loads(text)
+        return ShoppingAction(**data)
+    except Exception as exc:
+        print(f"[DEBUG] LLM parse error: {exc}", flush=True)
+        return _fallback_action(obs_dict)
+
+
+def _fallback_action(obs_dict: dict) -> ShoppingAction:
+    """Smart heuristic fallback when the LLM is unavailable."""
+    cart = obs_dict.get("cart", [])
+    shortlisted = obs_dict.get("shortlisted", [])
+    viewed = obs_dict.get("viewed_items", [])
+    compared = obs_dict.get("compared_sets", [])
+    products = obs_dict.get("candidate_products", [])
+
+    if cart:
+        return ShoppingAction(action_type="buy", item_ids=list(cart))
+    if shortlisted:
+        return ShoppingAction(action_type="add_to_cart", item_ids=[shortlisted[0]])
+    if compared:
+        flat = []
+        for s in compared:
+            flat.extend(s)
+        unique = list(dict.fromkeys(flat))[:2]
+        return ShoppingAction(action_type="shortlist", item_ids=unique)
+    if len(viewed) >= 2:
+        return ShoppingAction(action_type="compare", item_ids=viewed[:3])
+    mid_range = [
+        p["id"] for p in products
+        if p.get("price", 999) < 150
+        and p.get("rating", 0) >= 3.5
+        and p.get("reviews", 0) >= 50
+    ][:3]
+    if mid_range:
+        return ShoppingAction(action_type="view_item", item_ids=mid_range)
+    if products:
+        return ShoppingAction(action_type="view_item", item_ids=[products[0]["id"]])
+    return ShoppingAction(action_type="skip")
+
+
+# ---------------------------------------------------------------------------
+# Run one episode DIRECTLY against the OpenEnv Environment (local mode)
+# ---------------------------------------------------------------------------
+def run_episode_local(llm_client: OpenAI, task: dict) -> tuple:
+    """Run a task episode using the OpenEnv Environment directly (no server)."""
+    task_name = task["name"]
+    query = task["query"]
+    max_steps = task["max_steps"]
+    product_count = task["product_count"]
+
+    env = ShoppingEnvironment()
+
+    history: List[str] = []
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    # Build personality-aware system prompt
+    profile = load_profile()
+    profile_text = profile.to_prompt_text(category=query)
+    system_prompt = build_system_prompt(profile_text)
+
+    log_start(task=task_name, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        # Use the OpenEnv reset() — returns Observation directly
+        obs = env.reset(
+            query=query,
+            product_count=product_count,
+            task_name=task_name,
+            max_steps=max_steps,
+        )
+        obs_dict = obs.model_dump()
+        last_reward = 0.0
+
+        for step_num in range(1, max_steps + 1):
+            if obs.done:
+                break
+
+            action = get_agent_action(
+                llm_client, system_prompt, step_num, obs_dict, last_reward, history
+            )
+
+            # Use the OpenEnv step() — returns Observation directly
+            obs = env.step(action)
+            reward = obs.reward or 0.0
+            done = obs.done
+            error = None
+
+            rewards.append(reward)
+            steps_taken = step_num
+            obs_dict = obs.model_dump()
+            last_reward = reward
+
+            # Compact action string for logging
+            ids_str = ",".join(action.item_ids) if action.item_ids else ""
+            if action.search_query:
+                action_str = f"{action.action_type}('{action.search_query}')"
+            elif ids_str:
+                action_str = f"{action.action_type}({ids_str})"
+            else:
+                action_str = action.action_type
+
+            log_step(step=step_num, action=action_str, reward=reward, done=done, error=error)
+            history.append(f"Step {step_num}: {action_str} -> reward {reward:+.2f}")
+
+            if done:
+                break
+
+        # Score calculation
+        if rewards:
+            buy_reward = max((r for r in rewards if r >= 0.3), default=0.0)
+            if buy_reward > 0:
+                score = buy_reward
+            else:
+                positive_rewards = sum(r for r in rewards if r > 0)
+                score = min(positive_rewards / 2.0, 0.3)
+        score = min(max(score, 0.0), 1.0)
+        success = score >= 0.5
+
+    finally:
+        env.close()
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+    return success, steps_taken, score, rewards
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def main() -> None:
+    print("=" * 60, flush=True)
+    print("OpenEnv Shopping Agent — Direct Local Execution", flush=True)
+    print("=" * 60, flush=True)
+    print(f"Model: {MODEL_NAME}", flush=True)
+    print(f"API:   {API_BASE_URL}", flush=True)
+    print(f"Key:   {'***' + API_KEY[-4:] if API_KEY else 'NOT SET (using fallback heuristic)'}", flush=True)
+    print("=" * 60, flush=True)
+    print(flush=True)
+
+    llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+    all_scores = {}
+    for task in TASKS:
+        _success, _steps, score, _rewards = run_episode_local(llm_client, task)
+        all_scores[task["name"]] = score
+        print(flush=True)
+
+    print("=" * 60, flush=True)
+    print("SUMMARY", flush=True)
+    for t, s in all_scores.items():
+        status = "PASS" if s >= 0.5 else "FAIL"
+        print(f"  [{status}] {t:16s}: {s:.2f}", flush=True)
+    avg = sum(all_scores.values()) / len(all_scores)
+    print(f"  {'average':19s}: {avg:.2f}", flush=True)
+    print("=" * 60, flush=True)
+
+
+if __name__ == "__main__":
+    main()

server/app.py

@@ -1,83 +1,50 @@
 """
-FastAPI server for the Personality-Driven Shopping Agent Environment.
-
-OpenEnv-compliant HTTP API:
-  POST /reset         → Reset environment, returns StepResult
-  POST /step          → Execute an action, returns StepResult
-  GET  /state         → Returns current ShoppingState
-  GET  /health        → {"status": "healthy"}
-
-Also serves:
-  GET  /              → Interactive web UI
-  POST /auto-run      → Autonomous RL episode (for web UI)
-  GET  /agent-stats   → Agent learning stats
-  POST /agent-reset   → Reset agent weights
-  GET  /profile       → User personality profile
+FastAPI app for the Shopping Agent — powered by OpenEnv.
+
+Uses openenv.core.env_server.http_server.create_app() to expose the
+ShoppingEnvironment over HTTP + WebSocket endpoints that any EnvClient
+(including ShoppingEnvClient) can consume.
+
+Endpoints auto-provided by OpenEnv:
+  POST /reset       → Reset environment
+  POST /step        → Execute action
+  GET  /state       → Current episode state
+  GET  /health      → Health check
+  GET  /schema      → Action/Observation schemas
+  WS   /ws          → WebSocket persistent session
+
+Custom endpoints added below:
+  GET  /             → Web UI
+  GET  /profile      → User personality profile
 """
 
 import os
-import json
-import yaml
-import datetime
-from contextlib import asynccontextmanager
+import sys
 from pathlib import Path
-from typing import Any, Dict, List, Optional
 
-from fastapi import FastAPI, Query
-from fastapi.responses import JSONResponse, FileResponse
-from fastapi.staticfiles import StaticFiles
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel, Field
-from dotenv import load_dotenv
+import uvicorn
 
-# Ensure parent directory is importable
-import sys
+# Ensure project root is importable
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
-from models import ResetRequest, StepResult, ShoppingAction, ShoppingState
-from shopping_env import ShoppingEnv
+from openenv.core.env_server.http_server import create_app
+from openenv_models import ShoppingAction, ShoppingObservation
+from server.shopping_environment import ShoppingEnvironment
 from memory_engine import load_profile
-from personality_grader import score_all_products
-from rl_agent import RLShoppingAgent
 
-load_dotenv()
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
 
 STATIC_DIR = Path(__file__).resolve().parent.parent / "static"
-YAML_PATH = Path(__file__).resolve().parent.parent / "openenv.yaml"
-
-# Load task configs from openenv.yaml
-TASK_CONFIGS = {}
-if YAML_PATH.exists():
-    with open(YAML_PATH, "r", encoding="utf-8") as f:
-        _yaml = yaml.safe_load(f)
-        for task in _yaml.get("tasks", []):
-            TASK_CONFIGS[task["name"]] = task
-
-
-# ---------------------------------------------------------------------------
-# RL Agent — persists across requests
-# ---------------------------------------------------------------------------
-_agent = RLShoppingAgent()
-_env: ShoppingEnv = None  # type: ignore
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    global _env
-    _env = ShoppingEnv()
-    yield
-    await _env.close()
-
 
-app = FastAPI(
-    title="Personality-Driven Shopping Agent",
-    description=(
-        "OpenEnv-compliant RL environment. The AI agent learns to shop "
-        "like YOU by reading your memory/ profile. Supports 3 tasks: "
-        "quick_pick (easy), smart_shop (medium), expert_deal (hard)."
-    ),
-    version="1.0.0",
-    lifespan=lifespan,
+# --- Create the OpenEnv app -------------------------------------------------
+# Pass the CLASS (factory), not an instance — create_app creates per-session.
+app = create_app(
+    ShoppingEnvironment,
+    ShoppingAction,
+    ShoppingObservation,
+    env_name="shopping_agent",
 )
 
 app.add_middleware(
@@ -88,196 +55,20 @@ app.add_middleware(
 )
 
 
-# ---------------------------------------------------------------------------
-# Frontend
-# ---------------------------------------------------------------------------
+# --- Custom endpoints -------------------------------------------------------
+
 @app.get("/", include_in_schema=False)
 async def serve_frontend():
+    """Serve the web UI."""
     index_path = STATIC_DIR / "index.html"
     if index_path.exists():
         return FileResponse(str(index_path), media_type="text/html")
-    return JSONResponse(content={"error": "Frontend not found"}, status_code=404)
-
-
-# ---------------------------------------------------------------------------
-# OpenEnv Core Endpoints: /reset, /step, /state, /health
-# ---------------------------------------------------------------------------
-
-class ResetBody(BaseModel):
-    """Body for /reset — accepts task name or free-form query."""
-    task: Optional[str] = Field(
-        default=None,
-        description="Task name: quick_pick, smart_shop, or expert_deal",
-    )
-    query: Optional[str] = Field(
-        default=None,
-        description="Free-form product query (used if task not specified)",
-    )
-
-
-@app.get("/health")
-async def health():
-    return {"status": "healthy"}
-
-
-@app.post("/reset")
-async def reset(body: ResetBody = ResetBody()):
-    """
-    Reset the environment. OpenEnv-compliant.
-    
-    Accepts either:
-      - task: "quick_pick" | "smart_shop" | "expert_deal"
-      - query: free-form product query
-    
-    Returns StepResult with initial observation.
-    """
-    global _env
-
-    # Resolve task config
-    task_name = body.task or "smart_shop"
-    task_config = TASK_CONFIGS.get(task_name, {})
-    query = body.query or task_config.get("query", "earbuds")
-    max_steps = task_config.get("max_steps", 12)
-    product_count = task_config.get("product_count", 8)
-    difficulty = task_config.get("difficulty", "medium")
-
-    _env = ShoppingEnv(task_name=task_name)
-    _env._max_steps = max_steps
-    result = await _env.reset(query=query, product_count=product_count)
-
-    # Add task metadata to info
-    profile = _env._user_profile
-    prefs = profile.get_prefs_for_category(query.lower())
-    scored = _env._scored_products
-
-    return {
-        "observation": result.observation.model_dump(),
-        "reward": result.reward,
-        "done": result.done,
-        "info": {
-            "task": task_name,
-            "difficulty": difficulty,
-            "query": query,
-            "product_count": len(_env.catalog),
-            "max_steps": max_steps,
-            "personality_traits": prefs,
-            "ideal_product": scored[0]["product"]["name"] if scored else None,
-            "ideal_score": scored[0]["personality_score"] if scored else 0,
-            "scored_products": [
-                {
-                    "id": s["product"]["id"],
-                    "name": s["product"]["name"],
-                    "score": s["personality_score"],
-                    "rank": s["rank"],
-                }
-                for s in scored
-            ],
-        },
-    }
-
-
-@app.post("/step")
-async def step(action: ShoppingAction):
-    """
-    Execute an action. OpenEnv-compliant.
-    
-    Returns StepResult with observation, reward, done, info.
-    """
-    if _env is None:
-        return JSONResponse(
-            status_code=400,
-            content={"error": "Environment not initialized. Call /reset first."},
-        )
-    result = await _env.step(action)
-    state = await _env.state()
-    return {
-        "observation": result.observation.model_dump(),
-        "reward": result.reward,
-        "done": result.done,
-        "info": {
-            "step_count": state.step_count,
-            "cumulative_reward": state.cumulative_reward,
-            "cart": state.cart,
-        },
-    }
-
-
-@app.get("/state")
-async def state():
-    """
-    Get current episode state. OpenEnv-compliant.
-    """
-    if _env is None:
-        return JSONResponse(
-            status_code=400,
-            content={"error": "Environment not initialized."},
-        )
-    s = await _env.state()
-    return s.model_dump()
-
-
-# ---------------------------------------------------------------------------
-# Autonomous RL Endpoints (for web UI)
-# ---------------------------------------------------------------------------
-
-@app.post("/auto-run")
-async def auto_run():
-    """
-    Run a FULL autonomous RL episode.
-    No human feedback needed — personality_grader IS the reward function.
-    """
-    if _env is None or not _env.catalog:
-        return JSONResponse(
-            status_code=400,
-            content={"error": "No active session. Call /reset first."},
-        )
-
-    attempts = _agent.run_episode(
-        products=_env.catalog,
-        scored_products=_env._scored_products,
-    )
-
-    ideal = _env._scored_products[0] if _env._scored_products else None
-    stats = _agent.get_stats()
-
-    return {
-        "attempts": attempts,
-        "episode_number": stats["episode_count"],
-        "total_episode_reward": round(
-            sum(a["reward"] for a in attempts), 4
-        ),
-        "success": any(a["is_success"] for a in attempts),
-        "success_attempt": next(
-            (a["attempt"] for a in attempts if a["is_success"]), None
-        ),
-        "ideal_product": {
-            "name": ideal["product"]["name"],
-            "score": ideal["personality_score"],
-            "id": ideal["product"]["id"],
-        } if ideal else None,
-        "agent_stats": stats,
-    }
-
-
-@app.get("/agent-stats")
-async def agent_stats():
-    """Get the agent's learning statistics and current weights."""
-    return _agent.get_stats()
-
-
-@app.post("/agent-reset")
-async def agent_reset():
-    """Reset the agent's learned weights — start fresh."""
-    _agent.reset_weights()
-    return {
-        "message": "Agent weights reset. Learning starts from scratch.",
-        "stats": _agent.get_stats(),
-    }
+    return JSONResponse(content={"message": "Shopping Agent OpenEnv server is running."})
 
 
 @app.get("/profile")
 async def profile():
-    """Returns the loaded user personality profile summary."""
+    """Return the loaded user personality profile summary."""
     prof = load_profile()
     return {
         "personality_summary": prof.personality_summary[:500],
@@ -299,6 +90,15 @@ async def profile():
     }
 
 
-# Mount static files — must be LAST
+# Mount static files
 if STATIC_DIR.exists():
     app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+
+def main():
+    """Run the server directly."""
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/shopping_environment.py

@@ -0,0 +1,414 @@
+"""
+OpenEnv-compatible ShoppingEnvironment.
+
+Wraps the existing shopping_env logic into the OpenEnv Environment
+interface (reset → Observation, step → Observation, state → property).
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+# Ensure parent directory is importable
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import (
+    EnvironmentMetadata,
+    State,
+)
+
+from openenv_models import ShoppingAction, ShoppingObservation, ShoppingState
+from memory_engine import load_profile, UserProfile
+from product_generator import generate_products
+from personality_grader import grade_purchase as personality_grade_purchase, score_all_products
+from task_config import DEFAULT_TASK_NAME, get_task_config
+
+
+DEFAULT_MAX_STEPS = 15
+DEFAULT_QUERY = "earbuds"
+
+
+class ShoppingEnvironment(Environment[ShoppingAction, ShoppingObservation, ShoppingState]):
+    """
+    OpenEnv-compliant shopping environment.
+
+    Implements the Environment interface:
+      - reset()  → ShoppingObservation
+      - step()   → ShoppingObservation
+      - state    → ShoppingState (property)
+      - close()  → cleanup
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__()
+        self._user_profile: UserProfile = load_profile()
+
+        # Episode state
+        self._step_count = 0
+        self._max_steps = DEFAULT_MAX_STEPS
+        self._done = False
+        self._cumulative_reward = 0.0
+        self._query = ""
+        self._category = ""
+        self._cart: List[str] = []
+        self._shortlisted: List[str] = []
+        self._viewed: List[str] = []
+        self._compared_sets: List[List[str]] = []
+        self._history: List[str] = []
+        self._feedback = ""
+        self._skipped_ids: List[str] = []
+        self.catalog: List[Dict[str, Any]] = []
+        self._scored_products: List[Dict[str, Any]] = []
+        self._episode_id = str(uuid4())
+        self._task_name = DEFAULT_TASK_NAME
+        self._difficulty = "medium"
+
+    # ---- OpenEnv interface -------------------------------------------------
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        query: str = DEFAULT_QUERY,
+        product_count: int = 8,
+        task_name: str = DEFAULT_TASK_NAME,
+        max_steps: int = DEFAULT_MAX_STEPS,
+        **kwargs: Any,
+    ) -> ShoppingObservation:
+        """Reset the environment. Returns initial ShoppingObservation."""
+        requested_task = kwargs.get("task", task_name)
+        task_config = get_task_config(requested_task)
+        query_was_explicit = "query" in kwargs or query != DEFAULT_QUERY
+        product_count_was_explicit = (
+            "product_count" in kwargs or product_count != 8
+        )
+        max_steps_was_explicit = "max_steps" in kwargs or max_steps != DEFAULT_MAX_STEPS
+
+        if task_config:
+            if not query_was_explicit:
+                query = task_config.get("query", query)
+            if not product_count_was_explicit:
+                product_count = task_config.get("product_count", product_count)
+            if not max_steps_was_explicit:
+                max_steps = task_config.get("max_steps", max_steps)
+            task_name = task_config["name"]
+            self._difficulty = task_config.get("difficulty", task_name)
+        else:
+            self._difficulty = "dynamic"
+
+        self._step_count = 0
+        self._done = False
+        self._cumulative_reward = 0.0
+        self._query = query.strip() or DEFAULT_QUERY
+        self._category = self._query.lower()
+        self._cart = []
+        self._shortlisted = []
+        self._viewed = []
+        self._compared_sets = []
+        self._history = []
+        self._skipped_ids = []
+        self._episode_id = episode_id or str(uuid4())
+        self._task_name = task_name
+        self._max_steps = max_steps
+
+        # Reload user profile (may have been updated)
+        self._user_profile = load_profile()
+
+        # Generate products dynamically
+        self.catalog = generate_products(self._query, count=product_count)
+
+        # Score all products against personality
+        self._scored_products = score_all_products(self.catalog, self._user_profile)
+
+        # Find the personality-ideal product
+        ideal = self._scored_products[0] if self._scored_products else None
+        ideal_name = ideal["product"]["name"] if ideal else "unknown"
+        ideal_score = ideal["personality_score"] if ideal else 0
+        research_depth = self._user_profile.research_depth
+
+        self._feedback = (
+            f"Welcome! Shopping for: {self._query}\n"
+            f"Generated {len(self.catalog)} products.\n"
+            f"Goal: Find the product that best matches your personality profile.\n"
+            f"The personality-ideal product is '{ideal_name}' "
+            f"(alignment score: {ideal_score:.2f}).\n"
+            f"Your research depth preference: {research_depth:.0%} — "
+            f"{'thorough research expected' if research_depth > 0.7 else 'quick decisions OK'}."
+        )
+
+        return self._get_obs(reward=0.0)
+
+    def step(
+        self,
+        action: ShoppingAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ShoppingObservation:
+        """Execute an action. Returns ShoppingObservation with reward and done."""
+        if self._done:
+            return self._get_obs(reward=0.0, done=True)
+
+        self._step_count += 1
+        reward = 0.0
+        action_log = ""
+        research_depth = self._user_profile.research_depth
+        atype = action.action_type.lower().strip()
+
+        # ---- search -------------------------------------------------------
+        if atype == "search":
+            self._query = action.search_query or self._query
+            action_log = f"Searched for '{self._query}'"
+            self._feedback = f"Found {len(self.catalog)} products for '{self._query}'."
+            reward = 0.05 * research_depth
+
+        # ---- view_item ----------------------------------------------------
+        elif atype == "view_item":
+            if action.item_ids:
+                details = []
+                for pid in action.item_ids:
+                    if pid not in self._viewed:
+                        self._viewed.append(pid)
+                    prod = self._find_product(pid)
+                    if prod:
+                        ps = self._get_personality_score(pid)
+                        details.append(
+                            f"{prod['name']}: ${prod['price']}, "
+                            f"{prod['rating']}★, {prod['reviews']} reviews, "
+                            f"brand {prod['brand']}, seller {prod['seller']}, "
+                            f"refundable={prod['refundable']}, "
+                            f"personality_alignment={ps:.2f}"
+                        )
+                action_log = f"Viewed {len(action.item_ids)} item(s): {action.item_ids}"
+                self._feedback = (
+                    "Details:\n" + "\n".join(f"  - {d}" for d in details)
+                    if details else "No matching products found."
+                )
+                reward = 0.05 * min(len(action.item_ids), 4) * research_depth
+            else:
+                self._feedback = "view_item requires at least one item_id."
+
+        # ---- compare ------------------------------------------------------
+        elif atype == "compare":
+            if not action.item_ids or len(action.item_ids) < 2:
+                self._feedback = "Compare requires at least 2 item_ids."
+            else:
+                self._compared_sets.append(list(action.item_ids))
+                names = []
+                for pid in action.item_ids:
+                    p = self._find_product(pid)
+                    if p:
+                        ps = self._get_personality_score(pid)
+                        names.append(
+                            f"{p['name']} (${p['price']}, {p['rating']}★, "
+                            f"alignment: {ps:.2f})"
+                        )
+                action_log = f"Compared {len(action.item_ids)} items: {action.item_ids}"
+                self._feedback = "Comparison:\n" + "\n".join(f"  - {n}" for n in names)
+                reward = 0.05 * min(len(action.item_ids), 5) * research_depth
+
+        # ---- shortlist ----------------------------------------------------
+        elif atype == "shortlist":
+            for pid in action.item_ids:
+                if pid not in self._shortlisted:
+                    self._shortlisted.append(pid)
+            action_log = f"Shortlisted {action.item_ids}"
+            self._feedback = f"Shortlist now: {self._shortlisted}"
+            reward = 0.1 * research_depth
+
+        # ---- add_to_cart --------------------------------------------------
+        elif atype == "add_to_cart":
+            for pid in action.item_ids:
+                if pid not in self._cart:
+                    self._cart.append(pid)
+            action_log = f"Added to cart: {action.item_ids}"
+            self._feedback = f"Cart: {self._cart}"
+            reward = 0.1
+
+        # ---- remove_from_cart ---------------------------------------------
+        elif atype == "remove_from_cart":
+            for pid in action.item_ids:
+                if pid in self._cart:
+                    self._cart.remove(pid)
+            action_log = f"Removed from cart: {action.item_ids}"
+            self._feedback = f"Cart: {self._cart}"
+            reward = 0.0
+
+        # ---- buy ----------------------------------------------------------
+        elif atype == "buy":
+            action_log = "Attempted purchase"
+            self._done = True
+            purchased = set(self._cart + action.item_ids)
+            if not purchased:
+                self._feedback = "Cannot buy — cart is empty and no item_ids given."
+                reward = 0.0
+            else:
+                reward = self._grade_purchase(purchased)
+                purchased_names = []
+                for pid in purchased:
+                    p = self._find_product(pid)
+                    if p:
+                        ps = self._get_personality_score(pid)
+                        purchased_names.append(f"{p['name']} (alignment: {ps:.2f})")
+                self._feedback = (
+                    f"Purchased: {', '.join(purchased_names)}.\n"
+                    f"Final score: {reward:.2f}"
+                )
+                self._log_episode(purchased, reward)
+
+        # ---- skip ---------------------------------------------------------
+        elif atype == "skip":
+            if action.item_ids:
+                self._skipped_ids.extend(action.item_ids)
+                action_log = f"Skipped items: {action.item_ids}"
+            else:
+                action_log = "Skipped turn"
+            self._feedback = "Turn skipped."
+            reward = 0.0
+
+        # ---- ask_more -----------------------------------------------------
+        elif atype == "ask_more":
+            action_log = "Asked for more options"
+            self._feedback = "No additional products available in this catalog."
+            reward = 0.0
+
+        # ---- unknown ------------------------------------------------------
+        else:
+            action_log = f"Unknown action: {atype}"
+            self._feedback = (
+                f"Invalid action_type '{atype}'. Valid: search, view_item, "
+                f"compare, shortlist, add_to_cart, remove_from_cart, buy, skip, ask_more."
+            )
+            reward = -0.1
+
+        if action_log:
+            self._history.append(action_log)
+
+        # Penalize running out of steps
+        if self._step_count >= self._max_steps and not self._done:
+            self._done = True
+            self._feedback += " Episode ended — max steps reached without purchase."
+            reward -= 0.2
+
+        self._cumulative_reward += reward
+        return self._get_obs(reward=round(reward, 4), done=self._done)
+
+    @property
+    def state(self) -> ShoppingState:
+        """Get current episode state."""
+        return ShoppingState(
+            episode_id=self._episode_id,
+            step_count=self._step_count,
+            task_name=self._task_name,
+            difficulty=self._difficulty,
+            done=self._done,
+            cumulative_reward=round(self._cumulative_reward, 4),
+            cart=list(self._cart),
+            shortlisted=list(self._shortlisted),
+            product_query=self._query,
+        )
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        return EnvironmentMetadata(
+            name="shopping_agent",
+            description=(
+                "Personality-driven RL shopping environment. "
+                "The agent learns to shop like a specific user."
+            ),
+            version="1.0.0",
+        )
+
+    def close(self) -> None:
+        pass
+
+    # ---- helpers ----------------------------------------------------------
+
+    def _find_product(self, pid: str) -> Optional[Dict[str, Any]]:
+        for p in self.catalog:
+            if p["id"] == pid:
+                return p
+        return None
+
+    def _get_personality_score(self, pid: str) -> float:
+        for item in self._scored_products:
+            if item["product"]["id"] == pid:
+                return item["personality_score"]
+        return 0.0
+
+    def _get_obs(self, reward: float = 0.0, done: bool = False) -> ShoppingObservation:
+        history_text = "\n".join(self._history[-6:]) if self._history else "No actions yet."
+        profile = self._user_profile
+        prefs = profile.get_prefs_for_category(self._category)
+
+        return ShoppingObservation(
+            done=done,
+            reward=reward,
+            query=self._query,
+            category=self._category,
+            candidate_products=self.catalog,
+            memory_profile={
+                "goal": (
+                    f"Find the best {self._query} that matches your personality: "
+                    f"research-heavy ({prefs.get('research_depth', 0.5):.0%}), "
+                    f"value-conscious ({prefs.get('price_sensitivity', 0.5):.0%}), "
+                    f"quality-focused ({prefs.get('quality_preference', 0.5):.0%})."
+                ),
+                **prefs,
+                "semantic_conclusions": [
+                    c.get("conclusion", "")
+                    for c in profile.semantic_conclusions[:6]
+                ],
+                "personality_summary": profile.personality_summary[:300],
+            },
+            cart=list(self._cart),
+            shortlisted=list(self._shortlisted),
+            viewed_items=list(self._viewed),
+            compared_sets=[list(s) for s in self._compared_sets],
+            history_summary=history_text,
+            feedback=self._feedback,
+            step_number=self._step_count,
+            max_steps=self._max_steps,
+        )
+
+    def _grade_purchase(self, purchased_ids: set) -> float:
+        return personality_grade_purchase(
+            purchased_ids=purchased_ids,
+            products=self.catalog,
+            profile=self._user_profile,
+            viewed=self._viewed,
+            compared_sets=self._compared_sets,
+            shortlisted=self._shortlisted,
+            skipped_ids=self._skipped_ids,
+        )
+
+    def _log_episode(self, purchased_ids: set, reward: float):
+        try:
+            import datetime
+            log_path = Path(__file__).parent.parent / "memory" / "episodic_log.jsonl"
+            purchased_products = []
+            for pid in purchased_ids:
+                p = self._find_product(pid)
+                if p:
+                    purchased_products.append({
+                        "id": p["id"],
+                        "name": p["name"],
+                        "price": p["price"],
+                        "brand": p["brand"],
+                    })
+            entry = {
+                "timestamp": datetime.datetime.now().isoformat(),
+                "event": "agent_purchase",
+                "query": self._query,
+                "purchased": purchased_products,
+                "reward": round(reward, 4),
+                "steps": self._step_count,
+                "viewed_count": len(self._viewed),
+                "compared_count": len(self._compared_sets),
+                "shortlisted_count": len(self._shortlisted),
+            }
+            with open(log_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+        except Exception as e:
+            print(f"[shopping_env] Error logging episode: {e}")

task_config.py

@@ -0,0 +1,39 @@
+"""Shared task configuration loaded from openenv.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+
+ROOT = Path(__file__).resolve().parent
+OPENENV_MANIFEST = ROOT / "openenv.yaml"
+
+
+def load_openenv_manifest() -> Dict[str, Any]:
+    """Load the environment manifest from disk."""
+    with OPENENV_MANIFEST.open("r", encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def load_task_configs() -> Dict[str, Dict[str, Any]]:
+    """Return tasks keyed by task name."""
+    manifest = load_openenv_manifest()
+    tasks = manifest.get("tasks", [])
+    return {task["name"]: task for task in tasks if "name" in task}
+
+
+TASK_CONFIGS = load_task_configs()
+DEFAULT_TASK_NAME = "smart_shop" if "smart_shop" in TASK_CONFIGS else next(
+    iter(TASK_CONFIGS),
+    "dynamic",
+)
+
+
+def get_task_config(task_name: str | None) -> Dict[str, Any] | None:
+    """Fetch a task configuration by name."""
+    if not task_name:
+        return None
+    return TASK_CONFIGS.get(task_name)

tests/test_openenv_requirements.py

@@ -0,0 +1,161 @@
+import json
+import os
+import subprocess
+import sys
+import time
+import unittest
+from pathlib import Path
+
+import requests
+
+ROOT = Path(__file__).resolve().parent.parent
+
+sys.path.insert(0, str(ROOT))
+
+from memory_engine import load_profile
+from personality_grader import grade_purchase
+
+
+class ServerProcess:
+    def __init__(self, port: int) -> None:
+        self.port = port
+        self.process: subprocess.Popen[str] | None = None
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+    def start(self) -> None:
+        env = os.environ.copy()
+        env["PYTHONPATH"] = os.pathsep.join([str(ROOT), env.get("PYTHONPATH", "")]).strip(
+            os.pathsep
+        )
+        self.process = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "uvicorn",
+                "server.app:app",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                str(self.port),
+            ],
+            cwd=ROOT,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+        for _ in range(30):
+            try:
+                response = requests.get(f"{self.base_url}/health", timeout=1)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                time.sleep(0.5)
+
+        stderr = ""
+        if self.process and self.process.stderr:
+            stderr = self.process.stderr.read()
+        raise RuntimeError(f"Server failed to start on port {self.port}: {stderr}")
+
+    def stop(self) -> None:
+        if not self.process:
+            return
+        self.process.terminate()
+        try:
+            self.process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.process.kill()
+            self.process.wait()
+
+
+class OpenEnvRequirementsTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.server = ServerProcess(port=8010)
+        cls.server.start()
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.server.stop()
+
+    def test_reset_uses_named_task_configuration(self) -> None:
+        expected = {
+            "quick_pick": ("lip balm", 4, 8),
+            "smart_shop": ("earbuds", 8, 12),
+            "expert_deal": ("laptop backpack", 12, 15),
+        }
+
+        for task_name, (query, product_count, max_steps) in expected.items():
+            with self.subTest(task=task_name):
+                response = requests.post(
+                    f"{self.server.base_url}/reset",
+                    json={"task": task_name},
+                    timeout=10,
+                )
+                response.raise_for_status()
+                payload = response.json()
+                observation = payload["observation"]
+
+                self.assertEqual(observation["query"], query)
+                self.assertEqual(len(observation["candidate_products"]), product_count)
+                self.assertEqual(observation["max_steps"], max_steps)
+
+                state_response = requests.get(f"{self.server.base_url}/state", timeout=10)
+                state_response.raise_for_status()
+                state = state_response.json()
+                self.assertEqual(state["step_count"], 0)
+
+    def test_purchase_grader_is_bounded(self) -> None:
+        profile = load_profile()
+        products = [
+            {
+                "id": "p1",
+                "name": "Budget Choice",
+                "price": 20.0,
+                "rating": 3.8,
+                "brand": "ValueCo",
+                "reviews": 120,
+                "category": "earbuds",
+                "seller": "Trusted Seller",
+                "refundable": True,
+                "archetype": "mid_range_best_value",
+            },
+            {
+                "id": "p2",
+                "name": "Risky Deal",
+                "price": 8.0,
+                "rating": 2.4,
+                "brand": "Mystery",
+                "reviews": 4,
+                "category": "earbuds",
+                "seller": "Unknown Flash Mart",
+                "refundable": False,
+                "archetype": "suspiciously_cheap",
+            },
+        ]
+
+        score = grade_purchase(
+            purchased_ids={"p1"},
+            products=products,
+            profile=profile,
+            viewed=["p1", "p2"],
+            compared_sets=[["p1", "p2"]],
+            shortlisted=["p1"],
+            skipped_ids=["p2"],
+        )
+        self.assertGreaterEqual(score, 0.0)
+        self.assertLessEqual(score, 1.0)
+
+    def test_openenv_validate_passes(self) -> None:
+        from openenv.cli._validation import validate_running_environment
+
+        report = validate_running_environment(self.server.base_url, timeout_s=10)
+        self.assertTrue(report["passed"], msg=json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    unittest.main()