hands-on-ai 0.5.0

Hands-on AI Toolkit for classrooms

HandsOnAI: Your AI Learning Lab

AI learning made simple for students and educators

New here? Try the quickstart notebook in your browser, no install needed.

HandsOnAI is a unified educational toolkit designed to teach students how modern AI systems work, by building and interacting with them directly.

It provides a clean, modular structure that introduces core AI concepts progressively through five modules:

🧱 Module Overview

Module	Purpose	CLI Name
chat	Chatbot with system prompts, personalities, and memory	chat
rag	Retrieval-Augmented Generation (RAG) over your documents	rag
agent	Tool use and step-by-step reasoning	agent
workflow	Orchestrate multi-step tasks as folders of stages	(library)
loop	Repeat a step until a goal is met (incl. the "ratchet" loop)	(library)
eval	Evaluate output quality with an LLM judge	(library)

(A small models utility module handles model detection and capabilities.)

Each module is:

• 🔌 Self-contained
• 🧩 Installable via one package: pip install hands-on-ai
• 🧠 Designed for progressive learning

🗂 Project Structure

hands_on_ai/
├── chat/           ← A simple prompt/response chatbot
├── rag/            ← Ask questions using your own documents
├── agent/          ← Agent reasoning + tools (ReAct-style)
├── workflow/       ← Multi-step tasks as folders of reviewable stages (ICM)
├── loop/           ← Repeat a step until a goal is met (run_loop, run_ratchet)
├── eval/           ← Score output quality with an LLM judge
├── config.py       ← Shared config (model, chunk size, paths)
├── cli.py          ← Meta CLI (list, config, version)
├── models.py       ← Centralized model utilities
├── utils/          ← Shared tools, prompts, paths, etc.
└── commands/       ← Shared CLI commands

Examples and scripts are available in the repository:

hands-on-ai/
├── examples/       ← Example scripts for all modules
└── scripts/        ← Utility scripts for package maintenance

🧑‍🏫 Why This Matters for Students

Each tool teaches a different level of modern AI interaction:

• chat – Prompt engineering, roles, and LLMs
• rag – Document search, embeddings, and grounded answers
• agent – Multi-step reasoning, tool use, and planning
• workflow – Orchestration as plain folders of stages you can read and review
• loop – Repetition with a goal: do, check, repeat (the core of agentic loops)
• eval – Judging output quality, the foundation of testing AI systems

Each module is intentionally small and readable: the goal is to make the concept legible, not to be production-grade. Once a concept clicks, students are encouraged to graduate to a more robust, dedicated library (LangChain, LlamaIndex, an agent framework, an eval harness, and so on).

🚀 Getting Started

Installation

# Install from PyPI
pip install hands-on-ai

# Or directly from GitHub
pip install git+https://github.com/michael-borck/hands-on-ai.git

Prerequisites

• Python 3.10 or higher
• Any OpenAI-compatible LLM provider (see Provider Compatibility)

Quick Start

Prefer a notebook? Open the starter in Colab:

Option 1: Set configuration in Python (Recommended for beginners)

import os

# Configure your provider
os.environ['HANDS_ON_AI_SERVER'] = 'https://ollama.serveur.au'
os.environ['HANDS_ON_AI_MODEL'] = 'llama3.2'
os.environ['HANDS_ON_AI_API_KEY'] = input('Enter your API key: ')

# Now use HandsOnAI
from hands_on_ai.chat import pirate_bot
print(pirate_bot("What is photosynthesis?"))

Option 2: Use environment variables

Run a local Ollama server, then set environment variables and start chatting:

export HANDS_ON_AI_SERVER="http://localhost:11434"
# No API key needed for local Ollama

from hands_on_ai.chat import pirate_bot
print(pirate_bot("What is photosynthesis?"))

For more options:

from hands_on_ai.chat import get_response, friendly_bot, pirate_bot

# Basic usage with default model
response = get_response("Tell me about planets")
print(response)

# Use a personality bot
pirate_response = pirate_bot("Tell me about sailing ships")
print(pirate_response)

get_response is stateless: each call is independent. For a multi-turn chat that remembers what was said, use Conversation:

from hands_on_ai.chat import Conversation

chat = Conversation(system="You are a helpful tutor.")
chat.ask("My name is Sam.")
print(chat.ask("What's my name?"))   # -> remembers "Sam"

print(f"Tokens used so far: {chat.total_tokens}")

chat.save("chat.json")               # persist and resume later
later = Conversation.load("chat.json")

You can also see token usage for a single call with get_response(..., return_usage=True), which returns a (response, usage) tuple (or chat ask "..." --usage on the CLI).

Stream a response as it is generated:

from hands_on_ai.chat import stream_response

for chunk in stream_response("Tell me a short story"):
    print(chunk, end="", flush=True)

Want reproducible, free reruns (great for classrooms)? Set HANDS_ON_AI_CACHE to a directory and identical calls return a cached answer instead of calling the model.

Workflows: multi-step tasks as folders (ICM)

The workflow module models a multi-step task as a plain folder of numbered stages. Each stage has a CONTEXT.md (its instructions) and an output/ folder. One model runs a stage at a time, writing a readable output.md you can review (and edit) before moving on, no opaque orchestration framework required.

from hands_on_ai.workflow import init_workspace, Pipeline

# Create a workspace with numbered stage folders
init_workspace("essay", stages=["research", "outline", "draft"])
# -> essay/stages/01_research, 02_outline, 03_draft (each with a CONTEXT.md)

