Skip to content

Learn how modern AI actually works, by building it

Hands-On AI is an educational toolkit for understanding AI, not just using it. You build the things you hear about (a chatbot, a retrieval system, a tool-using agent) in small, readable Python, and run them on free local models.

It's designed for the classroom: no API keys required, works offline, and one install (pip install hands-on-ai) gives you four progressively deeper modules.

🔬 Small on purpose. This is a learning lab, not a production framework. It captures the essence of each idea in code you can read in an afternoon, then points you to bigger tools when you're ready to ship. What this is (and isn't) →

Start in 3 steps

# 1. Install
pip install hands-on-ai

# 2. Connect a provider (easiest: local Ollama, no API key)
ollama pull llama3

# 3. Run your first bot
from hands_on_ai.chat import get_response
print(get_response("Explain photosynthesis like I'm 10."))

New here? Follow the Install & First Run guide, then Choose a Provider.

Where to go next

The modules

Each module introduces the next layer of how modern AI systems are built:

  • 💬 Chat: chat

    Prompting, system prompts, personalities, and multi-turn conversation. The foundation: talking to an LLM.

    Learn Chat →

  • 📚 RAG: rag

    Retrieval-Augmented Generation: chunk your documents, embed them, and ground the model's answers in your own sources.

    Learn RAG →

  • 🤖 Agent: agent

    Tool use and step-by-step reasoning. The model decides which tool to call to solve a problem.

    Learn Agents →

  • 🗂️ Workflow: workflow

    Orchestrate multi-step tasks as folders of stages, sequential and human-in-the-loop, no framework required.

    Learn Workflows →

  • ⚖️ Evaluation: eval

    The question after "how do I build it?": how do you know if the output is good? Use an LLM to judge a response against your criteria.

    Learn Evaluation →

Why Hands-On AI

  • 🔑 No API keys required: runs on free local models via Ollama
  • 🌍 Provider-agnostic: swap to OpenAI, OpenRouter, Together, Groq, or any OpenAI-compatible provider without changing code
  • 📴 Works offline: ideal for classrooms with unreliable internet
  • 🧠 Beginner-friendly: small, readable code you're meant to open and understand
  • 🧩 Progressive: chat → RAG → agents → workflows → evaluation mirrors a real learning path

Offline resources

  • Project Browser: a standalone HTML file to browse and filter every project offline. Great for classrooms without reliable internet.