Update app.py

app.py

@@ -1,5 +1,5 @@
 # app.py
-# @title Beer Game Final Version (v4.11 - Corrected Order Passing Logic)
+# @title Beer Game Final Version (v4.13 - Classic UI Timing & Backlog Explanation)
 
 # -----------------------------------------------------------------------------
 # 1. Import Libraries
@@ -30,7 +30,7 @@ st.set_page_config(page_title="Beer Game: Human-AI Collaboration", layout="wide"
 WEEKS = 24
 INITIAL_INVENTORY = 12
 INITIAL_BACKLOG = 0
-ORDER_PASSING_DELAY = 1 # *** CRITICAL: This is now handled directly in step_game ***
+ORDER_PASSING_DELAY = 1
 SHIPPING_DELAY = 2 # General shipping delay
 FACTORY_LEAD_TIME = 1
 FACTORY_SHIPPING_DELAY = 1 # Specific delay from Factory to Distributor
@@ -75,7 +75,7 @@ def init_game_state(llm_personality: str, info_sharing: str):
         'factory_production_pipeline': deque([0] * FACTORY_LEAD_TIME, maxlen=FACTORY_LEAD_TIME),
         'decision_step': 'initial_order',
         'human_initial_order': None,
-        'last_week_orders': {name: 0 for name in roles} # Store previous week's final orders
+        'last_week_orders': {name: 4 for name in roles} # Seed initial orders/production for week 1
     }
 
     for i, name in enumerate(roles):
@@ -86,11 +86,15 @@ def init_game_state(llm_personality: str, info_sharing: str):
         elif name == "Factory": shipping_weeks = 0
         else: shipping_weeks = SHIPPING_DELAY
 
+        # 'inventory' and 'backlog' now consistently represent END-OF-WEEK state
         st.session_state.game_state['echelons'][name] = {
-            'name': name, 'inventory': INITIAL_INVENTORY, 'backlog': INITIAL_BACKLOG,
-            # 'order_pipeline' is no longer needed for passing delay = 1
+            'name': name,
+            'inventory': INITIAL_INVENTORY, # End-of-week state (used as opening state for next week)
+            'backlog': INITIAL_BACKLOG,     # End-of-week state (used as opening state for next week)
             'incoming_shipments': deque([0] * shipping_weeks, maxlen=shipping_weeks),
-            'incoming_order': 0, 'order_placed': 0, 'shipment_sent': 0,
+            'incoming_order': 0, # Order received THIS week
+            'order_placed': 0,   # Order placed THIS week
+            'shipment_sent': 0,  # Shipment sent THIS week
             'weekly_cost': 0, 'total_cost': 0, 'upstream_name': upstream, 'downstream_name': downstream,
         }
     st.info(f"New game started! AI Mode: **{llm_personality} / {info_sharing}**. You are playing as the: **{human_role}**.")
@@ -118,73 +122,84 @@ def get_llm_order_decision(prompt: str, echelon_name: str) -> (int, str):
             st.error(f"API call failed for {echelon_name}: {e}. Defaulting to 8.")
             return 8, f"API_ERROR: {e}"
 
-def get_llm_prompt(echelon_state: dict, week: int, llm_personality: str, info_sharing: str, all_echelons_state: dict) -> str:
-    # This function's logic remains correct.
-    base_info = f"Your Current Status at the **{echelon_state['name']}** for **Week {week}**:\n- On-hand inventory: {echelon_state['inventory']} units.\n- Backlog (unfilled orders): {echelon_state['backlog']} units.\n- Incoming order this week (from your customer): {echelon_state['incoming_order']} units.\n"
-    if echelon_state['name'] == 'Factory':
+# =============== MODIFIED FUNCTION (Prompt uses state AFTER arrivals/orders) ===============
+def get_llm_prompt(echelon_state_after_arrivals: dict, week: int, llm_personality: str, info_sharing: str, all_echelons_state_after_arrivals: dict) -> str:
+    """Generates the prompt for the LLM based on the game scenario.
+       Uses the state AFTER arrivals and new orders are processed, as this is the decision point."""
+
+    e_state = echelon_state_after_arrivals # Use the passed-in state for prompts
+
+    base_info = f"Your Current Status at the **{e_state['name']}** for **Week {week}** (Before Shipping):\n- On-hand inventory: {e_state['inventory']} units.\n- Backlog (total unfilled orders): {e_state['backlog']} units.\n- Incoming order this week (just received): {e_state['incoming_order']} units.\n"
+
+    if e_state['name'] == 'Factory':
         task_word = "production quantity"
+        # Factory needs access to the global pipeline state
         base_info += f"- Production pipeline (completing in future weeks): {list(st.session_state.game_state['factory_production_pipeline'])}"
     else:
         task_word = "order quantity"
-        # Base info now correctly reflects only incoming shipments for non-factory roles
-        base_info += f"- Shipments on the way to you: {list(echelon_state['incoming_shipments'])}"
-        # We don't need 'Orders in pipeline' in the prompt anymore as delay=1 is handled directly
+        # Non-factory prompt needs its incoming shipments queue
+        base_info += f"- Shipments on the way to you (arriving next week and later): {list(e_state['incoming_shipments'])}"
 
+    # --- Perfect Rational ---
     if llm_personality == 'perfect_rational' and info_sharing == 'full':
         stable_demand = 8
