pykel 1.0.0__py3-none-any.whl

kel/__init__.py

@@ -0,0 +1,47 @@
+from kel.models import (
+    ChatModel,
+    EmbeddingModel,
+    ImagePart,
+    Message,
+    MessageStop,
+    ModelResponse,
+    Role,
+    StructuredOutputError,
+    TextDelta,
+    TextPart,
+    ToolCallDelta,
+    ToolResultPart,
+    ToolSpec,
+    ToolUsePart,
+    Usage,
+    agenerate_structured,
+    generate_structured,
+    get_embedding_model,
+    get_model,
+)
+from kel.observability import get_tracer
+
+__all__ = [
+    "ChatModel",
+    "EmbeddingModel",
+    "ImagePart",
+    "Message",
+    "MessageStop",
+    "ModelResponse",
+    "Role",
+    "StructuredOutputError",
+    "TextDelta",
+    "TextPart",
+    "ToolCallDelta",
+    "ToolResultPart",
+    "ToolSpec",
+    "ToolUsePart",
+    "Usage",
+    "agenerate_structured",
+    "generate_structured",
+    "get_embedding_model",
+    "get_model",
+    "get_tracer",
+]
+
+__version__ = "1.0.0"

kel/agents/__init__.py

@@ -0,0 +1,14 @@
+from kel.agents.agent import Agent
+from kel.agents.events import ToolResultEvent
+from kel.agents.orchestration import run_parallel, run_supervisor, run_swarm, sequential_pipeline
+from kel.agents.tool import Tool
+
+__all__ = [
+    "Agent",
+    "Tool",
+    "ToolResultEvent",
+    "run_parallel",
+    "run_supervisor",
+    "run_swarm",
+    "sequential_pipeline",
+]

kel/agents/agent.py

