Omar SobhandClaude Opus 4.8
e93a3cfb53
Every TopologyKind now runs, mapped to five execution patterns: - hierarchical ← hub_spoke, star_moe, market - pipeline ← ring - swarm ← flat, holacratic - mesh (new) ← blackboard (two peer-exchange rounds + aggregate) - debate (new) (propose → critique → revise → judge) execute()'s match is now exhaustive (adding a kind upstream forces an executor), so the Unsupported error is gone. Benchmark spans all five distinct patterns. 14 tests with --features provider; clippy clean. Doc updated. Co-Authored-By: Claude Opus 4.8 <[email protected]>
83 lines
5.2 KiB
Markdown
83 lines
5.2 KiB
Markdown
# Dynamic Agentic Topologies — platform architecture
|
|
|
|
Status: **Phase 0/1 (foundation)**. Source of truth for the topology-switching capability.
|
|
|
|
## Goal
|
|
Let users build agentic systems that **swap into any organizational topology**, run a task across
|
|
topologies on ClawMates' real **§15-safe per-tenant runtime**, and **measure** which patterns yield
|
|
better results — producing both a product capability and reproducible data for a paper on
|
|
*large dynamic agentic topologies*.
|
|
|
|
We re-implement the topology IP from `~/projects/agentorg` in **pure Rust** (agentorg's modeling is
|
|
real; its execution is largely simulated — ClawMates supplies the missing safe execution).
|
|
|
|
## Curated topology set (v1)
|
|
Start with topologies that **differ meaningfully in execution** (governance/novel forms deferred):
|
|
|
|
| Kind | Shape | Execution pattern |
|
|
|---|---|---|
|
|
| `hierarchical` | tree | orchestrator delegates down; results bubble up |
|
|
| `flat` | peers, light coord | autonomous peers, minimal coordination |
|
|
| `pipeline` | linear stages | output of stage *n* → input of stage *n+1* |
|
|
| `swarm` | broadcast + vote | parallel attempts, consensus/aggregation |
|
|
| `mesh` | dense peer-to-peer | peers exchange freely until convergence |
|
|
| `hub_spoke` | central hub | hub routes to spokes, aggregates |
|
|
| `ring` | cycle | sequential round-trips, refine each lap |
|
|
| `star_moe` | router + experts | router picks expert(s) per subtask (MoE) |
|
|
| `market` | auction | tasks bid out to agents by fit/cost |
|
|
| `blackboard` | shared memory | agents read/write a shared workspace |
|
|
| `debate` | adversarial | proposer vs critic rounds → judge |
|
|
| `holacratic` | self-org circles | circles self-assign within roles |
|
|
|
|
Each kind carries **heuristics** (default role distribution + optimization weights), ported from
|
|
agentorg `agents/swarmagentic/swarm/topology_manager.py`.
|
|
|
|
## `TopologyGraph` schema (`cm-topology`)
|
|
- **Node** = a role slot: `{ id, role, level?, attrs }` (bound to a real claw/`AgentId` at run time).
|
|
- **Edge** = a relationship: `{ from, to, kind }` where `EdgeKind ∈ {delegates_to, reports_to,
|
|
pipes_to, peers_with, routes_to, bids_to, reads_writes}`.
|
|
- A graph also records its declared `TopologyKind`. The **classifier** can also *infer* the kind from
|
|
graph metrics (degree/centrality variance, density, clustering, modularity, hierarchy score,
|
|
diameter) → `{ kind, confidence }`, ported from `topology_classifier.py`.
|
|
- **Adapter:** a serde `TopologySpec` (JSON/YAML) normalizes into a `TopologyGraph` (mirrors
|
|
`org_adapter/normalize_topology.py`).
|
|
|
|
## §15 edge contract (non-negotiable)
|
|
A topology only describes *who talks to whom and who decides*. **Execution semantics never bypass
|
|
ClawMates safety:** any edge whose action leaves the sandbox (email/Slack/pay/delete/etc.) routes
|
|
through `cm-safety` (approvals + single-use secret broker + audit journal), exactly as a single claw
|
|
does today. Switching topology cannot widen an agent's authority. This is the platform's moat and the
|
|
paper's safety contribution.
|
|
|
|
## Crate / component map
|
|
- **`crates/cm-topology`** ✅: pure, offline — kinds, graph, adapter, classifier, heuristics.
|
|
- **`crates/cm-orchestrator`** ✅ (Phase 2): executes a task across a `TopologyGraph` by sequencing safe
|
|
turns via a generic `TurnExecutor`. **All 12 kinds run**, mapped to five execution patterns: hierarchical
|
|
(also hub_spoke/star_moe/market), pipeline (also ring), swarm (also flat/holacratic), mesh (also
|
|
blackboard), debate. `ProviderExecutor` (cm-llm) runs real tool-free turns today; a `cm-runtime`
|
|
tool-using executor (full §15 + `run_events`) is the remaining adapter.
|
|
- **Experiment harness** ✅ (Phase 4 core, in orchestrator): `compare()` runs a task across N topologies;
|
|
captures tokens/quality(`JudgeScorer`)/turns/#blocked-approvals; computes Pareto + leaderboard. Runnable
|
|
via `examples/topology_bench.rs`.
|
|
- **`cm-api`** (next): CRUD topologies; create runs (single / workflow-of-topologies / comparison); fetch results.
|
|
- **`cm-db`**: `topologies`, `topology_runs`, `run_results`, `pareto_snapshots`.
|
|
- **`frontend/`**: ReactFlow topology builder + Pareto/leaderboard view.
|
|
|
|
## agentorg → Rust port map
|
|
| agentorg (Python) | ClawMates (Rust) |
|
|
|---|---|
|
|
| `agents/topology_classifier.py` (`TopologyType`, classifier) | `cm-topology::kind`, `cm-topology::classifier` |
|
|
| `org_adapter/normalize_topology.py` (`OrganizationGraph`, adapter) | `cm-topology::graph`, `cm-topology::adapter` |
|
|
| `agents/swarmagentic/swarm/topology_manager.py` (heuristics) | `cm-topology::heuristics` |
|
|
| `swarm_templates/` (templates) | seed catalog under `cm-topology` (later) |
|
|
| `benchmarks/`, `monitoring/pareto/` | experiment harness (Phase 4) |
|
|
| `papers/*` | `papers/dynamic-agentic-topologies.md` |
|
|
|
|
## Phases & verification
|
|
- **P1** `cm-topology`: `cargo test -p cm-topology` — known graphs classify to expected kinds; spec
|
|
round-trips; every kind has heuristics.
|
|
- **P2** runtime: one task runs under a topology on a dev tenant; every gated action still needs approval.
|
|
- **P3/P4**: user selects a topology/workflow and runs it; same task across ≥3 topologies → real
|
|
cost/quality leaderboard + Pareto; existing e2e/§15 suites stay green.
|
|
- **Paper**: one command reproduces a benchmark table from logged runs.
|