agentkernel 0.9.1__tar.gz → 0.9.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.1
+Version: 0.9.2
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.1"
+version = "0.9.2"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/api/handler.py

@@ -14,6 +14,8 @@ from ..core.runtime import Runtime
 
 
 class RESTRequestHandler(ABC):
+    requires_pipeline: bool = False
+
     @abstractmethod
     def get_router(self) -> APIRouter:
         """

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/api/http.py

@@ -105,11 +105,31 @@ class RESTAPI:
                 cls._log.info("in_memory queue transport resolved: starting the single-process pipeline topology")
                 return IOHandler.run()
 
+        handlers = handlers if handlers is not None else cls.get_default_handlers()
+        cls._reject_pipeline_only_handlers(handlers)
+
         host = AKConfig.get().api.host
         port = AKConfig.get().api.port
         cls._log.info(f"Agent Kernel REST API listening on http://{host}:{port}")
         uvicorn.run(app=cls.build_app(handlers), host=host, port=port, reload=False)
 
+    @classmethod
+    def _reject_pipeline_only_handlers(cls, handlers: list[RESTRequestHandler] = None) -> None:
+        """Refuse to serve a handler that only works inside the queue pipeline.
+
+        :param handlers: The handlers this run was asked to serve.
+        :raises AKConfigError: If any of them declares ``requires_pipeline``.
+        """
+        offenders = sorted({type(handler).__name__ for handler in handlers or [] if getattr(handler, "requires_pipeline", False) is True})
+        if offenders:
+            from ..core.util.factory import AKConfigError
+
+            raise AKConfigError(
+                f"{', '.join(offenders)} require the queue pipeline: serve them with "
+                "IOHandler.run(handlers=[...]) instead of RESTAPI.run([...]), which builds a bare "
+                "API with no runner to drain what they enqueue"
+            )
+
     @classmethod
     def build_app(cls, handlers: list[RESTRequestHandler] = None) -> FastAPI:
         """Assemble the complete FastAPI app (handlers, A2A/MCP mounts, custom routers) without serving it.

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/chat_service.py

@@ -1,8 +1,8 @@
-import asyncio
 import base64
+import contextlib
 import json
 import logging
-from collections.abc import AsyncGenerator, Generator
+from collections.abc import AsyncGenerator, Generator, Iterator
 from typing import Any, Dict, List, Optional, Union
 
 from .config import AKConfig
@@ -21,6 +21,7 @@ from .model import (
     StreamChunk,
 )
 from .service import AgentService
+from .util.async_bridge import iterate_async_sync, run_async_sync
 
 
 class RequestBuilder:
@@ -138,6 +139,7 @@ class RequestBuilder:
             "schedule",
             "scheduled_task_id",
             "scheduled_time",
+            "requests",
         }
         for key, value in req.model_dump().items():
             if key in known_fields:
@@ -225,21 +227,25 @@ class AgentHandler:
     def _run_async_sync(coro) -> Any:
         """Run an async coroutine from sync code, handling event loop state.
 
-        Only a RuntimeError from get_event_loop() itself (no loop in this thread) falls back to
-        asyncio.run: a RuntimeError raised by the coroutine must propagate as-is, not trigger a
-        second await of the already-consumed coroutine.
+        Kept as a method because callers (and their tests) reach the bridge through it; the
+        loop handling itself is shared with the pipeline's synchronous consumers.
 
         :param coro: Coroutine to execute
         :return: Result of the coroutine
         """
-        try:
-            loop = asyncio.get_event_loop()
-        except RuntimeError:
-            return asyncio.run(coro)
-        if loop.is_closed():
-            asyncio.set_event_loop(asyncio.new_event_loop())
-            return asyncio.run(coro)
-        return loop.run_until_complete(coro)
+        return run_async_sync(coro)
+
+    @staticmethod
+    def _iterate_async_sync(agen) -> Iterator[Any]:
+        """Consume an async generator from sync code, handling event loop state.
+
+        The streaming sibling of _run_async_sync, and a method for the same reason: callers
+        (and their tests) reach the bridge through the handler.
+
+        :param agen: Async generator to consume
+        :return: Iterator over the generator's items
+        """
+        return iterate_async_sync(agen)
 
     def run_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> Any:
         """Run agent requests synchronously.
@@ -259,23 +265,17 @@ class AgentHandler:
         """
         return await self.service.run_multi(requests=requests, acting_user_id=acting_user_id)
 
