The package has more modules than the product uses. This page is the map a new contributor or integrator should read before adding another one. It is a design contract, not an API list: three paths are supported, a few layers are advanced, and everything else is experimental or a compatibility seam.
Use python -m tools.module_audit to see the current static picture. The audit
classifies modules as cli/mcp, exported-only or isolated: cli/mcp is the
product path, exported-only is supported Python API without a product surface,
and isolated is a candidate for productization, an experimental namespace, or
removal.
tasks + reward + agent + Strategy
-> evolve() / async_evolve()
-> Policies (sampler/selection/proposal/conflict/fusion/acceptance/staleness)
-> verifier / ledger / runstore
| concern | canonical modules |
|---|---|
| artifact | strategies, treestrategy, filetree, evolvable |
| loop | evolution, async_evolve, aggregator, policies, sampling, selection, fusion, staleness, governance |
| execution | agents, runners, executor, parallel, scheduler, sandbox, sandbox_container, sandbox_shared |
| evidence | verifier, verifier_ensemble, audit/, stats, stats_eval, conformal, sequential |
| state | ledger, runstore, snapshot, checkpoint, manifest, trajectory, decisions |
This is the path every CLI/MCP plan/evolve/status/show/apply verb uses. A portable snapshot is that same candidate taken off the run: full FileTree context plus ledger lineage, scored or restored without a new search.
paired scores -> TrustEvidence -> PromotionDecision -> signed ReleaseRecord
| step | canonical module |
|---|---|
| build evidence | trust_evidence.build_trust_evidence |
| decide | promotion.promote + PromotionRules |
| sign + lineage | promotion_ledger.PromotionLedger.record |
| one-call surface | release_pipeline.release_candidate/release_evidence |
| admission (optional) | policy_release (signed manifest + admission, not a second decision engine) |
agentdescent release and the MCP release tool are the product surface.
agentdescent release verify (and MCP release_verify) checks the signed
receipt independently: it recomputes the signature over the embedded manifest
and can pin the expected key id and lineage node. Do not hand-wire the three
steps in application code; use release_pipeline or the CLI.
LoopKernel (durable) -> RSIPlatform (five layers) -> PlatformCampaign (multi-cycle)
| concern | canonical module |
|---|---|
| durable loop | loop_kernel + durable_runs |
| one cycle | platform.RSIPlatform |
| multi-cycle | platform_campaign.PlatformCampaign |
| stop policy | rsi_control.RSIController |
| compute | compute_policy + model_router |
| experience | experience.ExperienceEngine |
| product surface | agentdescent platform / MCP platform |
run_guarded (runtime) is one guarded session, not a second platform. Use it
when you need a single session with acceptance/decision logging; use
RSIPlatform when the five layers must hand off to each other.
agentdescent platform status (and MCP platform_status) reads a finished
campaign's run database without the compute, foundry or experience callbacks;
it only inspects the durable run store.
The package exports the research surface too, and that surface changes. An
integrator that embeds the engine should pin agentdescent.facade instead:
from agentdescent.facade import API_VERSION, EvolutionResult, evolve
result = evolve(tasks, reward, agent, SingleSlot(initial_value=""))facade re-exports one curated list covering Path A and the durable
LoopKernel path: the artifact strategies, the policies, the verifier, the
ledger, the run store, evolve/async_evolve and the loop kernel. The promise,
tied to API_VERSION:
- a new symbol is additive and does not change the version;
- a name is not removed or renamed without a version bump;
- everything outside
facade.__all__-- including everythingagentdescent/__init__.pyexports -- is not covered by this promise.
tests/test_facade.py pins the list and the version, so widening or narrowing
the surface is a deliberate test edit. Extending the package still means
importing from the canonical module; facade defines nothing of its own.
| layer | canonical modules | surface |
|---|---|---|
| capability growth | task_pipeline, capability_scout, capability_foundry, capability_archive, capability_loop |
agentdescent capability |
| tenancy | workspaces, tenant_platform, workspace_store |
agentdescent tenant (plan, run, report) |
| operations | ops_fabric (write), ops_console (read), rsi_metrics, rsi_telemetry, campaign_ops |
agentdescent ops (plan, publish, history) |
| meta-learning | meta (including continuous_meta_run), meta_curriculum, meta_population, meta_campaign, meta_audit, meta_exam, verified_seed |
agentdescent meta-campaign, exam, audit |
| governed harness | safe_selfmod, proofs, approval, safety_controller, governed_harness |
agentdescent governed-harness (plan, run, approvals, approve, reject) |
These are not “extra algorithms”; they are the control, evidence and memory layers around the three paths.
| surface | verbs | guide |
|---|---|---|
| release | release, release verify |
release.md |
| traces | traces digest/show |
traces.md |
| governed harness | governed-harness plan/run/approvals/approve/reject |
governed-harness.md |
| tenant | tenant plan/run/report |
tenant.md |
| operations | ops plan/publish/history |
ops.md |
| platform | platform init/plan/run/status |
platform.md |
| capability growth | capability init/plan/run |
capability-loop.md |
Every surface is a wrapper over the same evolve() engine or a durable run
store; none is a second optimiser. release verify, platform status,
ops history, tenant report and the harness approval verbs are read-only or
append-only where their guides say so.
The package grew by adding a module per capability. That left several near duplicates. The canonical/alias split is:
| concept | canonical | what it is not |
|---|---|---|
| session stop | rsi_control.RSIController |
controller.run_controller is a generic wrapper; do not add a third stop rule |
| durable run | durable_runs + loop_kernel |
runtime.run_guarded is one session; campaign is spec sessions |
| promotion decision | promotion.promote |
policy_release is admission, not a second decision |
| signed release | promotion_ledger |
manifest is a file-input manifest, not a release receipt |
| ops metrics | rsi_metrics |
metrics is the per-run meter |
| traces | rsi_telemetry |
ops_console is the read model, not the writer |
| experience | experience.ExperienceEngine |
adaptive_experience is a surface, not a second learner |
| platform campaign | platform_campaign |
campaign is spec-file sessions; meta_campaign is meta sessions |
When two modules disagree, the canonical one wins. Until the alias PRs land this is documentation/behavior intent, not a runtime switch: both code paths still exist, so new code should follow the canonical column.
- Name the product consumer before writing the module: a CLI/MCP verb, an existing canonical module, or a documented advanced path.
- Reuse
surface_common,trust_evidence,promotion,experienceandloop_kernel; do not reimplement evidence, stops, quotas or replay. - Every new command returns
schema_version: 1, fails closed with{"ok": false, "error": ...}under--json, and confines MCP refs/writes withAGENTDESCENT_SURFACE_ALLOW/AGENTDESCENT_SURFACE_WRITE_DIRS. - If it is research, do not export it from
agentdescent/__init__; describe it as experimental inmodules.mdand keep it inagentdescent/experimental/. - If it duplicates an existing concept, extend the canonical module or add a documented alias; do not ship a second engine.
- Module audit — the current static reachability report.
- Experimental status — research prototypes and recently productized modules.
- Architecture — the five layers and their data flow.
- Module map — the catalog.