kyno 0.1.0__py3-none-any.whl

kyno/__init__.py

@@ -0,0 +1,11 @@
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    # `import kyno` stays cheap for the CLI and the server; the SDK loads on
+    # first use of kyno.connect.
+    if name == "connect":
+        from kyno.sdk import connect
+
+        return connect
+    raise AttributeError(f"module 'kyno' has no attribute {name!r}")

kyno/adapters/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Camilo Zambrano
+
+
+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.

kyno/adapters/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+"""Adapters that wire the Kyno control plane into agent orchestrators.
+
+The framework-agnostic core lives in ``kyno.sdk``; per-framework
+shims live in ``kyno.adapters.crewai`` and ``kyno.adapters.langgraph`` and
+are installed with the ``kyno[crewai]`` / ``kyno[langgraph]`` extras.
+"""

kyno/adapters/crewai/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+"""CrewAI shim — install with ``pip install "kyno[crewai]"``."""
+
+from kyno.adapters.crewai.hooks import CrewAiKyno
+
+__all__ = ["CrewAiKyno"]

kyno/adapters/crewai/hooks.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from typing import Any
+
+from kyno.sdk.binder import DirectionBinder
+from kyno.sdk.cell import Direction, refresh
+from kyno.sdk.gate import RealignmentGate
+from kyno.sdk.trace import RunTrace
+
+
+class TaskBlockedByKyno(RuntimeError):
+    """Raised from task_callback when the gate rules DRIFTED.
+
+    task_callback has no return-based block signal the way before_llm_call /
+    after_llm_call do, so raising is the only lever at this granularity --
+    the exception propagates through Crew.kickoff() like any other.
+    """
+
+    def __init__(self, reason: str, *, direction: Direction) -> None:
+        super().__init__(
+            f"kyno gate blocked task: {reason} "
+            f"(constitution={direction.constitution}, version={direction.version})"
+        )
+        self.reason = reason
+        self.direction = direction
+
+
+class CrewAiKyno:
+    """Direction injection (before_llm_call) and the gate (task_callback) for CrewAI.
+
+    Gating is per finished task, not per LLM call: a task can involve
+    several model calls, and once a real judge is attached, gating each one
+    multiplies its cost by every call instead of charging it once.
+    """
+
+    def __init__(
+        self,
+        binder: DirectionBinder,
+        gate: RealignmentGate | None = None,
+        constitution: str = "default",
+        trace: RunTrace | None = None,
+    ) -> None:
+        self._binder = binder
+        # No gate unless one is handed in. Kyno carries direction; checking the
+        # work against it needs a judge Kyno does not ship, so a default gate
+        # would only ever answer "unchecked".
+        self.gate = gate
+        self.constitution = constitution
+        self.trace = trace
+
+    def before_llm_call(self, ctx: Any) -> None:
+        direction = self._binder.bind(self.constitution)
+        messages = getattr(ctx, "messages", None)
+        if messages is None:
+            messages = ctx.messages = []
+        # CrewAI's executor keeps a reference to this list, so rebinding it
+        # would silently detach the hook from the call it is editing.
+        messages[:] = refresh(
+            messages,
+            direction.render(),
+            text_of=_system_content,
+            make=lambda block: {"role": "system", "content": block},
+        )
+
+    def task_callback(self, task_output: Any) -> None:
+        direction = self._binder.cell.get(self.constitution) or Direction.empty(self.constitution)
+        output = _output_text(task_output)
+        decision = self.gate.review(output=output, direction=direction) if self.gate else None
+        if self.trace is not None:
+            self.trace.record_step(
+                agent=_name_of(getattr(task_output, "agent", "")),
+                goal=str(getattr(task_output, "description", "")),
+                output=output,
+                direction=direction,
+                decision=decision,
+            )
+        if decision is not None and decision.halts(can_pause=False):
+            # CrewAI cannot resume a paused task, so a pause behaves like a
+            # block here.
+            raise TaskBlockedByKyno(decision.reason, direction=direction)
+
+    def step_callback(self, step_output: Any) -> None:
+        if self.trace is None:
+            return
+        direction = self._binder.cell.get(self.constitution) or Direction.empty(self.constitution)
+        self.trace.record_step(
+            agent=_name_of(getattr(step_output, "agent", "")),
+            goal=_name_of(getattr(step_output, "task", "")),
+            output=str(getattr(step_output, "output", step_output)),
+            direction=direction,
+        )
+
+    def register(self) -> None:
+        """Only before_llm_call is globally registrable; the callbacks below
+        are Crew constructor parameters. The decorator form stamps an
+        attribute on what it is handed and so rejects a bound method."""
+        from crewai.hooks import register_before_llm_call_hook
+
+        register_before_llm_call_hook(self.before_llm_call)
+
+    def unregister(self) -> bool:
+        from crewai.hooks import unregister_before_llm_call_hook
+
+        return unregister_before_llm_call_hook(self.before_llm_call)
+
+
+def _system_content(message: Any) -> str:
+    # Only a system message can be the block this adapter injected; marker
+    # text on any other role is data (a tool result echoed into the
+    # transcript, a user paste) and is never the adapter's to delete.
+    if not isinstance(message, dict) or message.get("role") != "system":
+        return ""
+    content = message.get("content", "")
+    return content if isinstance(content, str) else ""
+
+
+def _output_text(ctx: Any) -> str:
+    for attribute in ("raw", "response", "payload", "output"):
+        value = getattr(ctx, attribute, None)
+        if value:
+            return str(value)
+    return ""
+
+
+def _name_of(value: Any) -> str:
+    for attribute in ("role", "name", "description"):
+        found = getattr(value, attribute, None)
+        if found:
+            return str(found)
+    return str(value)

