update README.md to enhance clarity and structure, emphasizing the principles of context engineering and providing detailed usage instructions for the visualizer

README.md

@@ -1,505 +1,461 @@
 # Context Engineering Visualizer
 
-A visual demonstration of **context engineering** principles in LLM-based agents. This project shows how information flows into an agent's context window before inference, making the abstract concept of "context engineering" concrete and understandable.
+A professional educational tool that demonstrates how information flows into an AI agent's context window before inference. Built with LangChain and Gradio.
 
-## What is Context Engineering?
+> **Context engineering is the practice of deliberately deciding what information an AI model sees, when it sees it, and in what format.**
 
-**Context engineering** is the practice of deliberately deciding:
+## What Is Context Engineering?
 
-- **What information** an AI model sees
-- **When** it sees it
-- **In what format** it's presented
+Most developers only focus on prompt engineering (optimizing the wording of queries). But the real power comes from **context engineering**: designing the entire information flow into your model.
 
-Unlike prompt engineering (which focuses on *how you ask*), context engineering shapes *what the model understands*.
+### Context Engineering vs. Prompt Engineering
 
-## Features
+| Aspect             | Prompt Engineering | Context Engineering       |
+| ------------------ | ------------------ | ------------------------- |
+| **Focus**    | Wording            | Information flow          |
+| **Scope**    | Single message     | Entire system             |
+| **Strategy** | Optimize phrasing  | Optimize context assembly |
+| **Tools**    | Text tricks        | RAG, memory, tools        |
 
-This visualizer demonstrates the **5 key context layers**:
+Think of it this way:
 
-1. 🎯 **System Instructions** - Stable behavioral guidelines
-2. 💬 **Conversation History** - Short-term memory with smart truncation
-3. 📚 **Retrieved Knowledge (RAG)** - Relevant documents from vector store
-4. 📝 **User Query** - Current user intent
-5. 🔧 **Available Tools** - External capabilities the agent can use
+> **Prompt engineering shapes how you ask. Context engineering shapes what the model understands.**
 
-## Project Structure
+## What Goes Into "Context"?
 
-```
-context-engineering-visualizer/
-├── main.py              # Main application with agent and visualizer
-├── pyproject.toml       # Dependencies (uv package manager)
-├── README.md           # This file
-└── .env                # Your OpenAI API key (create from .env.example)
-```
+When you call an LLM, you're not just sending a prompt. You're sending a **multi-layered context window**:
 
-## Installation
+1. **System Instructions**: Stable behavioral guidelines
+2. **Conversation History**: Recent interactions for continuity
+3. **Retrieved Knowledge (RAG)**: Relevant documents from a knowledge base
+4. **User Query**: The current question or request
+5. **Available Tools**: External functions the agent can use
 
-### 1. Clone & Setup
+Most developers only optimize layer #4 (the user query). **Context engineering optimizes all five layers.**
 
-```bash
-# Make sure you have Python 3.12+ installed
-python --version
-
-# Install uv if you haven't (fast Python package manager)
-pip install uv
-```
+## The Four Principles of Context Engineering
 
-### 2. Install Dependencies
+### 1. Relevance: Only Include What Helps
 
-```bash
-# Using uv (recommended)
-uv sync
+```python
+# Bad: Dump everything
+docs = vectorstore.get_all_documents()  # 1000+ docs, 50k tokens
 
-# Or using pip
-pip install -e .
+# Good: Retrieve top-k relevant
+docs = retriever.invoke(query, k=2)  # 2 docs, ~100 tokens
 ```
 
-### 3. Set Up API Key
+More context ≠ better answers. Noise hurts performance and costs money.
 
-Create a `.env` file in the project root:
+### 2. Structure: Organize Information Clearly
 
-```bash
-OPENAI_API_KEY=your-api-key-here
-```
-
-Get your API key from: https://platform.openai.com/api-keys
+```python
+# Bad: Mix everything together
+context = f"{system_prompt} {docs} {history} {query} {tools}"
 