-        if echelon_state['name'] == 'Factory': total_lead_time = FACTORY_LEAD_TIME
-        elif echelon_state['name'] == 'Distributor': total_lead_time = ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY
+        if e_state['name'] == 'Factory': total_lead_time = FACTORY_LEAD_TIME
+        elif e_state['name'] == 'Distributor': total_lead_time = ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY
         else: total_lead_time = ORDER_PASSING_DELAY + SHIPPING_DELAY
         safety_stock = 4
         target_inventory_level = (stable_demand * total_lead_time) + safety_stock
-        if echelon_state['name'] == 'Factory':
-            inv_pos_components = f"(Inv: {echelon_state['inventory']} - Backlog: {echelon_state['backlog']} + In_Production: {sum(st.session_state.game_state['factory_production_pipeline'])})"
-            inventory_position = (echelon_state['inventory'] - echelon_state['backlog'] + sum(st.session_state.game_state['factory_production_pipeline']))
+        # Calculate Inventory Position based on state AFTER arrivals/orders
+        if e_state['name'] == 'Factory':
+            inv_pos_components = f"(Current Inv: {e_state['inventory']} - Current Backlog: {e_state['backlog']} + In_Production: {sum(st.session_state.game_state['factory_production_pipeline'])})"
+            inventory_position = (e_state['inventory'] - e_state['backlog'] + sum(st.session_state.game_state['factory_production_pipeline']))
         else:
-            # Simplified inventory position for delay=1
-            inv_pos_components = f"(Inv: {echelon_state['inventory']} - Backlog: {echelon_state['backlog']} + In_Transit: {sum(echelon_state['incoming_shipments'])})"
-            inventory_position = (echelon_state['inventory'] - echelon_state['backlog'] + sum(echelon_state['incoming_shipments']))
+            inv_pos_components = f"(Current Inv: {e_state['inventory']} - Current Backlog: {e_state['backlog']} + In_Transit: {sum(e_state['incoming_shipments'])})"
+            inventory_position = (e_state['inventory'] - e_state['backlog'] + sum(e_state['incoming_shipments']))
         optimal_order = max(0, int(target_inventory_level - inventory_position))
         return f"**You are a perfectly rational supply chain AI with full system visibility.**\nYour only goal is to maintain stability and minimize costs based on mathematical optimization.\n**System Analysis:**\n* **Known Stable End-Customer Demand:** {stable_demand} units/week.\n* **Your Current Total Inventory Position:** {inventory_position} units. {inv_pos_components}\n* **Optimal Target Inventory Level:** {target_inventory_level} units (Target for {total_lead_time} weeks lead time).\n* **Mathematically Optimal {task_word.title()}:** The optimal decision is **{optimal_order} units**.\n**Your Task:** Confirm this optimal {task_word}. Respond with a single integer."
 
     elif llm_personality == 'perfect_rational' and info_sharing == 'local':
-        safety_stock = 4; anchor_demand = echelon_state['incoming_order']
-        inventory_correction = safety_stock - (echelon_state['inventory'] - echelon_state['backlog'])
-        if echelon_state['name'] == 'Factory':
+        safety_stock = 4; anchor_demand = e_state['incoming_order']
+        # Use state AFTER arrivals/orders for inventory correction calculation
+        inventory_correction = safety_stock - (e_state['inventory'] - e_state['backlog'])
+        if e_state['name'] == 'Factory':
             supply_line = sum(st.session_state.game_state['factory_production_pipeline'])
             supply_line_desc = "In Production"
         else:
-            # Simplified supply line for delay=1
-            supply_line = sum(echelon_state['incoming_shipments'])
+            supply_line = sum(e_state['incoming_shipments'])
             supply_line_desc = "In Transit Shipments"
         calculated_order = anchor_demand + inventory_correction - supply_line
         rational_local_order = max(0, int(calculated_order))
-        return f"**You are a perfectly rational supply chain AI with ONLY LOCAL information.**\nYou must use a logical heuristic to make a stable decision. A proven method is \"Anchoring and Adjustment\".\n\n{base_info}\n\n**Rational Calculation (Anchoring & Adjustment):**\n1.  **Anchor on Demand:** Your best guess for future demand is your last incoming order: **{anchor_demand} units**.\n2.  **Adjust for Inventory:** You want to hold a safety stock of {safety_stock} units. Your current stock is {echelon_state['inventory'] - echelon_state['backlog']}. You need to order an extra **{inventory_correction} units** to correct this.\n3.  **Account for {supply_line_desc}:** You already have **{supply_line} units** being processed. These should be subtracted from your new order.\n\n**Final Calculation:**\n* Decision = (Anchor Demand) + (Inventory Adjustment) - ({supply_line_desc})\n* Decision = {anchor_demand} + {inventory_correction} - {supply_line} = **{rational_local_order} units**.\n**Your Task:** Confirm this locally rational {task_word}. Respond with a single integer."
+        return f"**You are a perfectly rational supply chain AI with ONLY LOCAL information.**\nYou must use a logical heuristic to make a stable decision. A proven method is \"Anchoring and Adjustment\".\n\n{base_info}\n\n**Rational Calculation (Anchoring & Adjustment):**\n1.  **Anchor on Demand:** Your best guess for future demand is your last incoming order: **{anchor_demand} units**.\n2.  **Adjust for Inventory:** You want to hold a safety stock of {safety_stock} units. Your current stock (before shipping) is {e_state['inventory'] - e_state['backlog']}. You need to order an extra **{inventory_correction} units** to correct this.\n3.  **Account for {supply_line_desc}:** You already have **{supply_line} units** being processed. These should be subtracted from your new order.\n\n**Final Calculation:**\n* Decision = (Anchor Demand) + (Inventory Adjustment) - ({supply_line_desc})\n* Decision = {anchor_demand} + {inventory_correction} - {supply_line} = **{rational_local_order} units**.\n**Your Task:** Confirm this locally rational {task_word}. Respond with a single integer."
 
