🕸️ AI Agent Loop From First-Principles

A hand-calculated and programmatically verified implementation of a pure Python ReAct Agent loop, vector search routing, memory stack tracking, and cost analytics. This repository mirrors a six-page worksheet workflow with handwritten scans in assets/ and a direct math-first software implementation in src/.

---

🚀 Section 1: Project Overview & Core Concept

This project is built in the spirit of the first-principles notebook practice popularized by Andrej Karpathy and the "AI by Hand" movement. The goal is to make the internal mechanics of an agent explicit, transparent, and reproducible without relying on abstraction layers such as LangChain or other agent frameworks.

The scenario is a comic-book universe network query:

• User query: "Find if Batman has a hidden connection to Spider-Man through an intermediate contact."
• Target problem: route the query through a small directed knowledge graph, choose a specialized tool, and build the step-by-step ReAct prompt trace.

This repository demonstrates:

• Manual vector routing via explicit cosine similarity.
• A deterministic graph lookup environment.
• Append-only prompt buffer growth tracking.
• Word-count-based cost modeling.
• Automated analytics chart generation.

---

🧠 Section 2: The Hand-Drawn Workbook Walkthrough

Each page of the physical workbook is paired below with its high-resolution scan alongside clean digital transcriptions, tables, and mathematical references for maximum accessibility.

Page 1: System Architecture & Topology Map

• Description: High-level system architecture and the 4-node directed knowledge graph layer.
• Code implementation: src/environment.py

🖥️ Digital Execution Loop Diagram

[User Query] -> [Prompt Context Window Buffer (S_t)]
          │             ▲
          ▼             │
     [LLM Reasoning]    │
          │             │
          ▼             │
     [Tool Selection] --┼-- [Vector Space Match]
          │             │
          ▼             │
     [Tool Execution] --┘
    (Graph_Lookup)

🕸️ Digital Knowledge Graph Topology

Batman -> Superman -> Iron Man -> Spider-Man

---

Pages 2 & 3: Phase A Vector Search & Similarity Matrix

• Description: The agent evaluates its tool registry and chooses between a Calculator tool and a Graph_Lookup tool using a hard-coded 2D vector space.
• Selection rule: $\text{Selected Tool} = \text{argmax}(\text{Similarity})$ over cosine similarity values.
• Code implementation: src/embeddings.py

📐 Cosine Similarity Formula

$$ \text{Similarity}(\vec{A}, \vec{B}) = \frac{\vec{A} \cdot \vec{B}}{|\vec{A}| \cdot |\vec{B}|} = \frac{(A_1 B_1) + (A_2 B_2)}{\sqrt{A_1^2 + A_2^2} \cdot \sqrt{B_1^2 + B_2^2}} $$

📊 Tool Selection Vector Matrix

• Query: $\vec{q} = [0.10, 0.90]$
• Calculator tool: $\vec{t}_0 = [0.95, 0.05]$
• Graph_Lookup tool: $\vec{t}_1 = [0.15, 0.85]$

Pair	Dot Product	$|A|$	$|B|$	Cosine Similarity	Decision
Query vs Calculator	0.1400	0.9055	0.9513	0.1625	Rejected
Query vs Graph_Lookup	0.7800	0.9055	0.8631	0.9980	Selected

---

Pages 4 & 5: The ReAct Trajectory Stack & Volumetric Memory Ledger

• Description: Tracking the append-only prompt buffer across generation steps, actions, and tool observations.
• Code implementation: src/agent.py

📝 Continuous ReAct Trajectory Transcript

• $t = 0$ Initial prompt: "User Query: Find if Batman has a hidden connection to Spider-Man through an intermediate contact. Available Tools: Graph_Lookup(character_name) which returns immediate neighbors."
• $t = 1$ Thought + action: "I need to check who Batman is directly connected to first. Graph_Lookup("Batman")"
• $t = 2$ Observation: "Neighbors of Batman = [Superman]"
• $t = 3$ Thought + action: "Batman connects to Superman. Now I need to see if Superman connects closer to Spider-Man or to someone else who does. Graph_Lookup("Superman")"
• $t = 4$ Observation: "Neighbors of Superman = [Iron Man]"
• $t = 5$ Final resolution bundle: "Superman connects to Iron Man. Let me check Iron Man's connections. Graph_Lookup("Iron Man") Neighbors of Iron Man = [Spider-Man] Iron Man connects directly to Spider-Man. Path found: Batman -> Superman -> Iron Man -> Spider-Man. Yes, Batman has a hidden connection to Spider-Man. The path is: Batman -> Superman -> Iron Man -> Spider-Man."

📈 Volumetric Context Tracking

Timestep	Component	Words Added	Cumulative Volume
0	Initial prompt $S_0$	22	22
1	Generation block $T_0 + A_0$	12	34
2	Observation $O_1$	5	39
3	Generation block $T_1 + A_1$	22	61
4	Observation $O_2$	6	67
5	Final bundle BUNDLE_5	49	116

🔁 Memory Growth Rule

$$ S_n = S_{n-1} + T_{n-1} + A_{n-1} + O_n $$

---

Page 6: Performance Analytics Dashboard

• Description: System diagnostics that quantify context growth formulas, path efficiency, and turn-level operational expense.
• Code implementation: src/metrics.py

📊 Financial & Efficiency Metrics

