Update app.py

app.py

@@ -1,5 +1,5 @@
 # app.py
-# @title Beer Game Final Version (v4.8 - Unified Human-Like Prompts)
+# @title Beer Game Final Version (v4.9 - Detailed Intro & Real-time Cost)
 
 # -----------------------------------------------------------------------------
 # 1. Import Libraries
@@ -57,7 +57,7 @@ else:
 
 
 # -----------------------------------------------------------------------------
-# 3. Core Game Logic Functions
+# 3. Core Game Logic Functions (No changes in this section)
 # -----------------------------------------------------------------------------
 
 def get_customer_demand(week: int) -> int:
@@ -115,13 +115,11 @@ def get_llm_order_decision(prompt: str, echelon_name: str) -> (int, str):
             st.error(f"API call failed for {echelon_name}: {e}")
             return 8, f"API_ERROR: {e}"
 
-# =============== MODIFIED FUNCTION (Unified Prompts) ===============
 def get_llm_prompt(echelon_state: dict, week: int, llm_personality: str, info_sharing: str, all_echelons_state: dict) -> str:
     """Generates the prompt for the LLM based on the game scenario."""
     
     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"
     
-    # Define task word and role-specific info
     if echelon_state['name'] == 'Factory':
         task_word = "production quantity"
         base_info += f"- Production pipeline (completing in future weeks): {list(st.session_state.game_state['factory_production_pipeline'])}"