# Edit each stage's CONTEXT.md to describe what it should do, then:
pipe = Pipeline("essay")
pipe.status()        # show stages and which are done
pipe.run_next()      # run stage 01, write output.md, stop for review
# ...open stages/01_research/output/output.md, edit if needed...
pipe.run_next()      # run stage 02 using stage 01's reviewed output

Run one reviewable stage at a time with run_next(), or run_all() once you trust the pipeline. See the workflow guide for the full layout (shared CONTEXT.md, references/, and more).

Loops: repeat a step until a goal is met

A loop is the same shape, repeated: do something, check whether you're done, repeat. The loop module gives you two small functions. run_loop keeps calling a step until a goal is satisfied, and the goal can be the eval LLM judge:

from hands_on_ai.chat import get_response
from hands_on_ai.loop import run_loop, judged

result = run_loop(
    step=lambda draft: get_response(f"Improve this paragraph, keep it short:\n{draft}"),
    goal=judged("clear, concise, and friendly", threshold=4),  # stop when judge scores >= 4
    start="loops are when you do stuff again and again",
    max_iters=5,
)
print(result["result"], "in", result["iterations"], "turns")

run_ratchet is the "Ralph Wiggum" loop: it keeps a change only when it scores higher than the best so far, so the result only ever moves forward. See the loop guide, and the Build a Ralph Loop project for the three-file contract, git-as-memory, and backpressure.

🌍 Provider-Agnostic Architecture

HandsOnAI is designed to work with any OpenAI-compatible LLM provider. The system uses standard OpenAI API endpoints (/v1/chat/completions, /v1/models) making it compatible with a wide range of AI services.

Configuration

Set your provider using environment variables:

# Set your provider's base URL
export HANDS_ON_AI_SERVER="https://your-provider-url"

# Set API key if required
export HANDS_ON_AI_API_KEY="your-api-key"

# Enable debug logging
export HANDS_ON_AI_LOG="debug"

Provider Examples

Ollama (Local)

export HANDS_ON_AI_SERVER="http://localhost:11434"
# No API key needed for local Ollama

OpenAI

export HANDS_ON_AI_SERVER="https://api.openai.com"
export HANDS_ON_AI_API_KEY="sk-your-openai-key"

Together AI

export HANDS_ON_AI_SERVER="https://api.together.xyz"
export HANDS_ON_AI_API_KEY="your-together-key"

OpenRouter

export HANDS_ON_AI_SERVER="https://openrouter.ai/api"
export HANDS_ON_AI_API_KEY="your-openrouter-key"
export HANDS_ON_AI_MODEL="openai/gpt-4o"  # or any model they support

Google Gemini

export HANDS_ON_AI_SERVER="https://generativelanguage.googleapis.com/v1beta/openai"
export HANDS_ON_AI_API_KEY="your-gemini-key"
export HANDS_ON_AI_MODEL="gpt-4o-mini"  # maps to gemini-1.5-flash

Groq

export HANDS_ON_AI_SERVER="https://api.groq.com/openai"
export HANDS_ON_AI_API_KEY="your-groq-key"

LocalAI

export HANDS_ON_AI_SERVER="http://localhost:8080"
# API key optional depending on setup

📊 Provider Compatibility

HandsOnAI works with any service that implements OpenAI-compatible endpoints:

Provider	Base URL Example	Authentication	Status
Ollama	http://localhost:11434	None (local)	✅ Tested
OpenAI	https://api.openai.com	Bearer token	✅ Compatible
Google Gemini	https://generativelanguage.googleapis.com/v1beta/openai	Bearer token	✅ Compatible
Groq	https://api.groq.com/openai	Bearer token	✅ Compatible
OpenRouter	https://openrouter.ai/api	Bearer token	✅ Compatible
Together AI	https://api.together.xyz	Bearer token	✅ Compatible
LocalAI	http://localhost:8080	Optional	✅ Compatible
vLLM	http://your-vllm-server	Optional	✅ Compatible
Hugging Face	https://api-inference.huggingface.co	Bearer token	✅ Compatible
Any OpenAI-compatible server	http://your-server	Varies	✅ Compatible

Requirements for Compatibility

Your provider must support:

• ✅ /v1/chat/completions endpoint
• ✅ /v1/models endpoint
• ✅ OpenAI message format ({"role": "user", "content": "..."})
• ✅ Bearer token authentication (if API key required)

Educational Benefits

This provider-agnostic approach offers several educational advantages:

• 🌍 No vendor lock-in - Switch providers without code changes
• 📚 Industry standards - Students learn OpenAI API patterns used across the industry
• 🔧 Real-world skills - Transferable knowledge to other AI tools and platforms
• 💡 Flexibility - Use local models for privacy or cloud models for power

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines on how to get involved.

License

This project is licensed under the MIT License - see the LICENSE file for details.

🤖 LLM Ready

This package is designed to work seamlessly with Large Language Models for coding assistance and learning:

For Students & Educators

• LLM.txt - Complete reference guide for LLMs
• Documentation - Full documentation site
• DeepWiki - Interactive code exploration and wiki

How to Use with LLMs

1. Download the LLM.txt file
2. Upload it to your LLM (Claude, ChatGPT, etc.)
3. Ask for help with HandsOnAI projects - get complete, working code examples

Example prompts:

• "Create a pirate chatbot using hands-on-ai"
• "Build a document Q&A system with the RAG module"
• "Make an agent that can calculate and search the web"

The LLM will have complete knowledge of the API, examples, and best practices.

Acknowledgments

• Built with education in mind
• Powered by open-source LLM technology
• Inspired by educators who want to bring AI into the classroom responsibly