• Input cost: $C_{in} = $0.001$ per word
• Output cost: $C_{out} = $0.003$ per word
• Billing formula: $\text{Cost}_t = (\text{Input}t \times C{in}) + (\text{Output}t \times C{out})$

Metric	Formula	Value
Context Explosion Ratio $\rho$	$116 / 22$	5.27
Tool Trajectory Efficiency $\eta$	$3 / 3$	1.00
Turn 1 cost (t=1)	$22 \times 0.001 + 12 \times 0.003$	$0.0580$
Turn 2 cost (t=3)	$39 \times 0.001 + 22 \times 0.003$	$0.1050$
Turn 3 cost (t=5)	$67 \times 0.001 + 49 \times 0.003$	$0.2140$
Total trajectory cost	Sum of turn costs	$0.3770$

---

💻 Section 3: Programmatic Verification & Automated Charts

Run the implementation to verify the handwritten calculations and generate analytics visualizations.

Installation

pip install -r requirements.txt

Execution

python main.py

Expected Output Summary

The script produces a terminal log showing:

• cosine similarity values for tool routing,
• exact word counts for every prompt step,
• cumulative context volumes,
• cost estimates per turn,
• and chart files saved into assets/.

The values shown in the log are printed with four-decimal precision using f"{sim:.4f}" so the reported similarity values match the explicit geometric calculations in src/embeddings.py.

Verified Terminal Output

======================================================================
PHASE A: INITIAL VECTOR ROUTING SEARCH
======================================================================
Calculating tool semantic weights via explicit Cosine Similarity...
 - Vector Match [Query vs. Calculator Tool]:  0.1625
 - Vector Match [Query vs. Graph_Lookup Tool]: 0.9980
>>> Decision Engine Output: Selected Tool 1 (Graph_Lookup Tool) [ARGMAX SUCCESS]

======================================================================
PHASE B & C: EXECUTION TRACE & TEXT VOLUMETRICS
======================================================================
[t = 0] Initial Context Window Payload Size (S0): 22 words.
[t = 1] Generation Cycle 1 Engine Block (T0 + A0) appended: 12 words.
[t = 2] Environment Input Step (O1) appended: 5 words. -> Payload Size: 39 words.
[t = 3] Generation Cycle 2 Engine Block (T1 + A1) appended: 22 words.
[t = 4] Environment Input Step (O2) appended: 6 words. -> Payload Size: 67 words.
[t = 5] Final Processing Sequence appended: 49 words.

Final Response (R): Yes, Batman has a hidden connection to Spider-Man.
The path is: Batman -> Superman -> Iron Man -> Spider-Man.

Tool validation from src/environment.py:
 - graph_lookup('Batman')  => ['Superman']
 - graph_lookup('Superman') => ['Iron Man']
 - graph_lookup('Iron Man') => ['Spider-Man']

======================================================================
PHASE D: SYSTEM DIAGNOSTICS & ANALYTICS REPORT
======================================================================
- Context Explosion Ratio (rho) : 5.27x (Payload expanded 527.27%)
- Tool Trajectory Efficiency (eta): 1.00  (Perfect path sequence achieved)

Financial Billing Breakdown per Turn:
 - Turn 1 Operational Expense (t=1): $0.0580
 - Turn 2 Operational Expense (t=3): $0.1050
 - Turn 3 Operational Expense (t=5): $0.2140
----------------------------------------------------------------------
>>> TOTAL AGENTIC TRAJECTORY COST: $0.3770
======================================================================
System charts successfully generated and saved to 'assets/' folder.

Generated Visualizations

• assets/context_growth.png
• assets/cost_per_step.png
• assets/dashboard_output.png

You can use these charts as the production-ready dashboard output for the final analytics page.

---

📊 Section 4: Key Structural Insights

Why build the agent from first principles?

Mechanistic reasoning reveals the true cost and complexity of an agentic loop. It helps explain why sequential reasoning with an append-only context window naturally increases memory usage and inference expense over time.

Important takeaways

• Context explosion is real: The prompt window grows at each step, forcing later turns to reprocess all prior state.
• Tool selection can be explicit: Cosine similarity in a small embedding space is enough to choose the correct tool for this scenario.
• ReAct is reproducible: The exact thought/action/observation trace can be expressed as plain strings and validated with code.
• Cost modeling matters: Explicit per-turn input/output pricing makes the production economics of an agent visible.

---

📚 References

• Yao, S., Zhang, D., Bansal, M., & Liang, P. (2022). ReAct: Synergizing Reasoning and Acting in Language Models.
• Karpathy, A. — inspiration from step-by-step low-level AI implementation and clear code-first education.
• Yeh, T. — inspiration from the "AI by Hand" first-principles workflow.

---

📁 Repository Layout

.
├── .gitignore
├── README.md
├── requirements.txt
├── assets/
│   ├── dashboard_output.png
│   ├── page1_architecture.jpg
│   ├── page2_phase_a_routing.jpg
│   ├── page3_worktable_2_1.jpg
│   ├── page4_phases_b_c_ledger.jpg
│   ├── page5_worktable_3_1.jpg
│   └── page6_phase_d_analytics.jpg
├── src/
│   ├── __init__.py
│   ├── agent.py
│   ├── embeddings.py
│   ├── environment.py
│   └── metrics.py
└── main.py