kyno/adapters/langgraph/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: MIT
+"""LangGraph shim — install with ``pip install "kyno[langgraph]"``."""
+
+from kyno.adapters.langgraph.nodes import (
+    KynoState,
+    direction_from_state,
+    direction_node,
+    direction_update,
+    gate_node,
+    pull_before,
+)
+
+__all__ = [
+    "KynoState",
+    "direction_from_state",
+    "direction_node",
+    "direction_update",
+    "gate_node",
+    "pull_before",
+]

kyno/adapters/langgraph/nodes.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypedDict
+
+from langgraph.types import interrupt
+
+from kyno.sdk.binder import DirectionBinder
+from kyno.sdk.cell import COMPACT, Direction
+from kyno.sdk.gate import Action, RealignmentGate
+from kyno.sdk.trace import RunTrace
+
+
+class KynoState(TypedDict, total=False):
+    """Inherit this in your graph's state schema. LangGraph only carries the
+    keys a schema declares, so without it the direction a node pulls never
+    reaches the gate node that must judge against it -- silently.
+    """
+
+    kyno_constitution: str
+    kyno_version: int
+    kyno_mission: str
+    kyno_principles: list[dict]
+    kyno_context: str
+    kyno_direction: str
+    kyno_verdict: str
+    kyno_checked: bool
+    kyno_blocked: bool
+
+
+def direction_update(direction: Direction) -> dict:
+    """Direction travels in graph state so a persisted checkpoint says which
+    constitution and version a step served, without any other context."""
+    return {
+        "kyno_constitution": direction.constitution,
+        "kyno_version": direction.version,
+        "kyno_mission": direction.mission,
+        "kyno_principles": [p.to_dict() for p in direction.principles],
+        "kyno_direction": direction.render(),
+        "kyno_context": direction.context,
+    }
+
+
+def direction_from_state(state: dict) -> Direction:
+    return Direction(
+        constitution=state.get("kyno_constitution", "default"),
+        version=state.get("kyno_version", 0),
+        mission=state.get("kyno_mission", ""),
+        principles=state.get("kyno_principles", ()),
+        context=state.get("kyno_context", COMPACT),
+    )
+
+
+def direction_node(binder: DirectionBinder, constitution: str = "default") -> Callable:
+    """A sentinel node, and the `pre_model_hook` for prebuilt ReAct agents:
+    one refresh ahead of a fan-out serves every node downstream."""
+
+    def node(state: dict) -> dict:
+        return direction_update(binder.bind(constitution))
+
+    return node
+
+
+def pull_before(binder: DirectionBinder, constitution: str = "default") -> Callable:
+    def decorator(node: Callable) -> Callable:
+        @functools.wraps(node)
+        def wrapped(state: dict, *args: Any, **kwargs: Any) -> dict:
+            direction = binder.bind(constitution)
+            update = direction_update(direction)
+            result = node({**state, **update}, *args, **kwargs) or {}
+            return {**update, **result}
+
+        return wrapped
+
+    return decorator
+
+
+def gate_node(
+    gate: RealignmentGate,
+    output_key: str = "output",
+    trace: RunTrace | None = None,
+) -> Callable:
+    """The gate as a node. It judges against the direction already in state --
+    binding is direction_node's job. On PAUSE it interrupts; LangGraph re-runs the
+    node from its start on resume, so everything before the interrupt here
+    is idempotent (a review and a record)."""
+
+    def node(state: dict) -> dict:
+        direction = direction_from_state(state)
+        output = str(state.get(output_key, ""))
+        decision = gate.review(output=output, direction=direction)
+        if trace is not None:
+            trace.record_step(
+                agent=str(state.get("kyno_agent", "graph")),
+                goal=str(state.get("kyno_goal", "")),
+                output=output,
+                direction=direction,
+                decision=decision,
+            )
+        blocked = decision.halts(can_pause=True)
+        if decision.action is Action.PAUSE:
+            answer = interrupt(
+                {
+                    "reason": decision.reason,
+                    "verdict": decision.verdict.value,
+                    "constitution": decision.constitution,
+                    "version": decision.version,
+                    "output": output,
+                }
+            )
+            blocked = not (isinstance(answer, dict) and answer.get("accept") is True)
+        return {
+            "kyno_verdict": decision.verdict.value,
+            "kyno_checked": decision.checked,
+            "kyno_blocked": blocked,
+        }
+
+    return node