-## Usage
+# Good: Clear layers
+context = f"""System Instructions:
+{system_prompt}
 
-### Demo Mode (Recommended First)
+Conversation History:
+{history}
 
-Run pre-built scenarios to see context engineering in action:
+Retrieved Knowledge:
+{docs}
 
-```bash
-python main.py
+Current Question:
+{query}"""
 ```
 
-This will walk you through 3 scenarios:
+Models perform better when they can distinguish between different types of information.
 
-1. RAG-based query
-2. Query requiring tool use
-3. Query using conversation context
+### 3. Timing: Retrieve Information When Needed
 
-### Interactive Mode
-
-Chat with the agent and see real-time context visualization:
-
-```bash
-python main.py interactive
+```python
+# Bad: Pre-load everything
+def __init__(self):
+    self.all_docs = load_entire_database()  # Loaded once
+  
+# Good: Dynamic retrieval
+def process_query(self, query: str):
+    docs = self.retriever.invoke(query)  # Retrieved per-query
 ```
 
-### Example Queries to Try for the interactive mode
+Don't front-load information. Fetch what you need, when you need it.
 
-**Basic Knowledge Questions:**
+### 4. Consistency: Use Stable Patterns
 
-- "What is Net Revenue?"
-- "What is Average Order Value?"
-- "Explain Customer Lifetime Value"
-- "What's the difference between gross and net revenue?"
-- "What is churn rate?"
-
-**Tool Usage (Calculations):**
+```python
+# Stable system prompt
+self.system_prompt = "You are a data analyst assistant..."
+
+# Predictable temperature
+self.llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)
+
+# Reusable context assembly
+def assemble_context(self, query):
+    return {
+        "system": self.system_prompt,
+        "history": self.memory.get_recent(n=4),
+        "knowledge": self.retrieve(query, k=2),
+        "query": query
+    }
+```
 
-- "Calculate AOV if revenue is $100000 and orders are 2000"
-- "Calculate conversion rate with 500 conversions from 10000 visitors"
-- "Calculate churn rate if 50 out of 1000 customers left"
-- "What time is it?"
+Consistency reduces randomness and improves reliability.
 
-**Using Conversation Context:**
+## Features
 
-- Ask: "What is AOV?"
-- Then: "Can you calculate it for $50000 revenue and 500 orders?"
-- Then: "What about with 750 orders?" ← *Uses previous context!*
+This visualizer demonstrates all four principles in action:
 
-**Complex Queries:**
+- **Interactive Chat Interface**: Clean, modern chatbot UI with conversation history
+- **Visual Context Breakdown**: Custom stacked container visualization showing proportional token distribution
+- **RAG Integration**: Demonstrates retrieval-augmented generation with a knowledge base
+- **Conversation Memory**: Smart truncation of conversation history
+- **Tool Usage**: Shows how agents use external tools for calculations
+- **Real-time Token Tracking**: See exactly how tokens are distributed across context layers
+- **Collapsible Sidebar**: Settings and example questions in an easy-to-access sidebar
 
-- "I have $80000 in revenue from 1200 orders. What's my AOV and is it good?"
-- "Calculate churn rate if 120 out of 2400 customers left, and explain what it means"
+## Project Structure
 
-## What Makes This "Context Engineering"?
+```
+context-engineering-visualizer/
+├── app/
+│   ├── __init__.py
+│   ├── agent.py          # Main agent implementation
+│   ├── visualizer.py     # Context visualization logic
+│   ├── memory.py         # Conversation memory management
+│   ├── knowledge.py      # RAG knowledge base
+│   ├── tools.py          # Agent tools
+│   └── ui.py             # Gradio interface
+├── config/
+│   ├── __init__.py
+│   └── settings.py       # Application configuration
+├── main.py               # Entry point
+├── pyproject.toml
+└── README.md
+```
 
-### NOT Just Prompt Engineering
+## Installation
 