-    def run_stream_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> List[Any]:
+    def run_stream_sync(self, requests: List[Any], acting_user_id: Optional[str] = None) -> Iterator[Any]:
         """Run agent streaming requests synchronously.
 
-        Manages event loop lifecycle internally and returns all chunks as a list.
+        Manages event loop lifecycle internally and hands over each chunk as the run produces
+        it, so a sync consumer streams live instead of receiving the whole run at once.
 
         :param requests: List of AgentRequest objects to process
         :param acting_user_id: When given, published as the run's acting user (see Runtime.stream)
-        :return: List of StreamChunk objects
+        :return: Iterator of StreamChunk objects
         """
-
-        async def _collect():
-            chunks = []
-            async for chunk in self.service.stream_multi(requests=requests, acting_user_id=acting_user_id):
-                chunks.append(chunk)
-            return chunks
-
-        return AgentHandler._run_async_sync(_collect())
+        return AgentHandler._iterate_async_sync(self.service.stream_multi(requests=requests, acting_user_id=acting_user_id))
 
     async def run_stream_async(self, requests: List[Any], acting_user_id: Optional[str] = None) -> AsyncGenerator[Any, None]:
         """Run agent streaming requests asynchronously.
@@ -444,8 +444,9 @@ class ChatService:
     def execute_stream_sync(self, req: BaseRunRequest, requests: Optional[List[AgentRequest]] = None) -> Generator[StreamChunk, None, None]:
         """Synchronous counterpart of execute_stream().
 
-        Preserves the sync path's buffering semantics: AgentHandler.run_stream_sync collects
-        all chunks before this generator yields the first one.
+        Chunks arrive as the run produces them: AgentHandler.run_stream_sync pumps the async
+        stream one chunk at a time, so an exception mid-run reaches the caller as an error
+        chunk after the chunks already yielded, exactly as on the async path.
 
         :param req: Run request carrying prompt, agent, and session_id
         :param requests: Optional prebuilt AgentRequest list (see execute())
@@ -460,11 +461,12 @@ class ChatService:
         handler = self.prepare_agent_handler(req.session_id, req.agent)
 
         def _stream() -> Generator[StreamChunk, None, None]:
-            try:
-                for chunk in handler.run_stream_sync(requests, acting_user_id=req.user_id):
-                    yield chunk
-            except Exception as e:
-                yield StreamChunk(error=str(e), done=True)
+            with contextlib.closing(handler.run_stream_sync(requests, acting_user_id=req.user_id)) as chunks:
+                try:
+                    for chunk in chunks:
+                        yield chunk
+                except Exception as e:
+                    yield StreamChunk(error=str(e), done=True)
 
         return _stream()
 
@@ -575,15 +577,18 @@ class ChatService:
         self._validate(req, requests)
         return RequestBuilder.from_base_request_sync(req) if requests is None else requests
 
-    def process_chat_request(self, req: BaseRunRequest) -> Union[tuple[int, Dict[str, Any]], Dict[str, Any]]:
+    def process_chat_request(
+        self, req: BaseRunRequest, requests: Optional[List[AgentRequest]] = None
+    ) -> Union[tuple[int, Dict[str, Any]], Dict[str, Any]]:
         """Process a chat request synchronously.
 
         :param req: Base run request with prompt, session_id, agent, and attachments
+        :param requests: Optional prebuilt AgentRequest list (see execute_sync())
         :return: When rest_api_mode=False: tuple of (status_code, response_dict).
                  When rest_api_mode=True: response_dict only.
         """
         try:
-            result, session_id = self.execute_sync(req)
+            result, session_id = self.execute_sync(req, requests)
             return ResponseBuilder.build_response(self._success_status(req), session_id, self.rest_api_mode, result=result)
         except ValueError as ve:
             self._log.error(f"ValueError processing request: {ve}")
@@ -642,6 +647,7 @@ class ChatService:
         self,
         req: BaseRunRequest,
         sse_format: bool = False,
