A hands-on learning repository for understanding Large Language Model (LLM) fundamentals and AI agent development. This project provides interactive demonstrations of core LLM concepts through Azure OpenAI or local models (Ollama) - no API keys required for local usage!

• LLM Fundamentals: Understanding stateless vs stateful interactions
• Token Economics: Real-time token usage tracking and cost awareness
• Azure OpenAI Integration: Practical API usage with the official SDK
• Agent Development: Building from primitives to frameworks

Option A: Azure OpenAI (Cloud)

• Azure OpenAI account and deployment
• API keys required

Option B: Local Models (Free)

• Ollama-based local models
• No API keys required after download
• Models run on your hardware
• Complete privacy - data stays local

The system automatically detects your configuration and uses the appropriate option!

# Using Homebrew (recommended)
brew install [email protected]

# Or download from python.org
# Visit https://www.python.org/downloads/macos/

# Using winget (Windows 10+)
winget install Python.Python.3.12

# Or download from python.org
# Visit https://www.python.org/downloads/windows/

# Add deadsnakes PPA for latest Python versions
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-pip python3.12-venv

# Verify installation
python3.12 --version

# Fedora
sudo dnf install python3.12

# CentOS/RHEL (may need EPEL)
sudo yum install python3.12

# Or compile from source if not available in repos

UV is a fast Python package installer and resolver. Install it with:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

curl -LsSf https://astral.sh/uv/install.sh | sh

For more installation options, visit: UV Installation Guide

# Verify installation
uv --version

1. Clone the repository:

   git clone https://github.com/your-username/ai-tech-coffee-hours.git
   cd ai-tech-coffee-hours

2. Run the setup script:

   python3 setup_workspace.py

3. Configure environment:

   cp .env.example .env
   # Edit .env with your Azure OpenAI credentials (or leave empty for local models)

4. Start learning:

   source .venv/bin/activate  # On macOS/Linux
   # .venv\Scripts\activate   # On Windows
   python main.py

1. Clone the repository:

   git clone https://github.com/your-username/ai-tech-coffee-hours.git
   cd ai-tech-coffee-hours

2. Verify Python and UV installation:

   # Check Python version (should be 3.12+)
   python --version
   # or
   python3 --version
   
   # Check UV installation
   uv --version

3. Create and activate a virtual environment using UV:

   # Create virtual environment
   uv venv
   
   # Activate virtual environment
   # On macOS/Linux:
   source .venv/bin/activate
   
   # On Windows:
   # .venv\Scripts\activate

4. Install dependencies:

   uv pip install -e .

5. Configure environment:

   cp .env.example .env
   # Edit .env with your Azure OpenAI credentials (or leave empty for local models)

6. Run the interactive learning session:

   python main.py

If you don't have Azure OpenAI API keys, you can use local models with Ollama:

macOS:

brew install ollama
# or: curl -fsSL https://ollama.com/install.sh | sh

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download from ollama.com

1. Start Ollama server:

   ollama serve

2. Pull a chat model (choose one):

   # Lightweight option (3B parameters, ~2GB)
   ollama pull llama3.2:3b
   
   # Balanced option (8B parameters, ~4.7GB)  
   ollama pull llama3.2:8b
   
   # High quality option (70B parameters, ~40GB)
   ollama pull llama3.1:70b

3. Pull embedding model (for RAG demos):

   ollama pull nomic-embed-text

4. Verify installation:

   ollama list

The system automatically detects Ollama and uses it when Azure OpenAI credentials are not available!

When you run python main.py, you'll first see a model selection menu:

Available Options:

• Azure OpenAI: Cloud-based models (requires API keys)
• Ollama Models: Local server-based models
• Auto-select: Use automatic detection

Features:

1. Model Selection: Choose your preferred model type and specific model
2. Download Models: Download new Ollama models during runtime
3. Change Models: Switch between different models without restarting
4. Model Information: See model type, size, and capabilities

The application stores your preference for the session and shows which model is being used for each demo.

The main learning experience offers multiple modes:

Experience how LLMs work naturally - each conversation is independent with no memory between exchanges. Perfect for understanding the fundamental stateless nature of language models.

Learn how LLMs can answer questions based on provided context. This demo includes three rap songs:

• "Heart on Fire" - A love-themed song
• "Rising from Ashes" - About overcoming challenges
• "Digital Dreams" - Social media and technology critique

The LLM can answer questions about these songs while remaining stateless - demonstrating how context windows work without conversation memory.

See how conversation history is preserved by explicitly sending context with each request. Watch how token usage grows as conversations get longer.

Explore how LLMs can use external functions/tools like weather queries, time checks, and calculations.

Experience a decision-making loop that demonstrates higher-level agent capabilities.

Every response shows real-time token consumption:

• Input tokens: Prompt + conversation history/context
• Output tokens: Assistant's response
• Total tokens: Complete request cost

The main interface is a command-line menu with 11 different demonstrations:

python main.py

The interactive menu provides:

• Model Selection: Choose your preferred model first
• Session 1: LLM Primitives (options 1-5)
• Session 2: RAG with Qdrant (options 6-7)
• Session 3: Agno Agents (options 8-10)
• Model Management: Change models or download new ones (options 11-12)
• Exit: Option 13

Each demonstration is self-contained and educational, showing different aspects of LLM development.

• Location: session_1/primitives/
• Focus: Basic Azure OpenAI integration, stateless vs stateful concepts, and context understanding
• Key Files:
  • stateless_chat.py - Basic stateless interactions
  • stateless_chat_with_context.py - Context-based Q&A demonstration
  • stateful_chat.py - Conversation history management
  • tools_chat.py - Function calling capabilities

• Location: session_2/rag/
• Focus: Import data and retrieve-augment-generate using Qdrant
• Menu: 6 (Import), 7 (RAG Agent)

• Location: session_3/
• Focus: Agent framework with streaming output and optional persistence
• Menu: 8 (Streaming, stateless), 9 (Persistent, stateful), 10 (Music Rapper)
• Key Files:
  • simple_agent_agno.py — Streams tokens and tool steps live
  • simple_agent_agno_persist.py — Same as above, but uses SQLite to persist sessions and history

Agno Music Toolkit (optional):

• Location: session_3/tools/music_gen.py
• Class: MusicGenToolkit — exposes compose_song(genre, lyrics, title=None, duration_seconds=30)
• Behavior: Calls ElevenLabs Music API, saves MP3s under ./songs/
• Attach to agent:

  from agno.agent import Agent
  from session_3.tools.music_gen import MusicGenToolkit
  
  agent = Agent(model=..., tools=[MusicGenToolkit()], markdown=True)
  # The agent can now call compose_song when appropriate

Optional dependency for persistence:

• SQLAlchemy is included in dependencies for SQLite support
• Persistence uses SQLite database files (no external database server needed)

If you have Azure OpenAI access, create a .env file with your configuration:

# Azure OpenAI (Primary option)
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-15-preview
AZURE_DEPLOYMENT_NAME=your-deployment-name
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-small

For local models, you can optionally customize the defaults:

# Local models (fallback when Azure keys missing)
OLLAMA_MODEL=llama3.2:3b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Note: If you don't have Azure OpenAI credentials, the system automatically falls back to Ollama. No additional configuration required!

The enhanced model management system provides three ways to use local models:

python setup_workspace.py
# Choose "y" when asked about local model setup
# Select from available Ollama models
# Available: Llama 3.2 3B, Llama 3.1 8B, and embedding models

python model_manager.py
# Interactive model selection and download
# Shows available Ollama models

python main.py
# Use options 11 (Change Model) and 12 (Download Models)
# Switch between Azure OpenAI and Ollama models

1. Automatic Detection: System detects Azure OpenAI credentials and Ollama models
2. User Choice: Select preferred model type and specific model at startup
3. Consistent Experience: All demos use your selected model
4. Easy Switching: Change models without restarting the application
5. Model Information: View model type, size, and capabilities in selection menu

• Azure OpenAI: GPT-4, GPT-3.5, text-embedding-3-small
• Ollama: Llama 3.2 3B, Llama 3.1 8B, Nomic Embed Text

*Requires embedding model (Ollama: nomic-embed-text)

Session 3 persistence:

• Agents automatically use agents.db file in the project root for persistence
• No additional configuration needed - SQLite database is created automatically

Optional for Session 3 music tool:

ELEVENLABS_API_KEY=your-elevenlabs-api-key
ELEVENLABS_MUSIC_BASE_URL=https://api.elevenlabs.io
# Override if your account uses a different compose path
# ELEVENLABS_MUSIC_COMPOSE_PATH=/v1/music/compose

ai-tech-coffee-hours/
├── session_1/
│   ├── primitives/
│   │   ├── shared_utils.py               # Client utilities (Azure OpenAI + Ollama)
│   │   ├── stateless_chat.py             # Basic stateless chat
│   │   ├── stateless_chat_with_context.py # Context-based Q&A
│   │   ├── stateful_chat.py              # Chat with conversation history
│   │   └── tools_chat.py                  # Function calling demo
├── session_2/
│   └── rag/
│       ├── importer.py                    # Import data to Qdrant
│       └── rag_agent.py                   # RAG agent demo
├── session_3/
│   ├── simple_agent_agno.py              # Streaming, stateless Agno agent
│   ├── simple_agent_agno_persist.py      # Persistent (SQLite) Agno agent
│   ├── the_agent_agno_rapper.py          # Music rapper agent
│   └── tools/
│       └── music_gen.py                  # MusicGenToolkit (compose_song)
├── models/                                # Local model storage
│   ├── .gitkeep                          # Keeps directory in git
│   └── models.json                       # Downloaded model info
├── model_manager.py                       # Model download and management
├── .env.example                           # Environment template
├── pyproject.toml                         # Dependencies and project config
└── main.py                                # Interactive menu entry point

MIT License - see LICENSE for details.