-```python
-# Prompt engineering
-prompt = "Calculate AOV using this formula..."
+1. Clone the repository:
 
-# Context engineering
-context = {
-    system: "You are a data analyst...",
-    history: [last_4_messages],
-    knowledge: retrieve_relevant(query),
-    query: user_question,
-    tools: [calculate_metric, get_time]
-}
+```bash
+git clone https://github.com/mcikalmerdeka/context-engineering-visualizer
+cd context-engineering-visualizer
 ```
 
-### The Key Difference
+2. Install dependencies using uv:
 
-| Aspect             | Prompt Engineering | Context Engineering       |
-| ------------------ | ------------------ | ------------------------- |
-| **Focus**    | Wording            | Information flow          |
-| **Scope**    | Single message     | Entire system             |
-| **Strategy** | Optimize phrasing  | Optimize context assembly |
-| **Tools**    | Text tricks        | RAG, memory, tools        |
+```bash
+uv sync
+```
 
-## How It Works
+3. Create a `.env` file with your OpenAI API key:
 
-### Context Engineering Principles Demonstrated
+```
+OPENAI_API_KEY=your_api_key_here
+```
 
-#### 1. **Relevance**
+## Usage
+
+Run the Gradio application:
 
-- Only retrieves top 2 most relevant documents (not entire knowledge base)
-- Keeps only last 4 conversation messages (prevents context bloat)
-- Each layer serves a specific purpose
+```bash
+python main.py
+```
 
-#### 2. **Structure**
+The interface will launch at `http://127.0.0.1:7860`
 
-- Clear separation between system instructions and data
-- Structured format: Context → History → Query
-- Models perform better with organized information
+## Interface Overview
 
-#### 3. **Timing**
+The Gradio interface features:
 
-- Knowledge retrieved *after* user query (not preloaded)
-- History summarized *before* sending to model
-- Tools called only when needed
+1. **Collapsible Sidebar**: Contains settings and sequential example questions organized by scenario
+2. **Chat Interface**: Main conversation area with user messages on the right, assistant on the left
+3. **Context Window Breakdown**: Visual stacked container showing proportional token distribution
+4. **Detailed Layer Contents**: Expandable section with full content of each context layer
 
-#### 4. **Consistency**
+### Visual Context Breakdown
 
-- Stable system prompt across all interactions
-- Low temperature (0) for predictable behavior
-- Reusable context assembly pattern
+The visualizer uses a custom stacked container visualization (similar to a database cylinder) where each layer's height is proportional to its token usage. When you ask a question, you'll see:
 
-### Common Patterns You'll Notice
+- **System Instructions** (Blue): Stable behavioral guidelines
+- **Conversation History** (Purple): Recent messages for context
+- **Retrieved Knowledge** (Green): Relevant documents from RAG
+- **User Query** (Orange): Your current question
+- **Available Tools** (Red): Functions the agent can call
 
-**Pattern 1: Relevance Filtering**
+Each section displays:
 
-- Doesn't send all 8 knowledge documents
-- Only sends top 2 relevant ones
-- Saves tokens, improves focus
+- Layer name and purpose
+- Token count and percentage
+- Proportional visual representation
 
-**Pattern 2: Smart Truncation**
+Notice what's happening:
 
-- Conversation history limited to 4 messages
-- Keeps recent context
-- Prevents token overflow
+- Only **2 relevant documents** retrieved (not the entire knowledge base)
+- **Clear separation** between instructions, data, and query
+- **Token-efficient** design
+- **Tools available** but only called when needed
 
-**Pattern 3: Layer Separation**
+The model receives exactly what it needs, no more, no less.
 
-- Instructions ≠ Data ≠ Query
-- Clear boundaries help model
-- Structured input → better output
+### Scenario Examples
 
-**Pattern 4: Dynamic Retrieval**
+The interface includes four sequential scenarios in the sidebar to help you understand context engineering:
 
-- Knowledge fetched per-query
-- Not pre-loaded
-- Timing matters
+**Scenario 1: Understanding AOV (Average Order Value)**
 
-### Understanding the Context Layers
+1. What is Average Order Value and how is it calculated?
+2. Calculate the AOV if total revenue is $50000 and we had 500 orders
+3. What if we had 700 orders with the same revenue instead?
 
