library_name: purpose-agent license: mit language:

• en tags:
• agents
• self-improving
• multi-agent
• memory-system
• local-first
• slm
• safety
• event-driven
• rag
• tools pipeline_tag: text-generation

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

📦 What's Inside (45+ modules)

🔌 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:

250+ automated tests. Zero failures required for release.

📚 Research Foundation

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

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.