Omar SobhandClaude Opus 4.8
817d8c712c
Foundation for the dynamic agentic-topologies platform (see docs/topology-platform.md), porting agentorg's topology modeling into pure Rust: - TopologyKind: curated 12-kind taxonomy (hierarchical, flat, pipeline, swarm, mesh, hub_spoke, ring, star_moe, market, blackboard, debate, holacratic). - TopologyGraph: role-slot nodes + typed edges, with validation. - adapter: normalize a loose JSON spec → validated graph (fills edge kinds). - classifier: structural metrics (density, hub dominance, clustering, diameter, hierarchy score) → inferred kind + confidence (tree→hierarchical, line→pipeline, cycle→ring, star→hub_spoke, complete→mesh, empty→flat). - heuristics: per-kind role distributions (ported from topology_manager.py). Pure, offline, dependency-light (serde/thiserror). 17 unit tests, clippy clean. Co-Authored-By: Claude Opus 4.8 <[email protected]>
79 lines
4.9 KiB
Markdown
79 lines
4.9 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`** (this phase): pure, offline — kinds, graph, adapter, classifier, heuristics. Tests only.
|
|
- **`crates/cm-orchestrator`** (Phase 2): binds a `TopologyGraph` to real claws and executes a task per
|
|
pattern, gating every sandbox-leaving edge via `cm-safety`; journals steps to `run_events`.
|
|
- **Experiment harness** (Phase 4, in orchestrator): run a task across N topologies; capture
|
|
cost/quality(`cm-llm` judge)/latency/#approvals/#steps; compute Pareto + leaderboard. Seeded + pinned model.
|
|
- **`cm-api`**: 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.
|