chp-adapter-planning 0.24.0__tar.gz

chp_adapter_planning-0.24.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.chp/
+.DS_Store
+*.tgz
+.env
+.env.*
+*.pyc
+.python-version
+.coverage
+.hypothesis/
+.chp-agent/
+*.sqlite

chp_adapter_planning-0.24.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: chp-adapter-planning
+Version: 0.24.0
+Summary: CHP capability adapter — observable agent cognition (planning and reflection)
+Author: Auxo
+License: Apache-2.0
+Keywords: adapter,capability-host-protocol,chp,cognition,planning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: chp-core>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chp-adapter-planning
+
+CHP capability adapter for observable agent cognition: planning and reflection.
+
+## Capabilities
+
+| Capability | Risk | Description |
+|---|---|---|
+| `chp.adapters.planning.create_plan` | medium | Declare an agent plan with ordered steps |
+| `chp.adapters.planning.step_update` | low | Record step started / completed / failed |
+| `chp.adapters.planning.revise` | medium | Record a plan revision with optional new steps |
+| `chp.adapters.planning.reflect` | low | Structured reflection with optional evaluation score |
+
+## Evidence Events
+
+`plan_created`, `plan_step_started`, `plan_step_completed`, `plan_revised`,
+`reflection_started`, `outcome_scored`, `reflection_completed`

chp_adapter_planning-0.24.0/README.md

@@ -0,0 +1,17 @@
+# chp-adapter-planning
+
+CHP capability adapter for observable agent cognition: planning and reflection.
+
+## Capabilities
+
+| Capability | Risk | Description |
+|---|---|---|
+| `chp.adapters.planning.create_plan` | medium | Declare an agent plan with ordered steps |
+| `chp.adapters.planning.step_update` | low | Record step started / completed / failed |
+| `chp.adapters.planning.revise` | medium | Record a plan revision with optional new steps |
+| `chp.adapters.planning.reflect` | low | Structured reflection with optional evaluation score |
+
+## Evidence Events
+
+`plan_created`, `plan_step_started`, `plan_step_completed`, `plan_revised`,
+`reflection_started`, `outcome_scored`, `reflection_completed`

chp_adapter_planning-0.24.0/chp_adapter_planning/__init__.py

@@ -0,0 +1,3 @@
+from chp_adapter_planning.adapter import PlanningAdapter, PlanningConfig
+
+__all__ = ["PlanningAdapter", "PlanningConfig"]

chp_adapter_planning-0.24.0/chp_adapter_planning/adapter.py