@@ -0,0 +1,160 @@
+"""Single-agent tool-calling loop, built directly on kel.context.Loop
+(step budget + stuck-loop detection) and kel.memory.Memory (working +
+episodic). This is the building block kel.agents' multi-agent orchestration
+patterns compose — a "multi-agent framework" that can't run one agent
+well isn't worth having a supervisor pattern on top of."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Any
+
+from kel.agents.events import ToolResultEvent
+from kel.agents.tool import Tool
+from kel.context.loop import Loop
+from kel.memory.memory import Memory
+from kel.models.base import ChatModel
+from kel.models.types import Message, MessageStop, ModelResponse, Role, StreamEvent, ToolResultPart
+
+
+class Agent:
+    def __init__(
+        self,
+        name: str,
+        model: ChatModel,
+        *,
+        system_prompt: str | None = None,
+        tools: list[Tool] | None = None,
+        memory: Memory | None = None,
+        loop_factory: Callable[[], Loop] | None = None,
+    ):
+        self.name = name
+        self.model = model
+        self.system_prompt = system_prompt
+        self.tools = {t.name: t for t in (tools or [])}
+        self.memory = memory or Memory(session_id=name)
+        self._loop_factory = loop_factory or (lambda: Loop(max_iterations=10))
+
+    def run(self, user_input: str) -> ModelResponse:
+        self.memory.remember_turn(Message.user(user_input))
+        loop = self._loop_factory()
+        tool_specs = [t.to_spec() for t in self.tools.values()] or None
+
+        while True:
+            loop.step()
+            response = self.model.generate(
+                self.memory.working.messages, system=self.system_prompt, tools=tool_specs
+            )
+            self.memory.remember_turn(Message(role=Role.ASSISTANT, content=response.content))
+
+            if response.stop_reason != "tool_use":
+                return response
+
+            result_parts: list[Any] = []
+            for call in response.tool_calls:
+                signature = f"{call.name}:{json.dumps(call.input, sort_keys=True)}"
+                loop.record_action(signature)
+                result_parts.append(self._execute_tool_call(call.id, call.name, call.input))
+
+            self.memory.remember_turn(Message(role=Role.USER, content=result_parts))
+
+    async def arun(self, user_input: str) -> ModelResponse:
+        """Async equivalent of `run()` — same loop, uses the model's real
+        `agenerate()` instead of blocking `generate()`."""
+        self.memory.remember_turn(Message.user(user_input))
+        loop = self._loop_factory()
+        tool_specs = [t.to_spec() for t in self.tools.values()] or None
+
+        while True:
+            loop.step()
+            response = await self.model.agenerate(
+                self.memory.working.messages, system=self.system_prompt, tools=tool_specs
+            )
+            self.memory.remember_turn(Message(role=Role.ASSISTANT, content=response.content))
+
+            if response.stop_reason != "tool_use":
+                return response
+
+            result_parts: list[Any] = []
+            for call in response.tool_calls:
+                signature = f"{call.name}:{json.dumps(call.input, sort_keys=True)}"
+                loop.record_action(signature)
+                result_parts.append(self._execute_tool_call(call.id, call.name, call.input))
+
+            self.memory.remember_turn(Message(role=Role.USER, content=result_parts))
+
+    def run_stream(self, user_input: str) -> Iterator[StreamEvent | ToolResultEvent]:
+        """Like `run()`, but yields StreamEvents as they arrive across
+        every model call in the loop — including intermediate tool-calling
+        turns, not just the final answer. A `ToolResultEvent` is yielded
+        after each tool finishes, so a UI can show "calling search..."
+        progress that model-level streaming alone can't express."""
+        self.memory.remember_turn(Message.user(user_input))
+        loop = self._loop_factory()
+        tool_specs = [t.to_spec() for t in self.tools.values()] or None
+
+        while True:
+            loop.step()
+            response: ModelResponse | None = None
+            for event in self.model.stream(self.memory.working.messages, system=self.system_prompt, tools=tool_specs):
+                yield event
+                if isinstance(event, MessageStop):
+                    response = event.response
+
+            assert response is not None  # every stream() implementation must end with a MessageStop
+            self.memory.remember_turn(Message(role=Role.ASSISTANT, content=response.content))
+
+            if response.stop_reason != "tool_use":
+                return
+
+            result_parts: list[Any] = []
+            for call in response.tool_calls:
+                signature = f"{call.name}:{json.dumps(call.input, sort_keys=True)}"
+                loop.record_action(signature)
+                result_part = self._execute_tool_call(call.id, call.name, call.input)
+                result_parts.append(result_part)
+                yield ToolResultEvent(tool_use_id=call.id, name=call.name, result=result_part)
+
+            self.memory.remember_turn(Message(role=Role.USER, content=result_parts))
+
+    async def arun_stream(self, user_input: str) -> AsyncIterator[StreamEvent | ToolResultEvent]:
+        """Async equivalent of `run_stream()`, using the model's real `astream()`."""
+        self.memory.remember_turn(Message.user(user_input))
+        loop = self._loop_factory()
+        tool_specs = [t.to_spec() for t in self.tools.values()] or None
+
+        while True:
+            loop.step()
+            response: ModelResponse | None = None
+            async for event in self.model.astream(
+                self.memory.working.messages, system=self.system_prompt, tools=tool_specs
+            ):
+                yield event
+                if isinstance(event, MessageStop):
+                    response = event.response
+
+            assert response is not None
+            self.memory.remember_turn(Message(role=Role.ASSISTANT, content=response.content))
+
+            if response.stop_reason != "tool_use":
+                return
+
+            result_parts: list[Any] = []
+            for call in response.tool_calls:
+                signature = f"{call.name}:{json.dumps(call.input, sort_keys=True)}"
+                loop.record_action(signature)
+                result_part = self._execute_tool_call(call.id, call.name, call.input)
+                result_parts.append(result_part)
+                yield ToolResultEvent(tool_use_id=call.id, name=call.name, result=result_part)
+
+            self.memory.remember_turn(Message(role=Role.USER, content=result_parts))
+
+    def _execute_tool_call(self, call_id: str, name: str, tool_input: dict[str, Any]) -> ToolResultPart:
+        tool = self.tools.get(name)
+        if tool is None:
+            return ToolResultPart(tool_use_id=call_id, content=f"error: unknown tool {name!r}", is_error=True)
+        try:
+            return ToolResultPart(tool_use_id=call_id, content=tool(tool_input), is_error=False)
+        except Exception as exc:
+            return ToolResultPart(tool_use_id=call_id, content=f"error: {exc}", is_error=True)

