🧠 Purpose Agent

The framework where AI agents actually learn from experience.

Local-first · Self-improving · Domain-agnostic · Production-hardened

pip install purpose-agent

🎯 What Problem Does This Solve?

Every other agent framework (LangChain, CrewAI, AutoGen) runs the same way every time. Your agent fails at a task? Next time, it fails the exact same way. No learning. No memory. No improvement.

Purpose Agent is different. After every task:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Task → Execute → Score → Extract Lessons → Remember      │
│     ↑                                           │           │
│     └───── Next task uses lessons ──────────────┘           │
│                                                             │
│   Run 1: Agent struggles ──────── Φ = 3.0                  │
│   Run 2: Uses learned heuristics ─ Φ = 7.0                 │
│   Run 3: Refined further ──────── Φ = 9.5                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

No fine-tuning. No GPU training. Just memory + experience.

⚡ 3-Line Quickstart

import purpose_agent as pa

team = pa.purpose("Help me write Python code")
result = team.run("Write a fibonacci function")

That's it. The framework auto-detects your model, builds the right team, executes the task, scores the result, and stores lessons for next time.

🏗️ Architecture at a Glance

╔══════════════════════════════════════════════════════════════════╗
║                     PURPOSE AGENT v3.0                          ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  ┌──────────┐    ┌─────────────┐    ┌──────────────────┐       ║
║  │  YOU      │───▶│  EASY API   │───▶│  ORCHESTRATOR    │       ║
║  │ (purpose) │    │ (auto-team) │    │ (step loop)      │       ║
║  └──────────┘    └─────────────┘    └────────┬─────────┘       ║
║                                               │                  ║
║              ┌────────────────────────────────┼──────────┐      ║
║              │                                ▼          │      ║
║              │    ┌──────────┐    ┌──────────────────┐   │      ║
║              │    │  ACTOR   │───▶│  ENVIRONMENT     │   │      ║
║              │    │ (decide) │    │  (execute)       │   │      ║
║              │    └──────────┘    └────────┬─────────┘   │      ║
║              │                             │             │      ║
║              │         ┌───────────────────▼─────┐      │      ║
║              │         │  PURPOSE FUNCTION (Φ)   │      │      ║
║              │         │  Score: 0 ──────── 10   │      │      ║
║              │         │  O(1) state-delta mode  │      │      ║
║              │         └───────────────────┬─────┘      │      ║
║              │                             │             │      ║
║              │    ┌────────────────────────▼─────────┐  │      ║
║              │    │  MEMORY (immune-scanned)          │  │      ║
║              │    │  7 types · 5 statuses · scoped   │  │      ║
║              │    │  quarantine → test → promote      │  │      ║
║              │    └──────────────────────────────────┘  │      ║
║              │                                          │      ║
║              └──── SELF-IMPROVEMENT LOOP ───────────────┘      ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

🎨 Three Ways to Use It

🟢 Level 1 — Just Describe What You Want

import purpose_agent as pa

# Auto-detects the right team composition
team = pa.purpose("Write Python code and test it")   # → architect + coder + tester
team = pa.purpose("Research quantum computing")       # → researcher + analyst
team = pa.purpose("Analyze sales data")              # → analyst + reporter
team = pa.purpose("Write a blog post")               # → writer + editor

result = team.run("Create a sorting algorithm")
team.teach("Always handle edge cases")    # Inject knowledge directly
print(team.status())                       # See what it's learned

🟡 Level 2 — Choose Your Model & Add Knowledge

import purpose_agent as pa

# 10+ providers supported
team = pa.purpose("Code helper", model="ollama:qwen3:1.7b")          # Local, free
team = pa.purpose("Code helper", model="openrouter:meta-llama/llama-3.3-70b-instruct")
team = pa.purpose("Code helper", model="groq:llama-3.3-70b-versatile")
team = pa.purpose("Code helper", model="openai:gpt-4o")

# Add your own documents as knowledge
team = pa.purpose("Answer questions about our product",
    knowledge="./docs/",              # Load entire folder
    model="qwen3:1.7b",
)
answer = team.ask("What's our refund policy?")

🔴 Level 3 — Full Control

import purpose_agent as pa

# ── Spark: single intelligent agent ──
spark = pa.Spark("coder", model="ollama:qwen3:1.7b", tools=[pa.PythonExecTool()])
result = spark.run("Write fibonacci")

