Skip to content

Latest commit

 

History

History
204 lines (142 loc) · 5.69 KB

PHILOSOPHY.md

File metadata and controls

204 lines (142 loc) · 5.69 KB

Philosophy

Why This Repository Exists

Most tutorials teach how to use agents. This repository teaches how agents work.

The goal is not to build the fastest demo or the most impressive chatbot. The goal is mechanical understanding - the kind that lets you debug, extend, and reason about agent systems confidently.

What We Avoid

1. Framework Abstractions

Frameworks like LangChain, CrewAI, and AutoGen are powerful tools, but they hide the mechanisms that make agents work. By the time you understand what they abstract, you no longer need them.

This repository builds agents from first principles so you can:

  • Understand what frameworks actually do
  • Make informed decisions about when to use them
  • Debug problems when they arise
  • Build custom solutions when needed

2. Anthropomorphic Language

Agents don't "think," "reason," or "understand." They:

  • Process text
  • Follow patterns
  • Make structured decisions
  • Execute predefined operations

Using precise language prevents magical thinking and keeps the focus on systems, not personalities.

3. Hidden Reasoning

Many agent frameworks hide the decision-making process in opaque "chain-of-thought" or "reasoning" steps. This creates an illusion of intelligence and makes debugging nearly impossible.

In this repository:

  • Every decision is explicit
  • Every state transition is visible
  • Every prompt is readable
  • Nothing happens behind the scenes

4. Premature Autonomy

Autonomous agents sound exciting but are dangerous without understanding. This repository builds agency gradually:

  • First: Model responds
  • Then: Model decides
  • Then: Model requests actions
  • Finally: System executes safely

Autonomy is the last thing added, not the first.

What We Focus On

1. Explicit State

class AgentState:
    def __init__(self):
        self.steps = 0
        self.done = False

State isn't hidden in conversation history or mysterious context. It's a Python object you can inspect, modify, and reason about.

2. Structured Outputs

schema = {
    "action": "string",
    "arguments": "object"
}

Free-text outputs are probabilistic and unreliable. Structured outputs are contracts that can be validated, retried, and trusted.

3. Validated Decisions

for attempt in range(3):
    response = llm.generate(prompt)
    parsed = safe_json_parse(response)
    if parsed:
        break

LLMs are probabilistic. Validation + retries turn them into reliable components.

4. Data-Driven Planning

plan = {
    "steps": [
        "step_1",
        "step_2",
        "step_3"
    ]
}

Plans aren't thoughts - they're data structures. This makes them inspectable, modifiable, and safe.

Core Beliefs

Agents Are Systems

An agent is:

while not done:
    observation = perceive(environment)
    decision = decide(observation, state)
    state = act(decision, state)

Not a personality. Not consciousness. A loop.

Structure Beats Cleverness

A mediocre prompt with good structure beats a clever prompt with free-form output every time.

Constraints Enable Reliability

The more constrained your agent's action space, the more reliably it behaves. This feels limiting at first but is liberating in practice.

Simplicity Scales

Complex agents emerge from simple patterns repeated consistently, not from complex patterns used once.

What This Means in Practice

Before: Mystery

agent.run("Analyze this document and suggest improvements")
# What happens? Who knows.

After: Clarity

agent.run("Analyze this document and suggest improvements")
# 1. Parse request
# 2. Decide: analysis required
# 3. Call tool: document_analyzer
# 4. Format results
# 5. Return structured suggestions

Every step is visible. Every decision is explicit. Every failure is debuggable.

Why No ReAct?

ReAct (Reasoning + Acting) was an important research contribution, but:

  1. Modern frameworks don't use it
  2. It adds cognitive overhead for beginners
  3. Tool calling + good prompts accomplish the same goals
  4. It conflates "reasoning" (opaque) with "planning" (data)

This repository replaces ReAct with simpler, more explicit patterns that are easier to understand and debug.

Why Local Models?

  1. No API costs - Experiment freely
  2. No rate limits - Iterate quickly
  3. Full control - See exactly what happens
  4. Privacy - Your data stays local
  5. Learning - Understand the full stack

Cloud APIs are great for production. Local models are better for learning.

The Learning Philosophy

This repository follows a specific pedagogical approach:

Progressive Complexity

Each lesson adds exactly one new concept. No shortcuts. No "trust me, this works."

Readable Code

Code is written to be read top-to-bottom, not to be clever. If you need comments to understand it, it's too complex.

Explicit Over Implicit

Magic is the enemy of understanding. If something feels magical, open the file - there's always a mechanical explanation.

Iterative Refinement

The same agent file grows across lessons. This mirrors real development and prevents "tutorial reset fatigue."

When to Use Frameworks

After completing this repository, you'll understand:

  • What frameworks abstract
  • When that abstraction helps
  • When it hurts
  • How to debug them

Then frameworks become tools, not magic boxes.

The Goal

By the end of this repository, you should be able to:

  1. Build a simple agent from scratch in an afternoon
  2. Explain how every part works
  3. Debug agent failures systematically
  4. Evaluate whether to use a framework
  5. Read framework code and understand it

That's the goal: confident, mechanical understanding.

Not hype. Not magic. Just systems.