Add Context-Aware Customer Support Agent with Langbase (Bottom-Up Learning)

langbase-support-agent/.env.example

@@ -0,0 +1,11 @@
+# Langbase API Key
+# Get your API key from: https://langbase.com/settings
+LANGBASE_API_KEY=your_api_key_here
+
+# Memory Configuration
+# This will be the name of your Memory (knowledge base)
+MEMORY_NAME=support-faq-memory
+
+# Pipe Configuration
+# This will be the name of your AI Agent Pipe
+PIPE_NAME=support-agent-pipe

langbase-support-agent/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment variables
+.env
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Test files
+coverage/
+.nyc_output/

langbase-support-agent/PROJECT-SUMMARY.md

@@ -0,0 +1,263 @@
+# 🎓 Project Summary: Context-Aware Customer Support Agent
+
+## What You've Built
+
+A **fully-functional RAG (Retrieval Augmented Generation) system** built from first principles using Langbase. This isn't a black-box framework - you have complete visibility into every component.
+
+## 📁 Project Overview
+
+```
+langbase-support-agent/
+├── 📚 Core Learning Scripts (Run in Order)
+│   ├── src/1-memory-creation.ts      → Learn: Embeddings, chunking, vector DB
+│   ├── src/2-retrieval-test.ts       → Learn: Semantic search, similarity scores
+│   ├── src/3-pipe-creation.ts        → Learn: System prompts, model selection
+│   └── src/main.ts                   → Learn: Full RAG orchestration
+│
+├── 🧪 Mini-Projects (Hands-on Experiments)
+│   ├── mini-projects/1-personality-swap.ts       → Prompt engineering
+│   ├── mini-projects/2-knowledge-injection.ts    → Dynamic knowledge updates
+│   ├── mini-projects/3-accuracy-tuner.ts         → Retrieval optimization
+│   └── mini-projects/4-multi-format-challenge.ts → Multi-format parsing
+│
+├── 📖 Documentation
+│   ├── README.md           → Comprehensive learning guide
+│   ├── QUICKSTART.md       → 5-minute getting started
+│   └── PROJECT-SUMMARY.md  → This file
+│
+├── 🗄️ Data
+│   └── data/FAQ.txt        → Sample knowledge base (replace with yours!)
+│
+└── ⚙️ Configuration
+    ├── .env.example        → Environment template
+    ├── tsconfig.json       → TypeScript config
+    └── src/config.ts       → Centralized settings
+```
+
+## 🎯 Learning Outcomes
+
+After completing this project, you understand:
+
+### 1. **The Memory Primitive** (Data Layer)
+- ✅ How text is converted to vectors (embeddings)
+- ✅ Why we chunk documents (~500 tokens)
+- ✅ How vector databases enable semantic search
+- ✅ The difference between keyword search and similarity search
+
+**Key insight:** Memory stores MEANING, not just text.
+
+### 2. **The Retrieval Layer** (Logic)
+- ✅ How semantic search finds relevant chunks
+- ✅ What similarity scores mean (0-1 scale)
+- ✅ The precision vs. recall trade-off (top_k tuning)
+- ✅ Why retrieval quality is critical for answer accuracy
+
+**Key insight:** If retrieval fails, the LLM can't help you.
+
+### 3. **The Pipe Primitive** (Cognition Layer)
+- ✅ How system prompts control AI behavior
+- ✅ Model selection trade-offs (speed vs. quality vs. cost)
+- ✅ Temperature's effect on output consistency
+- ✅ How Memory attaches to Pipe for automatic RAG
+
+**Key insight:** Separate knowledge (Memory) from behavior (Pipe).
+
+### 4. **RAG Architecture** (Orchestration)
+- ✅ The full pipeline: Query → Embed → Retrieve → Inject → Generate
+- ✅ Where costs come from (embeddings + LLM tokens)
+- ✅ Why RAG beats fine-tuning for knowledge updates
+- ✅ How to debug when answers are wrong
+
+**Key insight:** RAG is just well-orchestrated primitives, not magic.
+
+## 🚀 Quick Start Reminder
+
+```bash
+# 1. Install
+npm install
+
+# 2. Configure (add your API key)
+cp .env.example .env
+# Edit .env with your Langbase API key
+
+# 3. Build component-by-component
+npm run memory:create    # Create knowledge base
+npm run retrieval:test   # Test semantic search
+npm run pipe:create      # Create AI agent
+
+# 4. Run!
+npm run dev              # Interactive mode
+npm run dev "Your question here"  # Single query
+```
+
+## 🧪 Recommended Learning Path
+
+### Week 1: Understand the Fundamentals
+1. **Day 1-2:** Run and study the 4 core scripts
+   - Read every comment
+   - Watch the console output
+   - Understand the flow
+
+2. **Day 3-4:** Complete Mini-Project 1 & 2
+   - Personality Swap (understand prompts)
+   - Knowledge Injection (understand RAG flexibility)
+
+3. **Day 5-7:** Complete Mini-Project 3 & 4
+   - Accuracy Tuner (optimize retrieval)
+   - Multi-Format (test different file types)
+
+### Week 2: Customize & Experiment
+1. **Replace the knowledge base** with your own docs
+2. **Modify the system prompt** for your use case
+3. **Tune top_k** for your specific queries
+4. **Test different models** (GPT-4, Claude, etc.)
+5. **Add conversation history** (multi-turn chat)
+
+### Week 3+: Build Something Real
+Ideas:
+- **Internal docs chatbot** for your company
+- **Customer support bot** for your product
+- **Research assistant** for your domain
+- **Code documentation helper**
+- **Personal knowledge management** system
+
+## 💡 Key Architectural Insights
+
+### Why This Design Works
+
+1. **Modularity**
+   ```
+   Memory ←→ Pipe
+   (Data)   (Logic)
+   ```
+   - Change knowledge → update Memory only
+   - Change behavior → update Pipe only
+   - No tight coupling!
+
+2. **Cost Efficiency**
+   - Only retrieve what you need (top_k)
+   - Cache common queries
+   - Pay per use, not per retrain
+
+3. **Transparency**
+   - Debug mode shows retrieved chunks
+   - You can see exactly what the LLM sees
+   - No black boxes
+
+4. **Scalability**
+   - Add more documents → just upload them
+   - Add more capabilities → create new Pipes
+   - Same Memory, different Pipes for different personas
+
+## 🎨 Customization Guide
+
+### Easy Customizations (< 5 minutes)
+- **Change personality:** Edit system prompt in `src/3-pipe-creation.ts`
+- **Change knowledge:** Replace `data/FAQ.txt` with your docs
+- **Change retrieval:** Adjust `topK` in `src/config.ts`
+- **Change model:** Set `model` in `src/config.ts`
+
+### Medium Customizations (30 minutes)
+- **Add conversation history:** Store previous messages in `main.ts`
+- **Add multiple Memories:** Attach 2+ Memories to one Pipe
+- **Add output formatting:** Modify system prompt for JSON/structured output
+- **Add query classification:** Route different queries to different Pipes
+
+### Advanced Customizations (2+ hours)
+- **Implement re-ranking:** Use second model to re-rank chunks
+- **Add hybrid search:** Combine semantic + keyword search
+- **Build agent workflows:** Chain multiple Pipes together
+- **Add feedback loops:** Collect user ratings, retrain retrieval
+
+## 📊 Performance Tuning Cheat Sheet
+
+### For Better Accuracy
+- ✅ Increase `topK` (more context)
+- ✅ Improve document quality (clearer, more comprehensive)
+- ✅ Add more relevant documents
+- ✅ Use a better model (GPT-4 vs GPT-3.5)
+- ✅ Improve system prompt clarity
+
+### For Lower Cost
+- ✅ Decrease `topK` (fewer chunks)
+- ✅ Use cheaper model (GPT-3.5 vs GPT-4)
+- ✅ Reduce `maxTokens` in responses
+- ✅ Cache common queries
+- ✅ Filter chunks by similarity threshold
+
+### For Faster Responses
+- ✅ Use faster model (GPT-3.5-turbo)
+- ✅ Decrease `topK`
+- ✅ Reduce `maxTokens`
+- ✅ Implement streaming responses
+- ✅ Add response caching
+
+## 🐛 Common Issues & Solutions
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| **Generic answers** | Retrieval failed | Check chunks in debug mode |
+| **Wrong answers** | Wrong chunks retrieved | Add better docs, tune top_k |
+| **Slow responses** | Too many chunks | Reduce top_k, use faster model |
+| **High costs** | Too many tokens | Reduce top_k, maxTokens |
+| **Inconsistent tone** | High temperature | Lower temperature to 0.0-0.3 |
+| **No chunks found** | Query mismatch | Rephrase question, add docs |
+
+## 🎓 Next Level: Advanced Concepts
+
+Once you master this project, explore:
+
+1. **Agentic RAG**
+   - Let the agent decide WHEN to retrieve
+   - Implement tool calling (retrieve, calculate, search web)
+
+2. **Multi-Step Reasoning**
+   - Chain-of-thought prompting
+   - Query decomposition (break complex questions into sub-questions)
+
+3. **Advanced Retrieval**
+   - Hypothetical document embeddings (HyDE)
+   - Parent-child chunking
+   - Metadata filtering
+
+4. **Production Hardening**
+   - Rate limiting
+   - Error recovery
+   - Monitoring & logging
+   - A/B testing different configurations
+
+## 🌟 What Makes This Project Special
+
+Unlike tutorials that give you a working system, this teaches you:
+- **WHY** each component exists
+- **HOW** they work together
+- **WHEN** to use different configurations
+- **WHERE** things can go wrong
+
+You're not just copy-pasting code - you're building understanding from first principles.
+
+## 🤝 Share Your Work
+
+Built something cool with this? Share it!
+- Add your use case to the examples
+- Contribute improvements via PR
+- Help others in discussions
+
+## 📚 Further Reading
+
+- [Langbase Documentation](https://langbase.com/docs)
+- [RAG Paper (Original)](https://arxiv.org/abs/2005.11401)
+- [Vector Databases Explained](https://www.pinecone.io/learn/vector-database/)
+- [Prompt Engineering Guide](https://www.promptingguide.ai/)
+
+---
+
+**Congratulations!** 🎉
+
+You've completed a comprehensive journey through RAG architecture. You now understand how modern AI agents work under the hood.
+
+**Remember:** The best way to learn is to BUILD. Start customizing this for your own use case today!
+
+---
+
+*Built with ❤️ for developers who refuse to treat AI as a black box.*