agentkernel 0.9.0__tar.gz → 0.9.1__tar.gz

{agentkernel-0.9.0 → agentkernel-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.0
+Version: 0.9.1
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -44,7 +44,7 @@ Requires-Dist: nest-asyncio>=1.6.0 ; extra == 'langfuse'
 Requires-Dist: langgraph~=1.2.10 ; extra == 'langgraph'
 Requires-Dist: langgraph-prebuilt~=1.1.0 ; extra == 'langgraph'
 Requires-Dist: langchain~=1.3.10 ; extra == 'langgraph'
-Requires-Dist: langchain-community==0.4.1 ; extra == 'langgraph'
+Requires-Dist: langchain-community~=0.4.1 ; extra == 'langgraph'
 Requires-Dist: litellm~=1.89.2 ; extra == 'langgraph'
 Requires-Dist: logfire>=3.0 ; extra == 'logfire'
 Requires-Dist: fastmcp>=3.2.0,<4.0.0 ; extra == 'mcp'
@@ -57,6 +57,7 @@ Requires-Dist: openai-agents>=0.7.0 ; extra == 'openai'
 Requires-Dist: openinference-instrumentation-openai-agents>=1.4.0 ; extra == 'openai'
 Requires-Dist: openai-guardrails>=0.2.1 ; extra == 'openai'
 Requires-Dist: traceloop-sdk>=0.61.0 ; extra == 'openllmetry'
+Requires-Dist: opik>=1.7.0 ; extra == 'opik'
 Requires-Dist: pydantic-ai-slim~=2.13.0 ; extra == 'pydanticai'
 Requires-Dist: openinference-instrumentation-pydantic-ai>=0.1.17 ; extra == 'pydanticai'
 Requires-Dist: redis>=7.1.0 ; extra == 'redis'
@@ -111,6 +112,7 @@ Provides-Extra: nats
 Provides-Extra: neo4j
 Provides-Extra: openai
 Provides-Extra: openllmetry
+Provides-Extra: opik
 Provides-Extra: pydanticai
 Provides-Extra: redis
 Provides-Extra: sandbox-docker
@@ -1261,7 +1263,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name, or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1283,8 +1285,8 @@ Configure test comparison modes for automated testing. Test configuration is sep
   - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in DeepEval evaluator: `Scorer.quasi_exact_match_score`)
-- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in DeepEval evaluator: `GEval`) for semantic similarity
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `pip install "agentkernel[opik]"`)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1646,7 +1648,7 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export LOGFIRE_TOKEN=your-write-token
 # Test harness (loaded from the separate test-config.yaml — see Test Configuration)
 export AK_TEST__MODE=fallback  # Options: score, llm, fallback
-export AK_TEST__EVALUATOR=deepeval  # Built-in short name, or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval or opik), or a dotted path to your own AKEvaluator subclass
 export AK_TEST__LLM__MODEL=gpt-4o-mini
 export AK_TEST__LLM__PROVIDER=openai
 export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
@@ -1916,6 +1918,8 @@ gmail:
 
 Test harness configuration (comparison mode, evaluator backend, llm models) is separate from the application configuration. It is not part of `config.yaml` — it lives in its own `test-config.yaml` file, resolved from the current working directory, and is only loaded when the testing utilities (`agentkernel.test`) are used. A legacy `test:` section in `config.yaml` is ignored. See [Test Configuration](#test-configuration) under Configuration Options for the full list of fields and defaults.
 
+The `evaluator` field accepts two built-in short names — `deepeval` (default, `pip install "agentkernel[test]"`) or `opik` (`pip install "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) — or a dotted path to your own `AKEvaluator` subclass.
+
 **test-config.yaml:**
 
 ```yaml

{agentkernel-0.9.0 → agentkernel-0.9.1}/README.md

@@ -1133,7 +1133,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name, or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1155,8 +1155,8 @@ Configure test comparison modes for automated testing. Test configuration is sep
   - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in DeepEval evaluator: `Scorer.quasi_exact_match_score`)
-- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in DeepEval evaluator: `GEval`) for semantic similarity
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `pip install "agentkernel[opik]"`)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1518,7 +1518,7 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export LOGFIRE_TOKEN=your-write-token
 # Test harness (loaded from the separate test-config.yaml — see Test Configuration)
 export AK_TEST__MODE=fallback  # Options: score, llm, fallback
