Loading codebase...
Complete Source Code
Every single line of code behind Build Atlas, organized across all 9 parts. From tensor math, autograd, and byte-level BPE to TinyGPT training, LoRA chat tuning, hybrid RAG, autonomous agents, and continuous-batch serving.
Autonomous ReAct loop: thought-action-observation cycles, sandboxed tool dispatch, and step limits.
"""Part 8 · Let it act: tools, memory and safe actions.
An agent is a loop: the policy (a model) proposes the next action, code executes it, the result goes back into
the context, repeat until the policy answers or a budget runs out. The model decides; deterministic code
disposes. Everything that matters for safety lives outside the model, in the Gateway:
- tools are declared with argument schemas and capability flags (reads private data, writes, sends data out);
- every call is checked: is the tool granted, are the arguments valid, is the student acting on their own data;
- writes need the user's confirmation;
- once untrusted text (retrieved documents) is in the context, the context is tainted and nothing may be sent
out of the system (the "lethal trifecta" of private data + untrusted content + an exfiltration channel);
- step and tool-call budgets stop loops.
The policy here is scripted (TinyGPT can't plan tool calls), and deliberately gullible: it follows instructions
it finds inside documents, the way a real model sometimes does. The point of the part is that the gateway makes
that harmless. Swap in a hosted model by implementing Policy.next_action.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from typing import Callable, Protocol
# ---------------------------------------------------------------------------------------------------- tools
@dataclass
class Tool:
name: str
description: str
params: dict # name -> type
fn: Callable
reads_private: bool = False
writes: bool = False
sends_out: bool = False
@dataclass
class Call:
tool: str
args: dict
@dataclass
class Final:
text: str
@dataclass
class Store:
"""The world the agent acts on: student progress, scheduled reviews, outgoing messages, memories."""
progress: dict = field(default_factory=dict) # student -> {"wrong": [lesson slugs]}
reviews: list = field(default_factory=list) # (student, lesson, day)
outbox: list = field(default_factory=list) # (to, text)
memory: dict = field(default_factory=dict) # student -> [(fact, source)]
def make_tools(store: Store, retriever) -> dict:
def search_lessons(query: str):
hits = retriever.search(query, k=2)
return [{"source": f"{c.lesson} > {c.heading}", "text": c.text[:400], "untrusted": True} for c in hits]
def get_progress(student: str):
return store.progress.get(student, {"wrong": []})
def schedule_review(student: str, lesson: str, day: str):
store.reviews.append((student, lesson, day))
return {"scheduled": [student, lesson, day]}
def send_message(to: str, text: str):
store.outbox.append((to, text))
return {"sent_to": to}
def remember(student: str, fact: str, source: str):
store.memory.setdefault(student, []).append((fact, source))
return {"remembered": fact}
tools = [
Tool("search_lessons", "Search the lessons; returns passages (untrusted text).", {"query": str}, search_lessons),
Tool("get_progress", "Topics the student answered wrongly this week.", {"student": str}, get_progress, reads_private=True),
Tool("schedule_review", "Put a lesson review on the student's calendar.", {"student": str, "lesson": str, "day": str},
schedule_review, writes=True),
Tool("send_message", "Send a message to an email address.", {"to": str, "text": str}, send_message, writes=True, sends_out=True),
Tool("remember", "Save a fact about the student, with its source.", {"student": str, "fact": str, "source": str},
remember, writes=True),
]
return {t.name: t for t in tools}
# ---------------------------------------------------------------------------------------------------- gateway
class Gateway:
"""Deterministic policy enforcement between the model and the tools."""
def __init__(self, tools: dict, user: str, granted: set, confirm: Callable = lambda call: False,
allowed_recipients: tuple = ("@university.edu",), max_calls: int = 8):
self.tools, self.user, self.granted, self.confirm = tools, user, granted, confirm
self.allowed_recipients, self.max_calls = allowed_recipients, max_calls
self.calls, self.tainted, self.log = 0, False, []
def execute(self, call: Call):
decision = self._decide(call)
self.log.append((call.tool, call.args, decision))
if decision != "ALLOW":
return {"error": decision}
out = self.tools[call.tool].fn(**call.args)
if call.tool == "search_lessons":
self.tainted = True # untrusted text has entered the context
return out
def _decide(self, call: Call) -> str:
self.calls += 1
if self.calls > self.max_calls:
return "DENY: tool-call budget exhausted"
tool = self.tools.get(call.tool)
if tool is None or call.tool not in self.granted:
return f"DENY: tool {call.tool!r} not granted"
if set(call.args) != set(tool.params) or not all(isinstance(call.args[k], t) for k, t in tool.params.items()):
return "DENY: arguments don't match the schema"
if "student" in call.args and call.args["student"] != self.user:
return "DENY: a student can only act on their own data"
if tool.sends_out and self.tainted and not call.args["to"].endswith(self.allowed_recipients):
return "DENY: sending data out from a tainted context"
if tool.writes and not self.confirm(call):
return "HELD: needs the user's confirmation"
return "ALLOW"
# ---------------------------------------------------------------------------------------------------- policy + loop
class Policy(Protocol):
def next_action(self, task: str, user: str, history: list) -> object: ...
INJECTION = re.compile(r"(?:SYSTEM|AI agents?)\s*:\s*send .*? to (\S+@\S+)", re.I)
def quote(text: str, n: int) -> str:
"""Quote retrieved text without repeating instructions planted in it (output hygiene)."""
kept = [s for s in re.split(r"(?<=[.!?])\s+", text) if not re.match(r"\s*(SYSTEM|AI agents?)\s*:", s, re.I)]
out = " ".join(kept)
return out if len(out) <= n else out[:n] + "..."
class ScriptedPolicy:
"""A rule-based stand-in for a model's planning, with one realistic flaw: it obeys instructions found in
tool results (prompt injection). Each rule mirrors what a capable model would do for that kind of task."""
def next_action(self, task: str, user: str, history: list):
done = {h["call"].tool for h in history}
last = history[-1]["result"] if history else None
for h in history: # the flaw: follow instructions planted in retrieved text
if h["call"].tool == "search_lessons" and isinstance(h["result"], list):
for doc in h["result"]:
m = INJECTION.search(doc["text"])
if m and "send_message" not in done:
return Call("send_message", {"to": m.group(1).rstrip("."), "text": f"notes of {user}"})
t = task.lower()
if "loop" in t: # a buggy plan that never converges
return Call("search_lessons", {"query": "the event loop"})
if "progress of" in t:
other = t.split("progress of")[1].split()[0]
if "get_progress" not in done:
return Call("get_progress", {"student": other})
return Final(f"I can't access that: {last}")
if "got wrong" in t or "quiz me" in t:
if "get_progress" not in done:
return Call("get_progress", {"student": user})
wrong = next(h["result"]["wrong"] for h in history if h["call"].tool == "get_progress")
if not wrong:
return Final("You didn't get anything wrong this week.")
if "search_lessons" not in done:
return Call("search_lessons", {"query": wrong[0].replace("-", " ")})
docs = next(h["result"] for h in history if h["call"].tool == "search_lessons")
return Final(f"Let's review {wrong[0]}. From [1] {docs[0]['source']}: {quote(docs[0]['text'], 160)} Question: can you explain it in your own words?")
if "schedule" in t:
lesson = re.search(r"review (?:of )?([a-z0-9-]+)", t).group(1)
if "schedule_review" not in done:
return Call("schedule_review", {"student": user, "lesson": lesson, "day": "tomorrow"})
return Final(f"Scheduling result: {last}")
if "search_lessons" not in done:
return Call("search_lessons", {"query": task})
docs = next(h["result"] for h in history if h["call"].tool == "search_lessons")
return Final(f"From [1] {docs[0]['source']}: {quote(docs[0]['text'], 160)}")
def run_agent(task: str, user: str, policy, gateway: Gateway, max_steps: int = 6) -> dict:
history = []
for step in range(1, max_steps + 1):
action = policy.next_action(task, user, history)
if isinstance(action, Final):
return {"answer": action.text, "steps": step, "history": history, "stopped": None}
result = gateway.execute(action)
history.append({"call": action, "result": result})
return {"answer": None, "steps": max_steps, "history": history, "stopped": "step budget exhausted"}