core-runtime 0.1.1__py3-none-any.whl

will/agents/planner_agent.py

@@ -0,0 +1,261 @@
+# src/will/agents/planner_agent.py
+
+"""
+The PlannerAgent is responsible for decomposing a high-level user goal
+into a concrete, step-by-step execution plan.
+
+CONSTITUTIONAL ENHANCEMENT (V2.3.0):
+"Legal Counsel": Now performs RAG (Retrieval Augmented Generation) against
+the Constitution before planning.
+The Planner searches the 'core_policies' vector collection for rules relevant
+to the specific user goal and injects them into the prompt.
+Prevents "Trial by Fire" (proposing illegal plans that get blocked by the Body).
+
+HARDENING (V2.3.0):
+- Removed non-deterministic random cleanup to satisfy P1.2.
+- Cleaned imports to reduce layer leakage.
+- Memory cleanup is now an explicit CLI command only (core-admin cleanup memory).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from body.atomic.registry import action_registry
+from shared.ai.prompt_model import PromptModel
+from shared.infrastructure.clients.qdrant_client import QdrantService
+from shared.logger import getLogger
+from shared.models import ExecutionTask, PlanExecutionError
+from shared.path_resolver import PathResolver
+from will.agents.base_planner import build_planning_prompt, parse_and_validate_plan
+from will.orchestration.cognitive_service import CognitiveService
+from will.orchestration.decision_tracer import DecisionTracer
+from will.tools.policy_vectorizer import PolicyVectorizer
+
+
+logger = getLogger(__name__)
+
+
+# ID: c0bf833c-f3a2-4508-8cd0-1d6474eebb4d
+class PlannerAgent:
+    """Decomposes goals into constitutionally-aligned executable plans."""
+
+    def __init__(
+        self,
+        cognitive_service: CognitiveService,
+        repo_path: Path,
+        qdrant_service: QdrantService | None = None,
+        max_retries: int = 3,
+    ):
+        self.cognitive_service = cognitive_service
+        self.repo_path = repo_path
+        self.max_retries = max_retries
+        self.tracer = DecisionTracer()
+
+        # PolicyVectorizer requires qdrant_service ? degrade gracefully if absent
+        if qdrant_service is not None:
+            self.policy_vectorizer = PolicyVectorizer(
+                repo_root=repo_path,
+                cognitive_service=cognitive_service,
+                qdrant_service=qdrant_service,
+            )
+        else:
+            self.policy_vectorizer = None
+            logger.warning("PlannerAgent: Qdrant not available, policy RAG disabled.")
+
+        # Load PromptModel artifact once
+        self.plan_goal_model = PromptModel.load("plan_goal")
+
+    # ID: 52208224-fea7-4d79-baee-d3b07d634624
+    async def create_execution_plan(
+        self, goal: str, reconnaissance_report: str = ""
+    ) -> list[ExecutionTask]:
+        """
+        Creates an execution plan from a user goal and a reconnaissance report.
+
+        CONSTITUTIONAL COMPLIANCE:
+        - P1.2: Pure planning ? no side effects, no random, no cleanup calls.
+        - Legal Counsel: Fetches relevant constitutional rules via RAG before planning.
+        - Tracing: Records decision for every plan created (planning.trace_mandatory).
+
+        Args:
+            goal: High-level user goal
+            reconnaissance_report: Optional context from ReconnaissanceAgent
+
+        Returns:
+            List of ExecutionTask objects representing the plan
+        """
+        # LEGAL COUNSEL: Fetch relevant constitutional rules for this goal
+        constitutional_context = await self._fetch_constitutional_context(goal)
+
+        # Load QA constraints from policy files
+        qa_constraints = self._load_qa_constraints()
+
+        # Enrich the reconnaissance report with constitutional rules and QA requirements
+        enriched_recon = (
+            f"{reconnaissance_report}\n{constitutional_context}\n{qa_constraints}"
+        )
+
+        # Build action descriptions from the live Registry
+        actions = action_registry.list_all()
+        action_descriptions = json.dumps(
+            [
+                {
+                    "action_id": a.action_id,
+                    "description": a.description,
+                    "impact": a.impact_level,
+                }
+                for a in actions
+            ],
+            indent=2,
+        )
+
+        # Load the planning prompt template
+        path_resolver = PathResolver(self.repo_path)
+        try:
+            prompt_dir = path_resolver.prompt("planner_agent")
+            prompt_template = (prompt_dir / "system.txt").read_text(encoding="utf-8")
+        except FileNotFoundError:
+            logger.error(
+                "Constitutional prompt 'planner_agent/system.txt' missing from var/prompts/"
+            )
+            raise
+
+        prompt = build_planning_prompt(
+            path_resolver=PathResolver(self.repo_path),
+            goal=goal,
+            action_descriptions_str=action_descriptions,
+            reconnaissance_report=enriched_recon,
+            prompt_template=prompt_template,
+        )
+
+        client = await self.cognitive_service.aget_client_for_role(
+            self.plan_goal_model._artifact.manifest.role
+        )
+
+        for attempt in range(self.max_retries):
+            logger.info(
+                "? Planning execution steps (Attempt %d/%d)...",
+                attempt + 1,
+                self.max_retries,
+            )
+
+            response_text = await self.plan_goal_model.invoke(
+                context={
+                    "prompt": prompt,
+                    "goal": goal,
+                    "action_descriptions_str": action_descriptions,
+                    "reconnaissance_report": enriched_recon,
+                },
+                client=client,
+                user_id="planner_agent",
+            )
+            if response_text:
+                try:
+                    plan = parse_and_validate_plan(response_text)
+
+                    # MANDATORY TRACING: Record the final plan decision (planning.trace_mandatory)
+                    self.tracer.record(
+                        agent=self.__class__.__name__,
+                        decision_type="task_execution",
+                        rationale=(
+                            "Decomposed goal into actionable steps "
+                            "based on Constitution and QA standards"
+                        ),
+                        chosen_action=f"Generated plan with {len(plan)} steps",
+                        context={"goal": goal, "steps": len(plan)},
+                        confidence=0.9,
+                    )
+                    return plan
+
+                except PlanExecutionError as e:
+                    logger.warning(
+                        "Plan validation failed on attempt %d: %s", attempt + 1, e
+                    )
+                    if attempt == self.max_retries - 1:
+                        raise
+
+        self.tracer.record(
+            agent=self.__class__.__name__,
+            decision_type="task_execution",
+            rationale=(
+                "Exhausted retries without producing a response; returning empty plan"
+            ),
+            chosen_action="Returned empty plan after exhausted retries",
+            context={"goal": goal, "steps": 0, "attempts": self.max_retries},
+            confidence=0.0,
+        )
+        return []
+
+    # ID: b3e7f1a2-5c9d-4e8f-a2b6-c8d1e4f7a3b9
+    async def _fetch_constitutional_context(self, goal: str) -> str:
+        """
+        Performs RAG against the Constitution for rules relevant to this goal.
+
+        This is the "Legal Counsel" step: the planner consults constitutional
+        rules before proposing a plan, preventing illegal proposals.
+
+        Args:
+            goal: The planning goal to search against
+
+        Returns:
+            Formatted string of relevant constitutional rules, or empty string
+        """
+        try:
+            policy_hits = await self.policy_vectorizer.search_policies(
+                query=goal, limit=5
+            )
+            if not policy_hits:
+                return ""
+
+            rules_text = "\n### Relevant Constitutional Rules\n"
+            for hit in policy_hits:
+                payload = hit.get("payload", {})
+                rule_id = payload.get("rule_id", "unknown")
+                statement = payload.get("statement", "")
+                enforcement = payload.get("enforcement", "reporting")
+                rules_text += f"- [{enforcement.upper()}] {rule_id}: {statement}\n"
+
+            return rules_text
+
+        except Exception as e:
+            # Legal Counsel failure is non-fatal ? plan without it, log the gap
+            logger.warning(
+                "Constitutional context fetch failed (planning without RAG): %s", e
+            )
+            return ""
+
+    # ID: d4f8e2c1-b7a5-9e3f-c6d2-a1f4e7b9c3d5
+    def _load_qa_constraints(self) -> str:
+        """
+        Loads QA constraints from constitutional policy files.
+
+        Uses PathResolver (injected via repo_path) instead of importing
+        settings directly, to comply with architecture.boundary.settings_access.
+        """
+        import json
+
+        import yaml
+
+        path_resolver = PathResolver(self.repo_path)
+
+        for policy_name in ["purity", "quality_assurance"]:
+            try:
+                qa_path = path_resolver.policy(policy_name)
+                if qa_path.exists():
+                    content = qa_path.read_text(encoding="utf-8")
+                    data = (
+                        json.loads(content)
+                        if qa_path.suffix == ".json"
+                        else yaml.safe_load(content)
+                    )
+                    rules = data.get("rules", [])
+                    return (
+                        f"\n### Quality Assurance Targets\n"
+                        f"{json.dumps(rules, indent=2)}"
+                    )
+            except Exception:
+                continue
+
+        return "\n### Quality Assurance Targets\n- Ensure 75%+ test coverage."

will/agents/resource_selector.py

@@ -0,0 +1,228 @@
+# src/will/agents/resource_selector.py
+
+"""
+Mind Reader: Applies constitutional rules for resource selection.
+Stateless - just applies rules from Mind to select best resource.
+"""
+
+from __future__ import annotations
+
+import json
+
+from shared.infrastructure.database.models import (
+    CognitiveRole,
+    LlmResource,
+    RoleResourceAssignment,
+)
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 208f325a-f664-4f3d-9ad3-7b481e1414f9
+class ResourceSelector:
+    """
+    Stateless rule applier: Given roles and resources from Mind,
+    select the best match based on constitutional rules.
+    """
+
+    @staticmethod
+    # ID: 3398db27-785f-4e20-bf33-bd962c8ef8c8
+    def select_resource_for_role(
+        role_name: str,
+        roles: list[CognitiveRole],
+        resources: list[LlmResource],
+        assignments: list[RoleResourceAssignment] | None = None,
+        system_operating_mode: str = "local_only",
+    ) -> LlmResource | None:
+        """
+        Apply Mind rules to select resource for role.
+        Pure function - no state, no side effects.
+
+        ADR-052 Phase 3: the role→resource override now arrives via
+        ``assignments`` (the role_resource_assignments table), not via
+        the dropped ``cognitive_roles.assigned_resource`` column. The
+        primary assignment is the active row at ``priority=1`` for the
+        role. When ``assignments`` is ``None`` or empty, the selector
+        falls back to qualified-by-capability scoring.
+
+        ADR-052 principle #6 (#333): resources are filtered by locality
+        against the effective operating mode — ``role.operating_mode``
+        if set, otherwise ``system_operating_mode`` — before any
+        assignment lookup or capability check.
+        """
+        role = next((r for r in roles if r.role == role_name), None)
+        if not role:
+            logger.error("Role '%s' not found in Mind", role_name)
+            return None
+
+        effective_mode = role.operating_mode or system_operating_mode
+        resources = ResourceSelector._filter_by_locality(
+            resources, effective_mode, role_name
+        )
+        if not resources:
+            logger.error(
+                "No resources match locality for role '%s' under operating_mode='%s'",
+                role_name,
+                effective_mode,
+            )
+            return None
+
+        primary = _primary_assignment(role_name, assignments)
+        if primary is not None:
+            resource = next((r for r in resources if r.name == primary), None)
+            if resource:
+                logger.debug(
+                    "Using assigned resource '%s' for '%s'", resource.name, role_name
+                )
+                return resource
+
+        qualified = [r for r in resources if ResourceSelector._is_qualified(r, role)]
+        if not qualified:
+            logger.error("No qualified resources for role '%s'", role_name)
+            return None
+        best = min(qualified, key=ResourceSelector._score_resource)
+        logger.info("Selected '%s' for '%s' (lowest cost)", best.name, role_name)
+        return best
+
+    @staticmethod
+    # ID: d4e7b2a9-3c5f-4862-9d1c-7e8b5a2f4c6d
+    def select_resources_for_role(
+        role_name: str,
+        roles: list[CognitiveRole],
+        resources: list[LlmResource],
+        assignments: list[RoleResourceAssignment] | None = None,
+        system_operating_mode: str = "local_only",
+    ) -> list[LlmResource]:
+        """
+        Plural counterpart to ``select_resource_for_role`` — return every
+        qualified resource for the role ordered by ``_score_resource``
+        (lowest cost first), with the assigned resource at position 0 if
+        present and resolvable by name.
+
+        Used by callers that need a fallback chain rather than a single
+        best match. Returns an empty list if the role is unknown.
+
+        Mirrors the singular function's semantic that an explicit
+        assignment is honored even if it does not satisfy
+        ``_is_qualified`` — assignment is a deliberate governor override.
+
+        ADR-052 Phase 3: ``assignments`` (the role_resource_assignments
+        table) replaces the dropped ``cognitive_roles.assigned_resource``
+        column as the source of the override.
+
+        ADR-052 principle #6 (#333): resources are filtered by locality
+        against the effective operating mode — ``role.operating_mode``
+        if set, otherwise ``system_operating_mode`` — before assignment
+        lookup or capability scoring.
+        """
+        role = next((r for r in roles if r.role == role_name), None)
+        if not role:
+            logger.error("Role '%s' not found in Mind", role_name)
+            return []
+
+        effective_mode = role.operating_mode or system_operating_mode
+        resources = ResourceSelector._filter_by_locality(
+            resources, effective_mode, role_name
+        )
+
+        qualified = [r for r in resources if ResourceSelector._is_qualified(r, role)]
+        ordered = sorted(qualified, key=ResourceSelector._score_resource)
+
+        primary = _primary_assignment(role_name, assignments)
+        if primary is not None:
+            assigned = next((r for r in resources if r.name == primary), None)
+            if assigned:
+                ordered = [assigned] + [r for r in ordered if r.name != assigned.name]
+
+        return ordered
+
+    @staticmethod
+    # ID: 59b27757-64e3-46b6-9e51-ca01f753e48e
+    def _filter_by_locality(
+        resources: list[LlmResource],
+        effective_mode: str,
+        role_name: str,
+    ) -> list[LlmResource]:
+        """
+        Filter ``resources`` by locality against ``effective_mode``
+        (ADR-052 principle #6 / #333).
+
+        - ``local_only``  → keep ``locality == 'local'`` only
+        - ``remote_only`` → keep ``locality == 'remote'`` only
+        - ``hybrid``      → keep all
+        - any other mode  → fail closed; treat as ``local_only``
+
+        Resources with ``None`` or unrecognised ``locality`` are treated
+        as ``'local'`` (matches the ``server_default`` on the column).
+
+        Excluded resource names are logged at INFO level.
+        """
+        kept: list[LlmResource] = []
+        excluded: list[str] = []
+        for r in resources:
+            locality = r.locality if r.locality in ("local", "remote") else "local"
+            if effective_mode == "hybrid":
+                kept.append(r)
+            elif effective_mode == "remote_only":
+                if locality == "remote":
+                    kept.append(r)
+                else:
+                    excluded.append(r.name)
+            else:
+                # local_only (default) plus any unrecognised mode fail closed to local
+                if locality == "local":
+                    kept.append(r)
+                else:
+                    excluded.append(r.name)
+
+        if excluded:
+            logger.info(
+                "Locality filter excluded %d resource(s) for role '%s' "
+                "under operating_mode='%s': %s",
+                len(excluded),
+                role_name,
+                effective_mode,
+                ", ".join(excluded),
+            )
+
+        return kept
+
+    @staticmethod
+    def _is_qualified(resource: LlmResource, role: CognitiveRole) -> bool:
+        """Check if resource capabilities match role requirements."""
+        res_caps = (
+            json.loads(resource.provided_capabilities)
+            if isinstance(resource.provided_capabilities, str)
+            else resource.provided_capabilities or []
+        )
+        req_caps = (
+            json.loads(role.required_capabilities)
+            if isinstance(role.required_capabilities, str)
+            else role.required_capabilities or []
+        )
+        return set(req_caps).issubset(set(res_caps))
+
+    @staticmethod
+    def _score_resource(resource: LlmResource) -> int:
+        """Lower is better (cost optimization)."""
+        md = (
+            json.loads(resource.performance_metadata)
+            if isinstance(resource.performance_metadata, str)
+            else resource.performance_metadata or {}
+        )
+        return int(md.get("cost_rating", 3))
+
+
+def _primary_assignment(
+    role_name: str,
+    assignments: list[RoleResourceAssignment] | None,
+) -> str | None:
+    """Return the resource name of the active priority=1 assignment, if any."""
+    if not assignments:
+        return None
+    for a in assignments:
+        if a.role == role_name and a.priority == 1 and a.is_active:
+            return a.resource
+    return None

will/agents/strategic_auditor/__init__.py

@@ -0,0 +1,15 @@
+# src/will/agents/strategic_auditor/__init__.py
+
+"""
+StrategicAuditor — CORE's self-awareness agent.
+
+Public API: import StrategicAuditor and StrategicCampaign from here.
+"""
+
+from __future__ import annotations
+
+from will.agents.strategic_auditor.agent import StrategicAuditor
+from will.agents.strategic_auditor.models import RootCauseCluster, StrategicCampaign
+
+
+__all__ = ["RootCauseCluster", "StrategicAuditor", "StrategicCampaign"]