agentic-paradigm-ladder

🪜 The Agentic Paradigm Ladder

Agent development is stuck writing assembly.
This repo builds the missing abstraction ladder — Levels 5→14 — as real, tested, running code.

pip install -e . && apl demo

_{One command. No PYTHONPATH wiring. Runs the Level-11 workflow compiler end-to-end and exits 0.}

⚡ Quickstart

Clone → install → run, in a single line:

git clone https://github.com/nguyenminhduc9988/agentic-paradigm-ladder && cd agentic-paradigm-ladder && pip install -e . && apl demo

Already cloned? Just:

pip install -e . && apl demo

apl demo — compiling bundled workflow: examples/example_workflow.json

  Workflow: research-digest-pipeline v1.0.0
  Nodes before: 6  →  after: 5

  [dead_task_elimination]
    - Removed 1 dead tasks: Legacy debug dump (unconsumed) (id=stale_debug)
  [model_reroute]
    - Summarize each document: summarize — rerouted from ~$0.0257 to ~$0.0000 (using glm-5-turbo)
    - Analyze market signals: analyze — rerouted from ~$0.0085 to ~$0.0005 (using glm-5.1)
    - Total savings: ~$0.0569 per cycle
  [batch_detection]
    - Found 1 batch opportunities: {analyze_market,analyze_risk}
  [checkpoint_insertion]
    - Inserted 2 checkpoint(s): ingest, report
  SUMMARY
    original_cost: $0.1208
    optimized_cost: $0.0017
    savings: 98.6%

  ✅ Demo complete — the Level 11 compiler optimized the workflow end-to-end.
  💰 Cost $0.1208 → $0.0017 (98.6% saved)

The apl command line

Run the tests yourself: pip install -e '.[test]' && apl test

🔌 Integrate into any agent

The ladder isn't just a library to read — it's a drop-in governor for any AI agent. One object, AgentIntegration, plugs into a bare async function or a LangChain / LlamaIndex / CrewAI / Autogen agent alike, and guides every aspect of its work: configuration, planning, compilation, contract validation, composition, observability, and evolution.

See it in one command:

apl integrate

That attaches the ladder to a plain agent and drives it across all seven lifecycle stages — here's the actual output:

①  configure : genome=researcher model=claude-sonnet-5 tools=['web_search', 'read_file', 'summarize']
②③ plan+compile : 2 node(s), cost $0.0257 -> $0.0001 (99.7% saved)
④  validate : rejected a contract-violating task (ContractMismatchError)
⑤b patterns : strategy->premium, chain->fallback
⑤a compose  : budget guard active, remaining=$0.08, critic approved=True
⑥  observe  : 1 observer event(s); trace() fail-safe with no tracer = True
⑦  record   : 1 TaskResult(s) captured as fitness signal
⑦  evolve   : best_fitness [0.98, 0.98, 0.98, 0.98] (non-decreasing=True)
✅ The ladder guided the agent across all 7 lifecycle stages.

Wire it into your own agent in 3 lines — any async (task: dict) -> dict callable works:

from agentlib.integration import AgentIntegration, FitnessEvaluator

async def my_agent(task: dict) -> dict:                 # ← YOUR agent (any framework)
    return {"answer": f"handled: {task['query']}", "cost": 0.02, "revenue": 1.0, "success": True}

guided = AgentIntegration(genome="researcher", budget=0.10,
                          fitness=FitnessEvaluator()).integrate(my_agent)
# `guided` is now a drop-in agent: contract-checked, budget-capped, traced, and self-recording.

What each hook guides

Full contract, adapters for popular frameworks, and precise hook signatures: docs/INTEGRATION.md. Runnable reference: examples/integration_demo.py.

🎯 The claim, and the proof

The interactive research page argues: agent development is stuck below Level 5 (the OOP-equivalent rung), while mainstream software engineering has built on Levels 5–11 — inheritance, functional composition, generics, interfaces, design patterns, metaprogramming, compilers — for decades. Levels 12–14 (agent OS, agent economy, autonomous discovery) are "nobody is building" territory.

This repo closes that gap with code, not more prose — every rung is an importable module with an automated test suite.

🪜 The ladder — what's implemented

flowchart TB
    subgraph L0_4 ["🟥 Levels 0–4 · below the abstraction floor"]
        direction TB
        A0["L0–L4 · prompts, loops, tools<br/><i>where most agents live today</i>"]
    end
    subgraph L5_11 ["🟩 Levels 5–11 · IMPLEMENTED here"]
        direction TB
        A5["L5 · Genomes &amp; inheritance<br/><code>agentlib/genome.py</code>"]
        A6["L6 · Functional composition<br/><code>agentlib/compose.py</code>"]
        A7["L7–8 · Contracts &amp; interfaces<br/><code>agentlib/contracts.py</code>"]
        A9["L9 · Design patterns<br/><code>agentlib/patterns.py</code>"]
        A11["L10–11 · Workflow compiler<br/><code>paradigm/agent_workflow_compiler.py</code>"]
        A5 --> A6 --> A7 --> A9 --> A11
    end
    subgraph L12_14 ["🟪 Levels 12–14 · 'nobody is building' — IMPLEMENTED here"]
        direction TB
        A12["L12–14 · Discovery loop<br/><code>agentlib/evolution.py</code>"]
    end
    L0_4 --> L5_11 --> L12_14

🏗️ How it fits together

flowchart LR
    G["🧬 AgentGenome<br/>(L5 · evolvable config)"] -->|specialize / mutate| C["🔧 Workflow Compiler<br/>(L11)"]
    C -->|dead-task elim<br/>model reroute<br/>batch · checkpoint · cache| P["📦 ExecutionPlan<br/>(optimized + priced)"]
    K["📇 Skill corpus<br/>(SKILL.md files)"] -->|discover + validate| H["🧪 Contract Harness<br/>(C2/C3)"]
    H -->|fitness signal| E["♻️ DiscoveryLoop<br/>(L12–14 · populations, elitism)"]
    G --> E
    E -->|published strategies| P
    E -.->|traces| O["🔭 Langfuse<br/>observability (C1)"]

The compiler and the evolution loop share the same genome type, and the evolution loop's selection pressure is real — it scores genomes by running the actual skill-contract validators against files on disk, not a mocked reward.

🧩 Components — C1 → C10

Each component maps to a specific ladder level and ships with its own tests. Full breakdown: docs/COMPONENTS.md.

📂 Project layout

agentic-paradigm-ladder/
├── apl_cli.py            # the `apl` entry point (one-liner front door)
├── pyproject.toml        # pip install -e . → `apl` console script
├── index.html            # the original interactive research page
├── agentlib/             # C5–C7, C10 — genomes, composition, contracts, evolution
├── skilltest/            # C2–C3 — SKILL.md contract & schema validation
├── paradigm/             # C9 — the workflow compiler
├── hooks/                # C4 — code-review queue hook
├── examples/             # bundled demo workflow + mini skill corpus
└── docs/                 # spec, gap analysis, verification logs, components guide

🤝 Contributing

PRs welcome. The bar is simple and enforced by CI:

pip install -e '.[test]'
apl test          # 72 tests must stay green

Every new skill contract must carry semver version: + a dependencies: list (C3), and every new pipeline step should declare a SkillContract (C6).

📜 License

MIT — build on it freely.