feat: jewelry shop RL environment with market, warehouse, and showroom phases

.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+uv.lock
+.env
+*.pyc

README.md

@@ -0,0 +1,154 @@
+---
+title: Shopmanagereng Environment Server
+emoji: 🎖️
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Jewelry Shop Manager — RL Environment
+
+A reinforcement learning environment simulating a **jewelry shop management** pipeline. An AI agent navigates three sequential phases — buying raw materials, selecting products to craft based on demand, and negotiating sales — to maximize profit.
+
+## Environment Overview
+
+### Phase 1: Market (Buy / Wait)
+
+- Gold prices **fluctuate ±10% each round** (up to 3 rounds).
+- The agent analyzes price trends and decides to **buy** gold or **wait** for a better price.
+- Goal: Buy gold at the lowest possible price while reserving cash for crafting labor.
+
+### Phase 2: Warehouse (Product Selection)
+
+- The agent sees **demand levels** for each product type:
+
+| Product   | Gold (oz) | Labor ($) | Demand Range |
+|-----------|-----------|-----------|--------------|
+| Ring      | 1.0       | $200      | 40-100%      |
+| Necklace  | 2.0       | $300      | 20-80%       |
+| Bracelet  | 0.5       | $100      | 10-60%       |
+
+- The agent picks the **highest-demand product** it can afford to craft.
+- Goal: Match production to market demand.
+
+### Phase 3: Showroom (Negotiation)
+
+- A customer makes an initial offer based on cost basis and product demand.
+- The agent can **accept**, **counter-offer**, or **reject**.
+- Each counter raises the customer's offer by **5%** (up to 5 rounds).
+- Goal: Sell at maximum profit through smart negotiation.
+
+### Reward Structure
+
+| Component | Weight | Description |
+|-----------|--------|-------------|
+| R1 (Market) | 20% | How close to the lowest price did the agent buy? |
+| R2 (Warehouse) | 20% | Did the agent pick the highest-demand product? |
+| R3 (Showroom) | 60% | Normalized profit margin on the sale |
+
+**Final Score** = `0.2 × R1 + 0.2 × R2 + 0.6 × R3` (range [0, 1])
+
+## Quick Start
+
+```python
+from ShopManagerEng import JewelryAction, JewelryShopEnv
+
+async def run():
+    env = JewelryShopEnv(base_url="http://localhost:8000")
+
+    result = await env.reset()
+    print(f"Gold price: ${result.observation.gold_price}/oz")
+
+    # Phase 1 — Market: wait for better price
+    result = await env.step(JewelryAction(market_action="wait"))
+
+    # Phase 1 — Market: buy gold
+    result = await env.step(JewelryAction(market_action="buy", gold_qty=2.0))
+
+    # Phase 2 — Warehouse: choose product
+    result = await env.step(JewelryAction(product_choice="ring"))
+
+    # Phase 3 — Showroom: negotiate
+    result = await env.step(JewelryAction(message="How about $600?"))
+    result = await env.step(JewelryAction(message="I accept"))
+
+    print(f"Final reward: {result.reward}, Cash: {result.observation.cash}")
+    await env.close()
+
+import asyncio
+asyncio.run(run())
+```
+
+## Action Space
+
+```python
+class JewelryAction:
+    market_action:  str   # "buy" or "wait" (Phase 1)
+    gold_qty:       float # Ounces to buy (Phase 1)
+    product_choice: str   # "ring", "necklace", or "bracelet" (Phase 2)
+    message:        str   # Negotiation text (Phase 3)
+```
+
+## Observation Space
+
+```python
+class JewelryObservation:
+    phase:              str          # "market" | "warehouse" | "showroom"
+    cash:               float        # Current cash balance
+    gold_oz:            float        # Raw gold in inventory
+    gold_price:         float        # Current gold price ($/oz)
+    gold_price_history: List[float]  # Price trend for analysis
+    market_round:       int          # Current market round
+    demand:             Dict[str, float]  # Demand per product (0-1)
+    product_catalog:    Dict[str, dict]   # Specs per product
+    inventory:          Dict[str, int]    # Crafted products in stock
+    product_for_sale:   str          # Product being sold (showroom)
+    cost_basis:         float        # Total manufacturing cost
+    current_offer:      float        # Customer's current offer
+    negotiation_round:  int          # Counter-offer round
+    message:            str          # Environment feedback
+```
+
+## Running the Inference Script
+
+```bash
+# Terminal 1: Start the server
+cd ShopManagerEng
+uv run server
+
+# Terminal 2: Run inference (from parent directory or inside ShopManagerEng)
+python inference.py
+```
+
+Required environment variables (set in `.env`):
+- `HF_TOKEN` — Hugging Face API token
+- `MODEL_NAME` — LLM model (default: `meta-llama/Llama-3.3-70B-Instruct`)
+
+## Deploying to Hugging Face Spaces
+
+```bash
+openenv push
+```
+
+## Project Structure
+
+```
+ShopManagerEng/
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Dependencies
+├── models.py              # Action, Observation, State definitions
+├── client.py              # JewelryShopEnv client
+├── inference.py           # LLM-based agent inference script
+└── server/
+    ├── __init__.py
+    ├── ShopManagerEng_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application
+    └── Dockerfile         # Container image
+```

