Summary

This repository provides a gentle, local-first introduction to building AI agents from first principles. It targets developers, learners, and educators seeking a fundamental, mechanical understanding of agent mechanics without relying on complex frameworks or cloud APIs. The benefit is a clear, step-by-step educational path to demystify AI agent construction.

How It Works

The project builds a single AI agent incrementally across 12 lessons, starting with basic LLM interactions and progressively adding capabilities like structured output, tools, memory, planning, and execution. Its core approach emphasizes an "explicit over implicit" philosophy, ensuring all logic is visible and understandable within a single agent.py file. This method avoids abstraction and "magic," fostering deep mechanical insight by demonstrating agent evolution directly, powered by local LLMs.

Quick Start & Requirements

• Install: pip install -r requirements.txt
• Prerequisites: Download a GGUF model and place it in the models/ folder.
• Run: python complete_example.py
• Links: See QUICKSTART.md for detailed setup. complete_example.py demonstrates all 12 lessons.

Highlighted Details

• A 12-lesson curriculum progressively adds core agent capabilities, from basic LLM calls to advanced planning and observability.
• Emphasizes a local-first design, eliminating the need for API keys, rate limits, or cloud dependencies.
• Core philosophy: Agents are loops, state, and constraints; logic is explicit and visible, not hidden.
• Focuses on structure and constraints over complex prompting for reliability.

Maintenance & Community

This is presented as an educational repository. Contributions are encouraged to maintain its gentle, progressive learning style and "no framework" philosophy. No specific community links (e.g., Discord/Slack) or active contributor details are provided in the README.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

This repository is explicitly not for users seeking the fastest demo, a SaaS starter kit, or those who believe agents "think" in a human-like sense. It prioritizes education over production-ready best practices and requires users to manage their own local LLM models (GGUF format).