@@ -0,0 +1,275 @@
+"""PlanningAdapter — observable agent cognition as CHP capabilities.
+
+Evidence hygiene (MUST PRESERVE):
+* Plan intent and step descriptions — included (they are declared agent cognition,
+  not secrets or diff content).
+* Revision reasons — included (declared governance metadata).
+* Reflection content — included (declared agent reasoning; the whole point of
+  the capability is to make cognition observable).
+
+Four capabilities:
+
+* ``planning.create_plan``  — declare a plan with ordered steps; emits plan_created
+* ``planning.step_update``  — record step started / completed / failed
+* ``planning.revise``       — record a plan revision with optional added steps
+* ``planning.reflect``      — record a structured reflection with optional score
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from chp_core import BaseAdapter, capability
+from chp_core.types import (
+    EvaluationResult,
+    PlanDescriptor,
+    PlanStep,
+    new_id,
+)
+
+
+@dataclass
+class PlanningConfig:
+    """Configuration for PlanningAdapter (currently stateless; reserved for future use)."""
+
+
+class PlanningAdapter(BaseAdapter):
+    """Observable agent cognition — planning and reflection as governed capabilities."""
+
+    def __init__(self, config: PlanningConfig | None = None) -> None:
+        self._config = config or PlanningConfig()
+
+    @capability(
+        id="chp.adapters.planning.create_plan",
+        emits=['plan_created'],
+        version="0.1.0",
+        category="agent_operations",
+        risk="medium",
+        description=(
+            "Declare an agent plan: intent + ordered steps. "
+            "Emits plan_created evidence. Returns the full PlanDescriptor."
+        ),
+        input_schema={
+            "type": "object",
+            "required": ["intent"],
+            "properties": {
+                "plan_id": {
+                    "type": "string",
+                    "description": "Stable plan identifier; auto-generated if omitted.",
+                },
+                "intent": {"type": "string", "minLength": 1},
+                "steps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": ["step_id", "description"],
+                        "properties": {
+                            "step_id": {"type": "string"},
+                            "description": {"type": "string"},
+                            "capability_id": {"type": ["string", "null"]},
+                        },
+                        "additionalProperties": False,
+                    },
+                    "default": [],
+                },
+                "parent_correlation_id": {"type": "string"},
+                "metadata": {"type": "object"},
+            },
+            "additionalProperties": False,
+        },
+    )
+    async def create_plan(self, ctx: Any, payload: dict) -> dict:
+        plan_id = payload.get("plan_id") or new_id("plan")
+        intent = payload["intent"]
+        raw_steps = payload.get("steps") or []
+        steps = [
+            PlanStep(
+                step_id=s["step_id"],
+                description=s["description"],
+                capability_id=s.get("capability_id"),
+            )
+            for s in raw_steps
+        ]
+        descriptor = PlanDescriptor(
+            plan_id=plan_id,
+            intent=intent,
+            steps=steps,
+            parent_correlation_id=payload.get("parent_correlation_id"),
+            metadata=dict(payload.get("metadata") or {}),
+        )
+        ctx.emit("plan_created", {
+            "plan_id": plan_id,
+            "intent": intent,
+            "step_count": len(steps),
+            "steps": [
+                {"step_id": s.step_id, "description": s.description}
+                for s in steps
+            ],
+        })
+        return descriptor.to_dict()
+
+    @capability(
+        id="chp.adapters.planning.step_update",
+        version="0.1.0",
+        category="agent_operations",
+        risk="low",
+        description=(
+            "Record a plan step transition: started → completed or failed. "
+            "Emits plan_step_started or plan_step_completed."
+        ),
+        input_schema={
+            "type": "object",
+            "required": ["plan_id", "step_id", "status"],
+            "properties": {
+                "plan_id": {"type": "string"},
+                "step_id": {"type": "string"},
+                "status": {
+                    "type": "string",
+                    "enum": ["started", "completed", "failed"],
+                },
+                "result": {
+                    "type": "object",
+                    "description": "Structured result (for status=completed).",
+                },
+                "error": {
+                    "type": "string",
+                    "description": "Error message (for status=failed).",
+                },
+            },
+            "additionalProperties": False,
+        },
+    )
+    async def step_update(self, ctx: Any, payload: dict) -> dict:
+        plan_id = payload["plan_id"]
+        step_id = payload["step_id"]
+        status = payload["status"]
+
+        if status == "started":
+            ctx.emit("plan_step_started", {"plan_id": plan_id, "step_id": step_id})
+        else:
+            ev: dict[str, Any] = {
+                "plan_id": plan_id,
+                "step_id": step_id,
+                "status": status,
+            }
+            if status == "completed" and (result := payload.get("result")):
+                ev["result"] = result
+            if status == "failed" and (error := payload.get("error")):
+                ev["error"] = error
+            ctx.emit("plan_step_completed", ev)
+
+        return {"plan_id": plan_id, "step_id": step_id, "status": status}
+
+    @capability(
+        id="chp.adapters.planning.revise",
+        version="0.1.0",
+        category="agent_operations",
+        risk="medium",
+        description=(
+            "Record a plan revision: why it changed and any added steps. "
+            "Emits plan_revised evidence."
+        ),
+        input_schema={
+            "type": "object",
+            "required": ["plan_id", "reason"],
+            "properties": {
+                "plan_id": {"type": "string"},
+                "reason": {"type": "string", "minLength": 1},
+                "added_steps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": ["step_id", "description"],
+                        "properties": {
+                            "step_id": {"type": "string"},
+                            "description": {"type": "string"},
+                        },
+                        "additionalProperties": False,
+                    },
+                    "default": [],
+                },
+            },
+            "additionalProperties": False,
+        },
+    )
+    async def revise(self, ctx: Any, payload: dict) -> dict:
+        plan_id = payload["plan_id"]
+        reason = payload["reason"]
+        added_steps = payload.get("added_steps") or []
+        ctx.emit("plan_revised", {
+            "plan_id": plan_id,
+            "reason": reason,
+            "added_step_count": len(added_steps),
+            "added_steps": [
+                {"step_id": s["step_id"], "description": s["description"]}
+                for s in added_steps
+            ],
+        })
+        return {"plan_id": plan_id, "added_step_count": len(added_steps)}
+
+    @capability(
+        id="chp.adapters.planning.reflect",
+        version="0.1.0",
+        category="agent_operations",
+        risk="low",
+        description=(
+            "Record a structured reflection. Emits reflection_started, "
+            "outcome_scored (if score provided), and reflection_completed."
+        ),
+        input_schema={
+            "type": "object",
+            "required": ["subject", "content"],
+            "properties": {
+                "subject": {"type": "string", "minLength": 1},
+                "content": {"type": "string"},
+                "score": {
+                    "type": "number",
+                    "minimum": 0.0,
+                    "maximum": 1.0,
+                    "description": "Normalised evaluation score 0–1.",
+                },
+                "rubric": {"type": "string"},
+                "evaluator": {
+                    "type": "string",
+                    "description": "'model' | 'human' | 'automated'",
+                    "default": "model",
+                },
+                "evidence_refs": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Event IDs cited by this evaluation.",
+                },
+            },
+            "additionalProperties": False,
+        },
+    )
+    async def reflect(self, ctx: Any, payload: dict) -> dict:
+        subject = payload["subject"]
+        content = payload["content"]
+        score = payload.get("score")
+        rubric = payload.get("rubric", "")
+        evaluator = payload.get("evaluator", "model")
+        evidence_refs = list(payload.get("evidence_refs") or [])
+
+        ctx.emit("reflection_started", {"subject": subject})
+
+        if score is not None:
+            evaluation = EvaluationResult(
+                score=score,
+                rubric=rubric,
+                evaluator=evaluator,
+                evidence_refs=evidence_refs,
+            )
+            ctx.emit("outcome_scored", {"subject": subject, **evaluation.to_dict()})
+
+        ctx.emit("reflection_completed", {
+            "subject": subject,
+            "content": content,
+            "content_parts": 1,
+        })
+
+        return {
+            "subject": subject,
+            "content_parts": 1,
+            "scored": score is not None,
+        }

chp_adapter_planning-0.24.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chp-adapter-planning"
+version = "0.24.0"
+description = "CHP capability adapter — observable agent cognition (planning and reflection)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Auxo" }]
+keywords = ["chp", "capability-host-protocol", "planning", "cognition", "adapter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "chp-core>=0.7.0",
+]
+
+[project.entry-points."chp.adapters"]
+planning = "chp_adapter_planning:PlanningAdapter"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["chp_adapter_planning"]

chp_adapter_planning-0.24.0/tests/test_planning.py

@@ -0,0 +1,335 @@
+"""Tests for PlanningAdapter.
+
+All tests are stateless — no subprocess or external backend required.
+"""
+from __future__ import annotations
+
+import pytest
+from chp_core import LocalCapabilityHost, register_adapter
+from chp_core.store import SQLiteEvidenceStore
+
+from chp_adapter_planning import PlanningAdapter, PlanningConfig
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_host() -> LocalCapabilityHost:
+    adapter = PlanningAdapter()
+    host = LocalCapabilityHost(store=SQLiteEvidenceStore(":memory:"))
+    register_adapter(host, adapter)
+    return host
+
+
+def _events(host: LocalCapabilityHost) -> list[dict]:
+    return [e for e in host.store.all() if "capability_uri" not in e.get("payload", {})]
+
+
+def _event_types(host: LocalCapabilityHost) -> list[str]:
+    return [e["event_type"] for e in _events(host)]
+
+
+# ---------------------------------------------------------------------------
+# Capability registration
+# ---------------------------------------------------------------------------
+
+class TestRegistration:
+    async def test_four_capabilities_registered(self):
+        host = _make_host()
+        # keys are "id:version" — check id prefix
+        keys = " ".join(host._capabilities.keys())
+        assert "chp.adapters.planning.create_plan" in keys
+        assert "chp.adapters.planning.step_update" in keys
+        assert "chp.adapters.planning.revise" in keys
+        assert "chp.adapters.planning.reflect" in keys
+
+
+# ---------------------------------------------------------------------------
+# create_plan
+# ---------------------------------------------------------------------------
+
+class TestCreatePlan:
+    async def test_success(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "implement Tier 3 adapters",
+            "steps": [
+                {"step_id": "s1", "description": "write planning adapter"},
+                {"step_id": "s2", "description": "write delegation adapter"},
+            ],
+        })
+        assert result.outcome == "success"
+        assert result.data["intent"] == "implement Tier 3 adapters"
+        assert len(result.data["steps"]) == 2
+
+    async def test_autogenerated_plan_id(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "do something",
+        })
+        assert result.outcome == "success"
+        assert result.data["plan_id"].startswith("plan_")
+
+    async def test_explicit_plan_id_preserved(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "plan_id": "my-plan-001",
+            "intent": "do something",
+        })
+        assert result.data["plan_id"] == "my-plan-001"
+
+    async def test_emits_plan_created(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "do something",
+            "steps": [{"step_id": "a", "description": "first step"}],
+        })
+        types = _event_types(host)
+        assert "plan_created" in types
+
+    async def test_plan_created_contains_step_count(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "x",
+            "steps": [
+                {"step_id": "s1", "description": "d1"},
+                {"step_id": "s2", "description": "d2"},
+                {"step_id": "s3", "description": "d3"},
+            ],
+        })
+        ev = next(e for e in _events(host) if e["event_type"] == "plan_created")
+        assert ev["payload"]["step_count"] == 3
+
+    async def test_no_steps_allowed(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "minimal plan",
+        })
+        assert result.outcome == "success"
+        assert result.data["steps"] == []
+
+    async def test_missing_intent_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {})
+        assert result.outcome == "denied"
+
+    async def test_unknown_field_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "x",
+            "bogus": True,
+        })
+        assert result.outcome == "denied"
+
+    async def test_parent_correlation_id_round_trips(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.create_plan", {
+            "intent": "child plan",
+            "parent_correlation_id": "corr_abc123",
+        })
+        assert result.data["parent_correlation_id"] == "corr_abc123"
+
+
+# ---------------------------------------------------------------------------
+# step_update
+# ---------------------------------------------------------------------------
+
+class TestStepUpdate:
+    async def test_started_emits_plan_step_started(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.step_update", {
+            "plan_id": "p1",
+            "step_id": "s1",
+            "status": "started",
+        })
+        assert result.outcome == "success"
+        assert "plan_step_started" in _event_types(host)
+
+    async def test_completed_emits_plan_step_completed(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.step_update", {
+            "plan_id": "p1",
+            "step_id": "s1",
+            "status": "completed",
+            "result": {"files_written": 3},
+        })
+        types = _event_types(host)
+        assert "plan_step_started" not in types
+        assert "plan_step_completed" in types
+
+    async def test_failed_emits_plan_step_completed_with_error(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.step_update", {
+            "plan_id": "p1",
+            "step_id": "s1",
+            "status": "failed",
+            "error": "subprocess exited 1",
+        })
+        ev = next(e for e in _events(host) if e["event_type"] == "plan_step_completed")
+        assert ev["payload"]["status"] == "failed"
+        assert ev["payload"]["error"] == "subprocess exited 1"
+
+    async def test_returns_ids_and_status(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.step_update", {
+            "plan_id": "p1", "step_id": "s2", "status": "completed",
+        })
+        assert result.data == {"plan_id": "p1", "step_id": "s2", "status": "completed"}
+
+    async def test_invalid_status_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.step_update", {
+            "plan_id": "p1", "step_id": "s1", "status": "unknown",
+        })
+        assert result.outcome == "denied"
+
+    async def test_missing_plan_id_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.step_update", {
+            "step_id": "s1", "status": "started",
+        })
+        assert result.outcome == "denied"
+
+
+# ---------------------------------------------------------------------------
+# revise
+# ---------------------------------------------------------------------------
+
+class TestRevise:
+    async def test_emits_plan_revised(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.revise", {
+            "plan_id": "p1",
+            "reason": "scope changed after retro",
+            "added_steps": [
+                {"step_id": "s_new", "description": "add safety tests"},
+            ],
+        })
+        assert result.outcome == "success"
+        assert "plan_revised" in _event_types(host)
+
+    async def test_added_step_count_in_event(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.revise", {
+            "plan_id": "p1",
+            "reason": "found gap",
+            "added_steps": [
+                {"step_id": "x1", "description": "new step 1"},
+                {"step_id": "x2", "description": "new step 2"},
+            ],
+        })
+        ev = next(e for e in _events(host) if e["event_type"] == "plan_revised")
+        assert ev["payload"]["added_step_count"] == 2
+
+    async def test_reason_in_event(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.revise", {
+            "plan_id": "p1",
+            "reason": "scope changed",
+        })
+        ev = next(e for e in _events(host) if e["event_type"] == "plan_revised")
+        assert ev["payload"]["reason"] == "scope changed"
+
+    async def test_no_added_steps_allowed(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.revise", {
+            "plan_id": "p1",
+            "reason": "minor adjustment",
+        })
+        assert result.outcome == "success"
+        assert result.data["added_step_count"] == 0
+
+    async def test_missing_reason_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.revise", {
+            "plan_id": "p1",
+        })
+        assert result.outcome == "denied"
+
+
+# ---------------------------------------------------------------------------
+# reflect
+# ---------------------------------------------------------------------------
+
+class TestReflect:
+    async def test_emits_started_and_completed(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "Tier 3 implementation",
+            "content": "All three adapters built and tested successfully.",
+        })
+        assert result.outcome == "success"
+        types = _event_types(host)
+        assert "reflection_started" in types
+        assert "reflection_completed" in types
+
+    async def test_no_outcome_scored_without_score(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x",
+            "content": "y",
+        })
+        assert "outcome_scored" not in _event_types(host)
+
+    async def test_outcome_scored_emitted_when_score_provided(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "code quality",
+            "content": "Adapter follows established patterns.",
+            "score": 0.9,
+            "rubric": "adherence to CHP adapter pattern",
+            "evaluator": "model",
+        })
+        types = _event_types(host)
+        assert "outcome_scored" in types
+
+    async def test_outcome_scored_has_score_value(self):
+        host = _make_host()
+        await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x",
+            "content": "y",
+            "score": 0.75,
+        })
+        ev = next(e for e in _events(host) if e["event_type"] == "outcome_scored")
+        assert ev["payload"]["score"] == pytest.approx(0.75)
+
+    async def test_returns_scored_flag(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x", "content": "y", "score": 0.5,
+        })
+        assert result.data["scored"] is True
+
+    async def test_returns_scored_false_when_no_score(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x", "content": "y",
+        })
+        assert result.data["scored"] is False
+
+    async def test_missing_content_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x",
+        })
+        assert result.outcome == "denied"
+
+    async def test_score_out_of_range_denied(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x",
+            "content": "y",
+            "score": 1.5,
+        })
+        assert result.outcome == "denied"
+
+    async def test_evidence_refs_accepted(self):
+        host = _make_host()
+        result = await host.ainvoke("chp.adapters.planning.reflect", {
+            "subject": "x",
+            "content": "y",
+            "score": 0.8,
+            "evidence_refs": ["ev_001", "ev_002"],
+        })
+        assert result.outcome == "success"