+        requests: Optional[List[AgentRequest]] = None,
     ) -> Generator[str, None, None]:
         """Process a streaming chat request synchronously.
 
@@ -652,19 +658,21 @@ class ChatService:
         :param req: Base run request with prompt, session_id, agent, and attachments
         :param sse_format: When True, yield Server-Sent Events formatted frames.
                            When False, yield raw StreamChunk JSON payloads.
+        :param requests: Optional prebuilt AgentRequest list (see execute_stream_sync())
         :return: Generator yielding StreamChunk payloads as JSON or SSE-formatted strings
         :raises ValueError: If session_id or prompt is missing, or no agent is available
         """
         session_id = req.session_id
-        chunks = self.execute_stream_sync(req)
+        chunks = self.execute_stream_sync(req, requests)
 
         def _stream() -> Generator[str, None, None]:
-            try:
-                for chunk in chunks:
-                    yield ResponseBuilder.stream_chunk(chunk, session_id, sse_format=sse_format)
-            except Exception as e:
-                error_chunk = StreamChunk(error=str(e), done=True)
-                yield ResponseBuilder.stream_chunk(error_chunk, session_id, sse_format=sse_format)
+            with contextlib.closing(chunks) as raw_chunks:
+                try:
+                    for chunk in raw_chunks:
+                        yield ResponseBuilder.stream_chunk(chunk, session_id, sse_format=sse_format)
+                except Exception as e:
+                    error_chunk = StreamChunk(error=str(e), done=True)
+                    yield ResponseBuilder.stream_chunk(error_chunk, session_id, sse_format=sse_format)
 
         return _stream()
 

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/config.py

@@ -161,6 +161,10 @@ class _SlackConfig(BaseModel):
         default="",
         description="The message to send as an acknowledgement when a Slack message is received",
     )
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Slack outbound adapter",
+    )
 
 
 class _WhatsAppConfig(BaseModel):
@@ -174,6 +178,10 @@ class _WhatsAppConfig(BaseModel):
     app_secret: str = Field(default="", description="WhatsApp app secret for signature verification")
     phone_number_id: str = Field(default="", description="WhatsApp Business phone number ID")
     api_version: str = Field(default="v24.0", description="WhatsApp API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in WhatsApp outbound adapter",
+    )
 
 
 class _MessengerConfig(BaseModel):
@@ -182,6 +190,10 @@ class _MessengerConfig(BaseModel):
     access_token: str = Field(default="", description="Facebook Page access token")
     app_secret: str = Field(default="", description="Facebook app secret for signature verification")
     api_version: str = Field(default="v24.0", description="Facebook Graph API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Facebook Messenger outbound adapter",
+    )
 
 
 class _InstagramConfig(BaseModel):
@@ -191,6 +203,10 @@ class _InstagramConfig(BaseModel):
     app_secret: str = Field(default="", description="Instagram app secret for signature verification")
     instagram_account_id: str = Field(default="", description="Instagram Business Account ID (IGSID)")
     api_version: str = Field(default="v21.0", description="Instagram Graph API version")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Instagram outbound adapter",
+    )
 
 
 class _TelegramConfig(BaseModel):
@@ -198,6 +214,10 @@ class _TelegramConfig(BaseModel):
     bot_token: str = Field(default="", description="Telegram bot token from BotFather")
     webhook_secret: str = Field(default="", description="Optional secret token for webhook security")
     api_version: str = Field(default="bot", description="Telegram Bot API version prefix")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Telegram outbound adapter",
+    )
 
 
 class _TeamsConfig(BaseModel):
@@ -212,6 +232,10 @@ class _TeamsConfig(BaseModel):
         default="",
         description="Entra ID tenant that owns the bot's app registration. Required only for a single-tenant registration, whose channel tokens must be issued by its own tenant; leave empty for a multi-tenant bot. Also the fallback tenant for the app-only token used to download attachments whose URL is not pre-authenticated, when the incoming activity carries none",
     )
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Microsoft Teams outbound adapter",
+    )
 
 
 class _GmailConfig(BaseModel):
