Update app.py

app.py

@@ -127,10 +127,68 @@ coordinator = CodeAgent(
 
 # --- Gradio UI ---
 with gr.Blocks() as demo:
-    gr.Markdown("""
-    # 🧠 Multi-Agent Thin Film Stack Optimizer
-    This demo simulates an AI agent coordinating spectrum simulations at 10nm and 100nm thickness to match a target.
-    """)
+    gr.Markdown(
+        """
+    # 🧠 Multi-Agent Thin-Film Stack Optimizer (10nm + 100nm RCWA)
+    
+    This interactive demo showcases a **multi-agent AI system** that cooperatively solves an inverse optics problem using physics-based simulation.  
+    Instead of relying on a single agent or a single simulator, the **Coordinator Agent** orchestrates two specialized agents, each tuned to simulate optical spectra for different layer thicknesses (10nm and 100nm), and uses a comparison tool to evaluate results.
+    
+    ---
+    
+    ### 🤖 Objective: Discover the correct layer **order** and **thickness**
+    
+    Given only a target transmission spectrum, the multi-agent system must identify:
+    - The correct **material permutation** (from a fixed set), and
+    - The correct **thickness choice** (10nm or 100nm, uniformly applied)
+    
+    **Constraints:**
+    - Materials: `Si`, `Si₃N₄`, `SiO₂`, `AlN` (used once each)
+    - Layer thickness options: `10nm` or `100nm`
+    - Terminate when `cosine_similarity > 0.999`
+    
+    ---
+    
+    ### 🧬 Agent Architecture Overview
+    
+    - 🧠 **Coordinator Agent** (`CodeAgent | gpt-4.1-mini`):  
+      Receives the target spectrum and is responsible for reasoning, selecting candidates, and delegating simulations to sub-agents.
+    
+    - 🔧 **agent_10nm_simulator**:  
+      Can simulate any material order using **10nm** thick layers via RCWA.
+    
+    - 🔧 **agent_100nm_simulator**:  
+      Can simulate any material order using **100nm** thick layers via RCWA.
+    
+    - 📏 **cosine_similarity tool**:  
+      Measures how close a simulated spectrum is to the target.
+    
+    ---
+    
+    ### 🔍 What’s Happening Under the Hood
+    
+    1. A **random 4-layer stack** is selected from `Si`, `Si₃N₄`, `SiO₂`, `AlN`, and simulated (at 100nm) to serve as the **target spectrum**.
+    2. The **Coordinator Agent** is provided the target and access to two sub-agents:
+        - `agent_10nm_simulator` for 10nm stacks
+        - `agent_100nm_simulator` for 100nm stacks
+    3. It explores permutations + thickness combinations by:
+        - Calling a simulation agent
+        - Comparing simulated output with the target using `cosine_similarity`
+        - Continuing exploration until similarity exceeds threshold
+    4. The system **halts automatically** once the optimal stack is found, and reports:
+        - The matched material order
+        - Thickness value
+        - Number of permutations tried
+    
+    ---
+    
+    ### 📊 Visualization
+    
+    > (Optional) Below: Transmission spectra for all permutations using 100nm layers  
+    Observe how layer order significantly affects optical behavior.
+    """
+    )
+    
     gr.Markdown("""
     CodeAgent | openai/gpt-4.1-mini  
 ├── ✅ Authorized imports: ['numpy']