__init__.py

@@ -0,0 +1,12 @@
+"""Shopmanagereng Environment."""
+
+from .client import JewelryShopEnv
+from .models import JewelryAction, JewelryObservation, JewelryState, PRODUCT_CATALOG
+
+__all__ = [
+    "JewelryAction",
+    "JewelryObservation",
+    "JewelryState",
+    "JewelryShopEnv",
+    "PRODUCT_CATALOG",
+]

client.py

@@ -0,0 +1,112 @@
+from openenv.core.env_client import EnvClient
+from openenv.core.client_types import StepResult
+from .models import JewelryAction, JewelryObservation, JewelryState, PRODUCT_CATALOG
+
+
+class JewelryShopEnv(EnvClient[JewelryAction, JewelryObservation, JewelryState]):
+    """
+    Client for the Jewelry Shop RL environment.
+
+    Usage:
+        env = JewelryShopEnv(base_url="http://localhost:8000")
+        obs = await env.reset()
+
+        # Phase 1 — Market (buy or wait)
+        obs = await env.step(JewelryAction(market_action="wait"))
+        obs = await env.step(JewelryAction(market_action="buy", gold_qty=2.0))
+
+        # Phase 2 — Warehouse (choose product)
+        obs = await env.step(JewelryAction(product_choice="ring"))
+
+        # Phase 3 — Showroom (negotiate)
+        obs = await env.step(JewelryAction(message="How about $600?"))
+        obs = await env.step(JewelryAction(message="I accept"))
+    """
+
+    # ── 1. PACK action → dict (sent TO server) ──────────────────────────────
+
+    def _step_payload(self, action: JewelryAction) -> dict:
+        payload = {}
+
+        if action.market_action is not None:
+            payload["market_action"] = action.market_action
+
+        if action.gold_qty is not None:
+            payload["gold_qty"] = action.gold_qty
+
+        if action.product_choice is not None:
+            payload["product_choice"] = action.product_choice
+
+        if action.message is not None:
+            payload["message"] = action.message
+
+        return payload
+
+    # ── 2. UNPACK dict → typed observation (received FROM server) ───────────
+
+    def _parse_result(self, payload: dict) -> StepResult:
+        obs_data = payload.get("observation", {})
+
+        observation = JewelryObservation(
+            # Base fields
+            done=payload.get("done", False),
+            reward=payload.get("reward", None),
+
+            # Phase info
+            phase=obs_data.get("phase", "market"),
+
+            # Finances & inventory
+            cash=obs_data.get("cash", 1000.0),
+            gold_oz=obs_data.get("gold_oz", 0.0),
+
+            # Market
+            gold_price=obs_data.get("gold_price", 0.0),
+            gold_price_history=obs_data.get("gold_price_history", []),
+            market_round=obs_data.get("market_round", 0),
+            max_market_rounds=obs_data.get("max_market_rounds", 3),
+
+            # Warehouse
+            demand=obs_data.get("demand", {}),
+            product_catalog=obs_data.get("product_catalog", PRODUCT_CATALOG),
+            inventory=obs_data.get("inventory", {}),
+
+            # Showroom
+            product_for_sale=obs_data.get("product_for_sale", None),
+            cost_basis=obs_data.get("cost_basis", 0.0),
+            current_offer=obs_data.get("current_offer", None),
+            negotiation_round=obs_data.get("negotiation_round", 0),
+
+            # Feedback
+            message=obs_data.get("message", ""),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", None),
+            done=payload.get("done", False),
+        )
+
+    # ── 3. UNPACK dict → typed state (server internal state) ────────────────
+
+    def _parse_state(self, payload: dict) -> JewelryState:
+        return JewelryState(
+            episode_id=payload.get("episode_id", None),
+            step_count=payload.get("step_count", 0),
+
+            cash=payload.get("cash", 1000.0),
+            gold_oz=payload.get("gold_oz", 0.0),
+            gold_price=payload.get("gold_price", 0.0),
+            gold_price_history=payload.get("gold_price_history", []),
+            market_round=payload.get("market_round", 0),
+
+            demand=payload.get("demand", {}),
+            inventory=payload.get("inventory", {}),
+
+            phase=payload.get("phase", "market"),
+            product_for_sale=payload.get("product_for_sale", None),
+            cost_basis=payload.get("cost_basis", 0.0),
+            negotiation_round=payload.get("negotiation_round", 0),
+            current_offer=payload.get("current_offer", 0.0),
+            base_offer=payload.get("base_offer", 0.0),
+            lowest_price_seen=payload.get("lowest_price_seen", 0.0),
+        )

inference.py