kel/agents/events.py

@@ -0,0 +1,18 @@
+"""Agent-loop-level stream events. A raw `ChatModel.stream()` only covers
+one model call; `Agent.run_stream()`/`arun_stream()` span the whole
+multi-turn tool loop, so a `ToolResultEvent` is added to announce a tool
+finished executing between model calls — the piece a UI needs to show
+"calling search..." progress that plain model-level streaming can't
+express on its own."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from kel.models.types import ToolResultPart
+
+
+class ToolResultEvent(BaseModel):
+    tool_use_id: str
+    name: str
+    result: ToolResultPart

kel/agents/orchestration.py

@@ -0,0 +1,133 @@
+"""Multi-agent orchestration patterns (DESIGN.md 3.11): sequential
+pipeline, supervisor/worker, parallel fan-out with merge, swarm (peer
+handoff). Each pattern shares state through a plain dict — the "shared
+context bus" is not a new abstraction, it's just letting every agent
+read/write the same dict instead of only seeing the last message, which is
+what directly targets the "agent 3 invents context agent 2 never
+produced" failure mode from DESIGN.md 1.2.
+
+Per-agent credentials (own API key/provider vs. one shared key) aren't
+special-cased here at all — that's just whatever `ChatModel` each `Agent`
+was constructed with; these orchestration functions only ever call
+`agent.run(...)`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from kel.agents.agent import Agent
+from kel.context.loop import Loop
+from kel.runtime.graph import Graph
+
+
+def sequential_pipeline(agents: list[Agent]) -> Graph:
+    """Each agent runs after the previous, seeing every prior agent's
+    output via shared graph state (`{agent_name}_output`), not just the
+    latest message."""
+    if not agents:
+        raise ValueError("sequential_pipeline requires at least one agent")
+
+    graph = Graph(entry=agents[0].name)
+
+    def make_node(agent: Agent) -> Callable[[dict[str, Any]], dict[str, Any]]:
+        def node(state: dict[str, Any]) -> dict[str, Any]:
+            upstream = "\n".join(f"[{k}]: {v}" for k, v in state.items() if k.endswith("_output"))
+            task = state.get("input", "")
+            combined = f"{upstream}\n\n{task}".strip() if upstream else task
+            response = agent.run(combined)
+            return {f"{agent.name}_output": response.text}
+
+        return node
+
+    for i, agent in enumerate(agents):
+        graph.add_node(agent.name, make_node(agent))
+        if i + 1 < len(agents):
+            graph.add_edge(agent.name, agents[i + 1].name)
+    graph.set_finish(agents[-1].name)
+    return graph
+
+
+def run_parallel(
+    agents: dict[str, Agent], task: str, *, merge: Callable[[dict[str, str]], str] | None = None
+) -> dict[str, Any]:
+    """Fan the same task out to every agent concurrently, then merge."""
+    with ThreadPoolExecutor(max_workers=max(1, len(agents))) as pool:
+        futures = {name: pool.submit(agent.run, task) for name, agent in agents.items()}
+        results = {name: future.result().text for name, future in futures.items()}
+    merged = merge(results) if merge else "\n\n".join(f"[{k}]: {v}" for k, v in results.items())
+    return {"results": results, "merged": merged}
+
+
+def run_supervisor(supervisor: Agent, workers: dict[str, Agent], task: str, *, max_rounds: int = 5) -> dict[str, Any]:
+    """Supervisor decides each round whether to delegate to a named worker
+    or finish, via a small text protocol (`DELEGATE: name :: instructions`
+    / `DONE: answer`). Bounded by Loop, same as a single agent's tool
+    loop — a stuck supervisor (repeating the same delegation) is caught
+    the same way a stuck tool-calling agent is."""
+    shared_state: dict[str, Any] = {"task": task, "results": {}}
+    loop = Loop(max_iterations=max_rounds)
+
+    while True:
+        loop.step()
+        instruction = (
+            f"Task: {shared_state['task']}\n"
+            f"Available workers: {', '.join(workers)}\n"
+            f"Results so far: {shared_state['results']}\n"
+            "Respond with exactly one line: either 'DELEGATE: <worker> :: <instructions>' "
+            "or 'DONE: <final answer>'."
+        )
+        decision = supervisor.run(instruction).text.strip()
+
+        if decision.upper().startswith("DONE:"):
+            loop.record_action("DONE")
+            shared_state["final_answer"] = decision[len("DONE:") :].strip()
+            return shared_state
+
+        if decision.upper().startswith("DELEGATE:"):
+            rest = decision[len("DELEGATE:") :].strip()
+            worker_name, _, instructions = rest.partition("::")
+            worker_name = worker_name.strip()
+            loop.record_action(f"DELEGATE:{worker_name}")
+            worker = workers.get(worker_name)
+            if worker is None:
+                shared_state["results"][worker_name] = f"error: unknown worker {worker_name!r}"
+                continue
+            result = worker.run(instructions.strip() or shared_state["task"])
+            shared_state["results"][worker_name] = result.text
+        else:
+            # supervisor didn't follow the protocol; surface its raw text
+            # as the final answer rather than looping forever on garbage.
+            shared_state["final_answer"] = decision
+            return shared_state
+
+
+def run_swarm(agents: dict[str, Agent], start_agent: str, task: str, *, max_handoffs: int = 5) -> dict[str, Any]:
+    """Peer handoff: whichever agent is active can either answer directly
+    or hand off to a named peer via `HANDOFF: name :: note`."""
+    shared_state: dict[str, Any] = {"task": task, "trace": []}
+    loop = Loop(max_iterations=max_handoffs)
+    current_name, current_input = start_agent, task
+
+    while True:
+        loop.step()
+        agent = agents[current_name]
+        response = agent.run(current_input).text.strip()
+        shared_state["trace"].append({"agent": current_name, "response": response})
+
+        if response.upper().startswith("HANDOFF:"):
+            rest = response[len("HANDOFF:") :].strip()
+            next_name, _, note = rest.partition("::")
+            next_name = next_name.strip()
+            loop.record_action(f"HANDOFF:{current_name}->{next_name}")
+            if next_name not in agents:
+                shared_state["final_answer"] = response
+                return shared_state
+            current_name, current_input = next_name, note.strip() or task
+            continue
+
+        loop.record_action(f"ANSWER:{current_name}")
+        shared_state["final_answer"] = response
+        return shared_state

