Store

Dockerfile

@@ -0,0 +1,82 @@
+# 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=store
+
+# 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"
+
+ENV ENABLE_WEB_INTERFACE=true
+
+# 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"]

README.md

@@ -0,0 +1,741 @@
+---
+title: Store Environment Server
+emoji: 🛒
+colorFrom: green
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Store Environment
+
+This repository now contains a CSV-backed neighborhood grocery simulation for
+OpenEnv. The environment is intentionally rooted in a kirana-store business
+loop: manage cash, stock, supplier orders, customer satisfaction, pricing, and
+durable operations upgrades over repeated decision windows.
+
+This README documents the current implementation, not the older echo-demo
+scaffold and not the earlier narrative plans. The runtime source of truth is:
+
+- `store/data/*.csv`
+- `store/models.py`
+- `store/server/store_environment.py`
+- `store/client.py`
+- `store/tests/*.py`
+
+If a note in `plan.md`, `plan2.md`, or `rules.md` conflicts with the code or the
+seed CSVs, this document follows the code and the current CSVs.
+
+## At A Glance
+
+- Episode horizon: `30` simulated days by default
+- Decision window: `3` committed days per step
+- Reward lookahead: `6` simulated days per step
+- Action shape: one bundled action containing `orders`, `prices`, and
+  `action_ids`
+- Observation shape: full store snapshot plus inventory, pending orders, market
+  catalog, seller profiles, marketing catalog, and an action guide
+- State storage: in-memory per environment instance, seeded from CSV files on
+  `reset()`
+- Reward form: `0.5 + normalized_difference`
+
+## Seed Data
+
+The environment seeds itself from the CSV files in `store/data/`.
+
+### Current seed snapshot
+
+- `store_state.csv`: 1 row
+- `stock.csv`: 30 rows
+- `market_offers.csv`: 100 rows
+- `seller_profiles.csv`: 4 rows
+- `pending_orders.csv`: 0 rows
+- `marketing_actions.csv`: 15 rows
+
+The opening store snapshot is currently:
+
+| Field | Value |
+|---|---:|
+| `day` | `1` |
+| `current_daily_expense_inr` | `3000` |
+| `bank_balance_inr` | `120000` |
+| `customer_satisfaction` | `70` |
+| `order_processing_capacity` | `500` |
+| `cumulative_profit_inr` | `0` |
+
+The current opening stock value is `237,192 INR`, which sits inside the intended
+`220k-260k INR` band.
+
+## Files And Roles
+
+| File | Role |
+|---|---|
+| `store/models.py` | Action, observation, and data models |
+| `store/server/store_environment.py` | Core simulation engine |
+| `store/client.py` | Client wrapper for remote HTTP/WebSocket usage |
+| `store/server/app.py` | FastAPI app factory entrypoint |
+| `store/data/*.csv` | Seed data and catalog source of truth |
+| `store/tests/test_seed_csvs.py` | Seed integrity checks |
+| `store/tests/test_store_environment.py` | Behavioral simulation tests |
+
+## Action Contract
+
+The agent sends one bundled action per decision window.
+
+```python
+from store import OrderRequest, PriceUpdate, StoreAction
+
+action = StoreAction(
+    orders=[
+        OrderRequest(product="Rice", seller="Seller A", quantity=25),
+        OrderRequest(product="Bread", seller="Seller C", quantity=12),
+    ],
+    prices=[PriceUpdate(product="Milk", price=33)],
+    action_ids=[7],
+)
+```
+
+Passing is:
+
+```python
+StoreAction()
+```
+
+### Action fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `orders` | `list[OrderRequest]` | Supplier orders to place at the start of the step |
+| `prices` | `list[PriceUpdate] \| None` | Optional selling-price updates for stocked products |
+| `action_ids` | `list[int]` | Durable marketing or operations actions to activate |
+
+### Nested action models
+
+| Model | Fields |
+|---|---|
+| `OrderRequest` | `product`, `seller`, `quantity` |
+| `PriceUpdate` | `product`, `price` |
+
+### Validation rules for actions
+
+- `quantity` must be a positive integer.
+- `seller` must be one of `Seller A`, `Seller B`, `Seller C`, or `Seller D`.
+- `orders[*].product` must exist in `market_offers.csv`.
+- `prices[*].product` must already exist in current stock.
+- `prices[*].price` must be positive.
+- `action_ids` must exist in `marketing_actions.csv`.
+- Duplicate price updates for the same product are rejected.
+- Duplicate marketing action IDs in one step are rejected.
+- Already-active marketing actions cannot be activated again.
+
+## Observation Contract
+
+`StoreObservation` is the agent-facing state. The OpenEnv transport `State`
+still only carries `episode_id` and `step_count`, but the business state lives in
+the observation payload.
+
+### Top-level observation fields
+
+| Field | Meaning |
+|---|---|
+| `store` | Current top-level business snapshot |
+| `stock` | Current in-store inventory rows |
+| `pending_orders` | In-flight supplier orders |
+| `market` | Full supplier catalog with prices and ETAs |
+| `seller_profiles` | Seller behavior notes |
+| `marketing_actions` | Full action catalog plus active flags |
+| `available_action` | Agent guide showing the action shape |
+| `summary` | Human-readable step summary |
+| `reward` | Reward returned for the step |
+| `done` | Whether the episode has terminated |
+| `metadata` | Reward breakdown and simulation diagnostics |
+
+### Store snapshot fields
+
+`store` is a `StoreSnapshot` with:
+
+- `day`
+- `current_daily_expense_inr`
+- `bank_balance_inr`
+- `customer_satisfaction`
+- `order_processing_capacity`
+- `cumulative_profit_inr`
+- `active_action_ids`
+- `active_recurring_cost_inr`
+- `episode_horizon_days`
+- `commit_window_days`
+- `reward_horizon_days`
+
+### Available action guide
+
+Each observation includes an `available_action` block with:
+
+- `name`: always `action`
+- `description`: short instruction about the bundled step contract
+- `pass_action`: empty `StoreAction()`
+- `example_action`: a concrete non-empty example
+- `notes`: quick reminders about pass behavior, stock-only pricing, and durable
+  marketing actions
+
+## Step Lifecycle
+
+One call to `step()` performs a full decision-window update.
+
+### High-level order of operations
+
+1. Validate the bundle.
+2. Read the current live state.
+3. Compute starting capital.
+4. Clone the live runtime state into two branches:
+   - commit branch for the next `3` days of live state
+   - reward branch for the `6`-day reward forecast
+5. Apply the same action bundle to both branches once at the start of the
+   window.
+6. Update customer satisfaction once per decision window.
+7. Simulate daily operations on both branches.
+8. Commit only the `3`-day branch back to the live environment state.
+9. Compute reward from the `6`-day branch.
+10. Increment `step_count` and set `done` if the committed state crosses a
+    terminal condition.
+
+### What the action does at step start
+
+- Supplier orders are placed immediately and enter the pending queue.
+- The store pays the supplier cost immediately when the order is placed.
+- Price updates apply immediately to stocked items.
+- Marketing actions activate immediately and remain active for the rest of the
+  episode.
+- Customer satisfaction is recomputed once for the decision window after the
+  bundle is applied.
+
+### What happens during simulated days
+
+For each simulated day:
+
+- Active recurring marketing cost is charged.
+- Demand is converted into sales.
+- Sales revenue is added to bank balance.
+- Daily operating expense is charged.
+- COGS is tracked in cumulative profit accounting.
+- Pending orders are decremented by one day.
+- Arriving orders are received into stock.
+- The day counter advances by one.
+
+## Simulation Formulas
+
+The formulas below reflect the current implementation in
+`store/server/store_environment.py`.
+
+### Starting capital
+
+```text
+starting_capital = starting_bank_balance + total_inventory_value
+```
+
+`total_inventory_value` is the sum of `stock_value_inr` across current stock
+rows.
+
+### Effective daily orders
+
+```text
+effective_daily_orders = order_processing_capacity * (customer_satisfaction / 100)
+```
+
+This means the current satisfaction score is treated as a percentage scale.
+
+### Product margin
+
+```text
+margin_percent = ((selling_price_inr - buying_price_inr) / selling_price_inr) * 100
+```
+
+The implementation uses the current selling price, not the buying price, as the
+denominator.
+
+### Product selling score
+
+```text
+product_selling_score = max(0, demand_score - margin_percent * 3)
+```
+
+This is computed separately for each stocked item with positive on-hand
+quantity.
+
+### Total selling score
+
+```text
+total_product_selling_score = sum(product_selling_score for each stocked item)
+```
+
+### Daily sales allocation
+
+```text
+desired_sales_for_item = effective_daily_orders * product_selling_score / total_product_selling_score
+actual_sales = min(quantity_on_hand, desired_sales_for_item)
+```
+
+Sales are proportional to selling score across stocked items. Because the model
+is proportional and not integer-rounded, `quantity_on_hand` can become
+fractional after simulated sales.
+
+### Customer satisfaction update
+
+Before the window is simulated, the environment applies any marketing action
+delays to customer satisfaction. Then it recomputes a score-based multiplier.
+
+```text
+adjusted_satisfaction = current_satisfaction + sum(customer_satisfaction_delta for activated actions)
+
+if after_score > 0:
+    next_satisfaction = (1 + ((after_score - before_score) / after_score)) * adjusted_satisfaction
+else:
+    next_satisfaction = adjusted_satisfaction
+
+next_satisfaction is then clamped to the range [1, 100]
+```
+
+`before_score` is the total selling score before the bundle is applied.
+`after_score` is the total selling score after price updates and before the
+simulated days begin.
+
+### Order arrival
+
+When a pending order reaches `days_remaining <= 0`:
+
+- If the product already exists in stock, the order is merged into that row and
+  the buying price becomes the weighted average of the existing and incoming
+  units.
+- If the product does not exist in stock, a new stock row is created.
+- Newly created stock uses:
+
+```text
+selling_price = max(buying_price + 1, ceil(buying_price * 1.18))
+```
+
+The `1.18` markup is the implementation default for a newly introduced SKU.
+
+### Reward
+
+Reward is computed from the `6`-day reward branch:
+
+```text
+difference =
+    (ending_inventory_value + ending_bank_balance)
+    - (starting_inventory_value + starting_bank_balance)
+    - recurring_costs_paid_over_6_days
+
+normalized_difference = difference / starting_capital
+reward = 0.5 + normalized_difference
+```
+
+If `starting_capital <= 0`, the implementation falls back to
+`normalized_difference = 0`.
+
+### Reward metadata
+
+The step response includes reward diagnostics in `metadata`:
+
+- `reward_breakdown.starting_capital_inr`
+- `reward_breakdown.ending_capital_inr`
+- `reward_breakdown.difference_inr`
+- `reward_breakdown.normalized_difference`
+- `reward_breakdown.commit_window_days`
+- `reward_breakdown.reward_horizon_days`
+- `reward_breakdown.recurring_costs_paid_inr`
+- `commit_metrics`
+- `reward_metrics`
+- `done_reason`
+
+The code rounds the high-level reward breakdown to two decimals, except for
+`normalized_difference`, which is kept at six decimal places in metadata.
+
+## Seller Behavior And ETA Sampling
+
+Supplier ETA is deterministic within an episode because the environment seeds
+its RNG from the reset count. Different resets get different seeds, but the same
+episode run is repeatable once started.
+
+### Seller profiles
+
+| Seller | Behavior | ETA sampling |
+|---|---|---|
+| Seller A | Overcommits | `quoted + {0, 1, 2}` with delay-heavy weights |
+| Seller B | Strict | Uses quoted ETA exactly |
+| Seller C | Undercommits | `quoted + {-2, -1, 0}` with early-heavy weights |
+| Seller D | Variable | `quoted + {-1, 0, 1, 2}` with mixed weights |
+
+### Actual ETA rules
+
+- The quoted ETA comes from the corresponding seller column in
+  `market_offers.csv`.
+- Actual ETA is sampled once when the order is placed.
+- The sampled ETA is floored at `1`.
+- Each simulated day decrements `days_remaining` by `1`.
+- When `days_remaining <= 0`, the order is received.
+
+### Exact weights in the current code
+
+- Seller A: offsets `[0, 1, 2]` with weights `[2, 4, 5]`
+- Seller B: offset `[0]`
+- Seller C: offsets `[-2, -1, 0]` with weights `[5, 4, 2]`
+- Seller D: offsets `[-1, 0, 1, 2]` with weights `[2, 4, 3, 2]`
+
+These weights are implementation details, not a business guarantee.
+
+## Data Contract
+
+### `store_state.csv`
+
+Current columns:
+
+- `day`
+- `current_daily_expense_inr`
+- `bank_balance_inr`
+- `customer_satisfaction`
+- `order_processing_capacity`
+- `cumulative_profit_inr`
+
+### `stock.csv`
+
+Current columns:
+
+- `product_name`
+- `unit`
+- `buying_price_inr`
+- `selling_price_inr`
+- `demand_score`
+- `quantity_on_hand`
+- `stock_value_inr`
+
+The seed data includes 30 stocked products and the stored value must equal
+`buying_price_inr * quantity_on_hand` on each row.
+
+### `market_offers.csv`
+
+Current columns:
+
+- `product_name`
+- `category`
+- `unit`
+- `demand_score`
+- `seller_a_price_inr`
+- `seller_a_etd_days`
+- `seller_b_price_inr`
+- `seller_b_etd_days`
+- `seller_c_price_inr`
+- `seller_c_etd_days`
+- `seller_d_price_inr`
+- `seller_d_etd_days`
+
+The current catalog contains 100 products.
+
+### `seller_profiles.csv`
+
+Current columns:
+
+- `seller_name`
+- `timeline_behavior`
+- `reliability_note`
+- `default_etd_days`
+
+### `pending_orders.csv`
+
+Current columns:
+
+- `order_id`
+- `product_name`
+- `quantity`
+- `seller_name`
+- `buy_price_inr`
+- `days_remaining`
+- `status`
+- `created_day`
+
+The seed file starts empty.
+
+### `marketing_actions.csv`
+
+Current columns:
+
+- `action_id`
+- `description`
+- `customer_satisfaction_delta`
+- `cost_inr`
+- `recurring_cost_inr`
+- `order_processing_capacity_delta`
+
+The current catalog contains 15 durable action rows.
+
+## Episode End Conditions
+
+The environment uses a default episode horizon of `30` days, but each step
+advances the live state by `3` days, so a full default episode lasts 10
+decision windows.
+
+The episode ends when either:
+
+- committed bank balance drops below `0`
+- committed day exceeds `30`
+
+The current implementation checks `day > 30` after the commit branch is
+applied, so the tenth decision window takes the day counter to `31` and ends
+the episode.
+
+## Practical Edge Cases
+
+### Fractional inventory
+
+Sales are proportional, so on-hand inventory can become fractional. The models
+use floats for inventory fields for that reason.
+
+### Empty sales mix
+
+If all stocked items have zero selling score or zero quantity, the sales loop
+returns zero revenue and zero COGS for that day.
+
+### Zero or negative starting capital
+
+The reward math guards against division by zero by falling back to a zero
+normalized difference.
+
+### Already-active marketing actions
+
+Once a marketing action is active, a later step that tries to re-activate it
+raises a validation error.
+
+### Product pricing
+
+Price updates only apply to products already in stock. If a product is not in
+stock yet, you must wait for a supplier order to arrive before changing its
+price.
+
+### New stock rows
+
+If a pending order arrives for a product not currently in stock, the environment
+creates a new stock row on arrival. This is rare in the seeded scenario, but the
+code supports it.
+
+## How To Run
+
+The project is designed to run through `uv` so the declared dependencies are
+available. In this workspace, the global shell does not include `openenv-core`
+or `pytest`, so prefer the project environment.
+
+### Install dependencies
+
+```bash
+cd store
+uv sync
+```
+
+### Start the server
+
+```bash
+cd store
+uv run --project . server --port 8000
+```
+
+### Start the Gradio playground
+
+```bash
+cd store
+uv run --project . gradio
+```
+
+By default the Gradio UI launches on `http://127.0.0.1:7860` and runs the
+environment in-process, so you do not need the FastAPI server running to play
+with the simulation manually.
+
+### Validate the OpenEnv package
+
+```bash
+cd store
+uv run --project . openenv validate .
+```
+
+### Run the tests
+
+```bash
+cd store
+uv run --project . python -m pytest
+```
+
+## How To Play Manually
+
+You can interact with the simulation directly from Python without starting a
+network server:
+
+```python
+from store import OrderRequest, PriceUpdate, StoreAction
+from store.server.store_environment import StoreEnvironment
+
+env = StoreEnvironment()
+obs = env.reset()
+
+print(obs.store)
+print(obs.summary)
+
+step = env.step(
+    StoreAction(
+        orders=[OrderRequest(product="Rice", seller="Seller A", quantity=25)],
+        prices=[PriceUpdate(product="Milk", price=33)],
+        action_ids=[7],
+    )
+)
+
+print(step.reward)
+print(step.done)
+print(step.metadata["reward_breakdown"])
+print(step.store.day)
+```
+
+### Passing a step
+
+```python
+env.step(StoreAction())
+```
+
+### Using the Gradio UI
+
+The Gradio frontend lives in `store/gradio_app.py` and is designed as a local
+playground for the same bundled action contract:
+
+- `Orders JSON`: JSON array of `{product, seller, quantity}` objects
+- `Price Updates JSON`: JSON array of `{product, price}` objects
+- `Action IDs`: either a JSON array like `[7, 12]`, a single integer, or a
+  comma-separated string like `7, 12`
+
+UI controls:
+
+- `Reset Episode`: creates a fresh `StoreEnvironment` instance and resets it
+- `Submit Step`: validates the current inputs and executes one step
+- `Pass Step`: executes a real pass action immediately
+- `Load Example`: fills the inputs using the observation's bundled example action
+
+The UI displays:
+
+- current store snapshot
+- stock table
+- pending orders
+- market catalog
+- marketing action catalog
+- reward breakdown
+- raw observation metadata
+
+Invalid JSON or action validation errors are shown in the UI while preserving
+the current episode state so you can correct the inputs and try again.
+
+### Inspecting the current state
+
+The most useful fields to inspect after each step are:
+
+- `obs.store`
+- `obs.stock`
+- `obs.pending_orders`
+- `obs.marketing_actions`
+- `obs.metadata["reward_breakdown"]`
+- `obs.metadata["done_reason"]`
+
+## OpenEnv Client Usage
+
+If you want to connect to a running server, use `StoreEnv`:
+
+```python
+from store import OrderRequest, PriceUpdate, StoreAction, StoreEnv
+
+with StoreEnv(base_url="http://localhost:8000") as client:
+    reset_result = client.reset()
+    print(reset_result.observation.store)
+
+    step_result = client.step(
+        StoreAction(
+            orders=[OrderRequest(product="Rice", seller="Seller A", quantity=10)],
+            prices=[PriceUpdate(product="Milk", price=33)],
+            action_ids=[7],
+        )
+    )
+
+    print(step_result.reward)
+    print(step_result.observation.summary)
+```
+
+The client serializes the action bundle to JSON and reconstructs typed
+observations from the server response.
+
+## Tests
+
+The current test suite includes:
+
+- `store/tests/test_seed_csvs.py`
+- `store/tests/test_store_environment.py`
+
+These tests cover:
+
+- CSV shape and seed integrity
+- opening store values
+- market catalog completeness
+- marketing action rows
+- reset behavior
+- 3-day commit semantics
+- 6-day reward forecasting
+- ETA sampling
+- customer satisfaction changes
+- durable marketing actions
+- episode termination
+- client serialization and parsing
+
+### Useful test command
+
+```bash
+cd store
+uv run --project . python -m pytest store/tests/test_seed_csvs.py store/tests/test_store_environment.py
+```
+
+## Known Limitations
+
+- The simulation is deterministic aside from seller ETA sampling, which is
+  seeded per reset.
+- Demand is not a full market model; it is based on stock-level selling score
+  proportions.
+- There is no spoilage, shrinkage, theft, or seasonality model.
+- There is no supplier cancellation workflow.
+- Sales can become fractional because the simulation allocates demand
+  proportionally.
+- The environment exposes the full market and marketing catalogs every step, so
+  observations are intentionally verbose.
+- Reward is unbounded and can be greater than `1.0` or less than `0.0`.
+- `plan.md` and `plan2.md` are useful design notes, but the code and CSVs are
+  the authoritative implementation.
+
+## Assumptions
+
+- The agent-facing state is the observation payload, not the OpenEnv transport
+  `State`.
+- CSV seed files are runtime truth and are re-read on every reset.
+- The bundled action is the only supported step input.
+- Marketing actions are durable and stay active once activated.
+- A 30-day horizon with 3-day windows is the intended default episode shape.
+- Current seed values in `store_state.csv` are intentional and should not be
+  replaced with the older numbers from the narrative docs unless the code and
+  tests are updated together.
+
+## Packaging Notes
+
+The OpenEnv manifest is `store/openenv.yaml`, and the server entry point is
+`store.server.app:app` with the script entry point `server = "store.server.app:main"`.
+
+The current package also declares:
+
+- `openenv-core[core]>=0.2.2`
+- `pydantic>=2.0.0`
+
+## Further Reading
+
+- `store/models.py`
+- `store/server/store_environment.py`
+- `store/tests/test_store_environment.py`
+- `store/tests/test_seed_csvs.py`

