feat: managed_organism() ergonomics pass (v0.23.2)

docs/site/releases.md

@@ -2,6 +2,22 @@
 
 This page tracks the recent direction of the project.
 
+## v0.23.2
+
+Focus:
+
+- pattern-first ergonomics pass for the v0.19-0.23 subsystems
+- one-call `managed_organism()` factory wiring the full stack
+- top-level `consolidate()` convenience function
+
+New:
+
+- `ManagedOrganism`, `ManagedRunResult` — full-stack organism with run/consolidate/export/scaffold
+- `managed_organism()` — batteries-included factory with sensible defaults
+- `consolidate()` — one-call sleep consolidation
+- `advise_topology()` gains optional `library` and `fingerprint` params
+- `examples/82_managed_organism.py`
+
 ## v0.23.1
 
 Focus:

examples/82_managed_organism.py

@@ -0,0 +1,120 @@
+"""
+Example 82 — Managed Organism
+===============================
+
+Demonstrates the managed_organism() factory: one function call wires the
+full v0.19-0.23 stack (library, watcher, substrate, development, social
+learning). Compare this with manually wiring 5-7 components.
+
+Usage:
+    python examples/82_managed_organism.py
+"""
+
+from operon_ai import (
+    BiTemporalMemory,
+    MockProvider,
+    Nucleus,
+    PatternLibrary,
+    PatternRunRecord,
+    PatternTemplate,
+    SkillStage,
+    TaskFingerprint,
+    Telomere,
+    managed_organism,
+    consolidate,
+)
+
+# ---------------------------------------------------------------------------
+# 1. Setup
+# ---------------------------------------------------------------------------
+
+lib = PatternLibrary()
+lib.register_template(PatternTemplate(
+    template_id="pipeline",
+    name="Enterprise Pipeline",
+    topology="skill_organism",
+    stage_specs=(
+        {"name": "intake", "role": "Normalizer"},
+        {"name": "process", "role": "Processor"},
+    ),
+    intervention_policy={},
+    fingerprint=TaskFingerprint("sequential", 2, 2, ("normalizer", "processor")),
+))
+lib.record_run(PatternRunRecord(
+    record_id=lib.make_id(), template_id="pipeline",
+    fingerprint=TaskFingerprint("sequential", 2, 2, ("normalizer", "processor")),
+    success=True, latency_ms=100, tokens_used=500,
+))
+
+fast = Nucleus(provider=MockProvider(responses={}))
+deep = Nucleus(provider=MockProvider(responses={}))
+
+# ---------------------------------------------------------------------------
+# 2. One function call — full stack
+# ---------------------------------------------------------------------------
+
+m = managed_organism(
+    task="Process quarterly report",
+    library=lib,
+    fingerprint=TaskFingerprint("sequential", 2, 2, ("normalizer", "processor")),
+    fast_nucleus=fast,
+    deep_nucleus=deep,
+    handlers={
+        "intake": lambda task: {"parsed": task},
+        "process": lambda task, state, outputs: "Report processed successfully.",
+    },
+    substrate=BiTemporalMemory(),
+    telomere=Telomere(max_operations=100),
+    organism_id="org-A",
+)
+
+# ---------------------------------------------------------------------------
+# 3. Run
+# ---------------------------------------------------------------------------
+
+result = m.run("Process quarterly report")
+
+print("=== Run Result ===")
+print(f"  Output: {result.run_result.final_output}")
+print(f"  Template: {result.template_used.name if result.template_used else 'none'}")
+print(f"  Watcher: {result.watcher_summary}")
+print(f"  Development: {result.development_status.stage.value if result.development_status else 'none'}")
+print()
+
+# ---------------------------------------------------------------------------
+# 4. Consolidate
+# ---------------------------------------------------------------------------
+
+cr = m.consolidate()
+print(f"=== Consolidation ===")
+print(f"  Result: {cr}")
+print()
+
+# ---------------------------------------------------------------------------
+# 5. Status
+# ---------------------------------------------------------------------------
+
+print("=== Status ===")
+for key, value in m.status().items():
+    print(f"  {key}: {value}")
+print()
+
+# ---------------------------------------------------------------------------
+# 6. Export templates (social learning)
+# ---------------------------------------------------------------------------
+
+exchange = m.export_templates()
+print(f"=== Export ===")
+print(f"  Templates: {len(exchange.templates) if exchange else 0}")
+
+# ---------------------------------------------------------------------------
+# --test
+# ---------------------------------------------------------------------------
+
+assert result.run_result.final_output is not None
+assert result.template_used is not None
+assert result.watcher_summary is not None
+assert result.development_status is not None
+assert cr is not None
+assert exchange is not None
+print("\n--- all assertions passed ---")