@@ -219,6 +243,10 @@ class _GmailConfig(BaseModel):
     token_file: str = Field(default="token.pickle", description="Path to store OAuth2 token")
     poll_interval: int = Field(default=30, description="Email polling interval in seconds")
     label_filter: str = Field(default="INBOX", description="Gmail label to monitor (e.g., INBOX, UNREAD)")
+    outbound_adapter: str = Field(
+        default="",
+        description="Dotted path to an OutboundAdapter subclass replacing the built-in Gmail outbound adapter",
+    )
 
 
 class _MultimodalStorageRedisConfig(_RedisConfig):

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/model.py

@@ -1,9 +1,9 @@
 import json
 import uuid
 from enum import Enum
-from typing import Any, Callable, List, Literal, Optional, Union
+from typing import Annotated, Any, Callable, List, Literal, Optional, Union
 
-from pydantic import BaseModel, ConfigDict, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .event import StreamEvent
 
@@ -125,6 +125,11 @@ class AgentReplyImage(AgentRequestImage):
 type AgentRequest = Union[AgentRequestText, AgentRequestFile, AgentRequestImage, AgentRequestAny, AgentRequestAttachmentRef]
 type AgentReply = Union[AgentReplyText, AgentReplyImage, AgentReplyAny]
 
+AgentRequestUnion = Annotated[
+    Union[AgentRequestText, AgentRequestFile, AgentRequestImage, AgentRequestAny, AgentRequestAttachmentRef],
+    Field(discriminator="type"),
+]
+
 
 class AgentReplyAny(BaseModel):
     """
@@ -268,10 +273,18 @@ class BaseRunRequest(BaseChatRequest):
     it delivers, identifying the task and the occurrence this run belongs to. They are
     typed fields (not extras) so an occurrence's metadata never reaches the agent as
     additional context.
+
+    requests carries an already-built AgentRequest list, for producers that compose it
+    themselves rather than leaving it to RequestBuilder: a messaging integration downloads
+    its attachments at the edge and stores them, so what reaches the queue is a request list
+    (including AgentRequestAttachmentRef entries, which files/images cannot express). Typed
+    for the same reason as the scheduling fields: an extra would reach the agent as
+    AgentRequestAny context.
     """
 
     files: Optional[List[FileData]] = None
     images: Optional[List[ImageData]] = None
+    requests: Optional[List[AgentRequestUnion]] = None
     scheduled_task_id: Optional[str] = None
     scheduled_time: Optional[str] = None
     model_config = ConfigDict(extra="allow")

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/multimodal/storage/__init__.py

@@ -1,8 +1,10 @@
-"""
-Storage sub-package for multimodal attachments.
-
-Provides pluggable storage backends (in_memory, session_cache, redis, dynamodb)
-and the ``AttachmentStorageManager`` high-level API.
-"""
-
-from .storage_manager import AttachmentStorageManager
+"""
+Storage sub-package for multimodal attachments.
+
+Provides pluggable storage backends (in_memory, session_cache, redis, dynamodb)
+and the ``AttachmentStorageManager`` high-level API.
+"""
+
+from .storage_manager import AttachmentStorageManager, StoredAttachment
+
+__all__ = ["AttachmentStorageManager", "StoredAttachment"]

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/multimodal/storage/base.py