kel/agents/tool.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from kel.models.types import ToolSpec
+
+
+class Tool:
+    def __init__(self, name: str, description: str, input_schema: dict[str, Any], fn: Callable[[dict], str]):
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.fn = fn
+
+    def to_spec(self) -> ToolSpec:
+        return ToolSpec(name=self.name, description=self.description, input_schema=self.input_schema)
+
+    def __call__(self, tool_input: dict[str, Any]) -> str:
+        return self.fn(tool_input)

kel/brain/__init__.py

@@ -0,0 +1,16 @@
+from kel.brain.brain import Brain
+from kel.brain.loop_control import should_continue
+from kel.brain.router import EmbeddingRouter, Rule, RuleRouter
+from kel.brain.scheduler import RaceResult, race_to_finish
+from kel.brain.types import Route
+
+__all__ = [
+    "Brain",
+    "EmbeddingRouter",
+    "RaceResult",
+    "Route",
+    "Rule",
+    "RuleRouter",
+    "race_to_finish",
+    "should_continue",
+]

kel/brain/brain.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from kel.brain.types import Route
+from kel.observability.tracer import Tracer, get_tracer
+
+FastTier = Callable[[Any], "Route | None"]
+SlowTier = Callable[[Any], Route]
+
+
+class Brain:
+    """Two-tier router (DESIGN.md 3.14): try the fast tier first; escalate
+    to the slow tier (typically an LLM call) only when the fast tier has
+    no confident answer. Every decision is traced — which tier answered,
+    at what confidence — so a bad routing call is debuggable."""
+
+    def __init__(
+        self,
+        *,
+        fast_tier: FastTier | None = None,
+        slow_tier: SlowTier | None = None,
+        confidence_threshold: float = 0.6,
+    ):
+        self.fast_tier = fast_tier
+        self.slow_tier = slow_tier
+        self.confidence_threshold = confidence_threshold
+
+    def route(self, state: Any, *, tracer: Tracer | None = None) -> Route:
+        tracer = tracer or get_tracer()
+        with tracer.span("kel.brain.route") as span:
+            fast_route: Route | None = None
+            if self.fast_tier is not None:
+                fast_route = self.fast_tier(state)
+                if fast_route is not None:
+                    span.set_attribute("fast_confidence", fast_route.confidence)
+                if fast_route is not None and fast_route.confidence >= self.confidence_threshold:
+                    span.set_attribute("decided_tier", "fast")
+                    span.set_attribute("target", fast_route.target)
+                    return fast_route
+
+            if self.slow_tier is not None:
+                slow_route = self.slow_tier(state)
+                span.set_attribute("decided_tier", "slow")
+                span.set_attribute("target", slow_route.target)
+                return slow_route
+
+            if fast_route is not None:
+                span.set_attribute("decided_tier", "fast_low_confidence_fallback")
+                span.set_attribute("target", fast_route.target)
+                return fast_route
+
+            raise RuntimeError(
+                "Brain could not produce a route: fast tier found no match and no slow tier is configured"
+            )

