AI Masterclass ADSUM — Student Repository

Repository Studenti / Student Repository

Benvenuti! Questo repository contiene tutto il codice, i notebook e gli esercizi della masterclass. Welcome! This repository contains all the code, notebooks and exercises for the masterclass.

Requisito minimo / Minimum requirement: Python 3.11+, Git, un terminale / a terminal

---

Quick Start (5 minuti)

git clone https://github.com/ams0/ai-masterclass-adsum
cd ai-masterclass-adsum/Student-Repo

# Crea e attiva l'ambiente virtuale / Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows

# Installa dipendenze / Install dependencies
pip install -r requirements.txt

# Configura l'ambiente / Configure environment
cp .env.example .env
# → edita .env con il tuo provider scelto / edit .env with your chosen provider

# Verifica setup / Verify setup
python scripts/check_setup.py

---

Configurazione LLM — Scegli il tuo Backend

Il codice usa l'OpenAI Python SDK, che funziona in modo identico con tutti i backend: The code uses the OpenAI Python SDK, which works identically with all backends:

Backend	Base URL	Quando usarlo / When to use
Ollama (locale)	http://localhost:11434/v1	Nessun API key, free, offline
Azure OpenAI	Fornito dal docente / Provided by instructor	GPT-4, modelli vocali
OpenAI	https://api.openai.com/v1	Tuo account personale / Personal account

Opzione A — Ollama (consigliata / recommended)

# Installa Ollama / Install Ollama: https://ollama.com/download
# macOS:  brew install ollama
# Windows: winget install Ollama
# Linux:  curl https://ollama.ai/install.sh | sh

# Scarica un modello / Download a model
ollama pull llama3.2       # 3B, leggero / lightweight
ollama pull nomic-embed-text  # Per embeddings (RAG)

# Avvia il server / Start the server
ollama serve

# Test rapido / Quick test
curl http://localhost:11434/v1/models

Opzione B — Azure OpenAI (endpoint docente / instructor endpoint)

# Nel tuo .env / In your .env:
LLM_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://[fornito-dal-docente].openai.azure.com/
AZURE_OPENAI_API_KEY=[fornito-dal-docente]
AZURE_OPENAI_DEPLOYMENT=gpt-4

Opzione C — OpenAI diretto / Direct OpenAI

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

---

Struttura del Repo / Repository Structure

Student-Repo/
├── .env.example              <-- Template variabili d'ambiente / env variables template
├── requirements.txt          <-- Dipendenze Python / Python dependencies
├── config.py                 <-- Client LLM configurabile / Configurable LLM client
│
├── scripts/
│   └── check_setup.py        <-- Verifica ambiente / Environment check
│
├── notebooks/
│   ├── 04_llm_basics.md      <-- Chiamate LLM (Ollama/Azure)
│   ├── 07_agents.md          <-- Agenti Python puri / Pure Python agents
│   ├── 08_rag.md             <-- RAG (Retrieval Augmented Generation)
│   └── 09_voice_realtime.md  <-- Azure Voice + Realtime API
│
├── src/
│   ├── agent.py              <-- Agent loop con ReAct / Agent loop with ReAct
│   ├── tools.py              <-- Tool per agenti / Agent tools
│   └── rag_pipeline.py       <-- Pipeline RAG con ChromaDB
│
├── data/                     <-- Dataset per lab e RAG
│   └── documents/            <-- Documenti per lab RAG
│
├── models/                   <-- Modelli salvati (gitignore)
└── notes/                    <-- Note salvate dagli agenti

---

Verifica del Setup / Setup Verification

python scripts/check_setup.py

Output atteso / Expected output:

==========================================================
  AI Masterclass ADSUM — Setup Check
==========================================================
  [OK] Python version — 3.11.x
  [OK] OpenAI SDK
  [OK] scikit-learn
  [OK] pandas
  [OK] Streamlit
  [OK] ChromaDB
  [OK] Config loaded — provider=ollama
  [OK] LLM responds — "Hello"
  [OK] src.tools — 5 tools available
  [OK] src.agent
  [OK] src.rag_pipeline
==========================================================
  All checks passed! You're ready for the masterclass.
==========================================================

---

Problemi Comuni / Common Problems

ollama: command not found → Scarica da / Download from https://ollama.com/download

Connection refused su localhost:11434 → Avvia ollama serve in un terminale separato / Start ollama serve in a separate terminal

CUDA out of memory → Usa un modello piu' piccolo / Use a smaller model: ollama pull llama3.2:1b

ModuleNotFoundError → Assicurati di avere il venv attivato / Make sure the venv is activated: source .venv/bin/activate

chromadb errori su Windows → Installa Visual C++ Build Tools: pip install chromadb puo' richiedere compilazione

---

Repo mantenuto da Alessandro Vozza | Masterclass ADSUM 2025