# ── Flow: workflow with conditional routing ──
flow = pa.Flow()
flow.add_node("research", pa.Spark("researcher"))
flow.add_node("write", pa.Spark("writer"))
flow.add_edge(pa.BEGIN, "research")
flow.add_conditional_edge("write", check_fn, {"pass": pa.DONE_SIGNAL, "revise": "research"})
result = flow.run(state)

# ── swarm: parallel execution ──
results = pa.swarm(["task_a", "task_b", "task_c"], agents=[a1, a2, a3])

# ── Council: multi-agent deliberation ──
council = pa.Council([pa.Spark("alice"), pa.Spark("bob"), pa.Spark("carol")])
result = council.run("Should we use microservices?", rounds=3)

# ── Vault: knowledge RAG ──
vault = pa.Vault.from_directory("./research_papers/")
agent = pa.Spark("analyst", tools=[vault.as_tool()])

# ── Generate entire systems ──
from purpose_agent.mas_generator import generate
system = generate("Monitor GitHub repos for CVEs and alert the team")
# → 4 agents + workflow + tools + eval suite + routing policy

🛡️ Safety & Security

┌─────────────────────────────────────────────┐
│           MEMORY IMMUNE SYSTEM              │
│                                             │
│  candidate ──→ immune scan ──→ quarantine   │
│                    │                │       │
│              ┌─────▼─────┐    ┌────▼────┐  │
│              │  REJECTED  │    │  TEST   │  │
│              │ (5 scans)  │    │ (replay)│  │
│              └────────────┘    └────┬────┘  │
│                                    │       │
│                              ┌─────▼─────┐ │
│                              │ PROMOTED  │ │
│                              │ (active)  │ │
│                              └───────────┘ │
└─────────────────────────────────────────────┘

5 threat scanners: prompt injection, score manipulation, tool misuse, privacy leaks, scope overreach

PEP 578 kernel sandbox: Unbypassable audit hooks at the C-interpreter level. No Docker needed.

Falsification critic: Code is scored by CPU-executed assertions, not LLM hallucinations.

🔬 First-Principles Engineering

Problem	Old Approach	Purpose Agent
Token cost grows O(N²)	Pass full history to critic	O(1) state-delta — only pass what changed
SLMs hallucinate scores	"Rate this 0-10" → guess	Falsification — generate asserts, CPU executes, score = math
Sandbox bypassed via dynamic code	AST analysis (weak)	PEP 578 audit hooks — kernel-level, unbypassable
Heuristics overflow context	Inject all 200 heuristics	MoH cap K=10 — only top heuristics by Q-value
UNKNOWN action crashes	Parse failure → crash	Safe fallback to DONE — never propagates garbage

📦 What's Inside (45+ modules)

🔧 Core Engine

Module	What
`orchestrator.py`	Main step loop with 3 critic modes (standard/delta/falsification)
`actor.py`	ReAct agent with 3-tier memory + heuristic cap
`purpose_function.py`	Φ(s) scorer with 7 anti-gaming rules
`experience_replay.py`	Thread-safe trajectory storage with Q-value retrieval
`optimizer.py`	Trajectory → heuristic distillation

🧬 Self-Improvement

Module	What
`memory.py`	7 memory kinds × 5 statuses, scoped, versioned
`memory_ci.py`	Quarantine → immune scan → test → promote/reject
`memory_homeostasis.py`	Budget enforcement, consolidation, archive
`immune.py`	5 threat scanners for memory safety
`breakthroughs.py`	Self-improving critic, MoH, hindsight relabeling, evolution

⚡ First-Principles

Module	What
`state_delta.py`	O(1) Markovian state-diff for critic
`falsification_critic.py`	Popperian scoring via adversarial assertions
`sandbox_hooks.py`	PEP 578 kernel-level audit hooks
`hardening.py`	Null safety, timeouts, validation, graceful degradation
`sre_patches.py`	5 auto-applied critical vulnerability fixes

🌐 Protocols & Interop

Module	What
`protocols/mcp_bridge.py`	MCP tool server integration
`protocols/a2a.py`	Agent-to-Agent delegation with circuit breaker
`protocols/agui.py`	AG-UI frontend streaming
`protocols/agents_md.py`	AGENTS.md repo-local instructions
`quorum.py`	Consensus/disagreement topology switching