@@ -1,69 +1,78 @@
-"""
-Base classes for multimodal attachment storage.
-
-This module defines the abstract storage interface and the
-AttachmentData dataclass used across all storage backends.
-"""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import Optional
-
-# Constants
-ATTACHMENT_KEY_PREFIX = "attachment:"
-ATTACHMENT_INDEX_KEY = "_attachment_index"
-DEFAULT_MAX_ATTACHMENTS = 20
-
-
-@dataclass
-class AttachmentData:
-    """
-    Full attachment data: either the base64 content, or the address of a remote attachment.
-
-    `url` is what separates the two. A remote reference (`http://`, `https://`, `s3://`, or a
-    `data:` URI that is not base64) is recorded here so a conversation thread has one uniform
-    record per attachment, but its bytes are never fetched — that is the framework adapter's job,
-    deliberately, so no system pre-hook makes outbound network calls. Such a record carries an
-    empty `data`, and any reader wanting bytes must check `url` first rather than trusting `data`
-    to hold base64.
-    """
-
-    id: str
-    type: str
-    data: str  # Base64 encoded
-    name: str
-    mime_type: str
-    description: str
-    timestamp: float
-    url: Optional[str] = None
-
-
-class AttachmentStore(ABC):
-    """Abstract base class for attachment stores."""
-
-    @abstractmethod
-    def save(self, attachment: dict, max_attachments: int) -> str:
-        """
-        Save attachment and return ID.
-        :param attachment: Attachment data dictionary
-        :param max_attachments: Max attachments policy
-        :return: Attachment ID
-        """
-        pass
-
-    @abstractmethod
-    def get(self, attachment_id: str) -> Optional[dict]:
-        """
-        Retrieve full attachment data by ID.
-        :param attachment_id: Attachment ID
-        :return: Attachment data dict or None
-        """
-        pass
-
-    @abstractmethod
-    def delete(self, attachment_id: str) -> None:
-        """
-        Delete attachment by ID.
-        :param attachment_id: Attachment ID
-        """
-        pass
+"""
+Base classes for multimodal attachment storage.
+
+This module defines the abstract storage interface and the
+AttachmentData dataclass used across all storage backends.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import ClassVar, Optional
+
+# Constants
+ATTACHMENT_KEY_PREFIX = "attachment:"
+ATTACHMENT_INDEX_KEY = "_attachment_index"
+DEFAULT_MAX_ATTACHMENTS = 20
+
+
+@dataclass
+class AttachmentData:
+    """
+    Full attachment data: either the base64 content, or the address of a remote attachment.
+
+    `url` is what separates the two. A remote reference (`http://`, `https://`, `s3://`, or a
+    `data:` URI that is not base64) is recorded here so a conversation thread has one uniform
+    record per attachment, but its bytes are never fetched — that is the framework adapter's job,
+    deliberately, so no system pre-hook makes outbound network calls. Such a record carries an
+    empty `data`, and any reader wanting bytes must check `url` first rather than trusting `data`
+    to hold base64.
+    """
+
+    id: str
+    type: str
+    data: str  # Base64 encoded
+    name: str
+    mime_type: str
+    description: str
+    timestamp: float
+    url: Optional[str] = None
+
+
+class AttachmentStore(ABC):
+    """Abstract base class for attachment stores.
+
+    ``shared`` says whether a second process can read what this store wrote. It is False by
+    default because the safe answer for a bring-your-own store is the conservative one: a driver
+    that keeps attachments in this process (or inside the session copy this process holds) cannot
+    serve a topology where the request is offloaded at one tier and resolved at another. Only a
+    store backed by an external service sets it True.
+    """
+
+    shared: ClassVar[bool] = False
+
+    @abstractmethod
+    def save(self, attachment: dict, max_attachments: int) -> str:
+        """
+        Save attachment and return ID.
+        :param attachment: Attachment data dictionary
+        :param max_attachments: Max attachments policy
+        :return: Attachment ID
+        """
+        pass
+
+    @abstractmethod
+    def get(self, attachment_id: str) -> Optional[dict]:
+        """
+        Retrieve full attachment data by ID.
+        :param attachment_id: Attachment ID
+        :return: Attachment data dict or None
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, attachment_id: str) -> None:
+        """
+        Delete attachment by ID.
+        :param attachment_id: Attachment ID
+        """
+        pass

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/multimodal/storage/dynamodb.py

@@ -29,6 +29,9 @@ class DynamoDBAttachmentStore(AttachmentStore):
     for pruning.
     """
 
+    # DynamoDB is an external service, so any process with the same config reads what another wrote.
+    shared = True
+
     _log = logging.getLogger("ak.core.multimodal.storage.dynamodb")
 
     def __init__(self, session_id: str, table_name: str, ttl: int):

{agentkernel-0.9.1 → agentkernel-0.9.2}/src/agentkernel/core/multimodal/storage/redis.py

@@ -21,6 +21,9 @@ class RedisAttachmentStore(AttachmentStore):
     ``{prefix}{session_id}:_index`` tracks insertion order for pruning.
     """
 
+    # Redis is an external service, so any process with the same config reads what another wrote.
+    shared = True
+
     def __init__(self, session_id: str, url: str, ttl: int, prefix: str):
         """
         Initialize the Redis attachment store.