Metadata-Version: 2.4
Name: llm-agents-from-scratch
Version: 0.0.18
Summary: Build an LLM agent, equipped with MCP, from scratch.
Author-email: Andrei Fajardo <andrei@nerdai.io>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: asyncio>=3.4.3
Requires-Dist: colorama>=0.4.6
Requires-Dist: jsonschema>=4.24.0
Requires-Dist: mcp[cli]>=1.9.4
Requires-Dist: ollama>=0.5.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: qdrant-client[fastembed]>=1.14.0
Requires-Dist: typing-extensions>=4.14.0
Provides-Extra: notebook-utils
Requires-Dist: pandas>=2.3.3; extra == 'notebook-utils'
Provides-Extra: notebooks
Requires-Dist: ipython>=8.37.0; extra == 'notebooks'
Requires-Dist: tqdm>=4.0.0; extra == 'notebooks'
Provides-Extra: openai
Requires-Dist: openai>=2.9.0; extra == 'openai'
Description-Content-Type: text/markdown

# LLM Agents From Scratch

[![Linting](https://github.com/nerdai/llm-agents-from-scratch/actions/workflows/lint.yml/badge.svg)](https://github.com/nerdai/llm-agents-from-scratch/actions/workflows/lint.yml)
[![Unit Testing and Upload Coverage](https://github.com/nerdai/llm-agents-from-scratch/actions/workflows/unit_test.yml/badge.svg)](https://github.com/nerdai/llm-agents-from-scratch/actions/workflows/unit_test.yml)
[![codecov](https://codecov.io/gh/nerdai/llm-agents-from-scratch/graph/badge.svg?token=I1CXFJXEXK)](https://codecov.io/gh/nerdai/llm-agents-from-scratch)
[![DOI](https://zenodo.org/badge/1002134625.svg)](https://doi.org/10.5281/zenodo.15857308)
[![GitHub License](https://img.shields.io/github/license/nerdai/llm-agents-from-scratch)](https://github.com/nerdai/llm-agents-from-scratch/blob/main/LICENSE)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/nerdai/llm-agents-from-scratch)
<a href="https://lightning.ai/nerdai/templates/build-a-multi-agent-system-from-scratch"><img src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/app-2/studio-badge.svg" alt="Open In Studio" height="20"/></a>

The companion library for *Build a Multi-Agent System — With MCP and A2A*
(Manning). Learn how LLM agents work by building one yourself, from first
principles, step by step.

> **Available now through Manning's Early Access Program (MEAP)** — buy today and get each chapter as it's completed.
> [Buy the Book →](https://hubs.la/Q03Q0h770)

---

## About

Multi-agent systems and the LLM agents that power them are among the most
discussed topics in AI today. There are already many capable frameworks out
there — the goal of this book isn't to replace them, but to help you deeply
understand how they work by having you build one yourself, from scratch.

All the code lives in the book's own hand-rolled agent framework, primarily
designed for educational purposes rather than production deployment. It will
give you the foundation to work more confidently with any other LLM agent
framework of your choosing, or even to build your own specialised solutions.

---

## From the Book

Each chapter builds on the last, progressively deepening your understanding from
core concepts to full multi-agent systems.

### Part 1 — Build Your First LLM Agent

| Ch | Title | Notebook |
| -- | ----- | -------- |
| 1 | What Are LLM Agents and Multi-Agent Systems? | — |
| 2 | Working with Tools | [Ch 2](https://masfromscratch.com/notebooks/ch02/) |
| 3 | Working with LLMs | [Ch 3](https://masfromscratch.com/notebooks/ch03/) |
| 4 | The LLM Agent Class | [Ch 4](https://masfromscratch.com/notebooks/ch04/) |

### Part 2 — Enhance Your LLM Agent

| Ch | Title | Notebook |
| -- | ----- | -------- |
| 5 | MCP Tools | [Ch 5](https://masfromscratch.com/notebooks/ch05/) |
| 6 | Skills | [Ch 6](https://masfromscratch.com/notebooks/ch06/) |
| 7 | Memory | — |
| 8 | Human in the Loop | — |

### Part 3 — Building Multi-Agent Systems

| Ch | Title | Notebook |
| -- | ----- | -------- |
| 9 | Multi-Agent Systems with Agent2Agent | — |

---

## Capstone Projects

Capstones are larger, end-to-end projects that pull together what you have built
in the book and apply it to something closer to a real-world system.

| Capstone | Description | Notebook |
| -------- | ----------- | -------- |
| Monte Carlo Estimation of Pi | Orchestrate parallel tool calls to estimate π using the Monte Carlo method. | [Open](https://masfromscratch.com/capstones/one/capstone_1_ch05/) |
| Deep Research Agent | *Coming soon.* | — |
| OpenClaw Personal Assistant | *Coming soon.* | — |

---

## Running the Notebooks

The chapter notebooks use **Qwen3:14B** as the default model via Ollama.
Minimum hardware: ~16 GB RAM with a discrete GPU, or any machine with a
dedicated GPU that can comfortably run a 14B model. You can swap in a
smaller model (e.g. `qwen3:4b`), but note that smaller models may not
follow tool-use instructions reliably — especially in later chapters.

### Option A — Run locally

Install [Ollama](https://ollama.com/) and pull the model:

```sh
ollama pull qwen3:14b
```

Then launch Jupyter from the project root:

```sh
uv run --with jupyter jupyter lab
```

### Option B — Lightning AI (recommended if you don't have a GPU)

[Lightning AI](https://lightning.ai) offers a free tier with ~22 GPU
compute hours/month — enough for several sessions on an L4 GPU.

1. [Create a free Lightning AI account](https://lightning.ai) if you don't have one
2. Visit the book template:
   [lightning.ai/nerdai/templates/build-a-multi-agent-system-from-scratch](https://lightning.ai/nerdai/templates/build-a-multi-agent-system-from-scratch)
3. Click **Clone** to copy it to your account
4. Make sure you have the latest version of the template
5. Launch the Studio with an **L4 GPU**
6. Open the chapter notebook you want to run and execute the cells —
   Ollama and the required model are already set up in the template

---

## Getting Started

### Prerequisites

- Python 3.10+
- [Ollama](https://ollama.com/) running locally (used as the default LLM backend)
- [uv](https://docs.astral.sh/uv/) for dependency management

### Installation

Clone the repository:

```sh
# SSH
git clone git@github.com:nerdai/llm-agents-from-scratch.git

# HTTPS
git clone https://github.com/nerdai/llm-agents-from-scratch.git

cd llm-agents-from-scratch
```

Install dependencies:

```sh
uv sync --all-extras --dev
```

### Quick Start

```python
from llm_agents_from_scratch.llms import OllamaLLM
from llm_agents_from_scratch.agent import LLMAgentBuilder
from llm_agents_from_scratch.tools import SimpleFunctionTool

def add(a: int, b: int) -> int:
    return a + b

llm = OllamaLLM(model="llama3.2")
tool = SimpleFunctionTool(fn=add)

agent = (
    LLMAgentBuilder()
    .with_llm(llm)
    .with_tools([tool])
    .build()
)

result = await agent.run("What is 3 + 5?")
print(result)
```

---

## Development

```sh
# Run all tests
make test

# Lint and format
make lint
make format

# Coverage report
make coverage-report
```

See [CLAUDE.md](CLAUDE.md) for full development guidance.

---

## Contributing

Bug reports, feature requests, and community project submissions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

- **Found a bug?** [Open an issue](https://github.com/nerdai/llm-agents-from-scratch/issues)
- **Built something cool?** [Share it on GitHub Discussions](https://github.com/nerdai/llm-agents-from-scratch/discussions)

---

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