-**1. System Instructions (Stable)**
+**Scenario 2: Conversion Rate Analysis**
 
-- Same every time
-- Defines agent behavior
-- Sets output style
+1. What is Conversion Rate?
+2. Calculate conversion rate with 250 conversions and 10000 visitors
+3. How would the rate change if we got 400 conversions?
 
-**2. Conversation History (Dynamic)**
+**Scenario 3: Understanding Revenue Metrics**
 
-- Last 4 messages only
-- Prevents context bloat
-- Enables follow-up questions
+1. What is the difference between gross and net revenue?
+2. If gross revenue is $100000 with $15000 in refunds and $5000 in discounts, what's the net revenue?
 
-**3. Retrieved Knowledge (Relevant)**
+**Scenario 4: Churn Rate**
 
-- Top N similar documents
-- Retrieved via semantic search
-- Based on current query
+1. Explain what Churn Rate means
+2. Calculate churn rate if we lost 50 customers out of 1000 total customers
 
-**4. User Query (Current)**
+These scenarios demonstrate:
 
-- Your actual question
-- Fresh every time
+- **RAG retrieval**: Fetching relevant knowledge
+- **Tool usage**: Calling calculation functions
+- **Context awareness**: Using conversation history for follow-up questions
 
-**5. Available Tools (Capabilities)**
+The third question in each scenario showcases context engineering - the agent understands follow-ups because we engineered the context to include relevant history.
 
-- Functions agent can call
-- Descriptions help model decide
-- Executed when needed
+## Using the Interface
 
-### Visualization Output
+1. **Open the sidebar** to see settings and example questions
+2. **Enable/disable context visualization** using the checkbox
+3. **Follow the sequential scenarios** to understand how context engineering works
+4. **Ask your own questions** about business metrics
+5. **Expand the Context Window Breakdown** to see the visual token distribution
+6. **View detailed layer contents** by expanding the nested accordion
 
-Each query shows:
+The interface is designed to be educational - each interaction shows you exactly how the context is assembled before being sent to the model.
 
-```
-================================================================================
-CONTEXT WINDOW VISUALIZATION
-================================================================================
-
-1. SYSTEM INSTRUCTIONS
-   Tokens: 45 (15.2%)
-   [███████                                           ]
-   Content:
-   You are a data analyst assistant...
-
-2. CONVERSATION HISTORY
-   Tokens: 67 (22.6%)
-   [███████████                                       ]
-   Content:
-   User: What is AOV?...
-
-3. RETRIEVED KNOWLEDGE (RAG)
-   Tokens: 89 (30.1%)
-   [███████████████                                   ]
-   Content:
-   - AOV (Average Order Value) is calculated...
-
-4. USER QUERY
-   Tokens: 32 (10.8%)
-   [█████                                             ]
-   Content:
-   Calculate AOV if revenue is $50000...
-
-5. AVAILABLE TOOLS
-   Tokens: 63 (21.3%)
-   [██████████                                        ]
-   Content:
-   - calculate_metric: Calculate a business metric...
-
-================================================================================
-TOTAL CONTEXT TOKENS: 296
-================================================================================
-```
+## Common Context Engineering Mistakes
 
-**Understanding the Token Bar:**
+### Mistake 1: Dumping Entire Documents
 
