{"id":41065721,"url":"https://github.com/pguso/agents-from-scratch","last_synced_at":"2026-01-22T12:37:02.201Z","repository":{"id":332181241,"uuid":"1120991338","full_name":"pguso/agents-from-scratch","owner":"pguso","description":"Build AI agents from first principles using a local LLM - no frameworks, no cloud APIs, no hidden reasoning.","archived":false,"fork":false,"pushed_at":"2026-01-12T19:05:41.000Z","size":927,"stargazers_count":114,"open_issues_count":0,"forks_count":35,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T00:18:43.494Z","etag":null,"topics":["agent-architecture","ai-agents","ai-education","ai-from-scratch","artificial-intelligence","llama","llm","local-llm","machine-learning","no-framework","open-source-education","prompt-engineering","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pguso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T09:09:42.000Z","updated_at":"2026-01-13T00:10:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pguso/agents-from-scratch","commit_stats":null,"previous_names":["pguso/agents-from-scratch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pguso/agents-from-scratch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fagents-from-scratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fagents-from-scratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fagents-from-scratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fagents-from-scratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pguso","download_url":"https://codeload.github.com/pguso/agents-from-scratch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fagents-from-scratch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28662962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-architecture","ai-agents","ai-education","ai-from-scratch","artificial-intelligence","llama","llm","local-llm","machine-learning","no-framework","open-source-education","prompt-engineering","python"],"created_at":"2026-01-22T12:37:01.043Z","updated_at":"2026-01-22T12:37:02.185Z","avatar_url":"https://github.com/pguso.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Agents from Scratch\n\nA gentle, local-first introduction to AI agents.\n\nThis repository teaches how AI agents actually work by building **one agent** step by step from a single local LLM call.\n\n**No frameworks. No cloud APIs. No hidden reasoning. No magic.**\n\n\n## Related Projects\n\n### [AI Product from Scratch](https://github.com/pguso/ai-product-from-scratch)\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-20232A?logo=react\u0026logoColor=61DAFB)](https://reactjs.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n\nLearn AI product development fundamentals with local LLMs. Covers prompt engineering, structured output, multi-step reasoning, API design, and frontend integration through 10 comprehensive lessons with visual diagrams.\n\n### [AI Agents from Scratch in JavaScript](https://github.com/pguso/ai-agents-from-scratch) \n\n![Python](https://img.shields.io/badge/JavaScript-3776AB?logo=javascript\u0026logoColor=yellow)\n\n![Agent Architecture](diagrams/agent-architecture.png)\n\n## Philosophy\n\nAgents are not personalities. They are loops, state, and constraints.\n\nIf something feels like magic, open the file — there is no hidden logic in this repo.\n\n## What You Will Learn\n\nThis repository builds one continuously evolving agent across 12 lessons:\n\n| Lesson | Capability Added | Link |\n|--------|------------------|------|\n| 01 | Text in / text out | [lessons/01_basic_llm_chat.md](lessons/01_basic_llm_chat.md) |\n| 02 | Roles and behavior (system prompts) | [lessons/02_system_prompt.md](lessons/02_system_prompt.md) |\n| 03 | Structured output (JSON contracts) | [lessons/03_structured_output.md](lessons/03_structured_output.md) |\n| 04 | Decisions (routing logic) | [lessons/04_decision_making.md](lessons/04_decision_making.md) |\n| 05 | Tools (external capabilities) | [lessons/05_tools.md](lessons/05_tools.md) |\n| 06 | Agent loop (observe → decide → act) | [lessons/06_agent_loop.md](lessons/06_agent_loop.md) |\n| 07 | Memory (short and long-term) | [lessons/07_memory.md](lessons/07_memory.md) |\n| 08 | Planning (as data, not thoughts) | [lessons/08_planning.md](lessons/08_planning.md) |\n| 09 | Atomic actions (safe execution) | [lessons/09_atomic_actions.md](lessons/09_atomic_actions.md) |\n| 10 | AoT - Atom of Thought (dependency graphs) | [lessons/10_atom_of_thought.md](lessons/10_atom_of_thought.md) |\n| 11 | Evals (regression testing) | [lessons/11_evals.md](lessons/11_evals.md) |\n| 12 | Telemetry (runtime observability) | [lessons/12_telemetry.md](lessons/12_telemetry.md) |\n\n## Who This Is For\n\n**This repo is for:**\n- Developers who can code but feel lost with agents\n- People tired of \"just use LangChain\"\n- Learners who want local models\n- Engineers who want mechanical understanding\n- Educators looking for a clean mental model\n\n**This repo is NOT for:**\n- People looking for the fastest demo\n- People who want a SaaS starter kit\n- People who believe agents \"think\"\n- People who want hidden chain-of-thought\n\n## Quick Start\n\n**For detailed setup instructions, see [QUICKSTART.md](QUICKSTART.md)**\n\nIn short:\n1. Install dependencies: `pip install -r requirements.txt`\n2. Download a GGUF model to the `models/` folder\n3. Run: `python complete_example.py`\n\n**Note:** The `complete_example.py` file contains executable code examples demonstrating all 12 lessons. You can use it as a reference to see how all the concepts fit together.\n\n## Repository Structure\n\n```\nai-agents-from-scratch/\n├─ README.md              # You are here\n├─ philosophy.md          # Why this repo exists\n├─ QUICKSTART.md          # Detailed setup guide\n├─ complete_example.py    # Demonstrations of all 12 lessons\n├─ requirements.txt       # Python dependencies\n│\n├─ models/                # Place GGUF models here\n├─ shared/                # Reusable utilities (LLM, prompts, utils)\n├─ agent/                 # The evolving agent implementation\n│  ├─ agent.py             # Main agent class \n│  ├─ memory.py            # Memory system\n│  ├─ planner.py           # Planning and atomic actions\n│  ├─ state.py             # Agent state management\n│  ├─ tools.py             # Tool definitions\n│  ├─ evals.py             # Evaluation framework (Lesson 11)\n│  └─ telemetry.py         # Telemetry system (Lesson 12)\n├─ evals/                 # Golden datasets for testing\n│  └─ golden_datasets.py   # Known-good test cases\n└─ lessons/               # Step-by-step explanations (01-12)\n```\n\n### Key Files Explained\n\n**`agent/agent.py`** - The heart of the repository\n- Contains the `Agent` class that evolves across all 12 lessons\n- Each lesson adds new methods and capabilities to this same class\n- This is what you study and modify as you learn\n\n**`complete_example.py`** - Learning reference\n- Contains 12 separate functions, one for each lesson\n- Each function demonstrates that lesson's concepts in isolation\n- Use this to see how individual lessons work before combining them\n- Run: `python complete_example.py`\n\n**`agent/evals.py`** - Regression testing (Lesson 11)\n- Test your agent against known-good cases\n- Catch prompt regressions before deployment\n\n**`agent/telemetry.py`** - Runtime observability (Lesson 12)\n- Structured logging for debugging\n- Track latency, success rates, and traces\n\n**Relationship**: \n- `agent/agent.py` = the code you're learning (the implementation)\n- `complete_example.py` = isolated examples of each lesson (for learning and experimentation)\n\n## What This Repo Is Not\n\n- This is **not a framework**\n- This is **not a chatbot demo**\n- This does **not claim models think**\n- This does **not expose chain-of-thought**\n- This does **not require OpenAI or cloud APIs**\n\n## Core Principles\n\n1. **One agent, many stages** - The same `agent.py` file grows across lessons\n2. **Explicit over implicit** - No hidden logic, no magic abstractions\n3. **Structure over prompting** - Reliability comes from constraints, not clever wording\n4. **Local-first** - No API keys, no rate limits, no cloud dependency\n5. **Educational, not production** - This teaches fundamentals, not best practices\n\n## Learning Path\n\nEach lesson builds on the previous one. **Do not skip ahead.**\n\nThe curriculum is designed to build understanding gradually:\n- Lessons 1-3: Foundation (LLM basics)\n- Lessons 4-6: Agency (decisions, tools, loops)\n- Lessons 7-10: Intelligence (memory, planning, execution)\n- Lessons 11-12: Observability (evals, telemetry)\n\n## Contributing\n\nThis is an educational repository. Contributions should:\n- Maintain the gentle, progressive learning style\n- Keep code readable over clever\n- Add explanations, not just features\n- Preserve the \"no framework\" philosophy\n\n## License\n\nMIT License - see LICENSE file\n\n## Acknowledgments\n\nThis repository synthesizes best practices from modern agent development while deliberately avoiding complexity that obscures understanding.\n\n---\n\n**If you find this useful, please star the repository and share it with others learning about AI agents.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpguso%2Fagents-from-scratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpguso%2Fagents-from-scratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpguso%2Fagents-from-scratch/lists"}