-export AK_TEST__EVALUATOR=deepeval  # Built-in short name, or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval or opik), or a dotted path to your own AKEvaluator subclass
 export AK_TEST__LLM__MODEL=gpt-4o-mini
 export AK_TEST__LLM__PROVIDER=openai
 export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
@@ -1788,6 +1788,8 @@ gmail:
 
 Test harness configuration (comparison mode, evaluator backend, llm models) is separate from the application configuration. It is not part of `config.yaml` — it lives in its own `test-config.yaml` file, resolved from the current working directory, and is only loaded when the testing utilities (`agentkernel.test`) are used. A legacy `test:` section in `config.yaml` is ignored. See [Test Configuration](#test-configuration) under Configuration Options for the full list of fields and defaults.
 
+The `evaluator` field accepts two built-in short names — `deepeval` (default, `pip install "agentkernel[test]"`) or `opik` (`pip install "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) — or a dotted path to your own `AKEvaluator` subclass.
+
 **test-config.yaml:**
 
 ```yaml

{agentkernel-0.9.0 → agentkernel-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.0"
+version = "0.9.1"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -43,7 +43,7 @@ langgraph = [
     "langgraph~=1.2.10",
     "langgraph-prebuilt~=1.1.0",
     "langchain~=1.3.10",
-    "langchain_community==0.4.1",
+    "langchain_community~=0.4.1",
     "litellm~=1.89.2"
 ]
 smolagents = [
@@ -188,6 +188,9 @@ daytona = [
 kubernetes = [
     "kubernetes>=29.0.0",
 ]
+opik = [
+    "opik>=1.7.0",
+]
 
 [project.scripts]
 ak = "agentkernel.cli.ak:main"

{agentkernel-0.9.0 → agentkernel-0.9.1}/src/agentkernel/core/__init__.py

@@ -44,7 +44,7 @@ from .config import AKConfig as Config
 from .module import Module
 from .runtime import ACTING_USER_CACHE_KEY, Runtime
 from .service import AgentService
-from .hooks import PreHook, PostHook
+from .hooks import PreHook, PostHook, StreamHalt
 from .tool import ToolContext, ToolBuilder
 from .util.key_value_cache import KeyValueCache
 from .chat_service import ChatService

{agentkernel-0.9.0 → agentkernel-0.9.1}/src/agentkernel/core/hooks.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from .base import Agent, Session
 
+from .event import StreamEvent
 from .model import AgentReply, AgentRequest
 
 """
@@ -16,6 +17,26 @@ Currently, they will get only called for the initial execution of an agent when
 """
 
 
+class StreamHalt(Exception):
+    """
+    Raised by a post-hook to end a streamed run early.
+
+    Runtime.stream catches it, emits the closing event for any boundary the stream left open, and
+    yields one terminal StreamChunk carrying `reason` as its error. The session is not stored, so a
+    halted turn leaves no trace in conversation state.
+
+    The partial response is invalid rather than merely truncated: a client must discard what it has
+    already rendered instead of presenting it as a short answer.
+    """
+
+    def __init__(self, reason: str):
+        """
+        :param reason: Why the run was halted. Reaches the client verbatim as StreamChunk.error.
+        """
+        super().__init__(reason)
+        self.reason = reason
+
+
 class PreHook(ABC):
     @abstractmethod
     async def on_run(self, session: "Session", agent: "Agent", requests: list[AgentRequest]) -> list[AgentRequest] | AgentReply:
@@ -70,19 +91,38 @@ class PostHook(ABC):
         """
         raise NotImplementedError
 
-    async def on_stream_chunk(
+    async def on_stream_event(
         self,
         session: "Session",
         requests: list[AgentRequest],
         agent: "Agent",
-        delta: str,
-    ) -> str | None:
+        event: StreamEvent,
+    ) -> StreamEvent | list[StreamEvent] | None:
         """
-        Called for each streaming token delta before it is sent to the client.
-        Return the (optionally modified) delta string, or None to drop the token.
-        Default implementation passes the delta through unchanged.
+        Hook method called for every event a streamed run produces, before it reaches the client.
+
+        Unlike on_run, this sees the whole stream: message and reasoning text, tool call names,
+        arguments and results, and the boundaries that pair them.
+
+        Returning a list emits several events in place of one, which is what makes hold-and-release
+        possible: return None per fragment while accumulating in the session's volatile cache, then
+        return [rewritten_payload, closing_event] at the boundary. Accumulate there, not on `self` —
+        one hook instance serves every concurrent request. A returned list is emitted as-is and ends
+        the chain for that event, so `return event` and `return [event]` are not equivalent.
+
+        :param: session (Session): The session instance.
+        :param: requests (list[AgentRequest]): The requests provided to the agent, after pre-hooks.
+        :param: agent (Agent): The agent being streamed.
+        :param: event (StreamEvent): The event to process, as produced by the runner or by an
+                              earlier hook in the chain.
+        :return:
+                - StreamEvent: The event, or a modified event of the same `type`, to pass on. A
+                               different `type` raises TypeError; use a list to emit another type.
+                - list[StreamEvent]: Emitted in order, in place of `event`, ending the chain for it.
+                - None: Drops the event; nothing is sent to the client for it.
+        :raises StreamHalt: To end the run without emitting anything further.
         """
-        return delta
+        return event
 
     @abstractmethod
     def name(self) -> str:

{agentkernel-0.9.0 → agentkernel-0.9.1}/src/agentkernel/core/runtime.py

@@ -13,7 +13,8 @@ from ..guardrail.guardrail import InputGuardrailFactory, OutputGuardrailFactory
 from ..sandbox.hooks import SandboxPreHookFactory
 from .base import Agent, Session
 from .builder import SessionStoreBuilder
-from .event import ReasoningDelta, TextDelta
+from .event import MessageEnd, ReasoningEnd, StepEnd, StreamEvent, TextDelta, ToolCallEnd
+from .hooks import StreamHalt
 from .model import (
     AgentReply,
     AgentReplyAny,
@@ -35,6 +36,72 @@ from .session import SessionStore
 ACTING_USER_CACHE_KEY = "ak.acting_user_id"
 
 
+class StreamBoundaryTracker:
+    """
+    Remembers which paired events a streamed run has left open, and how to close them.
+
+    Several of the events in `event.py` come in pairs: a `MessageStart` is closed by a `MessageEnd`, a
+    `ToolCallStart` by a `ToolCallEnd`. A post-hook can end a run part-way through such a pair by
+    raising `StreamHalt`, which would otherwise leave the client holding something that never closes —
+    an AG-UI frontend renders an unclosed tool call as work still in progress. `Runtime.stream` tracks
+    what it has emitted so its halt path can emit the closes the stream still owes.
+
+    Only events that were actually emitted are observed, never what the runner yielded, so a hook that
+    holds, drops or injects a boundary cannot desynchronise the tracker from the client's view.
+
+    Malformed sequences are tolerated rather than rejected: closing an id that was never opened is a
+    no-op, and opening one twice keeps the later close. Validating a runner's event sequence is a wider
+    contract question than this class, and raising mid-stream would turn a third-party adapter's bug
+    into a failed run.
+
+    Internal to `Runtime.stream`, and deliberately not exported from the package.
+    """
+
+    def __init__(self) -> None:
+        self._open: dict[tuple[str, str], StreamEvent] = {}
+
+    def observe(self, event: StreamEvent) -> None:
+        """
+        Records an emitted event, opening or closing the boundary it represents.
+
+        The closing event is built when the boundary opens and stored against it, so `drain` needs no
+        mapping from a boundary back to its event type. Events that open nothing are ignored.
+
+        :param event: An event that has just been emitted to the client.
+        """
+        match event.type:
+            case "message_start":
+                self._open[("message", event.message_id)] = MessageEnd(message_id=event.message_id)
+            case "message_end":
+                self._open.pop(("message", event.message_id), None)
+            case "reasoning_start":
+                self._open[("reasoning", event.message_id)] = ReasoningEnd(message_id=event.message_id)
+            case "reasoning_end":
+                self._open.pop(("reasoning", event.message_id), None)
+            case "tool_call_start":
+                self._open[("tool", event.tool_call_id)] = ToolCallEnd(tool_call_id=event.tool_call_id)
+            case "tool_call_end":
+                self._open.pop(("tool", event.tool_call_id), None)
+            case "step_start":
+                self._open[("step", event.name)] = StepEnd(name=event.name)
+            case "step_end":
+                self._open.pop(("step", event.name), None)
+
+    def drain(self) -> list[StreamEvent]:
+        """
+        Returns the closing events for everything still open, innermost first, and forgets them.
+
+        Insertion order is the order the boundaries opened, so reversing it closes the innermost
+        boundary first — a tool call opened inside a message is closed before the message. The tracker
+        is emptied, since a halted run emits these once and then ends.
+
+        :return: The closing events the run still owes its client, innermost first.
+        """
+        closes = list(reversed(self._open.values()))
+        self._open.clear()
+        return closes
+
+
 class Runtime:
     """
     Runtime class provides the environment for hosting and running agents.
@@ -237,12 +304,14 @@ class Runtime:
         Streams the specified agent response as StreamChunks carrying typed stream events.
 
         Pre-hooks run first; if halted, yields a StreamChunk with error and done=True.
-        The runner's events pass through the post-hook chain via on_stream_chunk(), which sees
-        text only: TextDelta and ReasoningDelta content reaches the hooks, and a hook's edit is
-        written back into the event so `delta` and `event` never disagree. Returning None drops
-        the chunk entirely, event included. Only TextDelta content is projected into `delta`,
-        keeping reasoning out of consumers that concatenate it as the answer; every event still
-        reaches `event`. The volatile cache is cleared on exit.
+        Every event the runner yields passes through the post-hook chain via on_stream_event(), which
+        may pass it, rewrite it in place, drop it by returning None, or return a list to emit several
+        events in its place; a returned list ends the chain for that event. Only TextDelta content is
+        projected into `delta`, keeping reasoning out of consumers that concatenate it as the answer,
+        and `delta` is taken from the event finally emitted so the two can never disagree. A hook
+        raising StreamHalt ends the run: the closing event for any boundary the stream left open is
+        emitted, then a single error chunk, and the session is not stored. Any other exception
+        propagates unchanged. The volatile cache is cleared on exit.
 
         :param agent: The agent to run.
         :param session: The session to use for the agent.
@@ -266,24 +335,39 @@ class Runtime:
                     self._log.debug(f"Streaming agent '{agent.name}' with requests: {requests}")
 
                     post_hooks = self._get_system_post_hooks() + agent.post_hooks
+                    boundaries = StreamBoundaryTracker()
 
-                    async for ev in agent.runner.stream(agent, session, requests):
-                        text = ev.content if isinstance(ev, (TextDelta, ReasoningDelta)) else None
-
-                        if text is not None:
+                    try:
+                        async for ev in agent.runner.stream(agent, session, requests):
                             for hook in post_hooks:
-                                text = await hook.on_stream_chunk(session, requests, agent, text)
-                                if text is None:
+                                result = await hook.on_stream_event(session, requests, agent, ev)
+                                if result is None:
+                                    emitted: list[StreamEvent] = []
                                     break
-                            if text is None:
-                                continue  # hook dropped the whole chunk, event included
-                            if text != ev.content:
-                                ev = ev.model_copy(update={"content": text})
-
-                        yield StreamChunk(delta=text if isinstance(ev, TextDelta) else None, event=ev)
-
-                    self.sessions().store(session)
-                    yield StreamChunk(done=True)
+                                if isinstance(result, list):
+                                    emitted = result
+                                    break
+                                if result.type != ev.type:
+                                    raise TypeError(
+                                        f"PostHook '{hook.name()}' returned event type '{result.type}' for a '{ev.type}'. "
+                                        "Return a list to emit a different type"
+                                    )
+                                ev = result
+                            else:
+                                emitted = [ev]
+
+                            for event in emitted:
+                                chunk = StreamChunk(delta=event.content if isinstance(event, TextDelta) else None, event=event)
+                                boundaries.observe(event)
+                                yield chunk
+
+                        self.sessions().store(session)
+                        yield StreamChunk(done=True)
+                    except StreamHalt as halt:
+                        self._log.warning(f"Stream halted for agent '{agent.name}': {halt.reason}")
+                        for closing in boundaries.drain():
+                            yield StreamChunk(event=closing)
+                        yield StreamChunk(error=halt.reason, done=True)
             finally:
                 session.get_volatile_cache().clear()
 

{agentkernel-0.9.0 → agentkernel-0.9.1}/src/agentkernel/deployment/aws/containerized/ecs_io_handler.py

@@ -16,7 +16,9 @@ class ECSIOHandler:
     Thread 1 (rest-api) runs the FastAPI/uvicorn app: ECSQueueRequestHandler in REST queue
     modes, or WebSocket (ASYNC/STREAM) frames via ECSWebSocketRequestHandler. Thread 2
     (output-queue-consumer) runs ECSOutputConsumer.run, writing to DB (REST) or pushing
-    over WebSocket (ASYNC). WebSocket mode requires ``run(auth_validator=MyValidator())``.
+    over WebSocket (ASYNC). Both modes take a single ``run(auth_validator=MyValidator())``:
+    it authenticates the ``$connect`` handshake in WebSocket mode (mandatory there), and in
+    REST modes it is bound onto every REST route via ``RESTAPI.add_auth_handlers``.
 
     Optional REST surfaces (the schedule and thread management routes, a Slack handler) are
     mounted by passing them as ``handlers``, the way the pipeline's ``IOHandler`` takes them.
@@ -26,11 +28,16 @@ class ECSIOHandler:
     _config = AKConfig.get()
 
     @classmethod
-    def run(cls, auth_validator: Optional[AuthValidator] = None, handlers: Optional[list[RESTRequestHandler]] = None) -> None:
+    def run(
+        cls,
+        auth_validator: Optional[AuthValidator] = None,
+        handlers: Optional[list[RESTRequestHandler]] = None,
+    ) -> None:
         """Boot the REST/WebSocket API and the output-queue consumer as peer threads, and serve until shutdown.
 
         :param auth_validator: Authenticates the ``$connect`` handshake in WebSocket (ASYNC/STREAM)
-            mode, where it is mandatory; unused in the REST queue modes.
+            mode, where it is mandatory. In the REST queue modes it is bound onto every REST route
+            via ``RESTAPI.add_auth_handlers``.
         :param handlers: Optional REST handlers mounted alongside the API's own defaults, which are
             always served (the chat route is the queue producer, not a replaceable default).
             Mounting an optional surface is the application's job here, as it is on the pipeline's
@@ -56,6 +63,9 @@ class ECSIOHandler:
         else:
             from .core.api.rest_api import AWSRestAPI
 
+            if auth_validator is not None:
+                AWSRestAPI.add_auth_handlers(auth_validators=[auth_validator])
+
             def run_api() -> None:
                 # Defaults first, then the application's: RESTAPI.run() replaces the defaults with
                 # whatever it is handed, and the queue-producing chat route must survive.

{agentkernel-0.9.0 → agentkernel-0.9.1}/src/agentkernel/integration/whatsapp/README.md

@@ -70,7 +70,7 @@ OpenAIModule([general_agent])
 
 if __name__ == "__main__":
     handler = AgentWhatsAppRequestHandler()
-    RESTAPI.run(handler=handler)
+    RESTAPI.run([handler])
 ```
 
 ## Configuration Options