__init__.py

@@ -0,0 +1,31 @@
+"""Store OpenEnv package exports."""
+
+from .client import StoreEnv
+from .models import (
+    AvailableActionSpec,
+    MarketingAction,
+    MarketOffer,
+    OrderRequest,
+    PendingOrder,
+    PriceUpdate,
+    SellerProfile,
+    StockItem,
+    StoreAction,
+    StoreObservation,
+    StoreSnapshot,
+)
+
+__all__ = [
+    "AvailableActionSpec",
+    "MarketingAction",
+    "MarketOffer",
+    "OrderRequest",
+    "PendingOrder",
+    "PriceUpdate",
+    "SellerProfile",
+    "StockItem",
+    "StoreAction",
+    "StoreEnv",
+    "StoreObservation",
+    "StoreSnapshot",
+]

_compat.py

@@ -0,0 +1,62 @@
+"""Compatibility helpers for local development without openenv-core."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+ActionT = TypeVar("ActionT")
+ObservationT = TypeVar("ObservationT")
+StateT = TypeVar("StateT")
+
+try:  # pragma: no cover - exercised when openenv-core is installed
+    from openenv.core import EnvClient
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import Action, Observation, State
+
+    OPENENV_AVAILABLE = True
+except ImportError:  # pragma: no cover - local fallback for unit tests
+    OPENENV_AVAILABLE = False
+
+    class Action(BaseModel):
+        """Fallback action model."""
+
+    class Observation(BaseModel):
+        """Fallback observation model."""
+
+        reward: float | None = None
+        done: bool = False
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+    class State(BaseModel):
+        """Fallback transport state."""
+
+        episode_id: str | None = None
+        step_count: int = 0
+
+    class Environment(Generic[ObservationT, ActionT]):
+        """Fallback environment interface."""
+
+        SUPPORTS_CONCURRENT_SESSIONS: bool = False
+
+    @dataclass
+    class StepResult(Generic[ObservationT]):
+        """Fallback step result container."""
+
+        observation: ObservationT
+        reward: float | None = None
+        done: bool = False
+
+    class EnvClient(Generic[ActionT, ObservationT, StateT]):
+        """Fallback client base class used only for local parsing tests."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            self._base_url = kwargs.get("base_url")
+
+        def close(self) -> None:
+            """Mirror the real client close method."""
+
+            return None

client.py