+    # --- Human-like ---
     elif llm_personality == 'human_like' and info_sharing == 'full':
-        full_info_str = f"\n**Full Supply Chain Information:**\n- End-Customer Demand this week: {get_customer_demand(week)} units.\n"
-        for name, e_state in all_echelons_state.items():
-            if name != echelon_state['name']: full_info_str += f"- {name}: Inventory={e_state['inventory']}, Backlog={e_state['backlog']}\n"
+        full_info_str = f"\n**Full Supply Chain Information (State Before Shipping):**\n- End-Customer Demand this week: {get_customer_demand(week)} units.\n"
+        # Display other players' state AFTER arrivals/orders
+        for name, other_e_state in all_echelons_state_after_arrivals.items():
+            if name != e_state['name']: full_info_str += f"- {name}: Inv={other_e_state['inventory']}, Backlog={other_e_state['backlog']}\n"
         return f"""
-        **You are a supply chain manager ({echelon_state['name']}) with full system visibility.**
-        You can see everyone's inventory and the real customer demand.
+        **You are a supply chain manager ({e_state['name']}) with full system visibility.**
+        You can see everyone's current inventory and backlog before shipping, and the real customer demand.
         {base_info}
         {full_info_str}
-        **Your Task:** Your primary responsibility is to meet the demand from your direct customer (your `Incoming order this week`: **{echelon_state['incoming_order']}** units).
-        While you can see the stable end-customer demand ({get_customer_demand(week)} units), your priority is to fulfill the order you just received to avoid a backlog.
+        **Your Task:** Your primary responsibility is to meet the demand from your direct customer (your `Incoming order this week`: **{e_state['incoming_order']}** units), which contributes to your total current backlog of {e_state['backlog']}.
+        While you can see the stable end-customer demand ({get_customer_demand(week)} units), your priority is to fulfill the order you just received and manage your inventory/backlog.
         You are still human and might get anxious about your own stock levels.
         What {task_word} should you decide on this week? Respond with a single integer.
         """
 
     elif llm_personality == 'human_like' and info_sharing == 'local':
         return f"""
-        **You are a reactive supply chain manager for the {echelon_state['name']}.** You have a limited view and tend to over-correct based on fear.
+        **You are a reactive supply chain manager for the {e_state['name']}.** You have a limited view and tend to over-correct based on fear.
         Your top priority is to NOT have a backlog.
         {base_info}
-        **Your Task:** You just received an incoming order for **{echelon_state['incoming_order']}** units.
-        Your gut instinct is to panic and {task_word.split(' ')[0]} enough to ensure you are never caught with a backlog again.
+        **Your Task:** You just received an incoming order for **{e_state['incoming_order']}** units, adding to your total backlog.
+        Your gut instinct is to panic and {task_word.split(' ')[0]} enough to ensure you are never caught with a backlog again, considering your current inventory.
         **React emotionally.** What is your knee-jerk {task_word}? Respond with a single integer.
         """
+# ==============================================================================
+
 
 # =============== CORRECTED step_game FUNCTION ===============
 def step_game(human_final_order: int, human_initial_order: int, ai_suggestion: int):