-```
-[███████████████                                   ]
+```python
+# Don't do this
+context = "\n".join(all_documents)  # 50,000 tokens
 ```
 
-- Shows percentage of total context
-- Longer bar = more tokens
-- Helps visualize context budget
+**Fix:** Use semantic search to retrieve only top-k relevant chunks.
 
-## Architecture & Information Flow
+### Mistake 2: Sending Full Chat History
 
-### Context Engineering Flow
-
-```mermaid
-graph TD
-    A["User Input: Calculate AOV for my data"] --> B["Context Engineering Layer"]
-  
-    B --> C1["1. System Instructions"]
-    B --> C2["2. Conversation History"]
-    B --> C3["3. Retrieved Knowledge RAG"]
-    B --> C4["4. User Query"]
-    B --> C5["5. Available Tools"]
-  
-    C1 --> D["System Instructions:<br/>You are a data analyst assistant<br/>Use provided context to answer<br/>Always explain reasoning"]
-  
-    C2 --> E["Last 4 Messages Only<br/>Smart Truncation"]
-    E --> F["User: What is gross revenue?<br/>AI: Gross revenue is total sales..."]
-  
-    C3 --> G["Vector Store FAISS"]
-    G -->|"Semantic Search"| H["Top 2 Relevant Documents:<br/>AOV = revenue / orders<br/>Net Revenue = gross - refunds"]
-  
-    C4 --> I["Current Question:<br/>Calculate AOV for my data"]
-  
-    C5 --> J["Tools:<br/>calculate_metric<br/>get_current_time"]
-  
-    D --> K["Assembled Context"]
-    F --> K
-    H --> K
-    I --> K
-    J --> K
-  
-    K --> L["Language Model<br/>GPT-4.1-mini"]
-    L -->|"Complete context with<br/>clear structure"| M["Inference / Reasoning"]
-  
-    M --> N["Agent Response"]
-    N --> O["Based on definition, AOV is<br/>calculated as total revenue<br/>divided by number of orders<br/>Calls calculate_metric tool<br/>Result: AOV = 66.67"]
+```python
+# Don't do this
+history = self.all_messages  # Entire conversation since session start
 ```
 
-### Context Engineering Principles
+**Fix:** Smart truncation (last N messages) or summarization.
 
-**1. Relevance (What to Include)**
+### Mistake 3: Mixing Instructions with Data
 
+```python
+# Don't do this
+prompt = f"You're a helpful assistant. Here's data: {data}. User asks: {query}"
 ```
-❌ BAD: Dump entire knowledge base (1000+ docs, 10,000 tokens)
-✅ GOOD: Retrieve top-2 most relevant docs (200 tokens)
 
-Token Savings: 10,000 → 200 tokens (50x reduction!)
-```
+**Fix:** Separate system instructions, data, and query into distinct layers.
 
-**2. Structure (How to Organize)**
+### Mistake 4: Static Context
 
+```python
+# Don't do this
+self.context = load_all_context()  # Loaded once, used forever
 ```
-❌ BAD: "You are helpful. User said X. Documents say Y. Calculate Z."
-✅ GOOD: Clear layers with separation:
-         System Instructions: [...]
-         Conversation History: [...]
-         Retrieved Knowledge: [...]
-         Current Query: [...]
-```
-
-**3. Timing (When to Retrieve)**
 
-```
-Timeline:
-1. User asks question
-2. Retrieve relevant knowledge (not before!)
-3. Fetch conversation history
-4. Assemble context
-5. Send to model
-
-⚠️ Don't pre-load all possible context!
-```
+**Fix:** Assemble context dynamically per query.
 
-**4. Consistency (Stable Patterns)**
+### Mistake 5: Ignoring Token Costs
 
-```
-✓ Same system prompt every time → predictable behavior
-✓ Low temperature (0) → consistent responses
-✓ Fixed context structure → reliable reasoning
+```python
+# Don't do this
+# (No awareness of context size or cost)
 ```
 
-### Token Efficiency Comparison
+**Fix:** Track token counts per layer. Visualize distribution. Optimize.
 
-| Approach                           | Total Tokens | Breakdown                                                                                       | Cost per Query | Performance                    |
-| ---------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | -------------- | ------------------------------ |
-| **Bad Context Engineering**  | 15,000       | All docs: 12,000``Full history: 2,000``System+Query: 1,000                        | $0.15          | Model struggles with noise     |
-| **Good Context Engineering** | 500          | System: 50``Last 4 msgs: 150``Top-2 docs: 200``Query: 50``Tools: 50 | $0.005         | Model focuses, performs better |
+## Code Architecture
 
-**Result: 30x cheaper + better performance!**
+### The Agent
 
-## Code Highlights
-
-### Agent Architecture
+The main agent assembles context layer by layer:
 
 ```python
 class ContextEngineeringAgent:
