1. Purpose & Features
2. Architecture & Repository Structure
3. Getting Started
4. Usage
5. Testing
6. GenAI Teacher Chat Mode
7. Troubleshooting & Codespaces Notes
8. Further Reading

This repository can be used as a starting point for building custom LLM applications using Open Source tooling and models. It incorporates Ollama, Open WebUI, Langchain, Streamlit, Chroma, and PGVector using Docker to containerize the application and Docker Compose to run the various service dependencies.

Key Features:

• LLM integration (Ollama, LangChain)
• RAG (Retrieval Augmented Generation) examples
• Agentic AI patterns (ReAct, multi-tool agents)
• Streamlit web interface
• Vector database support (Chroma, PGVector)
• Integrated teaching assistant (GenAI Teacher)

Main Components:

• src - Application code and examples
• etc - Scripts and configuration
• tests - Unit and integration tests
• Dockerfile, compose.yml - Containerization and orchestration

• Docker Engine installed
  • Option 1: Docker Engine configured with >= 12 GB memory
  • Option 2: Docker Engine configured with >= 8 GB memory and Ollama Executable installed

    brew install ollama

• Register for a free Brave Search API key here
  • 2000 calls/month free, affordable scaling
  • Brave Search API info
• Add your key to a .env file in the project root:

  echo "BRAVE_SEARCH_API_KEY=your_key_here" >> .env

Option 1 (CPU-only, easiest):

docker compose --profile=cpu up -d

Option 2 (GPU, fastest):

docker compose up -d
./etc/ollama_entrypoint.sh

Option 3 (GitHub Codespaces):

1. Open in Codespaces: Click "Code" → "Codespaces" → "Create codespace"
2. Setup environment:

   docker compose --profile=cpu up -d

3. Access the application:
   • Streamlit App: Auto-opens or check "Ports" tab
   • Open WebUI: Available on port 3000

docker compose --profile=cpu up -d      # Start all services
docker compose down                     # Stop all services
docker compose logs -f                  # View service logs
docker compose ps                       # Check service status
docker compose run --rm app pytest tests/ -v   # Run tests

• Streamlit: http://localhost:8501/
• Open WebUI: http://localhost:3000/

• List Ollama Models:

  curl http://localhost:11434/api/tags

• Ollama API Docs

This application includes a comprehensive test suite that runs in Docker for consistency. Unit tests use mocks, while integration tests connect to real services.

# Run all tests
docker compose run --rm app pytest tests/ -v

# Run just unit tests
docker compose run --rm app pytest tests/unit/ -v

# Run integration tests (requires services running)
docker compose run --rm app pytest tests/integration/ -m integration -v

# Run with coverage
docker compose run --rm app pytest tests/ --cov=src --cov-report=term

# Test a specific file
docker compose run --rm app pytest tests/unit/test_app.py -v

# Test a specific class
docker compose run --rm app pytest tests/unit/example/test_simple_chat.py::TestSimpleChat -v

# Test a specific method
docker compose run --rm app pytest tests/unit/test_app.py::TestApp::test_model_selection_logic -v

1. Run the full test suite: docker compose run --rm app pytest tests/ -v
2. Ensure all tests pass before making any changes
3. Update packages incrementally and test after each change

This repository includes an integrated AI teaching assistant accessible through GitHub Copilot Chat. The GenAI Teacher provides personalized guidance for learning LLM, RAG, and Agentic AI patterns.

In any GitHub interface (VS Code, GitHub.com, or GitHub Mobile), use the #genai-teacher chat mode:

#genai-teacher [your question or request]

Get detailed explanations of demo files and concepts:

#genai-teacher explain simple_chat.py
#genai-teacher explain RAG patterns
#genai-teacher explain the ReAct agent pattern

Receive structured learning guidance through topics:

#genai-teacher guide me through RAG
#genai-teacher guide me through the basics
#genai-teacher guide me through agent development

Get personalized learning progressions:

#genai-teacher learning path for beginners
#genai-teacher learning path for RAG
#genai-teacher learning path for agents

Get help implementing new features:

#genai-teacher how to create a new RAG example
#genai-teacher implement a custom retriever
#genai-teacher add error handling to my chain

Beginner Starting Point:

#genai-teacher guide me through the basics

Understanding a Specific File:

#genai-teacher explain src/example/agentic_chat.py

Getting Implementation Help:

#genai-teacher how to add a new vector database example

The GenAI Teacher understands the repository structure, coding patterns, and can provide context-aware guidance tailored to your current learning needs.

• CPU-Only: Codespaces uses CPU-only mode (no GPU acceleration)
• Model Loading: Initial model downloads may take 5-10 minutes
• Port Forwarding: All ports are automatically forwarded and accessible via HTTPS
• Persistence: Your workspace persists across sessions

For the web search example, add your API key to the .env file:

echo "BRAVE_SEARCH_API_KEY=your_key_here" >> .env
docker compose up -d
./etc/ollama_entrypoint.sh

• Ollama - Open source app for LLM models, prompts, tools, and functions
  • Website: https://ollama.com/
  • Github: https://github.com/ollama/ollama
• Open WebUI - Web UI wrapper for Ollama
  • Website: https://openwebui.com/
  • Github: https://github.com/open-webui/open-webui
• RAG
  • Retrieval Augmented Generation Article
• LangChain
  • Website: https://python.langchain.com/docs/get_started/introduction
• Hugging Face
  • Website: https://huggingface.co/
  • LangChain Hugging Face Support
• Chroma
  • Website: https://www.trychroma.com/
  • LangChain Chroma Support
• PGVector
  • Website: https://github.com/pgvector/pgvector
  • LangChain PGVector Support
• Wikipedia
  • Website: https://wikipedia.org
  • LangChain Wikipedia Support
• Web - Brave API Search Loader
  • Website: https://brave.com/search/api/
  • LangChain BraveSearchLoader Docs
• Arxiv
  • Website: https://arxiv.org/
  • LangChain ArxivRetriever Support