Copilot Instructions

# Copilot Instructions for GenAI Demo Application

This repository demonstrates various LLM/RAG/Agentic AI patterns using LangChain, Ollama, and Streamlit. When working with this codebase, follow these guidelines and understand the established patterns.

## Interactive Teaching Modes

When users ask questions or request help, respond according to these specialized modes:

### 🔍 Explain Mode (`explain` or `@workspace explain [file]`)
When users ask to explain a file or concept:
- **For demo files**: Provide detailed explanation of the example type, key features, and what to focus on
- **For simple_chat.py**: Explain basic LLM integration, ChatOllama, memory, Streamlit interface
- **For RAG examples**: Explain vector storage, document retrieval, context integration, chain composition
- **For agentic_chat.py**: Explain ReAct pattern, tool integration, agent executor, reasoning cycles

### 🎯 Guide Mode (`guide` or `@workspace guide [topic]`)
When users ask for learning guidance:
- **Basics**: Guide through simple_chat.py → city.py → country.py → state.py → mtg.py
- **RAG**: Guide through wikipedia.py → arxiv.py → web.py → chroma.py → pgvector.py  
- **Agents**: Focus on agentic_chat.py, prompts.py, and tool integration patterns

### 🛤️ Learning Path Mode (`path` or `@workspace learning path [type]`)
Provide structured learning progressions:
- **Beginner Path**: Start with basic LLM concepts, move to prompt engineering
- **Intermediate Path**: RAG implementation, vector databases, document processing
- **Advanced Path**: Agent development, tool integration, ReAct patterns

### ❓ Question Mode (general questions about concepts)
For concept questions, provide context-aware answers:
- **Ollama questions**: Explain local hosting, model configuration, integration patterns
- **LangChain questions**: Explain chains, retrievers, agents, memory, prompt templates
- **RAG questions**: Explain retrieval, embedding, vector storage, context integration
- **Agent questions**: Explain ReAct pattern, tool use, reasoning, decision making

### 🔧 Implementation Mode (`how to` or `implement`)
When users want to implement features:
- Provide code examples following established patterns
- Reference existing examples as templates
- Include proper error handling and testing approaches
- Follow the separation of concerns pattern (create_chain, process_query, handle_ui)

## Repository Structure & Architecture

### Core Application
- **`src/app.py`**: Main Streamlit application with example type selection
- **`src/example/`**: Contains all demo implementations organized by complexity
- **`src/internal/`**: Shared utilities and prompt templates
- **`tests/`**: Comprehensive test suite with unit and integration tests

### Example Categories

#### 🌟 Basic Examples (Beginner)
- **`simple_chat.py`**: Basic LLM integration with memory using ChatOllama
- **`city.py`, `country.py`, `state.py`**: Prompt templating and chain composition
- **`mtg.py`**: External API integration with structured output

#### 🔍 RAG Examples (Intermediate)
- **`wikipedia.py`**: Dynamic document retrieval using WikipediaRetriever
- **`arxiv.py`**: Academic paper search and analysis with ArxivRetriever
- **`web.py`**: Real-time web search using BraveSearchLoader
- **`chroma.py`**: Vector storage with ChromaDB for document embeddings
- **`pgvector.py`**: Production PostgreSQL vector storage with PGVector

#### 🤖 Agent Examples (Advanced)
- **`agentic_chat.py`**: Multi-tool ReAct agent with Wikipedia and Arxiv tools

## Key Technical Patterns

### LLM Integration
- **Primary LLM Provider**: Ollama (local hosting)
- **Model Configuration**: Set via `OLLAMA_HOST` environment variable
- **LLM Creation**: Use `internal.util.create_llm(model_name)` for consistency
- **Streaming**: Enabled for real-time responses in Streamlit interface

### RAG Chain Architecture