@@ -129,52 +127,39 @@ def get_llm_prompt(echelon_state: dict, week: int, llm_personality: str, info_sh
         task_word = "order quantity"
         base_info += f"- Shipments on the way to you: {list(echelon_state['incoming_shipments'])}\n- Orders you have placed being processed by your supplier: {list(echelon_state['order_pipeline'])}"
 
-    # --- Perfect Rational (Unchanged from last version, logic is correct) ---
     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
-        else:
-            total_lead_time = ORDER_PASSING_DELAY + SHIPPING_DELAY
-        
+        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
+        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']))
         else:
             inv_pos_components = f"(Inv: {echelon_state['inventory']} - Backlog: {echelon_state['backlog']} + In_Transit: {sum(echelon_state['incoming_shipments'])} + In_Pipeline: {sum(echelon_state['order_pipeline'])})"
             inventory_position = (echelon_state['inventory'] - echelon_state['backlog'] + sum(echelon_state['incoming_shipments']) + sum(echelon_state['order_pipeline']))
-        
         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':
             supply_line = sum(st.session_state.game_state['factory_production_pipeline'])
             supply_line_desc = "In Production"
         else:
             supply_line = sum(echelon_state['incoming_shipments']) + sum(echelon_state['order_pipeline'])
             supply_line_desc = "Supply Line (In Transit + In Pipeline)"
-
         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."
 
-    # --- Human-like (Unified Prompts as requested) ---
     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"
-        
         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.
@@ -195,7 +180,6 @@ def get_llm_prompt(echelon_state: dict, week: int, llm_personality: str, info_sh
         Your gut instinct is to panic and {task_word.split(' ')[0]} enough to ensure you are never caught with a backlog again.
         **React emotionally.** What is your knee-jerk {task_word}? Respond with a single integer.
         """
-# ===============================================
 
 def step_game(human_final_order: int, human_initial_order: int, ai_suggestion: int):
     # This core logic function remains correct and unchanged.
@@ -316,64 +300,83 @@ else:
     # --- Game Setup & Instructions ---
     if 'game_state' not in st.session_state or not st.session_state.game_state.get('game_running', False):
         
+        # =============== NEW DETAILED INTRODUCTION ===============
         st.markdown("---")
         st.header("📖 Welcome to the Beer Game!")
-        st.markdown("""
-        The Beer Game is a classic supply chain simulation that demonstrates a phenomenon called the **"Bullwhip Effect."** Even with stable customer demand, small variations in orders can amplify as they move up the supply chain, causing massive shortages and overstocks.
-        """)
-        st.subheader("Your Goal")
-        st.markdown("""
-        Minimize the total cost for your position in the supply chain. Costs are incurred for:
-        - **Holding Inventory:** **$0.50 per unit per week**
-        - **Backlog (Unfilled Orders):** **$1.00 per unit per week**
-        """)
+        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.")
 
-        col1, col2 = st.columns(2)
-        with col1:
-            st.subheader("🔗 The Supply Chain")
-            try:
-                st.image(IMAGE_PATH, caption="Orders flow upstream (right), beer flows downstream (left).")
-            except FileNotFoundError:
-                st.warning("Image file not found. Please ensure 'beer_game_diagram.png' is uploaded to the repository.")
+        st.subheader("1. Your Goal: Minimize Costs")
+        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.** (Holding 10 units costs $5.00)
+        - **Backlog (Unfilled Orders):** **${BACKLOG_COST:,.2f} per unit per week.** (Having 5 unfilled orders costs $5.00)
+        """)
+        
+        with st.expander("Click to see a cost calculation example"):
+            st.markdown(f"""
+            Imagine at the end of Week 5, your dashboard shows:
+            - `Current Inventory: 20`
+            - `Current Backlog: 3`
             
-            st.markdown("""
-            You will play the role of the **Distributor**. The other three roles (Retailer, Wholesaler, Factory) will be controlled by AI agents.
-            - **Retailer (AI):** Fulfills end-customer demand. Orders from the Wholesaler.
-            - **Wholesaler (AI):** Fulfills Retailer orders. Orders from the Distributor.
-            - **Distributor (You):** Fulfills Wholesaler orders. Orders from the Factory.
-            - **Factory (AI):** Fulfills your orders. Produces new beer.
+            Your cost for Week 5 would be:
+            - `(20 units of Inventory * ${HOLDING_COST:,.2f})` = $10.00
+            - `(3 units of Backlog * ${BACKLOG_COST:,.2f})` = $3.00
+            - **Total Weekly Cost:** = **$13.00**
+            
+            Your goal is to keep this number as low as possible, every week.
             """)
 
-        with col2:
-            st.subheader("⏳ The Challenge: Delays!")
-            st.markdown(f"""
-            The key challenge is managing the **delays** in our specific game:
+        st.subheader("2. Your Role: The Distributor")
+        st.markdown("""
+        You will always play as the **Distributor**. The other 3 roles are played by AI.
+        
+        - **Retailer (AI):** Sells to the final customer.
+        - **Wholesaler (AI):** Sells to the Retailer.
+        - **Distributor (You):** You sell to the Wholesaler.
+        - **Factory (AI):** You order from the Factory.
+        """)
+        try:
+            st.image(IMAGE_PATH, caption="You are the Distributor. You get orders from the Wholesaler and place orders to the Factory.")
+        except FileNotFoundError:
+            st.warning("Image file not found. Please ensure 'beer_game_diagram.png' is uploaded to the repository.")
             
-            * **Order Delay:** It takes **{ORDER_PASSING_DELAY} week** for your order to reach the Factory.
-            * **Production Delay:** The Factory needs **{FACTORY_LEAD_TIME} week** to produce your order.
-            * **Shipping Delay:** It takes **{FACTORY_SHIPPING_DELAY} week** for the Factory to ship the finished beer to you.
+        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.**")
+        
+        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.
             
-            This means there is a **{ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY}-week total lead time** from when you place an order to when you receive the beer. You must order for what you'll need 3 weeks from now!
+            **Conclusion:** You must always think 3 weeks ahead. The order you place in Week 10 will not help you until Week 13.
             """)
         
-        st.subheader("🎮 How Each Week Works")
-        st.markdown(f"""
-        Your main job is to place an order each week. The system handles the rest.
+        st.subheader("4. The Bullwhip Effect (What to Avoid)")
+        st.markdown("""
+        The "Bullwhip Effect" is the main challenge of this game. It describes how small, normal changes in customer demand (at the Retailer) get **amplified** into huge, chaotic swings in orders as they move up the supply chain.
         
-        **1. Automated Steps (Start of Week)**
-        When a new week begins, the system first automates three steps based on past decisions:
-        * **(Step 1: Shipments Arrive):** Shipments from the Factory (which you ordered {ORDER_PASSING_DELAY + FACTORY_LEAD_TIME + FACTORY_SHIPPING_DELAY} weeks ago) arrive and are added to your inventory.
-        * **(Step 2: New Orders Arrive):** You receive a new incoming order from the Wholesaler.
-        * **(Step 3: Ship Beer):** The system automatically ships as much beer as you have in stock to fulfill the Wholesaler's order, plus any leftover backlog. Any unfulfilled amount becomes your new backlog for next week.
+        This often leads to a cycle of **panic ordering** (ordering way too much because you are out of stock) followed by a **massive pile-up of inventory** (when all your late orders finally arrive). This cycle is extremely expensive. Your goal is to avoid it by ordering smoothly.
+        """)
+
+        st.subheader("5. How Each Week Works (Your Task)")
+        st.markdown(f"""
+        Your main job is simple: place one order each week.
         
-        **2. Your Decision (Two-Step Process)**
-        After the automated steps, you will see your new inventory and backlog. Now, it's your turn to perform **Step 4**:
-        * **(Step 4a):** Based on your new status, submit your **initial order** to the Factory.
-        * **(Step 4b):** After submitting, you will see an **AI suggestion**. Review it, then submit your **final order**.
+        **A) At the start of every week, the system automatically does 3 things:**
+        * **(Step 1) Your Shipments Arrive:** The beer you ordered 3 weeks ago arrives and is added to your `Current Inventory`.
+        * **(Step 2) New Orders Arrive:** You receive a new `Incoming Order` from the Wholesaler.
+        * **(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`).
         
-        Submitting your final order advances the game to the next week, and the cycle repeats.
+        **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.
         """)
-
+        # =======================================================
+        
         st.markdown("---")
         st.header("⚙️ Game Configuration")
         c1, c2 = st.columns(2)
@@ -402,8 +405,13 @@ else:
                     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'])
+                    
+                    # =============== NEW: REAL-TIME COST METRIC ===============
+                    if name == human_role:
+                        st.metric("Your Total Cost", f"${e['total_cost']:,.2f}")
+                    # =========================================================
+                        
                     st.write(f"Incoming Order: **{e['incoming_order']}**")
-
                     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}**")
@@ -419,6 +427,10 @@ else:
             col2.metric("Current Backlog", e['backlog'])
             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}")
+            
+            # =============== NEW: REAL-TIME COST METRIC ===============
+            st.metric("Your Total Cumulative Cost", f"${e['total_cost']:,.2f}")
+            # =========================================================
         
         st.markdown("---")
         st.header("Your Decision (Step 4)")
@@ -488,13 +500,11 @@ else:
         state = st.session_state.game_state
         logs_df = pd.json_normalize(state['logs'])
         
-        # =============== FIXED Typo Bug ===============
         fig = plot_results(
             logs_df, 
             f"Beer Game (Human: {state['human_role']})\n(AI: {state['llm_personality']} | Info: {state['info_sharing']})", 
             state['human_role']
         )
-        # ==============================================
         
         st.pyplot(fig)
         save_logs_and_upload(state)