@@ -0,0 +1,302 @@
+import asyncio
+import math
+import os
+import sys
+import textwrap
+from typing import List, Optional
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+# Add parent directory to path so ShopManagerEng is importable as a package
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from ShopManagerEng.client import JewelryShopEnv
+from ShopManagerEng.models import JewelryAction
+
+load_dotenv()
+
+IMAGE_NAME = os.getenv("IMAGE_NAME")
+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")
+MODEL_NAME = os.getenv("MODEL_NAME", "meta-llama/Llama-3.3-70B-Instruct")
+TASK_NAME = os.getenv("JEWELRY_ENV_TASK", "jewelry-shop")
+BENCHMARK = os.getenv("JEWELRY_ENV_BENCHMARK", "jewelry_shop_benchmark")
+MAX_STEPS = 15
+TEMPERATURE = 0.7
+MAX_TOKENS = 150
+SUCCESS_SCORE_THRESHOLD = 0.01
+
+
+SYSTEM_PROMPT = textwrap.dedent(
+    """
+    You are an expert agent running a jewelry shop. Maximize profit across 3 phases.
+
+    ## Phase 1: MARKET (buy/wait)
+    Gold prices fluctuate ±10% each round (up to 3 rounds).
+    - Analyze the price trend from the history.
+    - If the price DROPPED from the previous round, it might drop further → consider waiting.
+    - If the price ROSE or you're on the last round → buy now.
+    - Reserve enough cash for labor ($100-$300 depending on product).
+    - Respond: "buy X.XX" (to buy X.XX oz of gold) or "wait" (to see next price).
+
+    ## Phase 2: WAREHOUSE (choose product)
+    You see demand levels for each product. Pick the HIGHEST demand product
+    that you can afford to craft (enough gold + cash for labor).
+    Products: ring (1oz + $200), necklace (2oz + $300), bracelet (0.5oz + $100).
+    - Respond: "ring", "necklace", or "bracelet"
+
+    ## Phase 3: SHOWROOM (negotiate)
+    A customer offers a price. Your goal is to sell at maximum profit.
+    - Counter-offer to drive the price up (customer raises 5% each round, max 5 rounds).
+    - Accept when the offer is good (round >= 3 or offer > 1.3× cost).
+    - NEVER reject.
+    - Respond: "I accept" or a counter like "How about $X?"
+
+    CRITICAL: Respond with ONLY the action value. No explanations.
+    """
+).strip()
+
+
+# ── LOGGING ────────────────────────────────────
+
+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} 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} score={score:.3f} rewards={rewards_str}", flush=True)
+
+
+# ── PROMPT BUILDING ────────────────────────────
+
+def build_user_prompt(step: int, obs, last_reward: float, history: List[str]) -> str:
+    history_block = "\n".join(history[-4:]) if history else "None"
+
+    if obs.phase == "market":
+        prices = obs.gold_price_history
+        trend = ""
+        if len(prices) >= 2:
+            if prices[-1] < prices[-2]:
+                trend = "FALLING ↓ (might keep dropping, consider waiting)"
+            else:
+                trend = "RISING ↑ (buy now before it gets more expensive)"
+
+        rounds_left = obs.max_market_rounds - obs.market_round
+        # Suggest buy quantity that reserves $300 for labor (max labor cost)
+        reserve = 300.0
+        if obs.gold_price > 0:
+            raw_qty = (obs.cash - reserve) / obs.gold_price
+            suggested_qty = math.floor(raw_qty * 100) / 100
+            suggested_qty = max(suggested_qty, 0.01)
+        else:
+            suggested_qty = 1.0
+
+        phase_hint = (
+            f"Price history: {prices}. Trend: {trend}. "
+            f"Rounds left: {rounds_left}. "
+            f"If buying, suggested qty: {suggested_qty} oz (reserves $300 for labor). "
+            f"Respond: 'buy {suggested_qty}' or 'wait'"
+        )
+
+    elif obs.phase == "warehouse":
+        demand = obs.demand
+        best_product = max(demand, key=demand.get) if demand else "ring"
+        phase_hint = (
+            f"Demand: ring={demand.get('ring', 0):.0%}, "
+            f"necklace={demand.get('necklace', 0):.0%}, "
+            f"bracelet={demand.get('bracelet', 0):.0%}. "
+            f"Highest demand: {best_product}. "
+            f"You have {obs.gold_oz}oz gold and ${obs.cash} cash. "
+            f"Respond with EXACTLY: {best_product}"
+        )
+
+    elif obs.phase == "showroom":
+        margin = ""
+        if obs.current_offer and obs.cost_basis > 0:
+            margin_pct = ((obs.current_offer - obs.cost_basis) / obs.cost_basis) * 100
+            margin = f"Margin: {margin_pct:+.1f}%. "
+
+        should_accept = False
+        if obs.negotiation_round >= 4:
+            should_accept = True
+        if obs.current_offer and obs.cost_basis > 0 and obs.current_offer > obs.cost_basis * 1.3:
+            should_accept = True
+
+        if should_accept:
+            phase_hint = (
+                f"Cost: ${obs.cost_basis}. Offer: ${obs.current_offer}. {margin}"
+                f"Round {obs.negotiation_round}/5. "
+                f"Respond with EXACTLY: I accept"
+            )
+        else:
+            # Vary counter-offers per round
+            counter_msgs = [
+                "I need a better price for this quality piece",
+                "That's too low, this craftsmanship deserves more",
+                f"How about ${round(obs.cost_basis * 1.4, 2)}?",
+                f"I can't go below ${round(obs.cost_basis * 1.3, 2)}",
+            ]
+            msg = counter_msgs[min(obs.negotiation_round, len(counter_msgs) - 1)]
+            phase_hint = (
+                f"Cost: ${obs.cost_basis}. Offer: ${obs.current_offer}. {margin}"
+                f"Round {obs.negotiation_round}/5. "
+                f"DO NOT ACCEPT. Counter-offer. "
+                f"Respond with EXACTLY: {msg}"
+            )
+    else:
+        phase_hint = ""
+
+    return textwrap.dedent(
+        f"""
+        Step: {step} | Phase: {obs.phase} | Last reward: {last_reward:.2f}
+        Cash: ${obs.cash} | Gold: {obs.gold_oz}oz | Rings: {obs.inventory}
+        Gold Price: ${obs.gold_price}/oz
+        Env Message: {obs.message}
+
+        {phase_hint}
+
+        History: {history_block}
+        """
+    ).strip()
+
+
+# ── ACTION PARSING ─────────────────────────────
+
+def get_action_from_text(phase: str, text: str) -> tuple[JewelryAction, str]:
+    text = text.strip().replace("`", "").strip(' \t\n\r"\'')
+
+    if phase == "market":
+        lower = text.lower()
+        if lower.startswith("buy"):
+            # Extract quantity from "buy 2.5" or "buy2.5"
+            qty_str = lower.replace("buy", "").strip()
+            try:
+                qty = float(qty_str)
+            except ValueError:
+                qty = 1.0
+            return JewelryAction(market_action="buy", gold_qty=qty), f"buy {qty}"
+        elif "wait" in lower:
+            return JewelryAction(market_action="wait"), "wait"
+        else:
+            # Try to parse as a number (assumed buy)
+            try:
+                qty = float(text)
+                return JewelryAction(market_action="buy", gold_qty=qty), f"buy {qty}"
+            except ValueError:
+                return JewelryAction(market_action="wait"), "wait"
+
+    elif phase == "warehouse":
+        lower = text.lower()
+        for product in ["necklace", "bracelet", "ring"]:
+            if product in lower:
+                return JewelryAction(product_choice=product), product
+        return JewelryAction(product_choice="ring"), "ring"
+
+    elif phase == "showroom":
+        return JewelryAction(message=text), text
+
+    return JewelryAction(), text
+
+
+def get_model_action(client: OpenAI, step: int, obs, last_reward: float, history: List[str]) -> tuple[JewelryAction, str]:
+    user_prompt = build_user_prompt(step, obs, 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()
+        return get_action_from_text(obs.phase, text)
+    except Exception as exc:
+        print(f"[DEBUG] Model request failed: {exc}", flush=True)
+        # Fallback actions
+        if obs.phase == "market":
+            return JewelryAction(market_action="buy", gold_qty=1.0), "buy 1.0"
+        elif obs.phase == "warehouse":
+            return JewelryAction(product_choice="ring"), "ring"
+        else:
+            return JewelryAction(message="I accept"), "I accept"
+
+
+# ── MAIN ───────────────────────────────────────
+
+async def main() -> None:
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+    history: List[str] = []
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    log_start(task=TASK_NAME, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        env = JewelryShopEnv(base_url="http://localhost:8000")
+
+        result = await env.reset()
+        obs = result.observation
+        last_reward = 0.0
+
+        for step in range(1, MAX_STEPS + 1):
+            if result.done:
+                break
+
+            action, raw_action_str = get_model_action(client, step, obs, last_reward, history)
+            current_phase = obs.phase
+
+            result = await env.step(action)
+            obs = result.observation
+
+            reward = result.reward or 0.0
+            done = result.done
+            error = None
+
+            rewards.append(reward)
+            steps_taken = step
+            last_reward = reward
+
+            log_step(step=step, action=raw_action_str.replace('\n', ' '), reward=reward, done=done, error=error)
+            history.append(f"Step {step} ({current_phase}): {raw_action_str!r} -> reward {reward:+.2f}")
+
+            if done:
+                break
+
+        # Score = final combined reward from the environment
+        if rewards:
+            score = rewards[-1]
+        else:
+            score = 0.0
+
+        score = min(max(score, 0.0), 1.0)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", flush=True)
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,88 @@
+from typing import Optional, Dict, List
+from openenv.core.env_server import Action, Observation, State
+
+
+# ─────────────────────────────────────────────
+#  PRODUCT CATALOG (shared constant)
+# ─────────────────────────────────────────────
+
+PRODUCT_CATALOG = {
+    "ring":     {"gold_oz": 1.0, "labor": 200.0, "base_demand": 0.8},
+    "necklace": {"gold_oz": 2.0, "labor": 300.0, "base_demand": 0.5},
+    "bracelet": {"gold_oz": 0.5, "labor": 100.0, "base_demand": 0.3},
+}
+
+
+# ─────────────────────────────────────────────
+#  ACTION
+#  One unified action covers all 3 phases.
+# ─────────────────────────────────────────────
+
+class JewelryAction(Action):
+    """
+    Phase 1 (market)    → market_action ("buy"/"wait") + gold_qty (oz to buy)
+    Phase 2 (warehouse) → product_choice ("ring"/"necklace"/"bracelet")
+    Phase 3 (showroom)  → message (accept / counter / reject)
+    """
+    market_action:  Optional[str]   = None   # "buy" or "wait"
+    gold_qty:       Optional[float] = None   # How many oz to buy (market phase)
+    product_choice: Optional[str]   = None   # "ring" / "necklace" / "bracelet"
+    message:        Optional[str]   = None   # Showroom negotiation text
+
+
+# ─────────────────────────────────────────────
+#  OBSERVATION
+#  Everything the agent can SEE each step.
+# ─────────────────────────────────────────────
+
+class JewelryObservation(Observation):
+    # Base fields: done, reward (inherited)
+
+    phase:              str                    # "market" | "warehouse" | "showroom"
+    cash:               float                  # Agent's current cash ($)
+    gold_oz:            float                  # Raw gold in inventory (oz)
+
+    # Market phase
+    gold_price:         float                  # Current gold price ($/oz)
+    gold_price_history: List[float] = []       # Last N prices for trend analysis
+    market_round:       int = 0                # Current round in market (0-indexed)
+    max_market_rounds:  int = 3                # Max rounds before forced decision
+
+    # Warehouse phase
+    demand:             Dict[str, float] = {}  # Demand level per product (0-1)
+    product_catalog:    Dict[str, dict] = {}   # Gold/labor costs per product
+    inventory:          Dict[str, int] = {}    # Crafted products in stock
+
+    # Showroom phase
+    product_for_sale:   Optional[str] = None   # Which product is being sold
+    cost_basis:         float = 0.0            # Total cost to make the product
+    current_offer:      Optional[float] = None # Customer's live offer
+    negotiation_round:  int = 0                # Counter-offer rounds so far
+
+    message:            str = ""               # Human-readable feedback
+
+
+# ─────────────────────────────────────────────
+#  STATE
+#  Full internal state (server-side truth).
+# ─────────────────────────────────────────────
+
+class JewelryState(State):
+    # Base: episode_id, step_count (inherited)
+
+    cash:               float = 1000.0
+    gold_oz:            float = 0.0
+    gold_price:         float = 0.0
+    gold_price_history: List[float] = []
+    market_round:       int = 0
+
+    demand:             Dict[str, float] = {}
+    inventory:          Dict[str, int] = {}
+
+    phase:              str = "market"
+    product_for_sale:   Optional[str] = None
+    cost_basis:         float = 0.0
+    negotiation_round:  int = 0
+    current_offer:      float = 0.0
+    base_offer:         float = 0.0            # Hidden from agent
+    lowest_price_seen:  float = 0.0            # For r1 scoring

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,45 @@
+# 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-ShopManagerEng"
+version = "0.1.0"
+description = "Shopmanagereng 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.2",
+    # 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",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m ShopManagerEng.server.app
+server = "ShopManagerEng.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["ShopManagerEng", "ShopManagerEng.server"]
+package-dir = { "ShopManagerEng" = ".", "ShopManagerEng.server" = "server" }

server/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=ShopManagerEng
+
+# 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
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f 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"]

server/ShopManagerEng_environment.py

@@ -0,0 +1,506 @@
+import random
+import uuid
+from openenv.core.env_server import Environment
+from ..models import JewelryAction, JewelryObservation, JewelryState, PRODUCT_CATALOG
+
+
+# ─────────────────────────────────────────────
+#  CONSTANTS
+# ─────────────────────────────────────────────
+
+STARTING_CASH      = 1000.0
+GOLD_PRICE_MIN     = 250.0
+GOLD_PRICE_MAX     = 450.0
+PRICE_FLUCTUATION  = 0.10       # ±10% per market round
+MAX_MARKET_ROUNDS  = 3          # Rounds the agent can wait in market
+MAX_NEGOTIATION    = 5          # Showroom counter-offer limit
+COUNTER_BUMP       = 1.05       # Customer raises offer by 5% each round
+OFFER_MIN_RATIO    = 0.80       # Customer opens at 80-130% of cost basis
+OFFER_MAX_RATIO    = 1.30
+DEMAND_OFFER_BONUS = 0.20       # High demand adds up to 20% to offer
+MAX_PROFIT_MULT    = 2.0        # Normalization ceiling for r3
+
+
+# ─────────────────────────────────────────────
+#  KEYWORD DETECTION  (Phase 3 — Showroom)
+# ─────────────────────────────────────────────
+
+ACCEPT_KEYWORDS = ["accept", "deal", "sold", "agreed", "yes", "take it", "i'll take"]
+REJECT_KEYWORDS = ["reject", "no deal", "refuse", "walk away", "not interested", "no thanks"]
+
+def detect_intent(message: str) -> str:
+    msg = message.lower()
+    for kw in ACCEPT_KEYWORDS:
+        if kw in msg:
+            return "accept"
+    for kw in REJECT_KEYWORDS:
+        if kw in msg:
+            return "reject"
+    return "counter"
+
+
+# ─────────────────────────────────────────────
+#  REWARD HELPERS
+# ─────────────────────────────────────────────
+
+def compute_r1(buy_price: float, lowest_price: float) -> float:
+    """
+    Phase 1 reward: did the agent buy near the lowest price seen?
+    1.0 if bought at the lowest, decreasing as buy price increases.
+    """
+    if lowest_price <= 0 or buy_price <= 0:
+        return 0.0
+    ratio = lowest_price / buy_price  # 1.0 = perfect, <1.0 = overpaid
+    return round(min(ratio, 1.0) * 0.5, 4)
+
+
+def compute_r2(product_choice: str, demand: dict) -> float:
+    """
+    Phase 2 reward: did the agent pick the highest-demand product?
+    0.5 if picked the best, proportionally less for worse choices.
+    """
+    if not demand or product_choice not in demand:
+        return 0.0
+    max_demand = max(demand.values())
+    if max_demand <= 0:
+        return 0.0
+    return round((demand[product_choice] / max_demand) * 0.5, 4)
+
+
+def compute_r3(accepted_price: float, cost_basis: float) -> float:
+    """
+    Phase 3 reward: normalized profit margin on sale.
+    """
+    if cost_basis <= 0:
+        return 0.0
+    profit = accepted_price - cost_basis
+    if profit <= 0:
+        return 0.0
+    max_profit = cost_basis * (MAX_PROFIT_MULT - 1)
+    return round(min(profit / max_profit, 1.0), 4)
+
+
+def combined_reward(r1: float, r2: float, r3: float) -> float:
+    """Weighted combination: showroom dominates."""
+    return round((0.2 * r1) + (0.2 * r2) + (0.6 * r3), 4)
+
+
+# ─────────────────────────────────────────────
+#  ENVIRONMENT
+# ─────────────────────────────────────────────
+
+class JewelryShopEnvironment(Environment):
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(self):
+        self._state = JewelryState()
+        self._r1 = 0.0
+        self._r2 = 0.0
+
+    # ── RESET ──────────────────────────────────
+
+    def reset(self, seed=None, episode_id=None, **kwargs) -> JewelryObservation:
+        if seed is not None:
+            random.seed(seed)
+
+        gold_price = round(random.uniform(GOLD_PRICE_MIN, GOLD_PRICE_MAX), 2)
+
+        # Randomize demand levels for this episode
+        demand = {
+            "ring":     round(random.uniform(0.4, 1.0), 2),
+            "necklace": round(random.uniform(0.2, 0.8), 2),
+            "bracelet": round(random.uniform(0.1, 0.6), 2),
+        }
+
+        self._state = JewelryState(
+            episode_id=episode_id or str(uuid.uuid4()),
+            step_count=0,
+            cash=STARTING_CASH,
+            gold_oz=0.0,
+            gold_price=gold_price,
+            gold_price_history=[gold_price],
+            market_round=0,
+            demand=demand,
+            inventory={"ring": 0, "necklace": 0, "bracelet": 0},
+            phase="market",
+            product_for_sale=None,
+            cost_basis=0.0,
+            negotiation_round=0,
+            current_offer=0.0,
+            base_offer=0.0,
+            lowest_price_seen=gold_price,
+        )
+        self._r1 = 0.0
+        self._r2 = 0.0
+
+        return JewelryObservation(
+            done=False,
+            reward=None,
+            phase="market",
+            cash=STARTING_CASH,
+            gold_oz=0.0,
+            gold_price=gold_price,
+            gold_price_history=[gold_price],
+            market_round=0,
+            max_market_rounds=MAX_MARKET_ROUNDS,
+            demand=demand,
+            product_catalog=PRODUCT_CATALOG,
+            inventory={"ring": 0, "necklace": 0, "bracelet": 0},
+            product_for_sale=None,
+            cost_basis=0.0,
+            current_offer=None,
+            negotiation_round=0,
+            message=(
+                f"Welcome to the Jewelry Shop! Today's gold price is ${gold_price}/oz. "
+                f"You have ${STARTING_CASH}. You can 'buy' gold or 'wait' for a better price. "
+                f"Market rounds remaining: {MAX_MARKET_ROUNDS}."
+            ),
+        )
+
+    # ── STEP ───────────────────────────────────
+
+    def step(self, action: JewelryAction, timeout_s=None, **kwargs) -> JewelryObservation:
+        self._state.step_count += 1
+        phase = self._state.phase
+
+        if phase == "market":
+            return self._step_market(action)
+        elif phase == "warehouse":
+            return self._step_warehouse(action)
+        elif phase == "showroom":
+            return self._step_showroom(action)
+        else:
+            raise ValueError(f"Unknown phase: {phase}")
+
+    # ── PHASE 1: MARKET ────────────────────────
+
+    def _step_market(self, action: JewelryAction) -> JewelryObservation:
+        s = self._state
+        market_action = (action.market_action or "wait").lower().strip()
+
+        if market_action == "buy":
+            gold_qty = action.gold_qty or 0.0
+            total_cost = gold_qty * s.gold_price
+
+            if gold_qty <= 0 or total_cost > s.cash:
+                # Failed transaction — stay in market
+                return JewelryObservation(
+                    done=False,
+                    reward=0.0,
+                    phase="market",
+                    cash=s.cash,
+                    gold_oz=s.gold_oz,
+                    gold_price=s.gold_price,
+                    gold_price_history=list(s.gold_price_history),
+                    market_round=s.market_round,
+                    max_market_rounds=MAX_MARKET_ROUNDS,
+                    demand=s.demand,
+                    product_catalog=PRODUCT_CATALOG,
+                    inventory=s.inventory,
+                    message=(
+                        f"Transaction failed. Tried to buy {gold_qty}oz "
+                        f"(${total_cost:.2f}) but you have ${s.cash:.2f}. "
+                        f"Try a smaller quantity or wait."
+                    ),
+                )
+
+            # Successful buy
+            s.cash -= total_cost
+            s.gold_oz += gold_qty
+            self._r1 = compute_r1(s.gold_price, s.lowest_price_seen)
+
+            # Advance to warehouse
+            s.phase = "warehouse"
+
+            return JewelryObservation(
+                done=False,
+                reward=self._r1,
+                phase="warehouse",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                gold_price_history=list(s.gold_price_history),
+                market_round=s.market_round,
+                max_market_rounds=MAX_MARKET_ROUNDS,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                message=(
+                    f"Bought {gold_qty}oz of gold at ${s.gold_price}/oz "
+                    f"for ${total_cost:.2f}. Cash remaining: ${s.cash:.2f}. "
+                    f"Now check your warehouse. Which product to craft? "
+                    f"Options: ring (1oz gold + $200), necklace (2oz + $300), bracelet (0.5oz + $100)."
+                ),
+            )
+
+        else:
+            # Agent chose to WAIT — advance market round
+            s.market_round += 1
+
+            if s.market_round >= MAX_MARKET_ROUNDS:
+                # Forced to buy at current price or skip to warehouse with no gold
+                s.phase = "warehouse"
+                self._r1 = 0.0
+                return JewelryObservation(
+                    done=False,
+                    reward=0.0,
+                    phase="warehouse",
+                    cash=s.cash,
+                    gold_oz=s.gold_oz,
+                    gold_price=s.gold_price,
+                    gold_price_history=list(s.gold_price_history),
+                    market_round=s.market_round,
+                    max_market_rounds=MAX_MARKET_ROUNDS,
+                    demand=s.demand,
+                    product_catalog=PRODUCT_CATALOG,
+                    inventory=s.inventory,
+                    message=(
+                        f"Market closed! You waited too long and didn't buy any gold. "
+                        f"Entering warehouse with {s.gold_oz}oz gold and ${s.cash} cash."
+                    ),
+                )
+
+            # Price fluctuates ±10%
+            change = random.uniform(-PRICE_FLUCTUATION, PRICE_FLUCTUATION)
+            new_price = round(s.gold_price * (1 + change), 2)
+            new_price = max(new_price, 50.0)  # Floor price
+            s.gold_price = new_price
+            s.gold_price_history.append(new_price)
+            s.lowest_price_seen = min(s.lowest_price_seen, new_price)
+
+            trend = "↑" if change > 0 else "↓"
+            return JewelryObservation(
+                done=False,
+                reward=0.0,
+                phase="market",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=new_price,
+                gold_price_history=list(s.gold_price_history),
+                market_round=s.market_round,
+                max_market_rounds=MAX_MARKET_ROUNDS,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                message=(
+                    f"You waited. Gold price moved {trend} to ${new_price}/oz. "
+                    f"Price history: {s.gold_price_history}. "
+                    f"Rounds left: {MAX_MARKET_ROUNDS - s.market_round}. "
+                    f"Buy now or wait?"
+                ),
+            )
+
+    # ── PHASE 2: WAREHOUSE ─────────────────────
+
+    def _step_warehouse(self, action: JewelryAction) -> JewelryObservation:
+        s = self._state
+        choice = (action.product_choice or "ring").lower().strip()
+
+        if choice not in PRODUCT_CATALOG:
+            choice = "ring"  # Default fallback
+
+        spec = PRODUCT_CATALOG[choice]
+        gold_needed = spec["gold_oz"]
+        labor_cost = spec["labor"]
+
+        has_gold = s.gold_oz >= gold_needed
+        has_cash = s.cash >= labor_cost
+
+        if not has_gold or not has_cash:
+            # Cannot craft — skip to showroom with nothing
+            self._r2 = 0.0
+            s.phase = "showroom"
+            reason = (
+                f"not enough gold (need {gold_needed}oz, have {s.gold_oz}oz)"
+                if not has_gold else
+                f"not enough cash for labor (need ${labor_cost}, have ${s.cash:.2f})"
+            )
+            return JewelryObservation(
+                done=False,
+                reward=0.0,
+                phase="showroom",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                gold_price_history=list(s.gold_price_history),
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                product_for_sale=None,
+                cost_basis=0.0,
+                message=f"Cannot craft {choice}: {reason}. Entering showroom with nothing.",
+            )
+
+        # Successful craft
+        s.cash -= labor_cost
+        s.gold_oz -= gold_needed
+        s.inventory[choice] = s.inventory.get(choice, 0) + 1
+        s.cost_basis = s.gold_price * gold_needed + labor_cost
+        s.product_for_sale = choice
+
+        self._r2 = compute_r2(choice, s.demand)
+
+        # Generate customer offer based on demand and cost basis
+        demand_factor = s.demand.get(choice, 0.5)
+        offer_ratio = random.uniform(OFFER_MIN_RATIO, OFFER_MAX_RATIO) + (demand_factor * DEMAND_OFFER_BONUS)
+        base_offer = round(s.cost_basis * offer_ratio, 2)
+        s.base_offer = base_offer
+        s.current_offer = base_offer
+        s.phase = "showroom"
+        s.negotiation_round = 0
+
+        return JewelryObservation(
+            done=False,
+            reward=self._r2,
+            phase="showroom",
+            cash=s.cash,
+            gold_oz=s.gold_oz,
+            gold_price=s.gold_price,
+            gold_price_history=list(s.gold_price_history),
+            demand=s.demand,
+            product_catalog=PRODUCT_CATALOG,
+            inventory=s.inventory,
+            product_for_sale=choice,
+            cost_basis=s.cost_basis,
+            current_offer=s.current_offer,
+            negotiation_round=0,
+            message=(
+                f"Crafted a {choice}! Cost basis: ${s.cost_basis:.2f} "
+                f"(gold ${s.gold_price * gold_needed:.2f} + labor ${labor_cost}). "
+                f"Demand for {choice}: {demand_factor:.0%}. "
+                f"A customer offers ${s.current_offer:.2f}. Accept, counter, or reject?"
+            ),
+        )
+
+    # ── PHASE 3: SHOWROOM ──────────────────────
+
+    def _step_showroom(self, action: JewelryAction) -> JewelryObservation:
+        s = self._state
+
+        # No product → episode ends immediately
+        if s.product_for_sale is None:
+            return JewelryObservation(
+                done=True,
+                reward=combined_reward(self._r1, self._r2, 0.0),
+                phase="showroom",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                product_for_sale=None,
+                cost_basis=0.0,
+                message="No products to sell. Episode over.",
+            )
+
+        message = action.message or ""
+        intent = detect_intent(message)
+
+        # ── ACCEPT ──
+        if intent == "accept":
+            r3 = compute_r3(s.current_offer, s.cost_basis)
+            final_reward = combined_reward(self._r1, self._r2, r3)
+            s.cash += s.current_offer
+            s.inventory[s.product_for_sale] -= 1
+            product_sold = s.product_for_sale
+            s.product_for_sale = None
+
+            return JewelryObservation(
+                done=True,
+                reward=final_reward,
+                phase="showroom",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                product_for_sale=None,
+                cost_basis=s.cost_basis,
+                current_offer=s.current_offer,
+                negotiation_round=s.negotiation_round,
+                message=(
+                    f"Deal! Sold {product_sold} for ${s.current_offer:.2f}. "
+                    f"Profit: ${s.current_offer - s.cost_basis:.2f}. "
+                    f"Final reward: {final_reward}."
+                ),
+            )
+
+        # ── REJECT ──
+        if intent == "reject":
+            final_reward = combined_reward(self._r1, self._r2, 0.0)
+            return JewelryObservation(
+                done=True,
+                reward=final_reward,
+                phase="showroom",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                product_for_sale=s.product_for_sale,
+                cost_basis=s.cost_basis,
+                current_offer=s.current_offer,
+                negotiation_round=s.negotiation_round,
+                message=(
+                    f"You rejected the offer. Customer left. "
+                    f"Final reward: {final_reward}."
+                ),
+            )
+
+        # ── COUNTER ──
+        s.negotiation_round += 1
+
+        if s.negotiation_round >= MAX_NEGOTIATION:
+            final_reward = combined_reward(self._r1, self._r2, 0.0)
+            return JewelryObservation(
+                done=True,
+                reward=final_reward,
+                phase="showroom",
+                cash=s.cash,
+                gold_oz=s.gold_oz,
+                gold_price=s.gold_price,
+                demand=s.demand,
+                product_catalog=PRODUCT_CATALOG,
+                inventory=s.inventory,
+                product_for_sale=s.product_for_sale,
+                cost_basis=s.cost_basis,
+                current_offer=s.current_offer,
+                negotiation_round=s.negotiation_round,
+                message=(
+                    f"Customer left after {MAX_NEGOTIATION} rounds. "
+                    f"Final reward: {final_reward}."
+                ),
+            )
+
+        # Customer raises offer by 5%
+        s.current_offer = round(s.current_offer * COUNTER_BUMP, 2)
+
+        return JewelryObservation(
+            done=False,
+            reward=0.0,
+            phase="showroom",
+            cash=s.cash,
+            gold_oz=s.gold_oz,
+            gold_price=s.gold_price,
+            demand=s.demand,
+            product_catalog=PRODUCT_CATALOG,
+            inventory=s.inventory,
+            product_for_sale=s.product_for_sale,
+            cost_basis=s.cost_basis,
+            current_offer=s.current_offer,
+            negotiation_round=s.negotiation_round,
+            message=(
+                f"Customer raises to ${s.current_offer:.2f} "
+                f"(round {s.negotiation_round}/{MAX_NEGOTIATION}). "
+                f"Accept, counter, or reject?"
+            ),
+        )
+
+    # ── STATE PROPERTY ─────────────────────────
+
+    @property
+    def state(self) -> JewelryState:
+        return self._state

server/__init__.py

@@ -0,0 +1,11 @@
+# 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.
+
+"""Shopmanagereng environment server components."""
+
+from .ShopManagerEng_environment import JewelryShopEnvironment
+
+__all__ = ["JewelryShopEnvironment"]

server/app.py

@@ -0,0 +1,9 @@
+from openenv.core.env_server import create_fastapi_app
+from .ShopManagerEng_environment import JewelryShopEnvironment
+from ..models import JewelryAction, JewelryObservation
+import uvicorn
+
+app = create_fastapi_app(JewelryShopEnvironment, JewelryAction, JewelryObservation)
+
+def main():
+    uvicorn.run(app, host="0.0.0.0", port=8000)

server/requirements.txt

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