examples/README.md

@@ -51,6 +51,8 @@ reconstructing past belief states:
   developmental stages, capability gating, and critical periods
 - [`81_critical_periods.py`](81_critical_periods.py) —
   teacher-learner scaffolding with developmental awareness
+- [`82_managed_organism.py`](82_managed_organism.py) —
+  one-call managed_organism() wiring the full v0.19-0.23 stack
 
 ## Import Style Guide
 

operon_ai/__init__.py

@@ -395,6 +395,10 @@
     adaptive_skill_organism,
     advise_topology,
     assemble_pattern,
+    consolidate,
+    managed_organism,
+    ManagedOrganism,
+    ManagedRunResult,
     resolve_cognitive_mode,
     skill_organism,
 )
@@ -497,6 +501,10 @@
     "adaptive_skill_organism",
     "advise_topology",
     "assemble_pattern",
+    "consolidate",
+    "managed_organism",
+    "ManagedOrganism",
+    "ManagedRunResult",
     "resolve_cognitive_mode",
     "skill_organism",
 
@@ -710,4 +718,4 @@
     "MetabolicAccessPolicy",
 ]
 
-__version__ = "0.23.1"
+__version__ = "0.23.2"

operon_ai/patterns/__init__.py

@@ -7,6 +7,12 @@
     assemble_pattern,
 )
 from .advisor import advise_topology
+from .managed import (
+    ManagedOrganism,
+    ManagedRunResult,
+    managed_organism,
+    consolidate,
+)
 from .organism import SkillOrganism, TelemetryProbe, skill_organism
 from .repository import (
     PatternLibrary,
@@ -47,6 +53,8 @@
     "CognitiveMode",
     "ExperienceRecord",
     "InterventionKind",
+    "ManagedOrganism",
+    "ManagedRunResult",
     "PatternLibrary",
     "PatternRunRecord",
     "PatternTemplate",
@@ -70,6 +78,8 @@
     "adaptive_skill_organism",
     "advise_topology",
     "assemble_pattern",
+    "consolidate",
+    "managed_organism",
     "resolve_cognitive_mode",
     "reviewer_gate",
     "skill_organism",

operon_ai/patterns/advisor.py

@@ -16,8 +16,27 @@ def advise_topology(
     tool_count: int,
     subtask_count: int,
     error_tolerance: float = 0.1,
+    library: object | None = None,
+    fingerprint: object | None = None,
 ) -> TopologyAdvice:
-    """Return a pattern-first recommendation from simple task inputs."""
+    """Return a pattern-first recommendation from simple task inputs.
+
+    If ``library`` (a PatternLibrary) and ``fingerprint`` (a TaskFingerprint)
+    are provided, the advice includes a ``suggested_template`` from the library.
+    """
+    advice = _compute_advice(task_shape, tool_count, subtask_count, error_tolerance)
+    if library is not None and fingerprint is not None:
+        advice = _enrich_with_library(advice, library, fingerprint)
+    return advice
+
+
+def _compute_advice(
+    task_shape: str,
+    tool_count: int,
+    subtask_count: int,
+    error_tolerance: float,
+) -> TopologyAdvice:
+    """Core topology advice logic."""
     normalized = task_shape.strip().lower().replace("-", "_")
 
     if normalized in {"sequential", "pipeline", "serial"}:
@@ -91,3 +110,22 @@ def advise_topology(
     raise ValueError(
         "task_shape must be one of: sequential, parallel, independent, mixed"
     )
+
+
+def _enrich_with_library(advice: TopologyAdvice, library: object, fingerprint: object) -> TopologyAdvice:
+    """If a library and fingerprint are available, attach the best template."""
+    try:
+        ranked = library.top_templates_for(fingerprint)  # type: ignore[union-attr]
+        if ranked:
+            template, score = ranked[0]
+            return TopologyAdvice(
+                recommended_pattern=advice.recommended_pattern,
+                suggested_api=advice.suggested_api,
+                topology=advice.topology,
+                rationale=advice.rationale + f" Library match: '{template.name}' (score={score:.3f}).",
+                raw=advice.raw,
+                suggested_template=template,
+            )
+    except Exception:
+        pass
+    return advice