kel/brain/loop_control.py

@@ -0,0 +1,22 @@
+"""Budget-aware continue-vs-stop decision (DESIGN.md 3.14). Honest v1
+scope: this is a fixed-reserve threshold check, not real marginal-value
+estimation — actually modeling "is another iteration worth it" needs
+outcome data (did past extra iterations actually help?) this project
+doesn't have yet. It's a placeholder for that, with the same call
+signature a smarter version could fill in later."""
+
+from __future__ import annotations
+
+from kel.budget.types import BudgetSnapshot
+
+
+def should_continue(
+    snapshot: BudgetSnapshot, *, min_tokens_reserve: int = 200, min_cost_reserve: float = 0.01
+) -> bool:
+    if snapshot.tokens_remaining is not None and snapshot.tokens_remaining < min_tokens_reserve:
+        return False
+    if snapshot.cost_usd_remaining is not None and snapshot.cost_usd_remaining < min_cost_reserve:
+        return False
+    if snapshot.wall_seconds_remaining is not None and snapshot.wall_seconds_remaining <= 0:
+        return False
+    return True

kel/brain/router.py

@@ -0,0 +1,75 @@
+"""Fast-tier routers (DESIGN.md 3.14, descoped per §7): rules and
+embedding-similarity, deliberately *not* a custom-trained model — that
+needs a training pipeline and real traffic volume this project doesn't
+have on day one. Both expose `predict_route(...) -> Route | None`
+(`None` means "no confident match, ask the slow tier"), the tiny
+interface a genuinely learned router could later drop in behind."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from kel.brain.types import Route
+
+
+@dataclass
+class Rule:
+    predicate: Callable[[dict[str, Any]], bool]
+    target: str
+    confidence: float = 1.0
+    reason: str = "rule matched"
+
+
+class RuleRouter:
+    def __init__(self, rules: list[Rule] | None = None, *, default: str | None = None, default_confidence: float = 0.3):
+        self.rules: list[Rule] = list(rules or [])
+        self.default = default
+        self.default_confidence = default_confidence
+
+    def add_rule(self, predicate: Callable[[dict[str, Any]], bool], target: str, confidence: float = 1.0) -> None:
+        self.rules.append(Rule(predicate=predicate, target=target, confidence=confidence))
+
+    def predict_route(self, state: dict[str, Any]) -> Route | None:
+        for rule in self.rules:
+            if rule.predicate(state):
+                return Route(target=rule.target, confidence=rule.confidence, tier="fast", reason=rule.reason)
+        if self.default is not None:
+            return Route(target=self.default, confidence=self.default_confidence, tier="fast", reason="default fallback")
+        return None
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(y * y for y in b))
+    return 0.0 if norm_a == 0 or norm_b == 0 else dot / (norm_a * norm_b)
+
+
+class EmbeddingRouter:
+    """Nearest-neighbor routing over a small set of labeled examples —
+    "if this looks like past query X, route the way X was routed." Grows
+    more useful as more examples are added over time (e.g. fed by
+    kel.heal's failure->fix history), without ever requiring a training
+    step."""
+
+    def __init__(self, embedder: Callable[[str], list[float]], examples: list[tuple[str, str]] | None = None):
+        self.embedder = embedder
+        self._examples: list[tuple[list[float], str]] = []
+        for text, target in examples or []:
+            self.add_example(text, target)
+
+    def add_example(self, text: str, target: str) -> None:
+        self._examples.append((self.embedder(text), target))
+
+    def predict_route(self, query_text: str) -> Route | None:
+        if not self._examples:
+            return None
+        query_vec = self.embedder(query_text)
+        best_score, best_target = max(
+            ((_cosine_similarity(query_vec, vec), target) for vec, target in self._examples),
+            key=lambda pair: pair[0],
+        )
+        return Route(target=best_target, confidence=best_score, tier="fast", reason="nearest example match")

kel/brain/scheduler.py

@@ -0,0 +1,44 @@
+"""Parallel-to-finish scheduling (DESIGN.md 3.14): run redundant branches
+concurrently, stop waiting as soon as one produces a sufficient result.
+
+Honest limitation: Python cannot forcibly interrupt a running thread.
+"Cancelling" a losing branch here means the caller stops waiting on it and
+its result is discarded — already-started branches keep running to
+completion in the background rather than being killed. Real cancellation
+would need cooperative checkpoints inside each branch or a process-based
+(not thread-based) executor; that's future work, not something to claim
+this does today.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures as cf
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class RaceResult:
+    winner: str | None
+    result: Any
+
+
+def race_to_finish(
+    branches: dict[str, Callable[[], Any]], *, is_sufficient: Callable[[Any], bool] | None = None
+) -> RaceResult:
+    is_sufficient = is_sufficient or (lambda _result: True)
+    pool = cf.ThreadPoolExecutor(max_workers=max(1, len(branches)))
+    futures = {pool.submit(fn): name for name, fn in branches.items()}
+    winner_name: str | None = None
+    winner_result: Any = None
+    try:
+        for future in cf.as_completed(futures):
+            name = futures[future]
+            result = future.result()
+            if is_sufficient(result):
+                winner_name, winner_result = name, result
+                break
+    finally:
+        pool.shutdown(wait=False, cancel_futures=True)
+    return RaceResult(winner=winner_name, result=winner_result)

kel/brain/types.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class Route(BaseModel):
+    target: str
+    confidence: float
+    tier: Literal["fast", "slow"]
+    reason: str | None = None

kel/budget/__init__.py

@@ -0,0 +1,15 @@
+from kel.budget.budgeted import BudgetedChatModel
+from kel.budget.errors import BudgetExceededError
+from kel.budget.pricing import estimate_cost_usd, is_priced
+from kel.budget.tracker import BudgetTracker
+from kel.budget.types import Budget, BudgetSnapshot
+
+__all__ = [
+    "Budget",
+    "BudgetExceededError",
+    "BudgetSnapshot",
+    "BudgetTracker",
+    "BudgetedChatModel",
+    "estimate_cost_usd",
+    "is_priced",
+]