README.md

metadata

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.

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:

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

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

effective_daily_orders = order_processing_capacity * (customer_satisfaction / 100)

This means the current satisfaction score is treated as a percentage scale.

Product margin

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

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

total_product_selling_score = sum(product_selling_score for each stocked item)

Daily sales allocation

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.

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:

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:

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

cd store
uv sync

Start the server

cd store
uv run --project . server --port 8000

Start the Gradio playground

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

cd store
uv run --project . openenv validate .

Run the tests

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:

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

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:

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

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