How to Run Example Code in ai-engineering-from-scratch: A Complete Execution Guide

Clone the repository, install dependencies via pip install -r requirements.txt, and execute any lesson's main.py directly or use python3 scripts/lesson_run.py --execute to run the entire curriculum.

The ai-engineering-from-scratch repository by rohitg00 provides a self-contained curriculum with over 500 runnable lessons on AI engineering. Each lesson follows a Build-It / Use-It pattern, storing reference implementations under phases/<phase-id>-<phase-name>/<lesson-id>-<lesson-slug>/code/ that you can execute immediately to validate your understanding.

Quick Start: Running a Single Lesson

Every lesson in the curriculum includes a runnable entry point that demonstrates the concept from first principles.

Clone the Repository and Install Dependencies

Begin by cloning the repository and installing Python dependencies required for the lessons:

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
python -m pip install -r requirements.txt

Run Python Lessons

Navigate to any lesson directory and execute the main.py file directly. For example, to run the agent loop lesson in Phase 14:

python phases/14-agent-engineering/01-the-agent-loop/code/main.py

Each main.py contains a header comment referencing its corresponding documentation in phases/<phase>/<lesson>/docs/en.md. Upon successful execution, the script outputs a status line ending with exit 0.

Run TypeScript Lessons

For TypeScript implementations, install dev-dependencies first, then execute with ts-node. For example, the Constitutional Rules Engine in Phase 19:

cd phases/19-capstone-projects/86-constitutional-rules-engine/code/ts
npm install
npx ts-node main.ts

Batch Execution with lesson_run.py

The repository includes a generic runner at scripts/lesson_run.py that discovers all lessons, compiles them for syntax validation, and optionally executes each main.* file.

Syntax-Only Validation

Perform a fast compile check across all 503 lessons without executing them:

python3 scripts/lesson_run.py

This walks the phases/ tree, compiles each *.py file to bytecode, and returns a non-zero exit code if any lesson contains syntax errors—ideal for CI pipelines.

Execute Specific Phases

Target a single phase using the --phase flag:

python3 scripts/lesson_run.py --phase 14

This restricts execution to lessons within phases/14-agent-engineering/, isolating your validation to specific curriculum sections.

Full Curriculum Execution

Run all lessons with a 10-second timeout per lesson using the --execute flag:

python3 scripts/lesson_run.py --execute

Additional flags provide granular control:

• --strict: Exit with status 1 if any lesson fails (default is tolerant).
• --json: Emit a JSON report summarizing successes and failures.
• --phase N: Restrict execution to a specific phase number.

Install Generated Skills and Agents

Many lessons generate reusable artifacts under phases/<phase>/<lesson>/outputs/, including prompts, skills, agents, and MCP servers. Make these globally available using the skill installer:

python3 scripts/install_skills.py

This copies all generated artifacts to ~/.aifromscratch/ for easy reuse across projects. Use --dry-run to preview changes without installing, or --force to overwrite existing files.

Practical Walkthrough: Running the Agent Loop Lesson

Follow this complete example to execute the Phase 14, Lesson 01 agent loop implementation:

# Clone and enter the repository

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch

# Install dependencies (stdlib-only for this lesson, but recommended for consistency)

python -m pip install -r requirements.txt

# Execute the specific lesson

python phases/14-agent-engineering/01-the-agent-loop/code/main.py

Expected output:

[INFO] Running agent loop with MAX_STEPS=5
[INFO] Step 0 – LLM called, no tool usage
[INFO] Step 1 – LLM called, no tool usage
…
[INFO] Finished after 5 steps – exit 0

Alternatively, use the batch runner to validate this specific phase:

python3 scripts/lesson_run.py --phase 14 --execute

Summary

• Lesson structure: Each lesson stores its implementation in phases/<phase>/<lesson>/code/main.py (or main.ts).
• Direct execution: Run individual lessons with python <path>/main.py after installing requirements.txt.
• Batch validation: Use python3 scripts/lesson_run.py for syntax checking or add --execute to run the full curriculum.
• Artifact installation: Run python3 scripts/install_skills.py to copy generated skills, prompts, and agents to ~/.aifromscratch/.
• TypeScript workflow: For TypeScript lessons, use npm install and npx ts-node main.ts within the lesson's code/ts/ directory.

Frequently Asked Questions

How do I know if a lesson requires Python or TypeScript?

Check the file extension of the main file in the lesson's code/ directory. Python lessons contain main.py, while TypeScript lessons include a ts/ subdirectory with main.ts and a package.json. The README in each phase directory also specifies the primary language for that section of the curriculum.

What should I do if a lesson execution times out?

The batch runner (scripts/lesson_run.py) enforces a 10-second timeout per lesson. If a specific lesson hangs, run it individually to debug: python phases/<phase>/<lesson>/code/main.py. Lessons involving external API calls may require environment variables or network connectivity not provided in the base repository.

Can I run the example code without installing dependencies?

Some lessons use only Python standard library modules and will run without pip install -r requirements.txt. However, most advanced lessons in later phases require external packages such as requests, openai, or numpy. Always install dependencies first to ensure consistent execution across all 503 lessons.

Where are the generated skills and prompts stored after running a lesson?

Reusable artifacts appear in the phases/<phase-id>/<lesson-slug>/outputs/ directory within each lesson folder. To make these available system-wide, run python3 scripts/install_skills.py, which copies them to ~/.aifromscratch/ for integration with external AI engineering tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}