🧠 Intelligence

Module	What
`routing.py`	Smart model selection (local-first, cost-aware)
`mas_generator.py`	Use-case → complete multi-agent system
`skills/schema.py`	Versioned, evolvable, testable skill cards
`skills/ci.py`	Skill testing + rollback + Darwinian selection
`llm_compiler.py`	Parallel tool execution via DAG planning

📈 Optimization

Module	What
`optimization/fingerprint.py`	Capability profiling from traces
`optimization/dataset.py`	Trace → filtered training dataset
`optimization/prompt_pack.py`	Epigenetic prompt optimization
`optimization/shadow_eval.py`	Candidate vs baseline comparison
`optimization/optimizer.py`	Improving/plateau/degrading policy
`optimization/lora_plan.py`	LoRA/distillation dry-run planning

🏗️ Runtime

Module	What
`runtime/events.py`	30 canonical event types
`runtime/event_bus.py`	Async pub/sub with backpressure
`runtime/state.py`	Typed execution state for checkpointing
`runtime/checkpoint.py`	InMemory/JSONL/SQLite durability
`streaming_v3.py`	AG-UI compatible stream adapters

🔌 Supported Providers

from purpose_agent import resolve_backend

resolve_backend("ollama:qwen3:1.7b")                    # Local (free)
resolve_backend("openrouter:meta-llama/llama-3.3-70b-instruct")
resolve_backend("groq:llama-3.3-70b-versatile")
resolve_backend("openai:gpt-4o")
resolve_backend("together:meta-llama/Llama-3.3-70B-Instruct-Turbo")
resolve_backend("fireworks:accounts/fireworks/models/llama-v3p1-70b")
resolve_backend("cerebras:llama-3.3-70b")
resolve_backend("deepseek:deepseek-chat")
resolve_backend("mistral:mistral-large-latest")
resolve_backend("hf:Qwen/Qwen3-32B")

📊 Real-World Test Results

Tested with Llama-3.3-70B and Gemma-4-26B via OpenRouter:

Test	Llama-70B	Gemma-26B
fibonacci (4 unit tests)	✅ 100%	✅ 100%
fizzbuzz (4 unit tests)	✅ 100%	✅ 100%
factorial (3 unit tests)	✅ 100%	✅ 100%
Self-improvement (heuristic growth)	0→18	0→11
Immune system (adversarial)	93% catch	—
Production test (19 checks)	19/19 ✅	—

250+ automated tests. Zero failures required for release.

📚 Research Foundation

Built on 13 published papers. Every module traces back to a specific result.

Paper	Module	Contribution
Ng et al. 1999 (PBRS)	purpose_function	Φ preserves optimal policy
MUSE (2510.08002)	actor, optimizer	3-tier memory hierarchy
REMEMBERER (2306.07929)	experience_replay	Q-value retrieval
Reflexion (2303.11366)	orchestrator	Verbal reinforcement
SPC (2504.19162)	immune	Anti-reward-hacking
Meta-Rewarding (2407.19594)	meta_rewarding	Self-improving critic
DSPy (2310.03714)	prompt_optimizer	Automatic few-shot bootstrap
LLMCompiler (2312.04511)	llm_compiler	Parallel tool DAG
Retroformer (2308.02151)	retroformer	Structured reflection
TinyAgent (2409.00608)	slm_backends	SLM-native patterns
DeepSeek MoE (2401.06066)	breakthroughs	MoH sparse selection
HER (1707.01495)	breakthroughs	Hindsight relabeling
Self-Taught Eval (2408.02666)	self_taught	Synthetic critic training

Full proofs: PURPOSE_LEARNING.md · Research trace: COMPILED_RESEARCH.md

🚀 Install

pip install purpose-agent                    # Core (zero dependencies)
pip install purpose-agent[openai]            # + OpenAI/Groq/OpenRouter
pip install purpose-agent[ollama]            # + Local Ollama
pip install purpose-agent[all]              # Everything

For local models (recommended — free, private):

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:1.7b

🖥️ CLI

python -m purpose_agent     # Interactive wizard
purpose-agent               # Same, via entry point

📄 License

MIT — use it for anything.

Built on 13 papers. Zero fine-tuning. Agents that actually improve.

PyPI · Architecture · Formal Proofs · Changelog

Downloads last month: -; Downloads are not tracked for this model. How to track