-    def __init__(self):
-        self.llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)
-        self.knowledge_base = KnowledgeBase()  # RAG component
-        self.memory = ConversationMemory()      # History management
-        self.visualizer = ContextVisualizer()   # Visualization
-        self.agent = create_agent(
-            model=self.llm,
-            tools=[calculate_metric, get_current_time],
-            system_prompt=self.system_prompt
-        )
-```
-
-### Context Assembly
-
-The key insight is **explicit context construction** before inference:
-
-```python
-context_message = f"""Context from Knowledge Base:
-{retrieved_context}
+    def process_query(self, user_query: str):
+        # Layer 1: System instructions (stable)
+        # Layer 2: Conversation history (recent only)
+        history_text = self.memory.get_history_text()
+    
+        # Layer 3: Retrieved knowledge (top-2 relevant)
+        retrieved_docs = self.knowledge_base.retrieve_relevant(user_query)
+    
+        # Layer 4: User query
+        # Layer 5: Tools (automatically handled by agent)
+    
+        # Assemble with clear structure
+        context_message = f"""Context from Knowledge Base:
+{retrieved_docs}
 
 Previous Conversation:
 {history_text}
 
 Current Question:
 {user_query}"""
-
-result = self.agent.invoke({
-    "messages": [{"role": "user", "content": context_message}]
-})
+    
+        return self.agent.invoke({"messages": [{"role": "user", "content": context_message}]})
 ```
 
-## Technologies Used
+### The RAG Component (Relevance in Action)
 
-- **LangChain** - Agent framework
-- **OpenAI GPT-4.1-mini** - Language model
-- **FAISS** - Vector store for RAG
-- **OpenAI Embeddings** - Text embeddings
-- **Python 3.12+** - Programming language
+```python
+class KnowledgeBase:
+    def __init__(self):
+        # 8 documents total, but only retrieve top 2
+        self.documents = [
+            "AOV = total revenue / number of orders",
+            "Net Revenue = gross revenue - refunds - discounts",
+            # ... more documents
+        ]
+    
+        # Retriever with k=2 (only top 2 docs)
+        self.retriever = self.vectorstore.as_retriever(search_kwargs={"k": 2})
+```
 
-## Common Context Engineering Mistakes (That This Avoids)
+We have 8 documents, but only send the **top 2 most relevant** to the model. This is context engineering in action.
 
-❌ **Dumping entire documents** → ✅ Retrieve only top-k relevant chunks
-❌ **Sending full chat history** → ✅ Smart truncation to recent messages
-❌ **Mixing instructions with data** → ✅ Clear layer separation
-❌ **No token awareness** → ✅ Token estimation and visualization
-❌ **Static context** → ✅ Dynamic retrieval based on query
+### The Memory Component (Smart Truncation)
 
-## Troubleshooting
+```python
+class ConversationMemory:
+    def __init__(self, max_messages: int = 4):
+        self.messages = []
+        self.max_messages = max_messages
+  
+    def _truncate(self):
+        if len(self.messages) > self.max_messages:
+            self.messages = self.messages[-self.max_messages:]
+```
 
-### "ModuleNotFoundError"
+We limit history to 4 messages. For longer conversations, this prevents context overflow while maintaining relevant continuity.
 
-```bash
-# Install dependencies
-uv sync
-# or
-pip install -e .
-```
+**Note:** There are several approaches to handle conversation history when it becomes too long:
 
-### "OpenAI API Error"
+- **Trimming**: Keep only the most recent N messages (used here)
+- **Summarization**: Compress older messages into summaries
+- **Deletion**: Permanently remove certain states
+- More info: [LangChain Memory Documentation](https://docs.langchain.com/oss/python/concepts/memory)
 
-- Check `.env` file exists
-- Verify API key is correct
-- Ensure key starts with `sk-`
+## Configuration
 
-### "RateLimitError"
+Edit `config/settings.py` to customize:
 
-- You've hit OpenAI rate limit
-- Wait a moment and try again
-- Consider upgrading OpenAI plan
+```python
+class Settings:
+    # Model settings
+    MODEL_NAME = "gpt-4.1-mini"
+    TEMPERATURE = 0
+  
+    # Memory settings
+    MAX_CONVERSATION_MESSAGES = 4
+  
+    # RAG settings
+    RAG_TOP_K = 2
+  
+    # UI settings
+    GRADIO_SERVER_PORT = 7860
+```
 
-### No output shown
+## How to Practice Context Engineering
 
-- Check API key has credits
-- Verify internet connection
-- Look for error messages
+### 1. Inspect Your Token Usage
 
-## Tips for Best Results
+```python
+def count_tokens(text: str) -> int:
+    # Simple estimate: ~4 chars per token
+    return len(text) // 4
+
+print(f"Context size: {count_tokens(context)} tokens")
+```
 
-### Writing Good Queries
+### 2. Separate Concerns
 
-✅ "Calculate AOV for $50000 revenue and 500 orders"
-❌ "do the aov thing"
+```python
+# Instead of one blob, create layers
+context = {
+    "system": system_instructions,
+    "history": recent_messages,
+    "knowledge": retrieved_docs,
+    "query": user_question
+}
+```
 
-✅ "What's the difference between gross and net revenue?"
-❌ "revenue?"
+### 3. Experiment with Context Size
 
-### Follow-up Questions
+```python
+# Try different values
+retriever = vectorstore.as_retriever(search_kwargs={"k": k})
+# Test k=1, k=2, k=5, k=10
+# Measure: quality vs. cost vs. latency
+```
 
-After asking about a metric:
+### 4. Treat Context as First-Class
 
-- "Can you calculate it for my data?"
-- "What about with different numbers?"
-- "Compare that to industry average"
+Don't think of context as "everything I stuff into the prompt." Think of it as a carefully engineered data pipeline with:
 
-### Observing Context Flow
+- **Sources** (RAG, memory, tools)
+- **Filters** (relevance, recency, size)
+- **Transformations** (formatting, structuring)
+- **Quality checks** (token budgets, validation)
 
-Watch how:
+## Key Takeaways
 
-- RAG retrieves different docs per query
-- History accumulates over conversation
-- Tools get called when numbers are involved
-- Token distribution changes
+1. **Context is multi-layered**: It's not just your prompt
+2. **Less is often more**: Relevant beats comprehensive
+3. **Structure matters**: Organization helps models reason
+4. **Dynamic beats static**: Assemble context per-query
+5. **Tokens cost money**: Engineering context saves budget
 
-## Key Insights
+## Why This Matters
 
-1. **Context is multi-layered** - Not just your prompt
-2. **Less is often more** - Relevant beats comprehensive
-3. **Structure matters** - Organization helps models
-4. **Dynamic beats static** - Assemble per-query
-5. **Tokens cost money** - Engineering saves budget
+As AI systems mature, **context design is becoming the main differentiator**:
 
-## Next Steps
+1. **Larger context windows ≠ free intelligence**: A 1M token context window doesn't mean you should use it all
+2. **AI agents depend on state & memory**: Poor context management = inconsistent behavior
+3. **Cost optimization is critical**: Every token costs money
+4. **Reliability > raw capability**: A GPT-3.5 with good context beats GPT-4 with bad context
 
-Want to extend this project?
+## Technologies
 
-- Add token cost tracking ($ per query)
-- Implement context compression techniques
-- Add more sophisticated memory (summarization)
-- Create a web UI with real-time visualization
-- Compare context strategies (with/without RAG, different window sizes)
+- **LangChain**: Agent framework and tools
+- **OpenAI**: Language model (GPT-4.1-mini)
+- **FAISS**: Vector store for RAG
+- **Gradio**: Web interface
+- **Python 3.11+**
 
 ## Contributing
 
-This is a learning/demo project. Feel free to fork and adapt for your own articles or projects!
+This is an educational project designed to help developers understand context engineering. Feel free to:
+
+- Open issues for bugs or suggestions
+- Submit pull requests for improvements
+- Use this as a learning resource for your own projects