v2.1.0: README with Spark/Flow/swarm/Council/Vault naming + API reference table

README.md

@@ -55,8 +55,8 @@ Tested with **Llama-3.3-70B** and **Gemma-4-26B** via OpenRouter:
 | Llama-3.3-70B | ✓ 100% | ✓ 100% | ✓ 100% | 0→3→9→18 heuristics |
 | Gemma-4-26B | ✓ 100% | ✓ 100% | ✓ 100% | 0→3→6→11 heuristics |
 
+**0-day production test:** 19/19 pass on Llama-3.3-70B across all 3 usage levels.
 **Immune system:** 93% adversarial catch rate, 0% false positives.
-
 **Test suite:** 119 unit tests, all passing. See [LAUNCH_READINESS.md](LAUNCH_READINESS.md).
 
 ## Install
@@ -90,7 +90,7 @@ print(team.status())  # See what it's learned
 # Local (free, private)
 team = pa.purpose("Code helper", model="qwen3:1.7b")
 
-# Cloud
+# Cloud providers
 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")
@@ -104,34 +104,53 @@ Supported providers: **OpenRouter, Groq, OpenAI, Ollama, HuggingFace, Together,
 
 ### Level 3 — Full control
 
+Purpose Agent has its own API vocabulary — original names, not borrowed from other frameworks.
+
 ```python
 import purpose_agent as pa
 
-# Graph workflows (LangGraph-style)
-graph = pa.Graph()
-graph.add_node("research", pa.Agent("researcher", model="qwen3:1.7b"))
-graph.add_node("write", pa.Agent("writer", model="qwen3:1.7b"))
-graph.add_edge(pa.START, "research")
-graph.add_edge("research", "write")
-graph.add_edge("write", pa.END)
-result = graph.run(pa.State(data={"topic": "AI safety"}))
+# ── Spark: a single intelligent agent ──
+spark = pa.Spark("coder", model="openrouter:meta-llama/llama-3.3-70b-instruct")
+result = spark.run("Write a fibonacci function")
+
+# ── Flow: workflow engine with conditional routing ──
+flow = pa.Flow()
+flow.add_node("research", pa.Spark("researcher", model="qwen3:1.7b"))
+flow.add_node("write", pa.Spark("writer", model="qwen3:1.7b"))
+flow.add_edge(pa.BEGIN, "research")
+flow.add_edge("research", "write")
+flow.add_conditional_edge("write", review_fn, {"pass": pa.DONE_SIGNAL, "retry": "research"})
+result = flow.run(initial_state)
 
-# Parallel execution (CrewAI-style)
-results = pa.parallel(["task 1", "task 2", "task 3"], agents=[a1, a2, a3])
+# ── swarm: run tasks concurrently ──
+results = pa.swarm(["task 1", "task 2", "task 3"], agents=[spark_a, spark_b, spark_c])
 
-# Agent conversations (AutoGen-style)
-chat = pa.Conversation([pa.Agent("researcher"), pa.Agent("coder")])
-result = chat.run("Design a web scraper", rounds=3)
+# ── Council: agents deliberate together ──
+council = pa.Council([pa.Spark("researcher"), pa.Spark("coder"), pa.Spark("reviewer")])
+result = council.run("Design a web scraper", rounds=3)
 
-# Knowledge-aware agents (LlamaIndex-style)
-kb = pa.KnowledgeStore.from_directory("./docs")
-agent = pa.Agent("assistant", tools=[kb.as_tool()])
+# ── Vault: knowledge store with RAG-as-a-tool ──
+vault = pa.Vault.from_directory("./docs")
+spark = pa.Spark("assistant", tools=[vault.as_tool()])
+result = spark.run("What does the documentation say about X?")
 
-# Parallel tool execution (LLMCompiler-style)
+# ── LLMCompiler: parallel tool execution via DAG planning ──
 compiler = pa.LLMCompiler(planner_llm=backend, tool_registry=registry)
 result = compiler.compile_and_execute("Calculate X and search Y simultaneously")
 ```
 
+## API Reference (Level 3)
+
+| Name | What | Example |
+|------|------|---------|
+| `pa.Spark(name, model, tools)` | Create an intelligent agent | `pa.Spark("coder", model="qwen3:1.7b")` |
+| `pa.Flow()` | Workflow engine with nodes and edges | `flow.add_node("step", handler)` |
+| `pa.swarm(tasks, agents)` | Run tasks concurrently | `pa.swarm(["a","b"], [s1, s2])` |
+| `pa.Council(agents)` | Agent deliberation rounds | `council.run("topic", rounds=3)` |
+| `pa.Vault.from_texts(list)` | Knowledge store for RAG | `vault.query("search term")` |
+| `pa.BEGIN` | Flow start node | `flow.add_edge(pa.BEGIN, "first")` |
+| `pa.DONE_SIGNAL` | Flow end node | `flow.add_edge("last", pa.DONE_SIGNAL)` |
+
 ## Evidence-Gated Memory
 
 Agents don't just accumulate knowledge blindly. Every new memory goes through a pipeline:
@@ -149,8 +168,6 @@ Seven memory types: `purpose_contract`, `user_preference`, `skill_card`, `episod
 
 ## Honest Evaluation
 
-Three run modes enforce what the framework can mutate:
-
 ```python
 from purpose_agent import RunMode
 
@@ -169,21 +186,20 @@ RunMode.EVAL_TEST            # NO writes — numbers you can trust
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for the complete technical documentation.
 
-34 Python modules, ~500KB, organized in layers:
+34 Python modules, ~500KB:
 
 ```
-Core Engine  → Actor, Purpose Function, Experience Replay, Optimizer, Orchestrator
-V2 Kernel    → Memory, Immune, Trace, Compiler, Memory CI, Eval Port, Benchmark
-Research     → Meta-Rewarding, Self-Taught, Prompt Optimizer, LLM Compiler, Retroformer
-Breakthroughs→ Self-Improving Critic, MoH, Hindsight Relabeling, Heuristic Evolution
-Capabilities → Agent, Graph, Parallel, Conversation, KnowledgeStore
-Easy API     → purpose(), Team, quickstart wizard
+Core Engine   → Actor, Purpose Function, Experience Replay, Optimizer, Orchestrator
+V2 Kernel     → Memory, Immune, Trace, Compiler, Memory CI, Eval Port, Benchmark
+Research      → Meta-Rewarding, Self-Taught, Prompt Optimizer, LLM Compiler, Retroformer
+Breakthroughs → Self-Improving Critic, MoH, Hindsight Relabeling, Heuristic Evolution
+Capabilities  → Spark, Flow, swarm, Council, Vault
+Easy API      → purpose(), Team, quickstart wizard
 ```
 
 ## Literature
 
-Built on 13 published papers. Full research trace: [COMPILED_RESEARCH.md](COMPILED_RESEARCH.md).
-Formal proofs: [PURPOSE_LEARNING.md](PURPOSE_LEARNING.md).
+Built on 13 published papers. Full research trace: [COMPILED_RESEARCH.md](COMPILED_RESEARCH.md). Formal proofs: [PURPOSE_LEARNING.md](PURPOSE_LEARNING.md).
 
 | Paper | What it contributes |
 |-------|-------------------|