Setup Guide

Prerequisites

For both paths

• Ollama running locally (the default; no API key needed)
• The default model pulled:

ollama pull granite4.1:3b

• Doing the RAG track? Also pull the local embedder (needed even if you chat on a hosted model):

ollama pull embeddinggemma

No Ollama? You can run the whole workshop on a hosted model instead — see Bring your own provider below.

Get the code

You don’t clone the repo. The workshop CLI copies just the path you picked into a fresh, history-free folder:

# Python path
npx @jagreehal/ai-workshop pydantic-ai

# TypeScript path
npx @jagreehal/ai-workshop vercel-ai-sdk

Run it with no arguments for an interactive picker (it also offers the Full-Stack templates, but the Full-Stack lesson tells you when to grab those).

Pydantic AI path (Python)

• Python 3.10+
• uv

cd pydantic-ai
uv sync --extra notebook
make verify

Vercel AI SDK path (TypeScript)

• Node.js 22+

cd vercel-ai-sdk
npm install
npm run verify

Running your first challenge

# Pydantic AI
cd pydantic-ai
make f1

# Vercel AI SDK
cd vercel-ai-sdk
npm run f1

Choosing a model

Both paths default to Ollama with granite4.1:3b. For Google Gemini, set GOOGLE_GENERATIVE_AI_API_KEY in your environment; the Python path switches automatically, and on the TS path you also swap the commented line in shared/model.ts.

Bring your own provider

Already have an API key for OpenAI, Anthropic, or another provider? Use it. Both SDKs are provider-agnostic, and the model lives in one shared file per path, so one edit moves the whole workshop onto your provider.

TypeScript (vercel-ai-sdk/shared/model.ts): install the provider package, set your key in the environment, and reassign model:

npm install @ai-sdk/openai     # or @ai-sdk/anthropic, @ai-sdk/mistral, ...
export OPENAI_API_KEY=sk-...

import { openai } from "@ai-sdk/openai";
export const model = openai("gpt-5-mini");

The full list of providers is in the AI SDK providers docs.

Python (pydantic-ai/shared/model.py): Pydantic AI resolves provider:model strings, and the main pydantic-ai package already bundles the major providers. Set your key in the environment and replace the model assignment at the bottom of the file:

export ANTHROPIC_API_KEY=sk-ant-...

model = "anthropic:claude-sonnet-4-6"  # or "openai:gpt-5-mini", "mistral:mistral-small-latest", ...

If a provider needs an extra package, the error tells you exactly what to install. The full list is in the Pydantic AI models docs. One Python-path note: the Jupyter notebooks inline their own model setup cell, so amend that cell (or run the challenges as scripts, make f1, which use shared/model.py).

Two things stay the same whatever you pick: the RAG track’s embedder is always local (embeddinggemma via Ollama), and every challenge is written to be model-proof, so the lessons land the same on a 3B local model or a frontier hosted one.

Getting help

Each challenge README has a Traps section covering its common failure modes. See the Troubleshooting guide for cross-cutting issues.