kyno/authoring.py

@@ -0,0 +1,85 @@
+"""Reading a constitution out of a file an operator wrote.
+
+A declaration is paragraphs and a description is a paragraph; both are
+miserable to type as command-line flags and worse to re-type on the next
+edit. A file is where a rich constitution actually gets written, and it is
+YAML because a block scalar is the readable way to hold prose (JSON parses
+too -- it is valid YAML).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from kyno.errors import AuthoringError, CoherenceError
+from kyno.models import Principle, normalize_principles
+
+# Every key a file may carry. An unknown one is refused rather than ignored:
+# a constitution missing the half somebody thought they wrote is worse than
+# a file that will not load.
+FIELDS = ("constitution", "mission", "declaration", "principles", "note", "by")
+
+
+@dataclass(frozen=True)
+class ConstitutionFile:
+    """What the file said. None means the key was absent, which set_direction
+    reads as "carry this one forward" -- clearing a field is spelled ""."""
+
+    constitution: str | None = None
+    mission: str | None = None
+    declaration: str | None = None
+    principles: tuple[Principle, ...] | None = None
+    note: str | None = None
+    created_by: str | None = None
+
+
+def read_constitution_file(path: str) -> ConstitutionFile:
+    document = _load(path)
+    if not isinstance(document, Mapping):
+        raise AuthoringError(f"{path}: a constitution file must be a mapping of fields")
+    unknown = sorted(set(document) - set(FIELDS))
+    if unknown:
+        raise AuthoringError(
+            f"{path}: unknown field(s) {', '.join(unknown)} "
+            f"(a constitution file takes {', '.join(FIELDS)})"
+        )
+    return ConstitutionFile(
+        constitution=_text(document, "constitution", path),
+        mission=_text(document, "mission", path),
+        declaration=_text(document, "declaration", path),
+        principles=_principles(document, path),
+        note=_text(document, "note", path),
+        created_by=_text(document, "by", path),
+    )
+
+
+def _load(path: str):
+    import yaml
+
+    try:
+        return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        raise AuthoringError(f"{path} could not be read: {exc}") from None
+
+
+def _text(document: Mapping, field: str, path: str) -> str | None:
+    # A key with nothing after it is far more often a half-written file than
+    # a deletion, so it reads as absent; clearing a field is spelled "".
+    value = document.get(field)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise AuthoringError(f"{path}: {field} must be text, got {type(value).__name__}")
+    return value.strip()
+
+
+def _principles(document: Mapping, path: str) -> tuple[Principle, ...] | None:
+    value = document.get("principles")
+    if value is None:
+        return None
+    try:
+        return normalize_principles(value)
+    except CoherenceError as exc:
+        raise AuthoringError(f"{path}: principles: {exc}") from None