@@ -193,92 +208,138 @@ def step_game(human_final_order: int, human_initial_order: int, ai_suggestion: i
     llm_personality, info_sharing = state['llm_personality'], state['info_sharing']
     echelon_order = ["Retailer", "Wholesaler", "Distributor", "Factory"]
     llm_raw_responses = {}
-    
-    # Store pre-step state for logging
-    pre_step_inventory = echelons[human_role]['inventory']
-    pre_step_backlog = echelons[human_role]['backlog']
-    arriving_shipment_this_week = list(echelons[human_role]['incoming_shipments'])[0] if echelons[human_role]['incoming_shipments'] else 0
 
-    # --- Game Simulation Steps (Corrected Logic for Order Passing Delay = 1) ---
+    # Store state at the very beginning of the week for logging opening balances
+    # These are the inventory/backlog values from the END of the previous week
+    opening_inventories = {name: e['inventory'] for name, e in echelons.items()}
+    opening_backlogs = {name: e['backlog'] for name, e in echelons.items()}
+    arrived_this_week = {name: 0 for name in roles} # Track arrivals for logging
+
+    # --- Game Simulation Steps ---
 
-    # Step 1a: Factory Production completes and adds to Factory inventory
+    # Step 1a: Factory Production completes
     factory_state = echelons["Factory"]
     produced_units = 0
     if state['factory_production_pipeline']:
         produced_units = state['factory_production_pipeline'].popleft()
-        factory_state['inventory'] += produced_units
+        # Temporarily store, don't update main state yet
+        inventory_after_production = factory_state['inventory'] + produced_units
+        arrived_this_week["Factory"] = produced_units
+    else:
+        inventory_after_production = factory_state['inventory']
+
 
     # Step 1b: Shipments arrive at downstream echelons
+    inventory_after_arrival = {} # Store intermediate state
     for name in ["Retailer", "Wholesaler", "Distributor"]:
         arrived_shipment = 0
         if echelons[name]['incoming_shipments']:
-            arrived_shipment = echelons[name]['incoming_shipments'].popleft() # Pop shipment for current week
-            echelons[name]['inventory'] += arrived_shipment
+            arrived_shipment = echelons[name]['incoming_shipments'].popleft()
+            arrived_this_week[name] = arrived_shipment
+        inventory_after_arrival[name] = echelons[name]['inventory'] + arrived_shipment
+    inventory_after_arrival["Factory"] = inventory_after_production # Add factory's state
 
     # Step 2: Orders arrive from downstream partners (using LAST week's placed order)
+    total_backlog_before_shipping = {} # Store intermediate state
     for name in echelon_order:
         if name == "Retailer":
             echelons[name]['incoming_order'] = get_customer_demand(week)
         else:
-            # Get the downstream partner's name
             downstream_name = echelons[name]['downstream_name']
+            order_from_downstream = 0
             if downstream_name:
-                # Retrieve the order placed by the downstream partner LAST week
                 order_from_downstream = state['last_week_orders'].get(downstream_name, 0)
-                echelons[name]['incoming_order'] = order_from_downstream
-            else: # Should not happen except maybe week 1 if not handled
-                 echelons[name]['incoming_order'] = 0
+            echelons[name]['incoming_order'] = order_from_downstream
+        # Calculate the total backlog BEFORE shipping
+        total_backlog_before_shipping[name] = echelons[name]['backlog'] + echelons[name]['incoming_order']
 
-    # Step 3: Fulfill orders (Ship Beer)
+    # --- Create State Snapshot for AI/Human Decision Point ---
+    # This reflects the state AFTER arrivals and new orders, BEFORE shipping
+    decision_point_states = {}
     for name in echelon_order:
-        e = echelons[name]
-        demand_to_meet = e['incoming_order'] + e['backlog']
-        e['shipment_sent'] = min(e['inventory'], demand_to_meet)
-        e['inventory'] -= e['shipment_sent']
-        e['backlog'] = demand_to_meet - e['shipment_sent']
+         # Need to create a copy, including deque if needed for prompt
+         decision_point_states[name] = {
+             'name': name,
+             'inventory': inventory_after_arrival[name], # Inventory available
+             'backlog': total_backlog_before_shipping[name], # Total demand to meet
+             'incoming_order': echelons[name]['incoming_order'], # Order received this week
+             # Pass the current state of queues for prompt generation
+             'incoming_shipments': echelons[name]['incoming_shipments'].copy() if name != "Factory" else deque(),
+         }
 
-    # Step 3b: Place shipped items into the *end* of the downstream partner's incoming shipment queue
-    for sender_name in ["Factory", "Distributor", "Wholesaler"]:
-        sender = echelons[sender_name]
-        receiver_name = sender['downstream_name']
-        if receiver_name:
-            # Append the shipment SENT this week to the receiver's incoming queue for the FUTURE
-            echelons[receiver_name]['incoming_shipments'].append(sender['shipment_sent'])
 
     # --- Step 4: Agent Decisions (Place Orders / Schedule Production) ---
-    current_week_orders = {} # Store this week's decisions
+    # Agents make decisions based on the decision_point_states
+    current_week_orders = {}
     for name in echelon_order:
-        e = echelons[name]
+        e = echelons[name] # Get the main state dict to store results
+        prompt_state = decision_point_states[name] # Use the snapshot for the prompt
+
         if name == human_role:
             order_amount, raw_resp = human_final_order, "HUMAN_FINAL_INPUT"
         else:
-            prompt = get_llm_prompt(e, week, llm_personality, info_sharing, echelons)
+            prompt = get_llm_prompt(prompt_state, week, llm_personality, info_sharing, decision_point_states)
             order_amount, raw_resp = get_llm_order_decision(prompt, name)
         llm_raw_responses[name] = raw_resp
-        e['order_placed'] = max(0, order_amount) # This is the order/production decision for the week
-        current_week_orders[name] = e['order_placed'] # Store decision for next week's Step 2
+        e['order_placed'] = max(0, order_amount) # Store the decision in the main state dict
+        current_week_orders[name] = e['order_placed']
 
     # Factory schedules production based on its 'order_placed' decision
     state['factory_production_pipeline'].append(echelons["Factory"]['order_placed'])
 
-    # --- Logging (End of Week) ---
+
+    # --- Step 3: Fulfill orders (Ship Beer) ---
+    # Now perform the shipping based on the inventory_after_arrival and total_backlog_before_shipping
+    for name in echelon_order:
+        e = echelons[name]
+        demand_to_meet = total_backlog_before_shipping[name]
+        available_inv = inventory_after_arrival[name]
+
+        e['shipment_sent'] = min(available_inv, demand_to_meet)
+        # Update the main state dict's inventory and backlog to reflect END OF WEEK state
+        e['inventory'] = available_inv - e['shipment_sent']
+        e['backlog'] = demand_to_meet - e['shipment_sent']
+
+    # Step 3b: Place shipped items into the *end* of the downstream partner's incoming shipment queue
+    for sender_name in ["Factory", "Distributor", "Wholesaler"]:
+        sender = echelons[sender_name]
+        receiver_name = sender['downstream_name']
+        if receiver_name:
+            echelons[receiver_name]['incoming_shipments'].append(sender['shipment_sent'])
+
+
+    # --- Calculate Costs & Log (End of Week) ---
     log_entry = {'timestamp': datetime.utcnow().isoformat() + "Z", 'week': week, **state}
     del log_entry['echelons'], log_entry['factory_production_pipeline'], log_entry['logs'], log_entry['last_week_orders']
 
     for name in echelon_order:
         e = echelons[name]
-        e['weekly_cost'] = (e['inventory'] * HOLDING_COST) + (e['backlog'] * BACKLOG_COST); e['total_cost'] += e['weekly_cost']
-        for key in ['inventory', 'backlog', 'incoming_order', 'order_placed', 'shipment_sent', 'weekly_cost', 'total_cost']:
-            log_entry[f'{name}.{key}'] = e[key]
+        # Costs are based on the END OF WEEK state
+        e['weekly_cost'] = (e['inventory'] * HOLDING_COST) + (e['backlog'] * BACKLOG_COST)
+        e['total_cost'] += e['weekly_cost']
+
+        # Log end-of-week internal state and decisions/events of the week
+        log_entry[f'{name}.inventory'] = e['inventory'] # End of week inventory
+        log_entry[f'{name}.backlog'] = e['backlog']     # End of week backlog
+        log_entry[f'{name}.incoming_order'] = e['incoming_order'] # Order received this week
+        log_entry[f'{name}.order_placed'] = e['order_placed'] # Decision made this week
+        log_entry[f'{name}.shipment_sent'] = e['shipment_sent'] # Shipped this week
+        log_entry[f'{name}.weekly_cost'] = e['weekly_cost'] # Cost for this week
+        log_entry[f'{name}.total_cost'] = e['total_cost'] # Cumulative cost
         log_entry[f'{name}.llm_raw_response'] = llm_raw_responses.get(name, "")
+
+        # Log opening balances for the week
+        log_entry[f'{name}.opening_inventory'] = opening_inventories[name]
+        log_entry[f'{name}.opening_backlog'] = opening_backlogs[name]
+        log_entry[f'{name}.arrived_this_week'] = arrived_this_week[name]
+
+        # Log prediction for next week's arrival/completion (based on queues AFTER this week's processing)
         if name != 'Factory':
              log_entry[f'{name}.arriving_next_week'] = list(e['incoming_shipments'])[0] if e['incoming_shipments'] else 0
         else:
              log_entry[f'{name}.production_completing_next_week'] = list(state['factory_production_pipeline'])[0] if state['factory_production_pipeline'] else 0
 
-    log_entry[f'{human_role}.opening_inventory'] = pre_step_inventory
-    log_entry[f'{human_role}.opening_backlog'] = pre_step_backlog
-    log_entry[f'{human_role}.arrived_this_week'] = arriving_shipment_this_week
+    # Log human-specific decisions
     log_entry[f'{human_role}.initial_order'] = human_initial_order
     log_entry[f'{human_role}.ai_suggestion'] = ai_suggestion
 
@@ -287,10 +348,11 @@ def step_game(human_final_order: int, human_initial_order: int, ai_suggestion: i
     # --- Advance Week ---
     state['week'] += 1
     state['decision_step'] = 'initial_order'
-    state['last_week_orders'] = current_week_orders # Store current decisions for next week
+    state['last_week_orders'] = current_week_orders # Store current decisions for next week's Step 2
     if state['week'] > WEEKS: state['game_running'] = False
 # ==============================================================================
 
+
 def plot_results(df: pd.DataFrame, title: str, human_role: str):
     # This function remains correct.
     fig, axes = plt.subplots(4, 1, figsize=(12, 22))
@@ -300,14 +362,14 @@ def plot_results(df: pd.DataFrame, title: str, human_role: str):
     for _, row in df.iterrows():
         for e in echelons:
             plot_data.append({'week': row.get('week', 0), 'echelon': e,
-                'inventory': row.get(f'{e}.inventory', 0),
+                'inventory': row.get(f'{e}.inventory', 0), # Use end-of-week inventory for plots
                 'order_placed': row.get(f'{e}.order_placed', 0),
                 'total_cost': row.get(f'{e}.total_cost', 0)})
     plot_df = pd.DataFrame(plot_data)
     inventory_pivot = plot_df.pivot(index='week', columns='echelon', values='inventory').reindex(columns=echelons)
-    inventory_pivot.plot(ax=axes[0], kind='line', marker='o', markersize=4); axes[0].set_title('Inventory Levels'); axes[0].grid(True, linestyle='--'); axes[0].set_ylabel('Stock (Units)')
+    inventory_pivot.plot(ax=axes[0], kind='line', marker='o', markersize=4); axes[0].set_title('Inventory Levels (End of Week)'); axes[0].grid(True, linestyle='--'); axes[0].set_ylabel('Stock (Units)')
     order_pivot = plot_df.pivot(index='week', columns='echelon', values='order_placed').reindex(columns=echelons)
-    order_pivot.plot(ax=axes[1], style='--'); axes[1].plot(range(1, WEEKS + 1), [get_customer_demand(w) for w in range(1, WEEKS + 1)], label='Customer Demand', color='black', lw=2.5); axes[1].set_title('Order Quantities (The Bullwhip Effect)'); axes[1].grid(True, linestyle='--'); axes[1].legend(); axes[1].set_ylabel('Ordered (Units)')
+    order_pivot.plot(ax=axes[1], style='--'); axes[1].plot(range(1, WEEKS + 1), [get_customer_demand(w) for w in range(1, WEEKS + 1)], label='Customer Demand', color='black', lw=2.5); axes[1].set_title('Order Quantities / Production Decisions'); axes[1].grid(True, linestyle='--'); axes[1].legend(); axes[1].set_ylabel('Ordered/Produced (Units)')
     total_costs = plot_df.loc[plot_df.groupby('echelon')['week'].idxmax()]
     total_costs = total_costs.set_index('echelon')['total_cost'].reindex(echelons, fill_value=0)
     total_costs.plot(kind='bar', ax=axes[2], rot=0); axes[2].set_title('Total Cumulative Cost'); axes[2].set_ylabel('Cost ($)')
@@ -329,6 +391,8 @@ def save_logs_and_upload(state: dict):
     participant_id = state['participant_id']
     df = pd.json_normalize(state['logs'])
     fname = LOCAL_LOG_DIR / f"log_{participant_id}_{int(time.time())}.csv"
+    for col in df.columns:
+        if df[col].dtype == 'object': df[col] = df[col].astype(str)
     df.to_csv(fname, index=False)
     st.success(f"Log successfully saved locally: `{fname}`")
     with open(fname, "rb") as f:
@@ -342,7 +406,7 @@ def save_logs_and_upload(state: dict):
                 st.error(f"Upload to Hugging Face failed: {e}")
 
 # -----------------------------------------------------------------------------
-# 4. Streamlit UI (No changes needed in this section)
+# 4. Streamlit UI
 # -----------------------------------------------------------------------------
 st.title("🍺 The Beer Game: A Human-AI Collaboration Challenge")
 
@@ -357,13 +421,24 @@ else:
         st.markdown("This is a simulation of a supply chain. You will play against 3 AI agents. **You do not need any prior knowledge to play.** Please read these instructions carefully.")
 
         st.subheader("1. Your Goal: Minimize Costs")
-        st.success("**You Need to: Fulfill the order and Minimize the total cost for your position in the supply chain.**")
+        st.success("**Your single, most important goal is to: Minimize the total cost for your position in the supply chain.**")
         st.markdown("You get costs from two things every week:")
         st.markdown(f"""
-        - **Holding Inventory:** **${HOLDING_COST:,.2f} per unit per week.
-        - **Backlog (Unfilled Orders):** **${BACKLOG_COST:,.2f} per unit per week.
+        - **Holding Inventory:** **${HOLDING_COST:,.2f} per unit per week.** (Cost applies to inventory left *after* shipping)
+        - **Backlog (Unfilled Orders):** **${BACKLOG_COST:,.2f} per unit per week.** (Cost applies to orders you couldn't fill *after* shipping)
         """)
-        
+        with st.expander("Click to see a cost calculation example"):
+            st.markdown(f"""
+            Imagine at the **end** of Week 5, *after* you shipped beer to the Wholesaler, your final state is:
+            - Inventory: 10 units
+            - Backlog: 0 units
+            Your cost for Week 5 would be calculated *at this point*:
+            - `(10 units of Inventory * ${HOLDING_COST:,.2f})` = $5.00
+            - `(0 units of Backlog * ${BACKLOG_COST:,.2f})` = $0.00
+            - **Total Weekly Cost:** = **$5.00**
+            This cost is added to your cumulative total.
+            """)
+
         st.subheader("2. Your Role: The Distributor")
         st.markdown("""
         You will always play as the **Distributor**. The other 3 roles are played by AI.
@@ -376,28 +451,65 @@ else:
         except FileNotFoundError: st.warning("Image file not found.")
 
         st.subheader("3. The Core Challenge: Delays!")
-        st.warning(f"This is the most important rule: **It takes {ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY} weeks for an order you place to actually arrive in your inventory.**")
+        st.warning(f"It takes **{ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY} weeks** for an order you place to arrive in your inventory.")
         with st.expander("Click to see a detailed example of the 3-week delay"):
             st.markdown(f"""
-            Let's follow a single order you place:
-            * **Week 10 (You):** You decide you need 50 units. You place an order for **50**.
-            * **Week 11 (System):** Your order of 50 *arrives* at the Factory. (This is the **{ORDER_PASSING_DELAY} week Order Delay**). The Factory AI sees your order and decides to produce 50.
-            * **Week 12 (System):** The Factory *finishes* producing the 50 units. (This is the **{FACTORY_LEAD_TIME} week Production Delay**). The Factory ships the 50 units to you.
-            * **Week 13 (System):** The 50 units *arrive* at your warehouse. (This is the **{FACTORY_SHIPPING_DELAY} week Shipping Delay**). You can now use this inventory.
-            **Conclusion:** You must always think 3 weeks ahead. The order you place in Week 10 will not help you until Week 13.
+            * **Week 10 (You):** You place an order for **50**.
+            * **Week 11 (System):** Your order arrives at the Factory (**{ORDER_PASSING_DELAY}w Order Delay**). Factory AI decides to produce 50.
+            * **Week 12 (System):** Factory finishes producing 50 (**{FACTORY_LEAD_TIME}w Production Delay**) & ships it.
+            * **Week 13 (System):** The 50 units arrive at your warehouse (**{FACTORY_SHIPPING_DELAY}w Shipping Delay**).
+            **Conclusion:** Think 3 weeks ahead! Your order in Week 10 arrives at the start of Week 13.
             """)
-    
-        st.subheader("4. How Each Week Works (Your Task)")
+
+        # =============== NEW: Understanding Inventory & Backlog ===============
+        st.subheader("4. Understanding Inventory & Backlog")
+        st.markdown("""
+        Managing your inventory and backlog is key to minimizing costs. Here's how they work:
+        * **Effective "Orders to Fill":** Each week, the total demand you need to satisfy is your `Incoming Order` for the week PLUS any `Backlog` carried over from the previous week.
+        * **If you DON'T have enough inventory:**
+            * You ship **all** the inventory you have.
+            * The remaining unfilled "Orders to Fill" becomes your **new Backlog** for next week.
+            * **Backlog is cumulative!** If you have a backlog of 5 and get a new order for 8 but can only ship 10, your new backlog is `(5 + 8) - 10 = 3`.
+        * **If you DO have enough inventory:**
+            * You ship all the "Orders to Fill".
+            * Your Backlog becomes 0.
+            * The remaining inventory is carried over to next week (and incurs holding costs).
+        """)
+        # ====================================================================
+
+        #st.subheader("5. The Bullwhip Effect (What to Avoid)")
+        #st.markdown("""
+        #The "Bullwhip Effect" happens when small changes in customer demand cause **amplified**, chaotic swings in orders further up the supply chain (like you and the Factory). This often leads to cycles of **panic ordering** (ordering too much when out of stock) followed by **massive inventory pile-ups** (when late orders arrive). This cycle is very expensive. Try to order smoothly.
+        #""")
+
+        # =============== UPDATED: How Each Week Works & Dashboard Explanation ===============
+        st.subheader("5. How Each Week Works & Understanding Your Dashboard")
         st.markdown(f"""
-        Your main job is simple: place one order each week.
-        **A) At the start of every week, the system automatically does 3 things:**
-        * **(Step 1) Your Shipments Arrive:** The beer you ordered {ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY} weeks ago arrives and is added to your `Current Inventory`.
-        * **(Step 2) New Orders Arrive:** You receive a new `Incoming Order` from the Wholesaler (This was their order from *last* week).
-        * **(Step 3) You Ship Beer:** The system automatically ships as much beer as possible from your inventory to fulfill the Wholesaler's order (plus any old `Backlog`).
-        **B) After this, you will see your new dashboard and must make your 2-part decision:**
-        * **Step 4a (Initial Order):** Based on your new status, submit your **initial order** to the Factory.
-        * **Step 4b (Final Order):** You will then see an **AI suggestion**. Review it, then submit your **final order** to end the week.
+        Your main job is simple: place one order each week based on the dashboard presented to you.
+
+        **A) At the start of every week, BEFORE your turn:**
+        * **(Step 1) Shipments Arrive:** Beer you ordered {ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY} weeks ago arrives.
+        * **(Step 2) New Orders Arrive:** You receive a new order from the Wholesaler (their order from *last* week).
+        * **(Step 3) You Ship Beer (Automatically):** The system ships beer *immediately* based on your inventory *after* Step 1 and the total demand *after* Step 2.
+
+        **B) Your Dashboard (What You See for Your Turn):**
+        The dashboard shows your status **at the start of the week, BEFORE Steps 1, 2, and 3 happen**:
+        * `Inventory`: Your stock **at the beginning of the week**. This is the inventory carried over from the end of last week.
+        * `Backlog`: Unfilled orders **carried over from the end of last week**.
+        * `Incoming Order`: The specific order quantity that **will arrive** from the Wholesaler *during* this week (Step 2).
+        * `Shipment Arriving (Next Week)`: The quantity scheduled to arrive at the start of the *next* week (Week {week+1}).
+        * `Your Total Cumulative Cost`: Sum of all weekly costs up to the **end of last week**.
+        * `Cost Last Week`: The specific cost incurred just **last week**.
+
+        **C) Your Decision (Step 4 - Two Parts):**
+        Now, looking at the dashboard (showing the start-of-week state) and considering the incoming order and future arrivals, you decide how much to order:
+        * **(Step 4a - Initial Order):** Submit your first estimate.
+        * **(Step 4b - Final Order):** See the AI's suggestion, then submit your final decision. This order will arrive in 3 weeks.
+
+        Submitting your final order ends the week. The system then calculates your `Weekly Cost` based on your inventory/backlog *after* Step 3 shipping, logs everything, and advances to the next week.
         """)
+        # ==============================================================================
+
 
         st.markdown("---")
         st.header("⚙️ Game Configuration")
@@ -419,42 +531,63 @@ else:
         st.header(f"Week {week} / {WEEKS}")
         st.subheader(f"Your Role: **{human_role}** | AI Mode: **{state['llm_personality'].replace('_', ' ')}** | Information: **{state['info_sharing']}**")
         st.markdown("---")
-        st.subheader("Supply Chain Status")
+        st.subheader("Supply Chain Status (Start of Week State)") # Clarified Timing
         if info_sharing == 'full':
             cols = st.columns(4)
             for i, name in enumerate(["Retailer", "Wholesaler", "Distributor", "Factory"]):
                 with cols[i]:
                     e, icon = echelons[name], "👤" if name == human_role else "🤖"
                     st.markdown(f"##### {icon} {name} {'(You)' if name == human_role else ''}")
-                    st.metric("Inventory", e['inventory']); st.metric("Backlog", e['backlog'])
-                    if name == human_role: st.metric("Your Total Cost", f"${e['total_cost']:,.2f}")
-                    st.write(f"Incoming Order: **{e['incoming_order']}**")
+                    # Display the END OF LAST WEEK state (which is OPENING state for this week)
+                    st.metric("Inventory (Opening)", e['inventory']); st.metric("Backlog (Opening)", e['backlog'])
+
+                    if name == human_role:
+                        st.metric("Total Cost (Cumulative)", f"${e['total_cost']:,.2f}")
+                        last_week_cost = state['logs'][-1][f"{human_role}.weekly_cost"] if week > 1 and state['logs'] else 0
+                        st.metric("Cost Last Week", f"${last_week_cost:,.2f}")
+
+                    # Display info about THIS week's events
+                    st.write(f"Incoming Order (This Week): **{e['incoming_order']}**") # Order arriving in Step 2
                     if name == "Factory":
-                        prod_completing = list(state['factory_production_pipeline'])[0] if state['factory_production_pipeline'] else 0
-                        st.write(f"Production Completing: **{prod_completing}**")
+                        # Production completing NEXT week
+                        prod_completing_next = list(state['factory_production_pipeline'])[0] if state['factory_production_pipeline'] else 0
+                        st.write(f"Completing Next Week: **{prod_completing_next}**")
                     else:
-                        arriving = list(e['incoming_shipments'])[0] if e['incoming_shipments'] else 0
-                        st.write(f"Arriving Next Week: **{arriving}**")
+                        # Shipment arriving NEXT week
+                        arriving_next = list(e['incoming_shipments'])[0] if e['incoming_shipments'] else 0
+                        st.write(f"Arriving Next Week: **{arriving_next}**")
         else:
             st.info("In Local Information mode, you can only see your own status dashboard.")
             e = echelons[human_role]
-            st.markdown(f"### 👤 {human_role} (Your Dashboard)")
+            st.markdown(f"### 👤 {human_role} (Your Dashboard - Start of Week State)")
             col1, col2, col3, col4 = st.columns(4)
-            col1.metric("Current Inventory", e['inventory'])
-            col2.metric("Current Backlog", e['backlog'])
+            # Display OPENING state
+            col1.metric("Inventory (Opening)", e['inventory'])
+            col2.metric("Backlog (Opening)", e['backlog'])
+            # Display info about THIS week's events / NEXT week's arrivals
             col3.write(f"**Incoming Order (This Week):**\n# {e['incoming_order']}")
             col4.write(f"**Shipment Arriving (Next Week):**\n# {list(e['incoming_shipments'])[0] if e['incoming_shipments'] else 0}")
+
             st.metric("Your Total Cumulative Cost", f"${e['total_cost']:,.2f}")
+            last_week_cost = state['logs'][-1][f"{human_role}.weekly_cost"] if week > 1 and state['logs'] else 0
+            st.metric("Cost Last Week", f"${last_week_cost:,.2f}")
+
 
         st.markdown("---")
         st.header("Your Decision (Step 4)")
-        human_echelon_state = echelons[human_role]
+        human_echelon_state_for_prompt = { # Construct the state needed for the prompt (AFTER arrivals/orders)
+             'name': human_role,
+             'inventory': echelons[human_role]['inventory'] + (list(echelons[human_role]['incoming_shipments'])[0] if echelons[human_role]['incoming_shipments'] else 0), # Opening + Arriving This Week (approx)
+             'backlog': echelons[human_role]['backlog'] + echelons[human_role]['incoming_order'], # Opening + Incoming Order This Week
+             'incoming_order': echelons[human_role]['incoming_order'],
+             'incoming_shipments': echelons[human_role]['incoming_shipments'] # Pass the queue
+        }
+
 
         if state['decision_step'] == 'initial_order':
             with st.form(key="initial_order_form"):
-                st.markdown("#### **Step 4a:** Based on the information available, submit your **initial** order.")
-                # Default initial order to incoming order, or 4 if incoming is 0 initially
-                default_initial = human_echelon_state['incoming_order'] if human_echelon_state['incoming_order'] > 0 else 4
+                st.markdown("#### **Step 4a:** Based on the dashboard, submit your **initial** order to the Factory.")
+                default_initial = echelons[human_role]['incoming_order'] if echelons[human_role]['incoming_order'] > 0 else 4
                 initial_order = st.number_input("Your Initial Order Quantity:", min_value=0, step=1, value=default_initial)
                 if st.form_submit_button("Submit Initial Order & See AI Suggestion", type="primary"):
                     state['human_initial_order'] = int(initial_order)
@@ -463,7 +596,25 @@ else:
 
         elif state['decision_step'] == 'final_order':
             st.success(f"Your initial order was: **{state['human_initial_order']}** units.")
-            prompt_sugg = get_llm_prompt(human_echelon_state, week, state['llm_personality'], state['info_sharing'], echelons)
+            # Prepare all states AFTER arrivals/orders for the full info prompt context
+            all_decision_point_states = {}
+            for name in echelon_order:
+                e_curr = echelons[name]
+                arrived = 0
+                if name == "Factory":
+                     if state['factory_production_pipeline']: arrived = list(state['factory_production_pipeline'])[0] # Peek, don't pop here
+                else:
+                     if e_curr['incoming_shipments']: arrived = list(e_curr['incoming_shipments'])[0] # Peek
+
+                all_decision_point_states[name] = {
+                    'name': name,
+                    'inventory': e_curr['inventory'] + arrived,
+                    'backlog': e_curr['backlog'] + e_curr['incoming_order'],
+                    'incoming_order': e_curr['incoming_order'],
+                    'incoming_shipments': e_curr['incoming_shipments'].copy() if name != "Factory" else deque()
+                }
+
+            prompt_sugg = get_llm_prompt(all_decision_point_states[human_role], week, state['llm_personality'], state['info_sharing'], all_decision_point_states)
             ai_suggestion, _ = get_llm_order_decision(prompt_sugg, f"{human_role} (Suggestion)")
 
             if 'final_order_input' not in st.session_state:
@@ -471,12 +622,12 @@ else:
 
             with st.form(key="final_order_form"):
                 st.markdown(f"#### **Step 4b:** The AI suggests ordering **{ai_suggestion}** units.")
-                st.markdown("Considering the AI's advice, submit your **final** order to end the week.")
+                st.markdown("Considering the AI's advice, submit your **final** order to end the week. (This order will arrive in 3 weeks).")
                 st.number_input("Your Final Order Quantity:", min_value=0, step=1, key='final_order_input')
                 if st.form_submit_button("Submit Final Order & Advance to Next Week"):
                     final_order_value = st.session_state.final_order_input
                     step_game(final_order_value, state['human_initial_order'], ai_suggestion)
-                    del st.session_state.final_order_input
+                    if 'final_order_input' in st.session_state: del st.session_state.final_order_input
                     st.rerun()
 
         st.markdown("---")