@@ -0,0 +1,53 @@
+"""Client for the Store OpenEnv simulation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from ._compat import EnvClient, State, StepResult
+    from .models import StoreAction, StoreObservation, dump_model
+except ImportError:  # pragma: no cover - supports direct module imports
+    from _compat import EnvClient, State, StepResult
+    from models import StoreAction, StoreObservation, dump_model
+
+
+class StoreEnv(
+    EnvClient[StoreAction, StoreObservation, State]
+):
+    """Client wrapper for the store environment."""
+
+    def _step_payload(self, action: StoreAction) -> dict[str, Any]:
+        """Convert a store action into a JSON payload."""
+
+        return dump_model(action, exclude_none=True, exclude_defaults=True)
+
+    def _parse_result(self, payload: dict[str, Any]) -> StepResult[StoreObservation]:
+        """Parse a server response into a typed observation."""
+
+        obs_data = payload.get("observation", {})
+        clean_obs_data = {
+            key: value
+            for key, value in obs_data.items()
+            if key not in {"done", "reward", "metadata"}
+        }
+        observation = StoreObservation(
+            **clean_obs_data,
+            done=payload.get("done", obs_data.get("done", False)),
+            reward=payload.get("reward", obs_data.get("reward")),
+            metadata=obs_data.get("metadata", payload.get("metadata", {})),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: dict[str, Any]) -> State:
+        """Parse the OpenEnv transport state payload."""
+
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

data/market_offers.csv

@@ -0,0 +1,101 @@
+product_name,category,unit,demand_score,seller_a_price_inr,seller_a_etd_days,seller_b_price_inr,seller_b_etd_days,seller_c_price_inr,seller_c_etd_days,seller_d_price_inr,seller_d_etd_days
+Rice,Pantry Staples,pack,92,138,2,160,3,165,5,164,4
+Wheat Flour,Pantry Staples,pack,88,87,2,100,3,94,5,101,4
+Other Flours,Pantry Staples,pack,65,139,2,140,3,141,4,139,3
+Dals,Pantry Staples,pack,80,154,2,175,3,182,5,172,4
+Pulses,Pantry Staples,pack,76,180,2,200,3,202,5,201,4
+Salt,Pantry Staples,pack,70,20,2,20,3,18,4,20,3
+Sugar,Pantry Staples,pack,74,78,2,80,3,76,4,78,3
+Jaggery,Pantry Staples,pack,58,81,2,90,3,91,4,90,3
+Cooking Oil,Pantry Staples,bottle,94,156,2,180,3,186,5,184,4
+Ghee,Pantry Staples,jar,68,521,2,520,3,526,5,522,4
+Spices,Pantry Staples,pack,81,345,2,400,3,405,5,402,4
+Masalas,Pantry Staples,pack,78,162,2,180,3,182,5,181,4
+Dry Fruits,Pantry Staples,pack,52,601,2,600,3,607,4,602,3
+Nuts,Pantry Staples,pack,54,451,2,450,3,455,4,452,3
+Seeds,Pantry Staples,pack,49,147,2,150,3,156,4,147,3
+Poha,Pantry Staples,pack,60,61,2,70,3,66,4,71,3
+Suji / Rava,Pantry Staples,pack,63,54,2,60,3,56,4,60,3
+Besan,Pantry Staples,pack,61,99,2,110,3,103,4,110,3
+Maida,Pantry Staples,pack,57,48,2,55,3,52,4,56,3
+Breakfast Cereals,Breakfast & Convenience,box,59,258,2,260,3,264,4,241,2
+Oats,Breakfast & Convenience,pack,64,175,2,180,3,186,4,170,2
+Pasta,Breakfast & Convenience,pack,62,92,2,95,3,98,4,90,2
+Noodles,Breakfast & Convenience,pack,75,64,2,65,3,68,4,59,2
+Vermicelli,Breakfast & Convenience,pack,53,67,2,70,3,72,4,66,2
+Ready-to-Cook Mixes,Breakfast & Convenience,pack,56,120,2,125,3,118,4,122,2
+Ready-to-Eat Foods,Breakfast & Convenience,pack,58,146,2,150,3,155,4,142,2
+Biscuits,Breakfast & Convenience,pack,90,20,2,20,3,18,4,19,2
+Cookies,Breakfast & Convenience,pack,66,74,2,75,3,79,4,68,2
+Rusk,Breakfast & Convenience,pack,51,58,2,60,3,57,4,57,2
+Snacks,Breakfast & Convenience,pack,72,68,2,70,3,73,4,66,2
+Namkeen,Breakfast & Convenience,pack,85,49,2,50,3,52,4,46,2
+Chips,Breakfast & Convenience,pack,82,35,2,35,3,36,4,32,2
+Sweets,Breakfast & Convenience,box,67,219,2,220,3,223,4,204,2
+Chocolates,Breakfast & Convenience,bar,77,38,2,40,3,41,4,38,2
+Candies,Breakfast & Convenience,pack,69,29,2,30,3,31,4,28,2
+Bakery Products,Breakfast & Convenience,pack,55,130,2,130,3,121,4,121,2
+Bread,Breakfast & Convenience,loaf,86,37,1,35,2,31,4,35,2
+Cakes,Breakfast & Convenience,piece,48,277,2,280,3,295,4,268,2
+Jams & Spreads,Condiments & Spreads,jar,55,165,2,170,3,176,4,169,3
+Peanut Butter,Condiments & Spreads,jar,50,234,2,240,3,250,4,241,3
+Honey,Condiments & Spreads,jar,46,257,2,260,3,274,4,252,3
+Pickles,Condiments & Spreads,jar,64,136,2,140,3,145,4,132,3
+Sauces,Condiments & Spreads,bottle,61,108,2,110,3,115,4,100,3
+Ketchup,Condiments & Spreads,bottle,73,103,2,105,3,110,4,96,3
+Chutneys,Condiments & Spreads,jar,57,89,2,90,3,95,4,83,3
+Vinegar,Condiments & Spreads,bottle,38,83,2,85,3,89,4,85,3
+Tea,Beverages,pack,87,307,2,350,3,365,4,348,2
+Coffee,Beverages,jar,62,505,2,500,3,524,4,475,2
+Health Drinks,Beverages,jar,49,323,2,320,3,335,4,304,2
+Soft Drinks,Beverages,bottle,79,41,2,40,3,41,4,37,2
+Packaged Juices,Beverages,pack,71,57,2,55,3,56,4,51,2
+Energy Drinks,Beverages,can,44,96,2,95,3,99,4,90,2
+Bottled Water,Beverages,bottle,89,18,2,18,3,18,4,17,2
+Dairy Products,Dairy & Protein,pack,52,231,2,220,3,209,4,216,3
+Milk,Dairy & Protein,pouch,96,32,1,30,2,28,4,30,2
+Curd,Dairy & Protein,cup,82,38,1,35,2,33,4,35,2
+Butter,Dairy & Protein,pack,69,416,2,400,3,396,4,404,3
+Paneer,Dairy & Protein,pack,73,312,1,300,2,284,4,305,2
+Cheese,Dairy & Protein,pack,60,437,2,420,3,418,4,427,3
+Eggs,Dairy & Protein,dozen,84,77,1,72,2,64,4,72,2
+Frozen Foods,Frozen & Fresh,pack,45,202,2,190,3,185,4,189,4
+Frozen Snacks,Frozen & Fresh,pack,52,180,2,170,3,172,4,168,4
+Frozen Vegetables,Frozen & Fresh,pack,57,139,2,130,3,121,4,131,4
+Fruits,Frozen & Fresh,kg,79,52,1,50,2,47,3,50,2
+Vegetables,Frozen & Fresh,kg,84,42,1,40,2,38,3,40,2
+Leafy Vegetables,Frozen & Fresh,kg,76,31,1,30,2,28,3,30,2
+Exotic Fruits,Frozen & Fresh,kg,43,187,3,180,4,179,6,183,5
+Exotic Vegetables,Frozen & Fresh,kg,41,170,3,160,4,156,6,159,5
+Cut Fruits & Vegetables,Frozen & Fresh,pack,58,95,2,90,3,86,4,89,4
+Sprouts,Frozen & Fresh,pack,62,48,1,45,2,42,3,45,2
+Detergents,Home Care,pack,78,249,2,250,3,260,5,251,3
+Fabric Care,Home Care,bottle,52,216,2,220,3,227,5,218,3
+Dishwash Products,Home Care,bottle,74,95,2,95,3,90,5,91,3
+Floor Cleaners,Home Care,bottle,57,139,2,140,3,145,5,139,3
+Toilet Cleaners,Home Care,bottle,56,113,2,115,3,118,5,114,3
+Bathroom Cleaners,Home Care,bottle,54,118,2,120,3,124,5,119,3
+Disinfectants,Home Care,bottle,61,178,2,180,3,186,5,179,3
+Utensil Cleaners,Home Care,pack,65,60,2,60,3,63,5,58,3
+Garbage Bags,Home Care,roll,59,75,2,75,3,78,5,71,3
+Tissues & Napkins,Home Care,pack,67,70,2,70,3,73,5,64,3
+Air Fresheners,Home Care,bottle,45,150,2,150,3,157,5,144,3
+Bath Soap,Personal Care,pack,76,100,2,95,3,89,5,89,3
+Handwash,Personal Care,bottle,73,87,2,85,3,81,5,85,3
+Shampoo,Personal Care,bottle,64,158,2,150,3,153,5,148,3
+Hair Oil,Personal Care,bottle,58,136,2,130,3,132,5,127,3
+Toothpaste,Personal Care,tube,83,52,2,50,3,48,5,48,3
+Toothbrushes,Personal Care,pack,68,56,2,55,3,57,5,52,3
+Oral Care Products,Personal Care,pack,54,126,2,120,3,123,5,118,3
+Skincare Products,Personal Care,bottle,46,252,2,240,3,245,5,236,3
+Personal Hygiene Products,Personal Care,pack,63,112,2,110,3,114,5,110,3
+Sanitary Products,Personal Care,pack,71,188,2,180,3,183,5,176,3
+Baby Care Products,Personal Care,pack,47,270,2,260,3,274,5,252,3
+Diapers & Wipes,Personal Care,pack,59,436,2,420,3,443,5,407,3
+Stationery,Home & Stationery,pack,44,88,3,90,4,94,7,88,5
+Notebooks,Home & Stationery,piece,55,59,3,60,4,63,7,55,5
+Pens & Pencils,Home & Stationery,pack,53,48,3,50,4,52,7,47,5
+Kitchen Tools,Home & Stationery,piece,48,178,3,180,4,190,6,178,5
+Storage Containers,Home & Stationery,set,51,257,3,260,4,274,6,257,5
+Kitchen Appliances,Home & Stationery,piece,28,1757,3,1800,4,1876,6,1843,5
+Household Utility Items,Home & Stationery,piece,50,219,3,220,4,223,6,219,5

data/marketing_actions.csv

@@ -0,0 +1,16 @@
+action_id,description,customer_satisfaction_delta,cost_inr,recurring_cost_inr,order_processing_capacity_delta
+1,Shelf placement upgrade,1,800,0,20
+2,Barcode billing / POS setup,3,12000,150,50
+3,Loyalty points program,5,2000,250,0
+4,Neighborhood WhatsApp ordering,4,1500,100,15
+5,Milk and dairy display fridge,5,25000,120,10
+6,Storage rack expansion,0,7000,0,30
+7,Local delivery partner tie-up,5,5000,600,40
+8,Referral rewards,3,1800,150,0
+9,Slow-mover clearance shelf reset,-2,500,0,6
+10,Staff merchandising training,2,2500,0,25
+11,Open second branch (deposit + fit-out),12,750000,3000,350
+12,Simple ordering website + catalog,6,60000,400,60
+13,Hire one delivery rider + scooter,6,45000,900,50
+14,Lease nearby stockroom / pickup counter,2,120000,1500,75
+15,Always-on targeted social ads,3,4000,1200,0

data/pending_orders.csv

@@ -0,0 +1 @@
+order_id,product_name,quantity,seller_name,buy_price_inr,days_remaining,status,created_day

data/seller_profiles.csv

@@ -0,0 +1,5 @@
+seller_name,timeline_behavior,reliability_note,default_etd_days
+Seller A,overcommits,Quotes aggressively and often slips past the quoted ETA,2
+Seller B,strict,Reliable and usually matches the committed ETA,3
+Seller C,undercommits,Quotes conservatively and often arrives by or before ETA,5
+Seller D,variable,Usually competitive on impulse categories but can slip due to staffing variability,3

data/stock.csv

@@ -0,0 +1,31 @@
+product_name,unit,buying_price_inr,selling_price_inr,demand_score,quantity_on_hand,stock_value_inr
+Rice,pack,160,189,92,180,28800
+Wheat Flour,pack,100,118,88,150,15000
+Dals,pack,175,207,80,90,15750
+Pulses,pack,200,234,76,75,15000
+Cooking Oil,bottle,180,213,94,120,21600
+Salt,pack,20,24,70,160,3200
+Tea,pack,350,413,87,60,21000
+Spices,pack,400,476,81,40,16000
+Namkeen,pack,50,61,85,90,4500
+Chips,pack,35,43,82,90,3150
+Detergents,pack,250,295,78,40,10000
+Toothpaste,tube,50,60,83,60,3000
+Vegetables,kg,40,48,84,60,2400
+Fruits,kg,50,59,79,45,2250
+Noodles,pack,65,78,75,90,5850
+Ketchup,bottle,105,124,73,40,4200
+Soft Drinks,bottle,40,48,79,96,3840
+Snacks,pack,70,84,72,80,5600
+Handwash,bottle,85,102,73,40,3400
+Paneer,pack,300,354,73,30,9000
+Shampoo,bottle,150,183,64,24,3600
+Sanitary Products,pack,180,209,71,24,4320
+Milk,pouch,30,32,96,96,2880
+Bread,loaf,35,37,86,36,1260
+Eggs,dozen,72,75,84,24,1728
+Bottled Water,bottle,18,20,89,48,864
+Sugar,pack,80,84,74,150,12000
+Biscuits,pack,20,22,90,40,800
+Coffee,jar,500,640,62,18,9000
+Kitchen Appliances,piece,1800,2790,28,4,7200

data/store_state.csv

@@ -0,0 +1,2 @@
+day,current_daily_expense_inr,bank_balance_inr,customer_satisfaction,order_processing_capacity,cumulative_profit_inr
+1,3000,120000,70,500,0

gradio_app.py

@@ -0,0 +1,629 @@
+"""Interactive Gradio frontend for the Store OpenEnv simulation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import gradio as gr
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "gradio is required for the UI. Install project dependencies with `uv sync`."
+    ) from exc
+
+try:
+    from .models import OrderRequest, PriceUpdate, StoreAction, StoreObservation, dump_model
+    from .server.store_environment import StoreEnvironment
+except ImportError:  # pragma: no cover
+    from models import OrderRequest, PriceUpdate, StoreAction, StoreObservation, dump_model
+    from server.store_environment import StoreEnvironment
+
+SELLERS = ["Seller A", "Seller B", "Seller C", "Seller D"]
+
+CSS = """
+/* ── Global ── */
+.gradio-container {
+    background: linear-gradient(135deg, #0f172a 0%, #1e293b 50%, #0f172a 100%) !important;
+    font-family: 'Inter', system-ui, -apple-system, sans-serif !important;
+}
+
+/* ── Header ── */
+.app-header {
+    text-align: center;
+    padding: 28px 16px 12px;
+}
+.app-header h1 {
+    font-size: 2rem;
+    font-weight: 700;
+    background: linear-gradient(135deg, #60a5fa, #a78bfa, #f472b6);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    margin: 0;
+}
+.app-header p {
+    color: #94a3b8;
+    font-size: 0.95rem;
+    margin-top: 4px;
+}
+
+/* ── Panels ── */
+.panel-card {
+    background: rgba(30, 41, 59, 0.85) !important;
+    border: 1px solid rgba(148, 163, 184, 0.12) !important;
+    border-radius: 16px !important;
+    padding: 20px !important;
+    backdrop-filter: blur(12px);
+}
+
+/* ── Section headings ── */
+.section-title {
+    color: #e2e8f0 !important;
+    font-size: 1.05rem !important;
+    font-weight: 600 !important;
+    border-bottom: 1px solid rgba(148, 163, 184, 0.15);
+    padding-bottom: 8px;
+    margin-bottom: 12px !important;
+}
+
+/* ── Metric cards ── */
+.metric-row {
+    display: flex;
+    gap: 10px;
+    flex-wrap: wrap;
+    margin-bottom: 8px;
+}
+.metric-card {
+    flex: 1;
+    min-width: 120px;
+    background: rgba(51, 65, 85, 0.6);
+    border: 1px solid rgba(148, 163, 184, 0.1);
+    border-radius: 12px;
+    padding: 14px 16px;
+    text-align: center;
+}
+.metric-card .label {
+    font-size: 0.72rem;
+    text-transform: uppercase;
+    letter-spacing: 0.6px;
+    color: #94a3b8;
+    margin-bottom: 4px;
+}
+.metric-card .value {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: #f1f5f9;
+}
+.metric-card .value.positive { color: #4ade80; }
+.metric-card .value.negative { color: #f87171; }
+
+/* ── Status banner ── */
+.status-banner {
+    padding: 12px 16px;
+    border-radius: 10px;
+    font-size: 0.92rem;
+    margin-bottom: 10px;
+}
+.status-banner.success {
+    background: rgba(34, 197, 94, 0.12);
+    border: 1px solid rgba(34, 197, 94, 0.25);
+    color: #86efac;
+}
+.status-banner.error {
+    background: rgba(239, 68, 68, 0.12);
+    border: 1px solid rgba(239, 68, 68, 0.25);
+    color: #fca5a5;
+}
+.status-banner.info {
+    background: rgba(59, 130, 246, 0.12);
+    border: 1px solid rgba(59, 130, 246, 0.25);
+    color: #93c5fd;
+}
+
+/* ── Buttons ── */
+.btn-primary {
+    background: linear-gradient(135deg, #3b82f6, #6366f1) !important;
+    border: none !important;
+    color: #fff !important;
+    font-weight: 600 !important;
+    border-radius: 10px !important;
+    padding: 10px 20px !important;
+    transition: opacity 0.2s !important;
+}
+.btn-primary:hover { opacity: 0.88 !important; }
+
+.btn-secondary {
+    background: rgba(51, 65, 85, 0.7) !important;
+    border: 1px solid rgba(148, 163, 184, 0.2) !important;
+    color: #cbd5e1 !important;
+    font-weight: 500 !important;
+    border-radius: 10px !important;
+    padding: 10px 20px !important;
+}
+.btn-secondary:hover { background: rgba(71, 85, 105, 0.7) !important; }
+
+.btn-danger {
+    background: rgba(239, 68, 68, 0.15) !important;
+    border: 1px solid rgba(239, 68, 68, 0.3) !important;
+    color: #fca5a5 !important;
+    font-weight: 500 !important;
+    border-radius: 10px !important;
+}
+
+/* ── Order rows ── */
+.order-row {
+    background: rgba(51, 65, 85, 0.4);
+    border: 1px solid rgba(148, 163, 184, 0.1);
+    border-radius: 10px;
+    padding: 10px 14px;
+    margin-bottom: 6px;
+}
+
+/* ── Fix Gradio element readability ── */
+.gradio-container label { color: #cbd5e1 !important; }
+.gradio-container .gr-input, .gradio-container input,
+.gradio-container select, .gradio-container textarea {
+    background: rgba(30, 41, 59, 0.9) !important;
+    color: #f1f5f9 !important;
+    border: 1px solid rgba(148, 163, 184, 0.2) !important;
+    border-radius: 8px !important;
+}
+.gradio-container .gr-input:focus, .gradio-container input:focus {
+    border-color: #3b82f6 !important;
+    box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.15) !important;
+}
+.gradio-container .gr-check-radio { accent-color: #6366f1 !important; }
+.gradio-container .tabs .tab-nav button {
+    color: #94a3b8 !important;
+    border: none !important;
+    font-weight: 500 !important;
+}
+.gradio-container .tabs .tab-nav button.selected {
+    color: #60a5fa !important;
+    border-bottom: 2px solid #60a5fa !important;
+}
+.gradio-container .json-holder { background: rgba(15, 23, 42, 0.6) !important; }
+.gradio-container .markdown-text { color: #e2e8f0 !important; }
+.gradio-container .markdown-text h1,
+.gradio-container .markdown-text h2,
+.gradio-container .markdown-text h3 { color: #f1f5f9 !important; }
+.gradio-container .markdown-text code {
+    background: rgba(99, 102, 241, 0.15) !important;
+    color: #a5b4fc !important;
+    padding: 2px 6px;
+    border-radius: 4px;
+}
+"""
+
+
+def _load_products_and_stock() -> tuple[list[str], list[str]]:
+    """Return (market product names, stock product names) from a fresh env."""
+    env = StoreEnvironment()
+    obs = env.reset()
+    market_products = [m.product_name for m in obs.market]
+    stock_products = [s.product_name for s in obs.stock]
+    return market_products, stock_products
+
+
+def _load_marketing_catalog() -> list[dict[str, Any]]:
+    env = StoreEnvironment()
+    obs = env.reset()
+    return [dump_model(m, exclude_none=True) for m in obs.marketing_actions]
+
+
+def _format_marketing_label(m: dict[str, Any]) -> str:
+    parts = [f"#{m['action_id']} {m['description']}"]
+    parts.append(f"cost ₹{m['cost_inr']:,}")
+    if m.get("recurring_cost_inr"):
+        parts.append(f"recurring ₹{m['recurring_cost_inr']:,}/day")
+    parts.append(f"satisfaction {m['customer_satisfaction_delta']:+d}")
+    if m.get("order_processing_capacity_delta"):
+        parts.append(f"capacity {m['order_processing_capacity_delta']:+d}")
+    return " · ".join(parts)
+
+
+def _render_status_html(message: str, kind: str = "info") -> str:
+    return f'<div class="status-banner {kind}">{message}</div>'
+
+
+def _render_metrics_html(obs: StoreObservation) -> str:
+    store = obs.store
+
+    def _card(label: str, value: str, css_class: str = "") -> str:
+        vc = f' class="value {css_class}"' if css_class else ' class="value"'
+        return (
+            f'<div class="metric-card">'
+            f'<div class="label">{label}</div>'
+            f"<div{vc}>{value}</div>"
+            f"</div>"
+        )
+
+    profit = store.cumulative_profit_inr
+    profit_cls = "positive" if profit >= 0 else "negative"
+    reward_val = f"{obs.reward:.4f}" if obs.reward else "—"
+    recurring_cost = store.active_recurring_cost_inr
+    total_daily_burn = store.current_daily_expense_inr + recurring_cost
+    burn_cls = "negative" if total_daily_burn > 0 else ""
+    recurring_cls = "negative" if recurring_cost > 0 else ""
+
+    cards = [
+        _card("Day", str(store.day)),
+        _card("Bank Balance", f"₹{store.bank_balance_inr:,.0f}"),
+        _card("Base Burn / Day", f"₹{store.current_daily_expense_inr:,.0f}", burn_cls),
+        _card("Recurring / Day", f"₹{recurring_cost:,.0f}", recurring_cls),
+        _card("Total Burn / Day", f"₹{total_daily_burn:,.0f}", burn_cls),
+        _card("Satisfaction", f"{store.customer_satisfaction:.0f}%"),
+        _card("Profit", f"₹{profit:,.0f}", profit_cls),
+        _card("Reward", reward_val),
+        _card("Capacity", f"{store.order_processing_capacity:.0f}"),
+    ]
+    return f'<div class="metric-row">{"".join(cards)}</div>'
+
+
+THEME = gr.themes.Base(
+    primary_hue=gr.themes.colors.blue,
+    secondary_hue=gr.themes.colors.indigo,
+    neutral_hue=gr.themes.colors.slate,
+    font=gr.themes.GoogleFont("Inter"),
+).set(
+    body_background_fill="transparent",
+    block_background_fill="rgba(30, 41, 59, 0.7)",
+    block_border_width="1px",
+    block_border_color="rgba(148, 163, 184, 0.12)",
+    block_label_text_color="#cbd5e1",
+    block_title_text_color="#e2e8f0",
+    input_background_fill="rgba(15, 23, 42, 0.6)",
+    input_border_color="rgba(148, 163, 184, 0.2)",
+    button_primary_background_fill="linear-gradient(135deg, #3b82f6, #6366f1)",
+    button_primary_text_color="#ffffff",
+    button_secondary_background_fill="rgba(51, 65, 85, 0.7)",
+    button_secondary_text_color="#cbd5e1",
+    button_secondary_border_color="rgba(148, 163, 184, 0.2)",
+)
+
+
+def make_demo() -> gr.Blocks:
+    """Build the interactive Gradio app."""
+
+    market_products, stock_products = _load_products_and_stock()
+    marketing_catalog = _load_marketing_catalog()
+    marketing_labels = [_format_marketing_label(m) for m in marketing_catalog]
+    marketing_id_by_label = {
+        _format_marketing_label(m): m["action_id"] for m in marketing_catalog
+    }
+
+    with gr.Blocks(title="Store OpenEnv Playground") as demo:
+        env_state = gr.State(value=None)
+        obs_state = gr.State(value=None)
+
+        # ── Header ──
+        gr.HTML(
+            '<div class="app-header">'
+            "<h1>Store OpenEnv Playground</h1>"
+            "<p>Simulate a neighborhood kirana store — place orders, set prices, activate marketing</p>"
+            "</div>"
+        )
+
+        # ── Top metrics ──
+        metrics_html = gr.HTML("")
+        status_html = gr.HTML(_render_status_html("Press Reset to start a fresh episode.", "info"))
+
+        with gr.Row(equal_height=False):
+            # ═══════════ LEFT: ACTION PANEL ═══════════
+            with gr.Column(scale=4, elem_classes=["panel-card"]):
+                gr.Markdown("### Place Orders", elem_classes=["section-title"])
+                gr.Markdown(
+                    "*Select a product from the market catalog, choose a seller, and specify quantity.*",
+                )
+
+                with gr.Group():
+                    with gr.Row():
+                        order_product = gr.Dropdown(
+                            choices=market_products,
+                            label="Product",
+                            value=market_products[0] if market_products else None,
+                            scale=3,
+                        )
+                        order_seller = gr.Dropdown(
+                            choices=SELLERS,
+                            label="Seller",
+                            value=SELLERS[0],
+                            scale=2,
+                        )
+                        order_qty = gr.Number(label="Qty", value=10, minimum=1, precision=0, scale=1)
+                        add_order_btn = gr.Button("+ Add", size="sm", elem_classes=["btn-primary"], scale=1)
+
+                orders_display = gr.Dataframe(
+                    headers=["Product", "Seller", "Quantity"],
+                    datatype=["str", "str", "number"],
+                    value=[],
+                    interactive=False,
+                    label="Pending Orders",
+                    row_count=(0, "dynamic"),
+                    column_count=(3, "fixed"),
+                )
+                clear_orders_btn = gr.Button("Clear Orders", size="sm", elem_classes=["btn-danger"])
+
+                gr.Markdown("---")
+                gr.Markdown("### Update Prices", elem_classes=["section-title"])
+                gr.Markdown("*Adjust selling prices for products currently in stock.*")
+
+                with gr.Group():
+                    with gr.Row():
+                        price_product = gr.Dropdown(
+                            choices=stock_products,
+                            label="Product",
+                            value=stock_products[0] if stock_products else None,
+                            scale=3,
+                        )
+                        price_value = gr.Number(label="New Price ₹", value=100, minimum=1, precision=0, scale=2)
+                        add_price_btn = gr.Button("+ Add", size="sm", elem_classes=["btn-primary"], scale=1)
+
+                prices_display = gr.Dataframe(
+                    headers=["Product", "Price (₹)"],
+                    datatype=["str", "number"],
+                    value=[],
+                    interactive=False,
+                    label="Price Changes",
+                    row_count=(0, "dynamic"),
+                    column_count=(2, "fixed"),
+                )
+                clear_prices_btn = gr.Button("Clear Prices", size="sm", elem_classes=["btn-danger"])
+
+                gr.Markdown("---")
+                gr.Markdown("### Marketing Actions", elem_classes=["section-title"])
+                gr.Markdown("*Select marketing or operational upgrades to activate.*")
+
+                marketing_checkboxes = gr.CheckboxGroup(
+                    choices=marketing_labels,
+                    label="Available Actions",
+                    value=[],
+                )
+
+                gr.Markdown("---")
+                with gr.Row():
+                    reset_btn = gr.Button("Reset Episode", variant="secondary", elem_classes=["btn-secondary"])
+                    pass_btn = gr.Button("Pass (Skip Turn)", variant="secondary", elem_classes=["btn-secondary"])
+                    step_btn = gr.Button("Submit Step", variant="primary", elem_classes=["btn-primary"], scale=2)
+
+            # ═══════════ RIGHT: OBSERVATION PANEL ═══════════
+            with gr.Column(scale=5, elem_classes=["panel-card"]):
+                gr.Markdown("### Live State", elem_classes=["section-title"])
+
+                with gr.Tabs():
+                    with gr.Tab("Store"):
+                        store_json = gr.JSON(label="Store snapshot")
+                    with gr.Tab("Stock"):
+                        stock_json = gr.JSON(label="Current stock levels")
+                    with gr.Tab("Pending Orders"):
+                        pending_json = gr.JSON(label="In-transit supplier orders")
+                    with gr.Tab("Market"):
+                        market_json = gr.JSON(label="Market catalog with seller quotes")
+                    with gr.Tab("Marketing"):
+                        marketing_json = gr.JSON(label="Marketing actions catalog")
+                    with gr.Tab("Reward"):
+                        reward_json = gr.JSON(label="Reward breakdown")
+                    with gr.Tab("Full Observation"):
+                        metadata_json = gr.JSON(label="Complete observation data")
+
+        # ── Helpers ──
+
+        def _initial_env() -> tuple[StoreEnvironment, StoreObservation]:
+            env = StoreEnvironment()
+            obs = env.reset()
+            return env, obs
+
+        def _render_obs(obs: StoreObservation, message: str = "", is_error: bool = False) -> list[Any]:
+            kind = "error" if is_error else "success"
+            if not message:
+                message = obs.summary or "Ready."
+                kind = "info"
+            return [
+                _render_metrics_html(obs),
+                _render_status_html(message, kind),
+                dump_model(obs.store, exclude_none=True),
+                [dump_model(item, exclude_none=True) for item in obs.stock],
+                [dump_model(item, exclude_none=True) for item in obs.pending_orders],
+                [dump_model(item, exclude_none=True) for item in obs.market],
+                [dump_model(item, exclude_none=True) for item in obs.marketing_actions],
+                obs.metadata.get("reward_breakdown", {}),
+                dump_model(obs, exclude_none=True),
+            ]
+
+        render_outputs = [
+            metrics_html, status_html,
+            store_json, stock_json, pending_json, market_json,
+            marketing_json, reward_json, metadata_json,
+        ]
+
+        def _update_stock_dropdown(env: StoreEnvironment | None, obs: StoreObservation | None):
+            if obs is None:
+                return gr.update()
+            names = [s.product_name for s in obs.stock]
+            return gr.update(choices=names, value=names[0] if names else None)
+
+        # ── Order management ──
+
+        def _df_to_list(df: Any) -> list[list]:
+            if df is None:
+                return []
+            try:
+                import pandas as pd
+                if isinstance(df, pd.DataFrame):
+                    return df.values.tolist() if not df.empty else []
+            except ImportError:
+                pass
+            if isinstance(df, list):
+                return df
+            return []
+
+        def _add_order(current_orders: Any, product: str, seller: str, qty: int | float):
+            if not product or not seller:
+                return current_orders
+            qty = int(qty) if qty else 10
+            row = [product, seller, qty]
+            updated = _df_to_list(current_orders)
+            updated.append(row)
+            return updated
+
+        def _clear_orders():
+            return []
+
+        add_order_btn.click(
+            fn=_add_order,
+            inputs=[orders_display, order_product, order_seller, order_qty],
+            outputs=[orders_display],
+        )
+        clear_orders_btn.click(fn=_clear_orders, outputs=[orders_display])
+
+        # ── Price management ──
+
+        def _add_price(current_prices: Any, product: str, price: int | float):
+            if not product:
+                return current_prices
+            price = int(price) if price else 100
+            updated = _df_to_list(current_prices)
+            for i, row in enumerate(updated):
+                if row[0] == product:
+                    updated[i] = [product, price]
+                    return updated
+            updated.append([product, price])
+            return updated
+
+        def _clear_prices():
+            return []
+
+        add_price_btn.click(
+            fn=_add_price,
+            inputs=[prices_display, price_product, price_value],
+            outputs=[prices_display],
+        )
+        clear_prices_btn.click(fn=_clear_prices, outputs=[prices_display])
+
+        # ── Reset ──
+
+        def _reset():
+            env, obs = _initial_env()
+            stock_names = [s.product_name for s in obs.stock]
+            active_ids = set(obs.store.active_action_ids)
+            available_labels = [
+                lbl for lbl, aid in marketing_id_by_label.items()
+                if aid not in active_ids
+            ]
+            return (
+                env, obs,
+                [],  # orders display
+                [],  # prices display
+                gr.update(choices=available_labels, value=[]),  # marketing
+                gr.update(choices=stock_names, value=stock_names[0] if stock_names else None),
+                *_render_obs(obs, "Episode reset. Day 1 loaded.", False),
+            )
+
+        reset_outputs = [
+            env_state, obs_state,
+            orders_display, prices_display,
+            marketing_checkboxes, price_product,
+            *render_outputs,
+        ]
+
+        reset_btn.click(fn=_reset, inputs=[], outputs=reset_outputs)
+        demo.load(fn=_reset, inputs=[], outputs=reset_outputs)
+
+        # ── Step ──
+
+        def _step(
+            env: StoreEnvironment | None,
+            obs: StoreObservation | None,
+            orders_data: Any,
+            prices_data: Any,
+            selected_marketing: list[str],
+        ):
+            if env is None or obs is None:
+                env, obs = _initial_env()
+
+            orders_rows = _df_to_list(orders_data)
+            prices_rows = _df_to_list(prices_data)
+
+            try:
+                order_requests = [
+                    OrderRequest(product=row[0], seller=row[1], quantity=int(row[2]))
+                    for row in orders_rows
+                    if len(row) >= 3 and row[0]
+                ]
+                price_updates = [
+                    PriceUpdate(product=row[0], price=int(row[1]))
+                    for row in prices_rows
+                    if len(row) >= 2 and row[0]
+                ]
+                action_ids = [
+                    marketing_id_by_label[lbl]
+                    for lbl in (selected_marketing or [])
+                    if lbl in marketing_id_by_label
+                ]
+
+                action = StoreAction(
+                    orders=order_requests,
+                    prices=price_updates if price_updates else None,
+                    action_ids=action_ids,
+                )
+                next_obs = env.step(action)
+                message = "Step completed successfully."
+            except Exception as exc:
+                message = f"{type(exc).__name__}: {exc}"
+                stock_names = [s.product_name for s in obs.stock]
+                return (
+                    env, obs,
+                    orders_rows, prices_rows,
+                    gr.update(), gr.update(),
+                    *_render_obs(obs, message, is_error=True),
+                )
+
+            stock_names = [s.product_name for s in next_obs.stock]
+            active_ids = set(next_obs.store.active_action_ids)
+            available_labels = [
+                lbl for lbl, aid in marketing_id_by_label.items()
+                if aid not in active_ids
+            ]
+            return (
+                env, next_obs,
+                [],  # clear orders
+                [],  # clear prices
+                gr.update(choices=available_labels, value=[]),
+                gr.update(choices=stock_names, value=stock_names[0] if stock_names else None),
+                *_render_obs(next_obs, message),
+            )
+
+        step_outputs = [
+            env_state, obs_state,
+            orders_display, prices_display,
+            marketing_checkboxes, price_product,
+            *render_outputs,
+        ]
+
+        step_btn.click(
+            fn=_step,
+            inputs=[env_state, obs_state, orders_display, prices_display, marketing_checkboxes],
+            outputs=step_outputs,
+        )
+
+        # ── Pass ──
+
+        def _pass_step(env: StoreEnvironment | None, obs: StoreObservation | None):
+            return _step(env, obs, [], [], [])
+
+        pass_btn.click(
+            fn=_pass_step,
+            inputs=[env_state, obs_state],
+            outputs=step_outputs,
+        )
+
+    return demo
+
+
+def main(host: str = "127.0.0.1", port: int = 7860, share: bool = False) -> None:
+    """Launch the Gradio app."""
+    demo = make_demo()
+    demo.launch(server_name=host, server_port=port, share=share, css=CSS, theme=THEME)
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,154 @@
+"""Data models for the Store OpenEnv simulation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+try:
+    from ._compat import Action, Observation
+except ImportError:  # pragma: no cover - supports direct module imports
+    from _compat import Action, Observation
+
+
+class OrderRequest(BaseModel):
+    """One supplier order request."""
+
+    product: str = Field(..., description="Product name from the market catalog")
+    seller: str = Field(..., description="Seller name, for example Seller A")
+    quantity: int = Field(..., gt=0, description="Number of units to order")
+
+
+class PriceUpdate(BaseModel):
+    """One price update for an in-stock product."""
+
+    product: str = Field(..., description="Product name currently stocked by the store")
+    price: int = Field(..., gt=0, description="New selling price in INR")
+
+
+class StockItem(BaseModel):
+    """Current in-store inventory row."""
+
+    product_name: str
+    unit: str
+    buying_price_inr: float
+    selling_price_inr: float
+    demand_score: float
+    quantity_on_hand: float
+    stock_value_inr: float
+
+
+class PendingOrder(BaseModel):
+    """Supplier order still in transit."""
+
+    order_id: str
+    product_name: str
+    quantity: int
+    seller_name: str
+    buy_price_inr: float
+    days_remaining: int
+    status: str
+    created_day: int
+
+
+class MarketOffer(BaseModel):
+    """Market catalog row with seller quotes."""
+
+    product_name: str
+    category: str
+    unit: str
+    demand_score: float
+    seller_a_price_inr: int
+    seller_a_etd_days: int
+    seller_b_price_inr: int
+    seller_b_etd_days: int
+    seller_c_price_inr: int
+    seller_c_etd_days: int
+    seller_d_price_inr: int
+    seller_d_etd_days: int
+
+
+class SellerProfile(BaseModel):
+    """Seller reliability profile."""
+
+    seller_name: str
+    timeline_behavior: str
+    reliability_note: str
+    default_etd_days: int
+
+
+class MarketingAction(BaseModel):
+    """Durable operational action the agent can activate."""
+
+    action_id: int
+    description: str
+    customer_satisfaction_delta: int
+    cost_inr: int
+    recurring_cost_inr: int
+    order_processing_capacity_delta: int
+    is_active: bool = False
+
+
+class StoreSnapshot(BaseModel):
+    """Top-level store state shown to the agent."""
+
+    day: int
+    current_daily_expense_inr: float
+    bank_balance_inr: float
+    customer_satisfaction: float
+    order_processing_capacity: float
+    cumulative_profit_inr: float
+    active_action_ids: list[int] = Field(default_factory=list)
+    active_recurring_cost_inr: float = 0.0
+    episode_horizon_days: int
+    commit_window_days: int
+    reward_horizon_days: int
+
+
+class StoreAction(Action):
+    """One bundled decision window for the environment."""
+
+    orders: list[OrderRequest] = Field(
+        default_factory=list,
+        description="Supplier orders to place at the start of the decision window",
+    )
+    prices: list[PriceUpdate] | None = Field(
+        default=None,
+        description="Optional selling-price updates for products already in stock",
+    )
+    action_ids: list[int] = Field(
+        default_factory=list,
+        description="Marketing or operations action IDs to activate",
+    )
+
+
+class AvailableActionSpec(BaseModel):
+    """Agent-facing action guide included in every observation."""
+
+    name: str
+    description: str
+    pass_action: StoreAction
+    example_action: StoreAction
+    notes: list[str] = Field(default_factory=list)
+
+
+class StoreObservation(Observation):
+    """Agent-facing observation for the store simulation."""
+
+    store: StoreSnapshot
+    stock: list[StockItem]
+    pending_orders: list[PendingOrder]
+    market: list[MarketOffer]
+    seller_profiles: list[SellerProfile]
+    marketing_actions: list[MarketingAction]
+    available_action: AvailableActionSpec
+    summary: str = ""
+
+
+def dump_model(model: BaseModel, **kwargs: Any) -> dict[str, Any]:
+    """Handle Pydantic v1/v2 model serialization."""
+
+    if hasattr(model, "model_dump"):
+        return model.model_dump(**kwargs)
+    return model.dict(**kwargs)

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,51 @@
+# 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-store"
+version = "0.1.0"
+description = "Store 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",
+    "gradio>=6.0.0",
+    "openenv-core[core]>=0.2.2",
+    "pydantic>=2.0.0",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m store.server.app
+server = "store.server.app:main"
+gradio = "store.gradio_app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["store", "store.server"]
+package-dir = { "store" = ".", "store.server" = "server" }
+
+[tool.setuptools.package-data]
+"store" = ["data/*.csv"]

scripts/generate_stock.py

@@ -0,0 +1,134 @@
+"""Generate a kirana-style opening inventory for stock.csv.
+
+The opening stock is intentionally hybrid:
+
+- mostly believable neighborhood-grocery inventory
+- a few teachable benchmark hooks for the agent
+- opening stock value kept in the 220k-260k INR range
+
+Embedded scenarios:
+
+- thin-margin anchor items the agent must reason about carefully
+- a believable replenishment miss on bottled water and biscuits
+- one obvious dead-stock item
+- a modest slow-mover pricing mistake
+"""
+
+import csv
+import math
+from pathlib import Path
+
+
+DATA_DIR = Path(__file__).resolve().parents[1] / "data"
+FIELDS = [
+    "product_name",
+    "unit",
+    "buying_price_inr",
+    "selling_price_inr",
+    "demand_score",
+    "quantity_on_hand",
+    "stock_value_inr",
+]
+
+market: dict[str, dict[str, str]] = {}
+with (DATA_DIR / "market_offers.csv").open(newline="", encoding="utf-8") as handle:
+    for row in csv.DictReader(handle):
+        market[row["product_name"]] = row
+
+
+def ref_price(name: str) -> int:
+    """Use Seller B as the reference buy price for opening inventory."""
+    return int(market[name]["seller_b_price_inr"])
+
+
+def build_row(name: str, quantity: int, markup: float) -> dict[str, str | int]:
+    buying_price = ref_price(name)
+    selling_price = math.ceil(buying_price * (1 + markup))
+    return {
+        "product_name": name,
+        "unit": market[name]["unit"],
+        "buying_price_inr": buying_price,
+        "selling_price_inr": selling_price,
+        "demand_score": int(market[name]["demand_score"]),
+        "quantity_on_hand": quantity,
+        "stock_value_inr": buying_price * quantity,
+    }
+
+
+rows: list[dict[str, str | int]] = []
+
+# Good baseline inventory: solid coverage of staples and daily-use products.
+good_items = [
+    ("Rice", 180, 0.18),
+    ("Wheat Flour", 150, 0.18),
+    ("Dals", 90, 0.18),
+    ("Pulses", 75, 0.17),
+    ("Cooking Oil", 120, 0.18),
+    ("Salt", 160, 0.18),
+    ("Tea", 60, 0.18),
+    ("Spices", 40, 0.19),
+    ("Namkeen", 90, 0.22),
+    ("Chips", 90, 0.22),
+    ("Detergents", 40, 0.18),
+    ("Toothpaste", 60, 0.20),
+    ("Vegetables", 60, 0.18),
+    ("Fruits", 45, 0.18),
+    ("Noodles", 90, 0.20),
+    ("Ketchup", 40, 0.18),
+    ("Soft Drinks", 96, 0.19),
+    ("Snacks", 80, 0.20),
+    ("Handwash", 40, 0.20),
+    ("Paneer", 30, 0.18),
+    ("Shampoo", 24, 0.22),
+    ("Sanitary Products", 24, 0.16),
+]
+
+# Customer-visible anchors: intentionally thin margins.
+anchor_items = [
+    ("Milk", 96, 0.04),
+    ("Bread", 36, 0.03),
+    ("Eggs", 24, 0.04),
+    ("Bottled Water", 48, 0.06),
+    ("Sugar", 150, 0.05),
+]
+
+# Benchmark hooks: one replenishment miss, one mild pricing miss, one dead-stock trap.
+special_items = [
+    ("Biscuits", 40, 0.10),
+    ("Coffee", 18, 0.28),
+    ("Kitchen Appliances", 4, 0.55),
+]
+
+for name, quantity, markup in good_items + anchor_items + special_items:
+    rows.append(build_row(name, quantity, markup))
+
+total_value = sum(int(row["stock_value_inr"]) for row in rows)
+print(f"Items: {len(rows)}")
+print(f"Total stock value: {total_value:,} INR")
+print(
+    f"Good items: {len(good_items)}  |  Anchor items: {len(anchor_items)}"
+    f"  |  Special hooks: {len(special_items)}"
+)
+
+with (DATA_DIR / "stock.csv").open("w", newline="", encoding="utf-8") as handle:
+    writer = csv.DictWriter(handle, fieldnames=FIELDS)
+    writer.writeheader()
+    writer.writerows(rows)
+
+print(f"\nWrote {len(rows)} rows to stock.csv")
+
+lookup = {row["product_name"]: row for row in rows}
+print("\n-- Scenario summary --")
+print(
+    "Thin-margin anchors:",
+    ", ".join(name for name, _, _ in anchor_items),
+)
+print(
+    "Replenishment miss:",
+    f"Biscuits qty={lookup['Biscuits']['quantity_on_hand']}, "
+    f"Bottled Water qty={lookup['Bottled Water']['quantity_on_hand']}",
+)
+print(
+    "Dead stock:",
+    f"Kitchen Appliances value={lookup['Kitchen Appliances']['stock_value_inr']:,} INR",
+)

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.
+
+"""Store environment server components."""
+
+from .store_environment import StoreEnvironment
+
+__all__ = ["StoreEnvironment"]

server/app.py

@@ -0,0 +1,51 @@
+# 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.
+
+"""FastAPI application for the Store OpenEnv simulation."""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import StoreAction, StoreObservation
+    from .store_environment import StoreEnvironment
+except ModuleNotFoundError:
+    from models import StoreAction, StoreObservation
+    from server.store_environment import StoreEnvironment
+
+
+app = create_app(
+    StoreEnvironment,
+    StoreAction,
+    StoreObservation,
+    env_name="store",
+    max_concurrent_envs=4,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via ``uv run`` or ``python -m``.
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    if args.port == 8000:
+        main()
+    else:
+        main(port=args.port)

server/requirements.txt

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

server/store_environment.py

@@ -0,0 +1,655 @@
+"""Store OpenEnv simulation."""
+
+from __future__ import annotations
+
+import csv
+import math
+import random
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+try:
+    from .._compat import Environment, State
+    from ..models import (
+        AvailableActionSpec,
+        MarketingAction,
+        MarketOffer,
+        OrderRequest,
+        PendingOrder,
+        PriceUpdate,
+        SellerProfile,
+        StockItem,
+        StoreAction,
+        StoreObservation,
+        StoreSnapshot,
+    )
+except ImportError:  # pragma: no cover - supports direct module imports
+    from _compat import Environment, State
+    from models import (
+        AvailableActionSpec,
+        MarketingAction,
+        MarketOffer,
+        OrderRequest,
+        PendingOrder,
+        PriceUpdate,
+        SellerProfile,
+        StockItem,
+        StoreAction,
+        StoreObservation,
+        StoreSnapshot,
+    )
+
+DATA_DIR = Path(__file__).resolve().parents[1] / "data"
+SELLER_PRICE_COLUMN = {
+    "Seller A": "seller_a_price_inr",
+    "Seller B": "seller_b_price_inr",
+    "Seller C": "seller_c_price_inr",
+    "Seller D": "seller_d_price_inr",
+}
+SELLER_ETD_COLUMN = {
+    "Seller A": "seller_a_etd_days",
+    "Seller B": "seller_b_etd_days",
+    "Seller C": "seller_c_etd_days",
+    "Seller D": "seller_d_etd_days",
+}
+NEW_PRODUCT_MARKUP = 1.18
+
+
+class StoreEnvironment(Environment):
+    """Simulation for a neighborhood grocery store."""
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+    EPISODE_HORIZON_DAYS = 30
+    COMMIT_WINDOW_DAYS = 3
+    REWARD_HORIZON_DAYS = 6
+
+    def __init__(self) -> None:
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+        self._rng = random.Random(0)
+        self._runtime = self._build_initial_runtime()
+
+    def reset(self) -> StoreObservation:
+        """Reset the environment back to the seed CSV state."""
+
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+        self._rng = random.Random(self._reset_count)
+        self._runtime = self._build_initial_runtime()
+        return self._build_observation(
+            self._runtime,
+            reward=0.0,
+            done=False,
+            summary=(
+                "Day 1 store snapshot loaded. Submit one bundled action for the next "
+                "3-day decision window; reward looks ahead across 6 simulated days."
+            ),
+            metadata={
+                "reset_count": self._reset_count,
+                "simulation": {
+                    "commit_window_days": self.COMMIT_WINDOW_DAYS,
+                    "reward_horizon_days": self.REWARD_HORIZON_DAYS,
+                },
+            },
+        )
+
+    def step(self, action: StoreAction) -> StoreObservation:  # type: ignore[override]
+        """Execute one bundled decision window."""
+
+        self._validate_action(action)
+
+        live_runtime = self._runtime
+        start_day = live_runtime["store"]["day"]
+        starting_capital = self._capital(live_runtime)
+        score_before = self._total_product_selling_score(live_runtime["stock"])
+
+        prepared_bundle = self._prepare_bundle(action, live_runtime)
+
+        commit_branch = deepcopy(live_runtime)
+        reward_branch = deepcopy(live_runtime)
+        self._apply_bundle(commit_branch, prepared_bundle)
+        self._apply_bundle(reward_branch, prepared_bundle)
+
+        adjusted_satisfaction = live_runtime["store"]["customer_satisfaction"] + prepared_bundle[
+            "customer_satisfaction_delta"
+        ]
+        score_after = self._total_product_selling_score(commit_branch["stock"])
+        next_satisfaction = self._updated_customer_satisfaction(
+            adjusted_satisfaction,
+            score_before,
+            score_after,
+        )
+        commit_branch["store"]["customer_satisfaction"] = next_satisfaction
+        reward_branch["store"]["customer_satisfaction"] = next_satisfaction
+
+        commit_metrics = self._simulate_days(commit_branch, self.COMMIT_WINDOW_DAYS)
+        reward_metrics = self._simulate_days(reward_branch, self.REWARD_HORIZON_DAYS)
+
+        ending_capital = self._capital(reward_branch)
+        difference = (
+            ending_capital
+            - starting_capital
+            - reward_metrics["recurring_costs_paid_inr"]
+        )
+        normalized_difference = 0.0 if starting_capital <= 0 else difference / starting_capital
+        reward = 0.5 + normalized_difference
+
+        self._runtime = commit_branch
+        self._state.step_count += 1
+
+        done_reason = ""
+        if self._runtime["store"]["bank_balance_inr"] < 0:
+            done_reason = "bank_balance_below_zero"
+        elif self._runtime["store"]["day"] > self.EPISODE_HORIZON_DAYS:
+            done_reason = "episode_horizon_reached"
+        done = bool(done_reason)
+
+        summary = (
+            f"Committed days {start_day}-{commit_branch['store']['day'] - 1}. "
+            f"Reward forecast extends through day {reward_branch['store']['day'] - 1}."
+        )
+        metadata = {
+            "reward_breakdown": {
+                "starting_capital_inr": self._round(starting_capital),
+                "ending_capital_inr": self._round(ending_capital),
+                "difference_inr": self._round(difference),
+                "normalized_difference": self._round(normalized_difference, digits=6),
+                "reward_horizon_days": self.REWARD_HORIZON_DAYS,
+                "commit_window_days": self.COMMIT_WINDOW_DAYS,
+                "recurring_costs_paid_inr": self._round(reward_metrics["recurring_costs_paid_inr"]),
+            },
+            "commit_metrics": self._rounded_metrics(commit_metrics),
+            "reward_metrics": self._rounded_metrics(reward_metrics),
+            "done_reason": done_reason,
+        }
+        return self._build_observation(
+            self._runtime,
+            reward=reward,
+            done=done,
+            summary=summary,
+            metadata=metadata,
+        )
+
+    @property
+    def state(self) -> State:
+        """Return the OpenEnv transport state."""
+
+        return self._state
+
+    def _build_initial_runtime(self) -> dict[str, Any]:
+        store_rows = self._read_csv("store_state.csv")
+        stock_rows = self._read_csv("stock.csv")
+        pending_order_rows = self._read_csv("pending_orders.csv")
+        seller_rows = self._read_csv("seller_profiles.csv")
+        market_rows = self._read_csv("market_offers.csv")
+        marketing_rows = self._read_csv("marketing_actions.csv")
+
+        if len(store_rows) != 1:
+            raise ValueError("store_state.csv must contain exactly one row")
+
+        store_row = store_rows[0]
+        pending_orders = [
+            {
+                "order_id": row["order_id"],
+                "product_name": row["product_name"],
+                "quantity": int(row["quantity"]),
+                "seller_name": row["seller_name"],
+                "buy_price_inr": float(row["buy_price_inr"]),
+                "days_remaining": int(row["days_remaining"]),
+                "status": row["status"],
+                "created_day": int(row["created_day"]),
+            }
+            for row in pending_order_rows
+        ]
+
+        return {
+            "store": {
+                "day": int(store_row["day"]),
+                "current_daily_expense_inr": float(store_row["current_daily_expense_inr"]),
+                "bank_balance_inr": float(store_row["bank_balance_inr"]),
+                "customer_satisfaction": float(store_row["customer_satisfaction"]),
+                "order_processing_capacity": float(store_row["order_processing_capacity"]),
+                "cumulative_profit_inr": float(store_row["cumulative_profit_inr"]),
+            },
+            "stock": [
+                {
+                    "product_name": row["product_name"],
+                    "unit": row["unit"],
+                    "buying_price_inr": float(row["buying_price_inr"]),
+                    "selling_price_inr": float(row["selling_price_inr"]),
+                    "demand_score": float(row["demand_score"]),
+                    "quantity_on_hand": float(row["quantity_on_hand"]),
+                    "stock_value_inr": float(row["stock_value_inr"]),
+                }
+                for row in stock_rows
+            ],
+            "pending_orders": pending_orders,
+            "market_offers": [
+                {
+                    "product_name": row["product_name"],
+                    "category": row["category"],
+                    "unit": row["unit"],
+                    "demand_score": float(row["demand_score"]),
+                    "seller_a_price_inr": int(row["seller_a_price_inr"]),
+                    "seller_a_etd_days": int(row["seller_a_etd_days"]),
+                    "seller_b_price_inr": int(row["seller_b_price_inr"]),
+                    "seller_b_etd_days": int(row["seller_b_etd_days"]),
+                    "seller_c_price_inr": int(row["seller_c_price_inr"]),
+                    "seller_c_etd_days": int(row["seller_c_etd_days"]),
+                    "seller_d_price_inr": int(row["seller_d_price_inr"]),
+                    "seller_d_etd_days": int(row["seller_d_etd_days"]),
+                }
+                for row in market_rows
+            ],
+            "seller_profiles": [
+                {
+                    "seller_name": row["seller_name"],
+                    "timeline_behavior": row["timeline_behavior"],
+                    "reliability_note": row["reliability_note"],
+                    "default_etd_days": int(row["default_etd_days"]),
+                }
+                for row in seller_rows
+            ],
+            "marketing_actions_catalog": [
+                {
+                    "action_id": int(row["action_id"]),
+                    "description": row["description"],
+                    "customer_satisfaction_delta": int(row["customer_satisfaction_delta"]),
+                    "cost_inr": int(row["cost_inr"]),
+                    "recurring_cost_inr": int(row["recurring_cost_inr"]),
+                    "order_processing_capacity_delta": int(row["order_processing_capacity_delta"]),
+                }
+                for row in marketing_rows
+            ],
+            "active_action_ids": set(),
+            "next_order_id": len(pending_orders) + 1,
+        }
+
+    def _read_csv(self, name: str) -> list[dict[str, str]]:
+        with (DATA_DIR / name).open(newline="", encoding="utf-8") as handle:
+            return list(csv.DictReader(handle))
+
+    def _validate_action(self, action: StoreAction) -> None:
+        market_by_product = {
+            row["product_name"]: row for row in self._runtime["market_offers"]
+        }
+        stock_by_product = {
+            row["product_name"]: row for row in self._runtime["stock"]
+        }
+        marketing_ids = {
+            row["action_id"] for row in self._runtime["marketing_actions_catalog"]
+        }
+
+        seen_price_products: set[str] = set()
+        for update in action.prices or []:
+            if update.product not in stock_by_product:
+                raise ValueError(
+                    f"Cannot set price for {update.product!r} because it is not currently stocked."
+                )
+            if update.product in seen_price_products:
+                raise ValueError(f"Duplicate price update for {update.product!r}.")
+            if update.price <= 0:
+                raise ValueError("Price updates must be positive.")
+            seen_price_products.add(update.product)
+
+        seen_action_ids: set[int] = set()
+        for action_id in action.action_ids:
+            if action_id not in marketing_ids:
+                raise ValueError(f"Unknown marketing action id {action_id}.")
+            if action_id in seen_action_ids:
+                raise ValueError(f"Duplicate marketing action id {action_id}.")
+            if action_id in self._runtime["active_action_ids"]:
+                raise ValueError(f"Marketing action {action_id} is already active.")
+            seen_action_ids.add(action_id)
+
+        for order in action.orders:
+            if order.product not in market_by_product:
+                raise ValueError(f"Unknown market product {order.product!r}.")
+            if order.seller not in SELLER_PRICE_COLUMN:
+                raise ValueError(f"Unknown seller {order.seller!r}.")
+            if order.quantity <= 0:
+                raise ValueError("Order quantity must be positive.")
+
+    def _prepare_bundle(self, action: StoreAction, runtime: dict[str, Any]) -> dict[str, Any]:
+        market_by_product = {
+            row["product_name"]: row for row in runtime["market_offers"]
+        }
+        marketing_by_id = {
+            row["action_id"]: row for row in runtime["marketing_actions_catalog"]
+        }
+        next_order_id = runtime["next_order_id"]
+
+        prepared_orders = []
+        for index, request in enumerate(action.orders):
+            market_row = market_by_product[request.product]
+            price_key = SELLER_PRICE_COLUMN[request.seller]
+            etd_key = SELLER_ETD_COLUMN[request.seller]
+            quoted_eta = int(market_row[etd_key])
+            actual_eta = self._sample_actual_eta(request.seller, quoted_eta)
+            prepared_orders.append(
+                {
+                    "order_id": f"ORD-{next_order_id + index:04d}",
+                    "product_name": request.product,
+                    "quantity": request.quantity,
+                    "seller_name": request.seller,
+                    "buy_price_inr": float(market_row[price_key]),
+                    "days_remaining": actual_eta,
+                    "status": "pending",
+                    "created_day": int(runtime["store"]["day"]),
+                }
+            )
+
+        prepared_actions = [
+            deepcopy(marketing_by_id[action_id]) for action_id in action.action_ids
+        ]
+        return {
+            "price_updates": {
+                update.product: float(update.price) for update in action.prices or []
+            },
+            "new_orders": prepared_orders,
+            "new_action_ids": list(action.action_ids),
+            "selected_actions": prepared_actions,
+            "customer_satisfaction_delta": sum(
+                row["customer_satisfaction_delta"] for row in prepared_actions
+            ),
+        }
+
+    def _apply_bundle(self, runtime: dict[str, Any], bundle: dict[str, Any]) -> None:
+        stock_by_product = {
+            row["product_name"]: row for row in runtime["stock"]
+        }
+
+        for product, price in bundle["price_updates"].items():
+            stock_by_product[product]["selling_price_inr"] = price
+            self._refresh_stock_value(stock_by_product[product])
+
+        for marketing_action in bundle["selected_actions"]:
+            runtime["store"]["bank_balance_inr"] -= marketing_action["cost_inr"]
+            runtime["store"]["cumulative_profit_inr"] -= marketing_action["cost_inr"]
+            runtime["store"]["order_processing_capacity"] += marketing_action[
+                "order_processing_capacity_delta"
+            ]
+            runtime["active_action_ids"].add(marketing_action["action_id"])
+
+        for order in bundle["new_orders"]:
+            runtime["store"]["bank_balance_inr"] -= order["buy_price_inr"] * order["quantity"]
+            runtime["pending_orders"].append(deepcopy(order))
+
+        runtime["next_order_id"] += len(bundle["new_orders"])
+
+    def _simulate_days(self, runtime: dict[str, Any], days: int) -> dict[str, float]:
+        recurring_costs_paid = 0.0
+        total_revenue = 0.0
+        total_cogs = 0.0
+        total_units_sold = 0.0
+
+        for _ in range(days):
+            recurring_cost = self._active_recurring_cost(runtime)
+            revenue, cogs, units_sold = self._run_daily_sales(runtime)
+            daily_expense = runtime["store"]["current_daily_expense_inr"] + recurring_cost
+
+            runtime["store"]["bank_balance_inr"] += revenue - daily_expense
+            runtime["store"]["cumulative_profit_inr"] += revenue - cogs - daily_expense
+
+            recurring_costs_paid += recurring_cost
+            total_revenue += revenue
+            total_cogs += cogs
+            total_units_sold += units_sold
+
+            self._advance_pending_orders(runtime)
+            runtime["store"]["day"] += 1
+
+        return {
+            "days_simulated": float(days),
+            "revenue_inr": total_revenue,
+            "cogs_inr": total_cogs,
+            "units_sold": total_units_sold,
+            "recurring_costs_paid_inr": recurring_costs_paid,
+        }
+
+    def _run_daily_sales(self, runtime: dict[str, Any]) -> tuple[float, float, float]:
+        effective_daily_orders = runtime["store"]["order_processing_capacity"] * (
+            runtime["store"]["customer_satisfaction"] / 100.0
+        )
+        if effective_daily_orders <= 0:
+            return 0.0, 0.0, 0.0
+
+        sale_candidates: list[tuple[dict[str, Any], float]] = []
+        total_score = 0.0
+        for row in runtime["stock"]:
+            if row["quantity_on_hand"] <= 0:
+                continue
+            score = self._product_selling_score(row)
+            if score <= 0:
+                continue
+            sale_candidates.append((row, score))
+            total_score += score
+
+        if total_score <= 0:
+            return 0.0, 0.0, 0.0
+
+        revenue = 0.0
+        cogs = 0.0
+        units_sold = 0.0
+        for row, score in sale_candidates:
+            desired_sales = effective_daily_orders * score / total_score
+            actual_sales = min(row["quantity_on_hand"], desired_sales)
+            if actual_sales <= 0:
+                continue
+            row["quantity_on_hand"] -= actual_sales
+            revenue += actual_sales * row["selling_price_inr"]
+            cogs += actual_sales * row["buying_price_inr"]
+            units_sold += actual_sales
+            self._refresh_stock_value(row)
+
+        return revenue, cogs, units_sold
+
+    def _advance_pending_orders(self, runtime: dict[str, Any]) -> None:
+        remaining_orders = []
+        for order in runtime["pending_orders"]:
+            order["days_remaining"] -= 1
+            if order["days_remaining"] <= 0:
+                self._receive_order(runtime, order)
+            else:
+                remaining_orders.append(order)
+        runtime["pending_orders"] = remaining_orders
+
+    def _receive_order(self, runtime: dict[str, Any], order: dict[str, Any]) -> None:
+        stock_by_product = {
+            row["product_name"]: row for row in runtime["stock"]
+        }
+        market_by_product = {
+            row["product_name"]: row for row in runtime["market_offers"]
+        }
+
+        if order["product_name"] in stock_by_product:
+            stock_row = stock_by_product[order["product_name"]]
+            existing_quantity = stock_row["quantity_on_hand"]
+            new_quantity = existing_quantity + order["quantity"]
+            if new_quantity <= 0:
+                return
+            stock_row["buying_price_inr"] = (
+                (existing_quantity * stock_row["buying_price_inr"])
+                + (order["quantity"] * order["buy_price_inr"])
+            ) / new_quantity
+            stock_row["quantity_on_hand"] = new_quantity
+            self._refresh_stock_value(stock_row)
+            return
+
+        market_row = market_by_product[order["product_name"]]
+        buying_price = order["buy_price_inr"]
+        runtime["stock"].append(
+            {
+                "product_name": order["product_name"],
+                "unit": market_row["unit"],
+                "buying_price_inr": buying_price,
+                "selling_price_inr": max(
+                    buying_price + 1,
+                    math.ceil(buying_price * NEW_PRODUCT_MARKUP),
+                ),
+                "demand_score": market_row["demand_score"],
+                "quantity_on_hand": float(order["quantity"]),
+                "stock_value_inr": buying_price * order["quantity"],
+            }
+        )
+
+    def _product_selling_score(self, stock_row: dict[str, Any]) -> float:
+        selling_price = stock_row["selling_price_inr"]
+        if selling_price <= 0:
+            return 0.0
+        margin_percent = (
+            (selling_price - stock_row["buying_price_inr"]) / selling_price
+        ) * 100.0
+        return max(0.0, stock_row["demand_score"] - (margin_percent * 3.0))
+
+    def _total_product_selling_score(self, stock_rows: list[dict[str, Any]]) -> float:
+        return sum(
+            self._product_selling_score(row)
+            for row in stock_rows
+            if row["quantity_on_hand"] > 0
+        )
+
+    def _updated_customer_satisfaction(
+        self,
+        base_satisfaction: float,
+        before_score: float,
+        after_score: float,
+    ) -> float:
+        if after_score <= 0:
+            updated = base_satisfaction
+        else:
+            updated = (1.0 + ((after_score - before_score) / after_score)) * base_satisfaction
+        return min(100.0, max(1.0, updated))
+
+    def _active_recurring_cost(self, runtime: dict[str, Any]) -> float:
+        marketing_by_id = {
+            row["action_id"]: row for row in runtime["marketing_actions_catalog"]
+        }
+        return float(
+            sum(
+                marketing_by_id[action_id]["recurring_cost_inr"]
+                for action_id in runtime["active_action_ids"]
+            )
+        )
+
+    def _sample_actual_eta(self, seller_name: str, quoted_eta: int) -> int:
+        if seller_name == "Seller A":
+            offset = self._rng.choices([0, 1, 2], weights=[2, 4, 5], k=1)[0]
+        elif seller_name == "Seller B":
+            offset = 0
+        elif seller_name == "Seller C":
+            offset = self._rng.choices([-2, -1, 0], weights=[5, 4, 2], k=1)[0]
+        else:
+            offset = self._rng.choices([-1, 0, 1, 2], weights=[2, 4, 3, 2], k=1)[0]
+        return max(1, quoted_eta + offset)
+
+    def _capital(self, runtime: dict[str, Any]) -> float:
+        return runtime["store"]["bank_balance_inr"] + self._inventory_value(runtime["stock"])
+
+    def _inventory_value(self, stock_rows: list[dict[str, Any]]) -> float:
+        return sum(row["stock_value_inr"] for row in stock_rows)
+
+    def _refresh_stock_value(self, stock_row: dict[str, Any]) -> None:
+        stock_row["stock_value_inr"] = stock_row["buying_price_inr"] * stock_row["quantity_on_hand"]
+
+    def _build_observation(
+        self,
+        runtime: dict[str, Any],
+        *,
+        reward: float,
+        done: bool,
+        summary: str,
+        metadata: dict[str, Any],
+    ) -> StoreObservation:
+        active_action_ids = sorted(runtime["active_action_ids"])
+        marketing_actions = [
+            MarketingAction(
+                **row,
+                is_active=row["action_id"] in runtime["active_action_ids"],
+            )
+            for row in runtime["marketing_actions_catalog"]
+        ]
+
+        return StoreObservation(
+            store=StoreSnapshot(
+                day=int(runtime["store"]["day"]),
+                current_daily_expense_inr=self._round(runtime["store"]["current_daily_expense_inr"]),
+                bank_balance_inr=self._round(runtime["store"]["bank_balance_inr"]),
+                customer_satisfaction=self._round(runtime["store"]["customer_satisfaction"]),
+                order_processing_capacity=self._round(runtime["store"]["order_processing_capacity"]),
+                cumulative_profit_inr=self._round(runtime["store"]["cumulative_profit_inr"]),
+                active_action_ids=active_action_ids,
+                active_recurring_cost_inr=self._round(self._active_recurring_cost(runtime)),
+                episode_horizon_days=self.EPISODE_HORIZON_DAYS,
+                commit_window_days=self.COMMIT_WINDOW_DAYS,
+                reward_horizon_days=self.REWARD_HORIZON_DAYS,
+            ),
+            stock=[
+                StockItem(
+                    product_name=row["product_name"],
+                    unit=row["unit"],
+                    buying_price_inr=self._round(row["buying_price_inr"]),
+                    selling_price_inr=self._round(row["selling_price_inr"]),
+                    demand_score=self._round(row["demand_score"]),
+                    quantity_on_hand=self._round(row["quantity_on_hand"]),
+                    stock_value_inr=self._round(row["stock_value_inr"]),
+                )
+                for row in runtime["stock"]
+            ],
+            pending_orders=[
+                PendingOrder(
+                    order_id=row["order_id"],
+                    product_name=row["product_name"],
+                    quantity=int(row["quantity"]),
+                    seller_name=row["seller_name"],
+                    buy_price_inr=self._round(row["buy_price_inr"]),
+                    days_remaining=int(row["days_remaining"]),
+                    status=row["status"],
+                    created_day=int(row["created_day"]),
+                )
+                for row in runtime["pending_orders"]
+            ],
+            market=[MarketOffer(**row) for row in runtime["market_offers"]],
+            seller_profiles=[SellerProfile(**row) for row in runtime["seller_profiles"]],
+            marketing_actions=marketing_actions,
+            available_action=self._available_action_spec(),
+            summary=summary,
+            reward=reward,
+            done=done,
+            metadata=metadata,
+        )
+
+    def _available_action_spec(self) -> AvailableActionSpec:
+        return AvailableActionSpec(
+            name="action",
+            description=(
+                "Submit one bundled action for the next 3 committed days. The same "
+                "bundle is used to forecast reward across 6 simulated days."
+            ),
+            pass_action=StoreAction(),
+            example_action=StoreAction(
+                orders=[
+                    OrderRequest(product="Rice", seller="Seller A", quantity=25),
+                    OrderRequest(product="Bread", seller="Seller C", quantity=12),
+                ],
+                prices=[PriceUpdate(product="Milk", price=33)],
+                action_ids=[7],
+            ),
+            notes=[
+                "Use an empty action to pass.",
+                "Orders can target any product in the market catalog.",
+                "Price changes only apply to products currently in stock.",
+                "Marketing actions are durable and cannot be activated twice.",
+            ],
+        )
+
+    def _rounded_metrics(self, metrics: dict[str, float]) -> dict[str, float]:
+        return {
+            key: self._round(value) if key != "days_simulated" else float(value)
+            for key, value in metrics.items()
+        }
+
+    def _round(self, value: float, *, digits: int = 2) -> float:
+        return round(float(value), digits)

tests/test_gradio_app.py

@@ -0,0 +1,24 @@
+from store import StoreAction
+from store.gradio_app import _render_metrics_html, make_demo
+from store.server.store_environment import StoreEnvironment
+
+
+def test_make_demo_builds_blocks() -> None:
+    demo = make_demo()
+    try:
+        assert demo is not None
+    finally:
+        demo.close()
+
+
+def test_metrics_html_shows_recurring_and_total_daily_burn() -> None:
+    env = StoreEnvironment()
+    env.reset()
+
+    observation = env.step(StoreAction(action_ids=[7]))
+    html = _render_metrics_html(observation)
+
+    assert "Recurring / Day" in html
+    assert "Total Burn / Day" in html
+    assert "₹600" in html
+    assert "₹3,600" in html

tests/test_seed_csvs.py

@@ -0,0 +1,378 @@
+import csv
+import math
+from pathlib import Path
+
+
+DATA_DIR = Path(__file__).resolve().parents[1] / "data"
+PLAN_PATH = Path(__file__).resolve().parents[2] / "plan2.md"
+EXPECTED_PRODUCTS = [
+    "Rice",
+    "Wheat Flour",
+    "Other Flours",
+    "Dals",
+    "Pulses",
+    "Salt",
+    "Sugar",
+    "Jaggery",
+    "Cooking Oil",
+    "Ghee",
+    "Spices",
+    "Masalas",
+    "Dry Fruits",
+    "Nuts",
+    "Seeds",
+    "Poha",
+    "Suji / Rava",
+    "Besan",
+    "Maida",
+    "Breakfast Cereals",
+    "Oats",
+    "Pasta",
+    "Noodles",
+    "Vermicelli",
+    "Ready-to-Cook Mixes",
+    "Ready-to-Eat Foods",
+    "Biscuits",
+    "Cookies",
+    "Rusk",
+    "Snacks",
+    "Namkeen",
+    "Chips",
+    "Sweets",
+    "Chocolates",
+    "Candies",
+    "Bakery Products",
+    "Bread",
+    "Cakes",
+    "Jams & Spreads",
+    "Peanut Butter",
+    "Honey",
+    "Pickles",
+    "Sauces",
+    "Ketchup",
+    "Chutneys",
+    "Vinegar",
+    "Tea",
+    "Coffee",
+    "Health Drinks",
+    "Soft Drinks",
+    "Packaged Juices",
+    "Energy Drinks",
+    "Bottled Water",
+    "Dairy Products",
+    "Milk",
+    "Curd",
+    "Butter",
+    "Paneer",
+    "Cheese",
+    "Eggs",
+    "Frozen Foods",
+    "Frozen Snacks",
+    "Frozen Vegetables",
+    "Fruits",
+    "Vegetables",
+    "Leafy Vegetables",
+    "Exotic Fruits",
+    "Exotic Vegetables",
+    "Cut Fruits & Vegetables",
+    "Sprouts",
+    "Detergents",
+    "Fabric Care",
+    "Dishwash Products",
+    "Floor Cleaners",
+    "Toilet Cleaners",
+    "Bathroom Cleaners",
+    "Disinfectants",
+    "Utensil Cleaners",
+    "Garbage Bags",
+    "Tissues & Napkins",
+    "Air Fresheners",
+    "Bath Soap",
+    "Handwash",
+    "Shampoo",
+    "Hair Oil",
+    "Toothpaste",
+    "Toothbrushes",
+    "Oral Care Products",
+    "Skincare Products",
+    "Personal Hygiene Products",
+    "Sanitary Products",
+    "Baby Care Products",
+    "Diapers & Wipes",
+    "Stationery",
+    "Notebooks",
+    "Pens & Pencils",
+    "Kitchen Tools",
+    "Storage Containers",
+    "Kitchen Appliances",
+    "Household Utility Items",
+]
+
+
+def read_csv(name: str) -> list[dict[str, str]]:
+    with (DATA_DIR / name).open(newline="", encoding="utf-8") as handle:
+        return list(csv.DictReader(handle))
+
+
+def header(name: str) -> list[str]:
+    with (DATA_DIR / name).open(newline="", encoding="utf-8") as handle:
+        return next(csv.reader(handle))
+
+
+def test_required_files_exist() -> None:
+    expected_files = {
+        "store_state.csv",
+        "stock.csv",
+        "pending_orders.csv",
+        "seller_profiles.csv",
+        "market_offers.csv",
+        "marketing_actions.csv",
+    }
+    assert expected_files == {path.name for path in DATA_DIR.glob("*.csv")}
+
+
+def test_headers_match_contract() -> None:
+    assert header("store_state.csv") == [
+        "day",
+        "current_daily_expense_inr",
+        "bank_balance_inr",
+        "customer_satisfaction",
+        "order_processing_capacity",
+        "cumulative_profit_inr",
+    ]
+    assert header("stock.csv") == [
+        "product_name",
+        "unit",
+        "buying_price_inr",
+        "selling_price_inr",
+        "demand_score",
+        "quantity_on_hand",
+        "stock_value_inr",
+    ]
+    assert header("pending_orders.csv") == [
+        "order_id",
+        "product_name",
+        "quantity",
+        "seller_name",
+        "buy_price_inr",
+        "days_remaining",
+        "status",
+        "created_day",
+    ]
+    assert header("seller_profiles.csv") == [
+        "seller_name",
+        "timeline_behavior",
+        "reliability_note",
+        "default_etd_days",
+    ]
+    assert header("market_offers.csv") == [
+        "product_name",
+        "category",
+        "unit",
+        "demand_score",
+        "seller_a_price_inr",
+        "seller_a_etd_days",
+        "seller_b_price_inr",
+        "seller_b_etd_days",
+        "seller_c_price_inr",
+        "seller_c_etd_days",
+        "seller_d_price_inr",
+        "seller_d_etd_days",
+    ]
+    assert header("marketing_actions.csv") == [
+        "action_id",
+        "description",
+        "customer_satisfaction_delta",
+        "cost_inr",
+        "recurring_cost_inr",
+        "order_processing_capacity_delta",
+    ]
+
+
+def test_stock_has_30_rows_and_consistent_values() -> None:
+    stock_rows = read_csv("stock.csv")
+    assert len(stock_rows) == 30
+
+    for row in stock_rows:
+        buying_price = int(row["buying_price_inr"])
+        quantity = int(row["quantity_on_hand"])
+        stock_value = int(row["stock_value_inr"])
+        assert stock_value == buying_price * quantity
+
+    total_value = sum(int(r["stock_value_inr"]) for r in stock_rows)
+    assert 220_000 <= total_value <= 260_000
+
+
+def test_store_state_matches_realistic_opening_values() -> None:
+    rows = read_csv("store_state.csv")
+    assert rows == [
+        {
+            "day": "1",
+            "current_daily_expense_inr": "3000",
+            "bank_balance_inr": "120000",
+            "customer_satisfaction": "70",
+            "order_processing_capacity": "500",
+            "cumulative_profit_inr": "0",
+        }
+    ]
+
+
+def test_perishable_stock_levels_fit_kirana_scale() -> None:
+    stock = {row["product_name"]: row for row in read_csv("stock.csv")}
+
+    assert int(stock["Milk"]["quantity_on_hand"]) <= 120
+    assert int(stock["Bread"]["quantity_on_hand"]) <= 50
+    assert int(stock["Eggs"]["quantity_on_hand"]) <= 40
+    assert int(stock["Vegetables"]["quantity_on_hand"]) <= 80
+    assert int(stock["Fruits"]["quantity_on_hand"]) <= 60
+    assert int(stock["Bottled Water"]["quantity_on_hand"]) <= 96
+    assert int(stock["Biscuits"]["quantity_on_hand"]) <= 80
+
+
+def test_stocked_products_exist_in_market_offers() -> None:
+    market_products = {row["product_name"] for row in read_csv("market_offers.csv")}
+    for row in read_csv("stock.csv"):
+        assert row["product_name"] in market_products
+
+
+def test_pending_orders_starts_empty() -> None:
+    assert read_csv("pending_orders.csv") == []
+
+
+def test_market_offers_contain_all_expected_products() -> None:
+    market_rows = read_csv("market_offers.csv")
+    product_names = [row["product_name"] for row in market_rows]
+
+    assert product_names == EXPECTED_PRODUCTS
+    assert len(set(product_names)) == len(EXPECTED_PRODUCTS)
+
+    for row in market_rows:
+        assert row["category"] != ""
+        assert row["unit"] != ""
+        for column in (
+            "seller_a_price_inr",
+            "seller_a_etd_days",
+            "seller_b_price_inr",
+            "seller_b_etd_days",
+            "seller_c_price_inr",
+            "seller_c_etd_days",
+            "seller_d_price_inr",
+            "seller_d_etd_days",
+        ):
+            assert row[column] != ""
+
+
+def test_market_offers_have_varied_seller_patterns() -> None:
+    market_rows = read_csv("market_offers.csv")
+
+    etd_patterns = {
+        (
+            row["seller_a_etd_days"],
+            row["seller_b_etd_days"],
+            row["seller_c_etd_days"],
+            row["seller_d_etd_days"],
+        )
+        for row in market_rows
+    }
+    assert len(etd_patterns) >= 8
+
+    c_beats_b = sum(
+        int(row["seller_c_price_inr"]) < int(row["seller_b_price_inr"])
+        for row in market_rows
+    )
+    d_beats_b = sum(
+        int(row["seller_d_price_inr"]) < int(row["seller_b_price_inr"])
+        for row in market_rows
+    )
+    a_not_cheapest = sum(
+        int(row["seller_a_price_inr"])
+        > min(
+            int(row["seller_a_price_inr"]),
+            int(row["seller_b_price_inr"]),
+            int(row["seller_c_price_inr"]),
+            int(row["seller_d_price_inr"]),
+        )
+        for row in market_rows
+    )
+
+    assert c_beats_b >= 25
+    assert d_beats_b >= 25
+    assert a_not_cheapest >= 10
+
+    bc_deltas = {int(row["seller_c_price_inr"]) - int(row["seller_b_price_inr"]) for row in market_rows}
+    bd_deltas = {int(row["seller_d_price_inr"]) - int(row["seller_b_price_inr"]) for row in market_rows}
+    assert len(bc_deltas) >= 12
+    assert len(bd_deltas) >= 12
+
+
+def test_marketing_actions_have_15_unique_ids() -> None:
+    rows = read_csv("marketing_actions.csv")
+    action_ids = [row["action_id"] for row in rows]
+    assert len(rows) == 15
+    assert len(set(action_ids)) == 15
+
+
+def test_marketing_actions_match_realistic_catalog() -> None:
+    rows = {row["action_id"]: row for row in read_csv("marketing_actions.csv")}
+
+    assert rows["7"] == {
+        "action_id": "7",
+        "description": "Local delivery partner tie-up",
+        "customer_satisfaction_delta": "5",
+        "cost_inr": "5000",
+        "recurring_cost_inr": "600",
+        "order_processing_capacity_delta": "40",
+    }
+    assert rows["11"] == {
+        "action_id": "11",
+        "description": "Open second branch (deposit + fit-out)",
+        "customer_satisfaction_delta": "12",
+        "cost_inr": "750000",
+        "recurring_cost_inr": "3000",
+        "order_processing_capacity_delta": "350",
+    }
+    assert rows["15"] == {
+        "action_id": "15",
+        "description": "Always-on targeted social ads",
+        "customer_satisfaction_delta": "3",
+        "cost_inr": "4000",
+        "recurring_cost_inr": "1200",
+        "order_processing_capacity_delta": "0",
+    }
+
+
+def test_doc_scenarios_match_seed_data() -> None:
+    plan_text = PLAN_PATH.read_text(encoding="utf-8")
+    stock = {row["product_name"]: row for row in read_csv("stock.csv")}
+    market = {row["product_name"]: row for row in read_csv("market_offers.csv")}
+
+    for phrase in (
+        "Rice at `138` vs Seller B at `160`",
+        "Cooking Oil at `156` vs Seller B at `180`",
+        "Spices at `345` vs Seller B at `400`",
+        "Bread at `31` vs Seller B at `35`",
+        "Eggs at `64` vs Seller B at `72`",
+        "Curd at `33` vs Seller B at `35`",
+        "Vegetables at `38` vs Seller B at `40`",
+        "Always-on targeted social ads",
+        "Kitchen Appliances",
+        "Biscuits | 40",
+        "Bottled Water | 48",
+    ):
+        assert phrase in plan_text
+
+    assert int(stock["Milk"]["selling_price_inr"]) <= math.ceil(int(stock["Milk"]["buying_price_inr"]) * 1.05)
+    assert int(stock["Bread"]["selling_price_inr"]) <= math.ceil(int(stock["Bread"]["buying_price_inr"]) * 1.05)
+    assert int(stock["Eggs"]["selling_price_inr"]) <= math.ceil(int(stock["Eggs"]["buying_price_inr"]) * 1.05)
+    assert int(stock["Sugar"]["selling_price_inr"]) <= math.ceil(int(stock["Sugar"]["buying_price_inr"]) * 1.06)
+    assert int(stock["Biscuits"]["quantity_on_hand"]) == 40
+    assert int(stock["Bottled Water"]["quantity_on_hand"]) == 48
+    assert int(stock["Kitchen Appliances"]["quantity_on_hand"]) == 4
+
+    assert int(market["Rice"]["seller_a_price_inr"]) == 138
+    assert int(market["Cooking Oil"]["seller_a_price_inr"]) == 156
+    assert int(market["Spices"]["seller_a_price_inr"]) == 345
+    assert int(market["Bread"]["seller_c_price_inr"]) == 31
+    assert int(market["Eggs"]["seller_c_price_inr"]) == 64
+    assert int(market["Curd"]["seller_c_price_inr"]) == 33
+    assert int(market["Vegetables"]["seller_c_price_inr"]) == 38

tests/test_store_environment.py

@@ -0,0 +1,174 @@
+import random
+
+import pytest
+
+from store import OrderRequest, PriceUpdate, StoreAction, StoreEnv
+from store.models import dump_model
+from store.server.store_environment import StoreEnvironment
+
+
+def test_reset_returns_full_plan_like_observation() -> None:
+    env = StoreEnvironment()
+
+    observation = env.reset()
+
+    assert observation.store.day == 1
+    assert len(observation.stock) == 30
+    assert len(observation.market) == 100
+    assert len(observation.marketing_actions) == 15
+    assert len(observation.seller_profiles) == 4
+    assert observation.pending_orders == []
+    assert observation.available_action.pass_action == StoreAction()
+    assert observation.available_action.example_action.action_ids == [7]
+
+
+def test_pass_step_advances_three_days_but_reward_uses_six_day_forecast() -> None:
+    env = StoreEnvironment()
+    env.reset()
+
+    observation = env.step(StoreAction())
+
+    assert observation.store.day == 4
+    assert observation.metadata["reward_breakdown"]["commit_window_days"] == 3
+    assert observation.metadata["reward_breakdown"]["reward_horizon_days"] == 6
+
+
+def test_eta_sampling_is_deterministic_for_a_seed() -> None:
+    env_a = StoreEnvironment()
+    env_b = StoreEnvironment()
+    env_a.reset()
+    env_b.reset()
+
+    env_a._rng = random.Random(7)
+    env_b._rng = random.Random(7)
+
+    assert env_a._sample_actual_eta("Seller C", 5) == env_b._sample_actual_eta("Seller C", 5)
+
+
+def test_commit_state_only_keeps_three_days_of_progress() -> None:
+    env = StoreEnvironment()
+    env.reset()
+    env._sample_actual_eta = lambda seller, quoted: 4  # type: ignore[method-assign]
+
+    observation = env.step(
+        StoreAction(
+            orders=[OrderRequest(product="Rice", seller="Seller B", quantity=10)],
+        )
+    )
+
+    assert observation.store.day == 4
+    assert len(observation.pending_orders) == 1
+    assert observation.pending_orders[0].days_remaining == 1
+
+
+def test_price_update_changes_customer_satisfaction() -> None:
+    env = StoreEnvironment()
+    reset_observation = env.reset()
+    milk_row = next(row for row in reset_observation.stock if row.product_name == "Milk")
+
+    observation = env.step(
+        StoreAction(
+            prices=[
+                PriceUpdate(
+                    product="Milk",
+                    price=max(1, int(milk_row.selling_price_inr) - 5),
+                )
+            ]
+        )
+    )
+
+    assert observation.store.customer_satisfaction > reset_observation.store.customer_satisfaction
+
+
+def test_marketing_actions_are_durable_and_cannot_be_reactivated() -> None:
+    env = StoreEnvironment()
+    env.reset()
+
+    observation = env.step(StoreAction(action_ids=[7]))
+
+    assert observation.store.active_action_ids == [7]
+    assert observation.store.active_recurring_cost_inr > 0
+    assert any(
+        action.action_id == 7 and action.is_active for action in observation.marketing_actions
+    )
+
+    with pytest.raises(ValueError):
+        env.step(StoreAction(action_ids=[7]))
+
+
+def test_recurring_costs_are_deducted_each_simulated_day() -> None:
+    env = StoreEnvironment()
+    env.reset()
+    runtime = env._build_initial_runtime()
+    runtime["store"]["bank_balance_inr"] = 10_000.0
+    runtime["store"]["cumulative_profit_inr"] = 0.0
+    runtime["store"]["current_daily_expense_inr"] = 0.0
+    runtime["store"]["customer_satisfaction"] = 0.0
+    runtime["active_action_ids"] = {7}
+
+    metrics = env._simulate_days(runtime, 3)
+
+    assert metrics["recurring_costs_paid_inr"] == 1_800.0
+    assert runtime["store"]["bank_balance_inr"] == 8_200.0
+    assert runtime["store"]["cumulative_profit_inr"] == -1_800.0
+
+
+def test_large_capital_loss_reduces_reward_and_ends_episode() -> None:
+    baseline = StoreEnvironment()
+    baseline.reset()
+    baseline_reward = baseline.step(StoreAction()).reward
+
+    env = StoreEnvironment()
+    env.reset()
+    observation = env.step(StoreAction(action_ids=[11]))
+
+    assert observation.reward < baseline_reward
+    assert observation.done is True
+    assert observation.metadata["done_reason"] == "bank_balance_below_zero"
+
+
+def test_episode_ends_after_tenth_decision_window() -> None:
+    env = StoreEnvironment()
+    env.reset()
+
+    observation = None
+    for _ in range(9):
+        observation = env.step(StoreAction())
+        assert observation.done is False
+
+    observation = env.step(StoreAction())
+
+    assert observation is not None
+    assert observation.done is True
+    assert observation.store.day == 31
+    assert observation.metadata["done_reason"] == "episode_horizon_reached"
+
+
+def test_client_payload_and_result_parsing_support_nested_models() -> None:
+    client = StoreEnv(base_url="http://localhost:8000")
+    action = StoreAction(
+        orders=[OrderRequest(product="Rice", seller="Seller A", quantity=5)],
+        prices=[PriceUpdate(product="Milk", price=33)],
+        action_ids=[7],
+    )
+
+    payload = client._step_payload(action)
+
+    assert payload == {
+        "orders": [{"product": "Rice", "seller": "Seller A", "quantity": 5}],
+        "prices": [{"product": "Milk", "price": 33}],
+        "action_ids": [7],
+    }
+
+    env = StoreEnvironment()
+    observation = env.reset()
+    result = client._parse_result(
+        {
+            "observation": dump_model(observation, exclude_none=True),
+            "reward": 0.0,
+            "done": False,
+        }
+    )
+
+    assert result.observation.store.day == 1
+    assert len(result.observation.market) == 100