cordis-runtime 0.1.1__py3-none-any.whl

cordis_runtime/__init__.py

@@ -0,0 +1,7 @@
+"""Minimal host-facing runtime for Cordis Core."""
+
+from .runtime import CordisHostRuntime, RuntimeValidationError
+
+__version__ = "0.1.1"
+
+__all__ = ["CordisHostRuntime", "RuntimeValidationError", "__version__"]

cordis_runtime/runtime.py

@@ -0,0 +1,374 @@
+"""Thin deterministic bridge from a host task to Cordis Core and a model."""
+
+from __future__ import annotations
+
+import copy
+import re
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+from cordis_core import CordisRuntime
+from cordis_memory import CognitiveStore
+
+
+RUNTIME_SCHEMA = "cordis.runtime.v1"
+VALID_MODES = {"fast", "advisory", "high_intervention", "takeover"}
+DESTRUCTIVE_TERMS = {"delete", "drop", "destroy", "wipe", "truncate", "remove", "format", "生产", "删除", "清空", "销毁"}
+
+
+class RuntimeValidationError(ValueError):
+    """Raised when a host breaks the minimal Runtime contract."""
+
+
+def _tokens(value: str) -> set[str]:
+    return set(re.findall(r"[a-z0-9_]{2,}|[\u4e00-\u9fff]{2}", value.lower()))
+
+
+def _string_list(value: Any, field: str) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item.strip() for item in value):
+        raise RuntimeValidationError(f"{field} must be a list of non-empty strings")
+    return [item.strip()[:1000] for item in value[:20]]
+
+
+class CordisHostRuntime:
+    """Expose Core as compact context and deterministic host control signals."""
+
+    def __init__(self, core: CordisRuntime, memory: Optional[CognitiveStore] = None):
+        if not isinstance(core, CordisRuntime):
+            raise RuntimeValidationError("core must be a CordisRuntime")
+        if memory is not None and not isinstance(memory, CognitiveStore):
+            raise RuntimeValidationError("memory must be a CognitiveStore or None")
+        self.core = core
+        self.memory = memory
+        self._focus: Dict[str, Dict[str, Any]] = {}
+
+    @staticmethod
+    def _control_mode(ir: Mapping[str, Any], complexity: float) -> str:
+        task = ir["task"]
+        prediction = ir["prediction"]
+        strategy = ir["strategy"]
+        if task["stakes"] == "critical" or (
+            strategy["status"] == "avoid_until_revalidated" and prediction["risk_score"] >= 0.62
+        ):
+            return "takeover"
+        if ir["escalation"]["advisor_required"]:
+            return "high_intervention"
+        if (
+            task["stakes"] == "low"
+            and complexity <= 0.25
+            and not ir["state"]["relevant_memory"]
+            and not ir["state"]["relevant_world_patterns"]
+        ):
+            return "fast"
+        return "advisory"
+
+    @staticmethod
+    def _exploration_policy(ir: Mapping[str, Any]) -> Dict[str, Any]:
+        """Choose exploit, explore, or revalidate from explicit evidence only."""
+        evidence = ir["prediction"]["strategy_evidence"]
+        entropy = ir["prediction"]["strategy_entropy"]
+        uses = int(evidence["uses"])
+        failures = int(evidence["failures"])
+        if failures >= 1 and ir["strategy"]["status"] == "avoid_until_revalidated":
+            return {
+                "mode": "revalidate",
+                "reason": "the selected strategy has failed more often than it has succeeded",
+                "requirements": ["do_not_repeat_failed_strategy", "compare_alternative_strategy", "verify_assumption"],
+            }
+        if uses < 3:
+            return {
+                "mode": "explore",
+                "reason": "the selected strategy has insufficient evidence",
+                "requirements": ["treat_success_as_tentative", "record_observable_evidence"],
+            }
+        if entropy is not None and entropy < 0.35:
+            return {
+                "mode": "explore",
+                "reason": "strategy selection is overly concentrated",
+                "requirements": ["propose_alternative_strategy", "do_not_randomly_explore_high_risk_work"],
+            }
+        return {
+            "mode": "exploit",
+            "reason": "current strategy has sufficient non-concentrated evidence",
+            "requirements": ["continue_to_collect_evidence"],
+        }
+
+    @staticmethod
+    def _prompt(
+        ir: Mapping[str, Any], focus: Mapping[str, Any], mode: str, cognition: Iterable[Mapping[str, Any]] = ()
+    ) -> str:
+        memory = [item.get("lesson") for item in ir["state"]["relevant_memory"] if item.get("lesson")]
+        patterns = [item["statement"] for item in ir["state"]["relevant_world_patterns"]]
+        acceptance = [
+            f"{item['id']}: {item['description']}" for item in ir["verification"]["acceptance_evidence"]
+        ]
+
+        sections = [
+            "[CORDIS CONTEXT]",
+            f"Task ID: {ir['task']['id']}",
+            f"Goal: {ir['task']['goal']}",
+            f"Control mode: {mode}",
+            f"Current step: {focus['current_step']}",
+            f"Risk: {ir['prediction']['risk_score']}",
+        ]
+        if focus["constraints"]:
+            sections.append("Constraints: " + " | ".join(focus["constraints"]))
+        if memory:
+            sections.append("Relevant experience: " + " | ".join(memory[:3]))
+        if patterns:
+            sections.append("World patterns: " + " | ".join(patterns[:3]))
+        cognition = list(cognition)
+        if cognition:
+            items = [f"[{item['id']}] {item['content']}" for item in cognition[:3]]
+            sections.append("Cognitive store: " + " | ".join(items))
+        sections.extend(
+            [
+                "Prefer: " + " | ".join(ir["strategy"]["prefer"]),
+                "Avoid: " + " | ".join(ir["strategy"]["avoid"]),
+            ]
+        )
+        if acceptance:
+            sections.append("Acceptance: " + " | ".join(acceptance))
+        if mode == "fast":
+            sections.append("Act on the smallest reversible next step; return observable evidence.")
+        elif mode == "advisory":
+            sections.append("Use this context while choosing and executing the next step.")
+        elif mode == "high_intervention":
+            sections.append("State the next step and its verification before acting.")
+        else:
+            sections.append("Do not act until a reviewed plan and verification path are available.")
+        return "\n".join(sections)
+
+    def _memory_snapshot(self, task: Mapping[str, Any]) -> list[Dict[str, Any]]:
+        if not self.memory:
+            return []
+        result = self.memory.query(
+            intent=str(task["goal"]), project_id=str(task["project_id"]), scopes=("project", "global"), limit=3
+        )
+        return [
+            item for item in result["items"]
+            if item["kind"] != "pattern" or item["status"] == "active"
+        ]
+
+    def export_focus(self) -> Dict[str, Dict[str, Any]]:
+        """Return a serializable snapshot of active host-task focus.
+
+        Core state already survives restarts. Hosts such as a CLI or MCP server
+        may need this separate snapshot because they receive later task events
+        in a new process.
+        """
+        return copy.deepcopy(self._focus)
+
+    def restore_focus(self, value: Mapping[str, Mapping[str, Any]]) -> None:
+        """Restore a snapshot produced by :meth:`export_focus`.
+
+        This restores host control metadata only; it neither opens Core tasks
+        nor changes learning state.
+        """
+        if not isinstance(value, Mapping):
+            raise RuntimeValidationError("focus must be an object")
+        restored: Dict[str, Dict[str, Any]] = {}
+        for task_id, focus in value.items():
+            if not isinstance(task_id, str) or not task_id.strip() or not isinstance(focus, Mapping):
+                raise RuntimeValidationError("focus must map task IDs to focus objects")
+            required = ("task_id", "goal", "current_step", "project_id", "control_mode", "constraints", "seen_cognition_ids")
+            if any(field not in focus for field in required):
+                raise RuntimeValidationError("focus object is missing required fields")
+            if focus["task_id"] != task_id:
+                raise RuntimeValidationError("focus task_id must match its map key")
+            if focus["control_mode"] not in VALID_MODES:
+                raise RuntimeValidationError("focus control_mode is invalid")
+            for field in ("goal", "current_step", "project_id"):
+                if not isinstance(focus[field], str) or not focus[field].strip():
+                    raise RuntimeValidationError(f"focus.{field} must be a non-empty string")
+            _string_list(focus["constraints"], "focus.constraints")
+            _string_list(focus["seen_cognition_ids"], "focus.seen_cognition_ids")
+            restored[task_id] = copy.deepcopy(dict(focus))
+        self._focus = restored
+
+    def begin(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        """Run Core Preflight and return host control plus compact model context."""
+        if not isinstance(payload, Mapping):
+            raise RuntimeValidationError("payload must be an object")
+        complexity = payload.get("complexity", 0.5)
+        if not isinstance(complexity, (int, float)):
+            raise RuntimeValidationError("complexity must be numeric")
+        constraints = _string_list(payload.get("constraints"), "constraints")
+        current_step = payload.get("current_step")
+        if current_step is not None and (not isinstance(current_step, str) or not current_step.strip()):
+            raise RuntimeValidationError("current_step must be a non-empty string")
+
+        ir = self.core.preflight(payload)
+        task_id = ir["task"]["id"]
+        cognition = self._memory_snapshot(ir["task"])
+        focus = {
+            "task_id": task_id,
+            "goal": ir["task"]["goal"],
+            "current_step": current_step.strip()[:1000] if current_step else ir["task"]["goal"],
+            "constraints": constraints,
+            "project_id": ir["task"]["project_id"],
+            "seen_cognition_ids": [item["id"] for item in cognition],
+        }
+        mode = self._control_mode(ir, max(0.0, min(1.0, float(complexity))))
+        exploration = self._exploration_policy(ir)
+        focus["control_mode"] = mode
+        self._focus[task_id] = focus
+        return {
+            "schema": RUNTIME_SCHEMA,
+            "task_id": task_id,
+            "control": {
+                "mode": mode,
+                "advisor_required": ir["escalation"]["advisor_required"],
+                "execution_allowed": mode != "takeover",
+            },
+            "exploration": exploration,
+            "focus": copy.deepcopy(focus),
+            "cognitive_ir": ir,
+            "cognition": cognition,
+            "model_context": self._prompt(ir, focus, mode, cognition)
+            + "\nExploration policy: "
+            + exploration["mode"]
+            + ". "
+            + " | ".join(exploration["requirements"]),
+        }
+
+    def query(
+        self,
+        task_id: str,
+        *,
+        intent: str,
+        scopes: Iterable[str] = ("project", "global"),
+        kinds: Iterable[str] = ("episode", "knowledge", "pattern", "capability", "principle"),
+        limit: int = 3,
+    ) -> Dict[str, Any]:
+        """Return novel cognition for an active task; never repeat seen item IDs."""
+        focus = self._focus.get(task_id)
+        if not focus:
+            raise RuntimeValidationError("unknown active task_id")
+        if not self.memory:
+            return {"items": [], "status": "memory_not_configured", "excluded_ids": []}
+        result = self.memory.query(
+            intent=intent,
+            project_id=focus["project_id"],
+            scopes=scopes,
+            kinds=kinds,
+            exclude_ids=focus["seen_cognition_ids"],
+            limit=limit,
+        )
+        focus["seen_cognition_ids"].extend(item["id"] for item in result["items"])
+        return result
+
+    def check_action(self, task_id: str, action: Mapping[str, Any]) -> Dict[str, Any]:
+        """Return a cheap drift signal; the host decides whether to enforce it."""
+        focus = self._focus.get(task_id)
+        if not focus:
+            raise RuntimeValidationError("unknown active task_id")
+        if not isinstance(action, Mapping):
+            raise RuntimeValidationError("action must be an object")
+        description = action.get("description")
+        purpose = action.get("purpose")
+        if not isinstance(description, str) or not description.strip():
+            raise RuntimeValidationError("action.description is required")
+        if not isinstance(purpose, str) or not purpose.strip():
+            raise RuntimeValidationError("action.purpose is required")
+        focus_tokens = _tokens(f"{focus['goal']} {focus['current_step']}")
+        action_tokens = _tokens(f"{description} {purpose}")
+        overlap = sorted(focus_tokens & action_tokens)
+        aligned = bool(overlap) or not focus_tokens
+        dangerous_terms = sorted(DESTRUCTIVE_TERMS & action_tokens)
+        requires_review = bool(dangerous_terms)
+        result = {
+            "task_id": task_id,
+            "aligned": aligned,
+            "signal": "destructive_action_review" if requires_review else ("on_focus" if aligned else "possible_drift"),
+            "heuristic": True,
+            "reason": (
+                "destructive action term detected: " + ", ".join(dangerous_terms)
+                if requires_review
+                else ("shared lexical terms: " + ", ".join(overlap) if aligned else "no shared lexical terms")
+            ),
+            "shared_terms": overlap[:10],
+            "dangerous_terms": dangerous_terms,
+            "requires_review": requires_review,
+            "control_mode": focus["control_mode"],
+        }
+        if self.memory:
+            self.memory.record_event(
+                {
+                    "event_type": "action_checked" if aligned else "possible_drift",
+                    "scope": "workflow",
+                    "project_id": focus["project_id"],
+                    "task_id": task_id,
+                    "subject": description,
+                    "actual": purpose,
+                    "expected": focus["current_step"],
+                    "error_class": None if aligned else "attention_drift",
+                }
+            )
+        return result
+
+    def observe(self, task_id: str, event: Mapping[str, Any]) -> Dict[str, Any]:
+        """Record any plan, tool, artifact, test, or verification event for an active task.
+
+        Hosts use this one method instead of maintaining a separate taxonomy for
+        shell errors, test failures, model mistakes, timeouts, or tool results.
+        """
+        focus = self._focus.get(task_id)
+        if not focus:
+            raise RuntimeValidationError("unknown active task_id")
+        if not isinstance(event, Mapping):
+            raise RuntimeValidationError("event must be an object")
+        if not self.memory:
+            return {"status": "memory_not_configured"}
+        normalized = dict(event)
+        normalized["task_id"] = task_id
+        normalized["project_id"] = focus["project_id"]
+        normalized.setdefault("scope", "workflow")
+        return self.memory.record_event(normalized)
+
+    def finish(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        """Finalize a Runtime task through Core's evidence-bound feedback."""
+        task_id = payload.get("task_id") if isinstance(payload, Mapping) else None
+        if not isinstance(task_id, str) or task_id not in self._focus:
+            raise RuntimeValidationError("unknown active task_id")
+        focus = self._focus[task_id]
+        result = self.core.feedback(payload)
+        if self.memory:
+            outcome = result["learning"]["event"]["outcome"] if "learning" in result else result["event"]["outcome"]
+            event = result["event"]
+            self.memory.record_event(
+                {
+                    "event_type": f"task_{outcome}",
+                    "scope": "workflow",
+                    "project_id": focus["project_id"],
+                    "task_id": task_id,
+                    "subject": focus["goal"],
+                    "actual": event["lesson"] or outcome,
+                    "expected": "task acceptance criteria",
+                    "error_class": event["attribution"] if outcome != "success" else None,
+                }
+            )
+            self.memory.remember(
+                kind="episode",
+                subject=focus["goal"],
+                content=event["lesson"] or f"Task ended with {outcome}.",
+                scope="project",
+                project_id=focus["project_id"],
+                task_id=task_id,
+                source_id=event["id"],
+                evidence={"outcome": outcome, "attribution": event["attribution"]},
+                confidence=0.7 if outcome == "success" else 0.5,
+                metadata={"strategy_id": result["event"].get("strategy_id"), "outcome": outcome},
+            )
+            if event["attribution"] == "world" and event.get("lesson"):
+                self.memory.observe_pattern(
+                    statement=event["lesson"],
+                    subject=f"world:{focus['project_id']}",
+                    scope="project",
+                    project_id=focus["project_id"],
+                    source_id=event["id"],
+                    evidence={"task_id": task_id, "outcome": outcome},
+                )
+        del self._focus[task_id]
+        return {"schema": "cordis.runtime-result.v1", "learning": result}

cordis_runtime-0.1.1.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: cordis-runtime
+Version: 0.1.1
+Summary: Minimal host runtime for Cordis Core.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cordis-core<0.2,>=0.1.1
+Requires-Dist: cordis-memory<0.2,>=0.1.1
+Dynamic: license-file
+
+# Cordis Runtime
+
+Cordis Runtime is the minimal host bridge for Cordis Core. It does not call a
+model and it does not split tasks.
+
+The semantic boundary is explicit:
+
+```text
+user language
+    -> host/main model interprets intent
+    -> structured Task Contract
+    -> Cordis Runtime + Core
+    -> compact model context and control signal
+```
+
+For an agent with tool calling, the main model fills the `begin` arguments as
+part of its normal turn. This does not require a second model call. A non-agent
+application that accepts raw natural language must provide an optional Task
+Interpreter. Task decomposition remains the responsibility of a Planner.
+
+## Minimal use
+
+```python
+from cordis_core import CordisRuntime
+from cordis_runtime import CordisHostRuntime
+
+runtime = CordisHostRuntime(CordisRuntime("cordis-state.json"))
+
+turn = runtime.begin({
+    "task": {
+        "goal": "Fix the login integration test",
+        "domain": "software",
+        "project_id": "my-app",
+        "strategy_id": "inspect_logs_first",
+        "stakes": "medium",
+    },
+    "complexity": 0.4,
+    "current_step": "Inspect the failing test and logs",
+    "constraints": ["Do not change the database schema"],
+    "acceptance_evidence": ["login integration test passes"],
+})
+
+# Send turn["model_context"] to the host's existing planner or main model.
+```
+
+The host calls `check_action(...)` before an action, `observe(...)` for any
+plan/tool/artifact/test/error event, and `finish(...)` with observable evidence
+after execution. When constructed with a `CognitiveStore`, Runtime retrieves a
+small project-safe snapshot on `begin`, supports deduplicated `query(...)`, and
+persists the final episode through `finish(...)`.
+
+## v0.1 boundary
+
+Runtime provides:
+
+- structured Task Contract validation through Core;
+- task-local Focus State;
+- deterministic control modes;
+- compact model context;
+- an experimental lexical drift heuristic, never a safety or attention guarantee;
+- evidence-bound feedback delegation.
+- optional `CognitiveStore` retrieval, event capture, and episode write-back.
+
+Runtime does not provide natural-language interpretation, planning, model
+calls, tool execution, durable conversation memory, or an HTTP service.
+
+`check_action` is deliberately conservative metadata: it reports lexical
+overlap and obvious destructive terms. Hosts must not treat it as semantic
+understanding, an authorization decision, or a complete attention-drift guard.

cordis_runtime-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+cordis_runtime/__init__.py,sha256=YmP3qYlZmqXWyQsk_do5_0jAS4UXMBmSOxmiiOc5EPo,212
+cordis_runtime/runtime.py,sha256=bLFhRHYX1sm5nXsaXy-gTvNzGTf__foMomw6TQVQOSQ,17201
+cordis_runtime-0.1.1.dist-info/licenses/LICENSE,sha256=loBxr-Xd1Q86pUdsN4__1DtAre2dUcrKUIhv3jQH_dc,1076
+cordis_runtime-0.1.1.dist-info/METADATA,sha256=zMKpVB2aD_lOJrH7VwMb7ObrF-Ueg5eGu_wX4iy-ZDI,2758
+cordis_runtime-0.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cordis_runtime-0.1.1.dist-info/top_level.txt,sha256=yfi7NMJSO_8vidnZbTs9wqSCAWMKQNn1UNTenPimFbo,15
+cordis_runtime-0.1.1.dist-info/RECORD,,

cordis_runtime-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cordis_runtime-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cordis Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cordis_runtime-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cordis_runtime