agentkernel 0.2.5__tar.gz → 0.2.7__tar.gz

{agentkernel-0.2.5 → agentkernel-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.2.5
+Version: 0.2.7
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -10,7 +10,6 @@ Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pydantic-settings>=2.10.1
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: singleton-type>=0.0.5
-Requires-Dist: redis>=6.4.0
 Requires-Dist: a2a-sdk[http-server]>=0.3.6 ; extra == 'a2a'
 Requires-Dist: google-adk>=1.14.1 ; extra == 'adk'
 Requires-Dist: litellm~=1.74.3 ; extra == 'adk'
@@ -18,6 +17,7 @@ Requires-Dist: openinference-instrumentation-google-adk>=0.1.6 ; extra == 'adk'
 Requires-Dist: fastapi>=0.118.0 ; extra == 'api'
 Requires-Dist: uvicorn>=0.37.0 ; extra == 'api'
 Requires-Dist: gunicorn>=23.0.0 ; extra == 'api'
+Requires-Dist: boto3>=1.41.4 ; extra == 'aws'
 Requires-Dist: crewai>=0.150.0 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-crewai>=0.1.16 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-litellm>=0.1.28 ; extra == 'crewai'
@@ -32,6 +32,7 @@ Requires-Dist: httpx>=0.27.0 ; extra == 'messenger'
 Requires-Dist: openai-agents>=0.2.3 ; extra == 'openai'
 Requires-Dist: openinference-instrumentation-openai-agents>=1.3.0 ; extra == 'openai'
 Requires-Dist: traceloop-sdk>=0.48.0 ; extra == 'openllmetry'
+Requires-Dist: redis>=7.1.0 ; extra == 'redis'
 Requires-Dist: slack-bolt==1.22.0 ; extra == 'slack'
 Requires-Dist: pytest>=8.4.1 ; extra == 'test'
 Requires-Dist: pytest-asyncio>=1.2.0 ; extra == 'test'
@@ -53,6 +54,7 @@ Provides-Extra: mcp
 Provides-Extra: messenger
 Provides-Extra: openai
 Provides-Extra: openllmetry
+Provides-Extra: redis
 Provides-Extra: slack
 Provides-Extra: test
 Provides-Extra: whatsapp

{agentkernel-0.2.5 → agentkernel-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.2.5"
+version = "0.2.7"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -18,7 +18,6 @@ dependencies = [
     "pydantic-settings>=2.10.1",
     "pyyaml>=6.0.2",
     "singleton-type>=0.0.5",
-    "redis>=6.4.0",
 ]
 
 [project.optional-dependencies]
@@ -44,7 +43,10 @@ cli = [
 
 ]
 aws = [
-
+    "boto3>=1.41.4",
+]
+redis = [
+    "redis>=7.1.0",
 ]
 openai = [
     "openai-agents>=0.2.3",

agentkernel-0.2.7/src/agentkernel/adk.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("agentkernel")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .framework.adk import *

{agentkernel-0.2.5 → agentkernel-0.2.7}/src/agentkernel/api/__init__.py

@@ -11,5 +11,5 @@ try:
 except importlib.metadata.PackageNotFoundError:
     __version__ = "0.1.0"
 
-from .rest_request_handler import RESTRequestHandler
-from .restapi import RESTAPI
+from .handler import AgentRESTRequestHandler, RESTRequestHandler
+from .http import RESTAPI

{agentkernel-0.2.5/src/agentkernel → agentkernel-0.2.7/src/agentkernel/api}/a2a/a2a.py

@@ -9,8 +9,8 @@ from a2a.types import AgentCard, InternalError, UnsupportedOperationError
 from a2a.utils import new_agent_text_message
 from a2a.utils.errors import ServerError
 
-from ..core import Agent, AgentService, GlobalRuntime
-from ..core.config import AKConfig
+from ...core import Agent, AgentService, GlobalRuntime
+from ...core.config import AKConfig
 
 
 class A2A:

agentkernel-0.2.5/src/agentkernel/api/a2a.py → agentkernel-0.2.7/src/agentkernel/api/a2a/handler.py

@@ -7,7 +7,7 @@ from a2a.utils import AGENT_CARD_WELL_KNOWN_PATH
 from fastapi import APIRouter
 from pydantic import BaseModel
 
-from ..a2a.a2a import A2A
+from .a2a import A2A
 
 
 class A2ARESTRequestHandler:

agentkernel-0.2.7/src/agentkernel/api/handler.py

@@ -0,0 +1,131 @@
+import logging
+import traceback
+from abc import ABC, abstractmethod
+from http import HTTPStatus
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, ConfigDict
+
+from agentkernel.core.model import AgentReplyImage, AgentReplyText, AgentRequestAny, AgentRequestText
+
+from ..core import AgentService, GlobalRuntime
+
+
+class RESTRequestHandler(ABC):
+    @abstractmethod
+    def get_router(self) -> APIRouter:
+        """
+        Returns the APIRouter instance which has configured routes
+        E.g.:
+        - GET /health: Health check
+        - GET /agents: List available agents
+
+        router = APIRouter()
+
+        @router.get("/health")
+        def health():
+            return {"status": "ok"}
+
+        @router.get("/agents")
+        def list_agents():
+            return {"agents": list(GlobalRuntime.instance().agents().keys())}
+
+        """
+        pass
+
+
+class AgentRESTRequestHandler(RESTRequestHandler):
+    """
+    API routers that expose endpoints to interact with Agent Kernel.
+    Endpoints:
+    - GET /health: Health check
+    - GET /agents: List available agents
+    - POST /run: Run an agent with a prompt
+      Payload JSON: { "prompt": str, "agent": str | null, "session_id": str | null }
+    """
+
+    def __init__(self):
+        self._log = logging.getLogger("ak.api.agent")
+
+    class RunRequest(BaseModel):
+        model_config = ConfigDict(extra="allow")
+
+        prompt: str
+        agent: Optional[str] = None
+        session_id: Optional[str] = None
+
+    def get_router(self) -> APIRouter:
+        """
+        Returns the APIRouter instance.
+        """
+
+        router = APIRouter()
+
+        @router.get("/health")
+        def health():
+            return {"status": "ok"}
+
+        @router.get("/agents")
+        def list_agents():
+            return {"agents": list(GlobalRuntime.instance().agents().keys())}
+
+        @router.post("/run")
+        async def run(body: AgentRESTRequestHandler.RunRequest):
+            return await self.run(body)
+
+        return router
+
+    async def run(self, req: RunRequest):
+        """
+        Async method to run the agent.
+        :param req: Request object containing the prompt, optional agent name, and additional properties.
+        """
+        requests = []
+        requests.append(AgentRequestText(text=req.prompt))
+
+        # Pack additional properties into AgentRequestAny
+        known_fields = {"prompt", "agent", "session_id"}
+        for key, value in req.model_dump().items():
+            if key not in known_fields:
+                self._log.debug(f"Adding additional context: {key}={value}")
+                requests.append(AgentRequestAny(name=key, content=value))
+        service = AgentService()
+
+        try:
+            service.select(req.session_id, req.agent)
+            if not service.agent:
+                raise ValueError("No agent available")
+
+            result = await service.run_multi(requests=requests)
+            self._log.debug(f"Result: {result}")
+
+            return {
+                "result": (
+                    str(result)
+                    if isinstance(result, (AgentReplyText, AgentReplyImage))
+                    else "Non textual result received"
+                ),  # sending image is not supported at the moment
+                "session_id": service.get_response_session_id(req.session_id),
+            }
+
+        except HTTPException:
+            raise
+        except ValueError as e:
+            self._log.error(f"POST /run error: {e}\n{traceback.format_exc()}")
+            raise HTTPException(
+                status_code=HTTPStatus.BAD_REQUEST,
+                detail={
+                    "error": str(e),
+                    "session_id": service.get_response_session_id(req.session_id),
+                },
+            )
+        except Exception as e:
+            self._log.error(f"POST /run error: {e}\n{traceback.format_exc()}")
+            raise HTTPException(
+                status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
+                detail={
+                    "error": str(e),
+                    "session_id": service.get_response_session_id(None),
+                },
+            )

agentkernel-0.2.5/src/agentkernel/api/restapi.py → agentkernel-0.2.7/src/agentkernel/api/http.py

@@ -5,9 +5,8 @@ from fastapi import APIRouter, FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.openapi.utils import get_openapi
 
-from ..api.rest_request_handler import RESTRequestHandler
 from ..core.config import AKConfig
-from .agent import AgentRESTRequestHandler
+from .handler import AgentRESTRequestHandler, RESTRequestHandler
 
 logging.basicConfig(
     level=logging.DEBUG,
@@ -22,7 +21,7 @@ class RESTAPI:
     Can run any FastAPI app instance or assemble one from routers.
     """
 
-    _log = logging.getLogger("ak.api.restapi")
+    _log = logging.getLogger("ak.api.http")
     _custom_routers = []
 
     @classmethod
@@ -79,12 +78,12 @@ class RESTAPI:
                 routers.append(handler.get_router())
 
         if AKConfig.get().a2a.enabled:
-            from .a2a import A2ARESTRequestHandler
+            from .a2a.handler import A2ARESTRequestHandler
 
             routers.append(A2ARESTRequestHandler.get_catalog_router())
             routers.extend(A2ARESTRequestHandler.get_agent_routers())
         if AKConfig.get().mcp.enabled:
-            from ..mcp.akmcp import MCP
+            from .mcp.akmcp import MCP
 
             mcp_app = MCP.get_http_app()
             app = cls._create_app(routers=routers, lifespan=mcp_app.lifespan)

{agentkernel-0.2.5/src/agentkernel → agentkernel-0.2.7/src/agentkernel/api}/mcp/akmcp.py

@@ -4,8 +4,8 @@ from typing import Any
 from fastmcp import Context, FastMCP
 from fastmcp.server.http import StarletteWithLifespan
 
-from ..core import Agent, AgentService, GlobalRuntime
-from ..core.config import AKConfig
+from ...core import Agent, AgentService, GlobalRuntime
+from ...core.config import AKConfig
 
 
 class MCP:

agentkernel-0.2.7/src/agentkernel/aws.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("agentkernel")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .deployment.aws import *

{agentkernel-0.2.5 → agentkernel-0.2.7}/src/agentkernel/core/__init__.py

@@ -12,8 +12,19 @@ except importlib.metadata.PackageNotFoundError:
     __version__ = "0.1.0"
 
 from .base import Agent, Runner, Session
+from .model import (
+    AgentRequest,
+    AgentRequestAny,
+    AgentRequestFile,
+    AgentRequestImage,
+    AgentRequestText,
+    AgentReply,
+    AgentReplyText,
+    AgentReplyImage,
+)
 from .config import AKConfig as Config
 from .module import Module
 from .runtime import GlobalRuntime, Runtime
 from .service import AgentService
-from .sessions.redis import RedisDriver, RedisSessionSerde
+from .hooks import Prehook, Posthook
+from .util.key_value_cache import KeyValueCache

{agentkernel-0.2.5 → agentkernel-0.2.7}/src/agentkernel/core/base.py

@@ -1,8 +1,13 @@
+import contextvars
 import logging
 from abc import ABC, abstractmethod
 from typing import Any, List
 
 from .config import AKConfig
+from .model import AgentReply, AgentRequest
+from .util.key_value_cache import KeyValueCache
+
+current_session = contextvars.ContextVar("session_id", default="")
 
 
 class Session:
@@ -17,6 +22,31 @@ class Session:
     the runtime configuration.
     """
 
+    VOLATILE_CACHE_KEY = "v_cache"
+    NON_VOLATILE_CACHE_KEY = "nv_cache"
+
+    @classmethod
+    def get_current_session_id(cls) -> str:
+        """
+        Returns the current session ID from the context variable.
+        :return: The current session ID.
+        """
+        return current_session.get()
+
+    def get_volatile_cache(self) -> KeyValueCache:
+        """
+        Returns the volatile key-value cache associated with this session.
+        :return: The volatile KeyValueCache instance.
+        """
+        return self.get(self.VOLATILE_CACHE_KEY)
+
+    def get_non_volatile_cache(self) -> KeyValueCache:
+        """
+        Returns the non-volatile key-value cache associated with this session.
+        :return: The non-volatile KeyValueCache instance.
+        """
+        return self.get(self.NON_VOLATILE_CACHE_KEY)
+
     def __init__(self, id: str):
         """
         Initializes a Session instance.
@@ -26,6 +56,12 @@ class Session:
         self._id = id
         self._data = {}
 
+        # Pre-initialize key-value caches to be used by application code which will not be part of the agent context
+        self.set(self.VOLATILE_CACHE_KEY, KeyValueCache())
+        self.set(self.NON_VOLATILE_CACHE_KEY, KeyValueCache())
+
+        self._token = None
+
     @property
     def id(self) -> str:
         """
@@ -62,6 +98,19 @@ class Session:
         self._data[key] = value
         return value
 
+    def set_context(self):
+        """
+        Sets the current session context variable to this session's ID.
+        """
+        self._token = current_session.set(self._id)
+
+    def reset_context(self):
+        """
+        Resets the current session context variable to the previous value.
+        """
+        if self._token:
+            current_session.reset(self._token)
+
 
 class Runner(ABC):
     """
@@ -88,12 +137,12 @@ class Runner(ABC):
         return self._name
 
     @abstractmethod
-    async def run(self, agent: Any, session: Session, prompt: Any) -> Any:
+    async def run(self, agent: Any, session: Session, requests: list[AgentRequest]) -> AgentReply:
         """
-        Runs the agent with the provided prompt.
+        Runs the agent with the provided multi modal inputs.
         :param agent: The agent to run.
         :param session: The session to use for the agent.
-        :param prompt: The prompt to provide to the agent.
+        :param requests: The list of requests to provide to the agent.
         :return: The result of the agent's execution.
         """
         pass

{agentkernel-0.2.5 → agentkernel-0.2.7}/src/agentkernel/core/builder.py

@@ -2,9 +2,7 @@ import logging
 from enum import StrEnum
 
 from .config import AKConfig
-from .sessions import SessionStore
-from .sessions.in_memory import InMemorySessionStore
-from .sessions.redis import RedisDriver, RedisSessionStore
+from .session import SessionStore
 
 
 class Builder:
@@ -29,6 +27,7 @@ class SessionStoreType(StrEnum):
 
     IN_MEMORY = "IN_MEMORY"
     REDIS = "REDIS"
+    DYNAMODB = "DYNAMODB"
 
     @classmethod
     def from_str(cls, type_str: str) -> "SessionStoreType":
@@ -67,9 +66,10 @@ class SessionStoreBuilder(Builder):
 
         This static method reads the session store type from the application configuration
         and instantiates the appropriate SessionStore implementation. Currently supports
-        Redis-backed and in-memory session stores.
+        Redis-backed, DynamoDB-backed, and in-memory session stores.
 
-        :returns: An instance of either RedisSessionStore (if configured type is REDIS)
+        :returns: An instance of RedisSessionStore (if configured type is REDIS),
+            DynamoDBSessionStore (if configured type is DYNAMODB),
             or InMemorySessionStore (for all other types).
 
         :raises: Any exceptions raised by SessionStoreType.from_str(), AKConfig.get(),
@@ -79,6 +79,14 @@ class SessionStoreBuilder(Builder):
 
         Builder._log.info(f"Building {session_store_type} session store")
         if session_store_type == SessionStoreType.REDIS:
-            return RedisSessionStore(RedisDriver())
+            from .session.redis import RedisSessionStore
+
+            return RedisSessionStore()
+        elif session_store_type == SessionStoreType.DYNAMODB:
+            from .session.dynamodb import DynamoDBSessionStore
+
+            return DynamoDBSessionStore()
         else:
+            from .session.in_memory import InMemorySessionStore
+
             return InMemorySessionStore()

{agentkernel-0.2.5 → agentkernel-0.2.7}/src/agentkernel/core/config.py

@@ -22,9 +22,20 @@ class _RedisConfig(BaseModel):
     prefix: str = Field(default="ak:sessions:", description="Key prefix for Redis session storage")
 
 
+class _DynamoDBConfig(BaseModel):
+    table_name: str = Field(
+        description="DynamoDB table name for session storage. Table should have a partition key named 'session_id' and a sort key named 'key'"
+    )
+    ttl: int = Field(
+        default=604800,
+        description="DynamoDB item TTL in seconds (0 disables). Used to compute UNIX epoch 'expiry_time' attribute written per item.",
+    )
+
+
 class _SessionStoreConfig(BaseModel):
-    type: str = Field(default="in_memory", pattern="^(in_memory|redis)$")
+    type: str = Field(default="in_memory", pattern="^(in_memory|redis|dynamodb)$")
     redis: Optional[_RedisConfig] = None
+    dynamodb: Optional[_DynamoDBConfig] = None
 
 
 class _RoutesConfig(BaseModel):

agentkernel-0.2.7/src/agentkernel/core/hooks.py

@@ -0,0 +1,74 @@
+from abc import ABC, abstractmethod
+
+from .base import Agent, Session
+from .model import AgentReply, AgentRequest
+
+"""
+Prehook and Posthook classes define the interface for hooks that can be executed before and after an agent's execution respectively.
+These hooks allow for modification of prompts before execution and replies after execution, enabling functionalities such as context injection, validation, moderation, logging, and analytics. 
+
+Currently, they will get only called for the initial execution of an agent when a user prompt is provided. It's unable to hook into agent-to-agent calls within a workflow. This will be a future enhancement.
+"""
+
+
+class Prehook(ABC):
+    @abstractmethod
+    async def on_run(
+        self, session: Session, agent: Agent, requests: list[AgentRequest]
+    ) -> list[AgentRequest] | AgentReply:
+        """
+        Hook method called before an agent starts executing a prompt. These hooks can modify the prompt or halt execution.
+        Some use cases:
+          - RAG context injection
+          - Prompt validation like input guard rails
+          - Logging or analytics
+
+        :param: session (Session): The session instance.
+        :param: agent (Agent): The agent that will execute the prompt.
+        :param: requests (list[AgentRequest]): The list of requests provided to the agent.
+        :return:
+                - AgentReply: If the hook decides to halt execution, it can return an AgentReply which will be sent
+                - list[AgentRequest]: The modified requests or the input list. You can modify the requests in place without taking copies
+                                      You can also add additional content to the requests list. e.g. files, images, etc.
+
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Returns the name of the prehook.
+        """
+        raise NotImplementedError
+
+
+class Posthook(ABC):
+    @abstractmethod
+    async def on_run(
+        self, session: Session, requests: list[AgentRequest], agent: Agent, agent_reply: AgentReply
+    ) -> AgentReply:
+        """
+        Hook method called after an agent finishes executing a prompt. These hooks can modify the agent's reply. Some use cases:
+          - Moderation of agent replies. e.g. output guardrails
+          - Adding disclaimers or additional information to the reply
+          - Logging or analytics
+
+        Note: if the hook changes the reply, the modified reply will be sent to the next hook for processing.
+              The agent_reply parameter contains the unmodified reply from the agent for the first posthook, and the reply modified by previous posthooks for subsequent hooks.
+
+        :param:  session (Session): The session instance.
+        :param:  requests (list[AgentRequest]): The original requests provided to the agent after any pre-execution hooks have been applied.
+        :param:  agent (Agent): The agent that executed the prompt.
+        :param:  agent_reply (AgentReply): The reply to process. For the first posthook, this is the unmodified
+                              agent reply. For subsequent posthooks, this is the reply modified by previous posthooks in the chain.
+
+        :return: The modified reply. If not modified, return the current reply.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def name(self) -> str:
+        """
+        :return: the name of the posthook.
+        """
+        raise NotImplementedError

agentkernel-0.2.7/src/agentkernel/core/model.py

@@ -0,0 +1,106 @@
+from typing import Any, Literal, Union
+
+from pydantic import BaseModel
+
+
+class AgentRequestText(BaseModel):
+    """
+    AgentRequestText encapsulates a text request to an agent.
+
+    text: str  : This is the user input text
+    type: Literal["text"]
+    """
+
+    text: str
+    type: Literal["text"] = "text"
+
+    def __str__(self) -> str:
+        return self.text
+
+
+class AgentRequestFile(BaseModel):
+    """
+    AgentRequestFile encapsulates a file attachment request to an agent
+
+    file_data: str  : This could be base64 encoded string or url
+    name: str : name of the file
+    type: Literal["file"]
+    mime_type: str | None = None : Optional. The IANA standard MIME type of the file
+    """
+
+    file_data: str  # This could be base64 encoded string or url
+    name: str
+    type: Literal["file"] = "file"
+    mime_type: str | None = None  # Optional. The IANA standard MIME type of the source data
+
+
+class AgentRequestImage(BaseModel):
+    """
+    AgentRequestImage encapsulates an image request to an agent
+
+    image_data: str  : This should be base64 encoded string
+    name: str : name of the image
+    type: Literal["image"]
+    mime_type: str | None = None : Optional. The IANA standard MIME type of the image
+    """
+
+    image_data: str
+    name: str
+    type: Literal["image"] = "image"
+    mime_type: str | None = None
+
+
+class AgentRequestAny(BaseModel):
+    """
+    AgentRequestAny encapsulates passing any type of request to be handled by the pre-execution hooks. These are not directly handled by the agent kernel runtime.
+
+    content: Any : This could be base64 encoded string or bytes or url
+    name: str : name of the data
+    type: Literal["other"]
+    """
+
+    content: Any
+    name: str
+    type: Literal["other"] = "other"
+
+
+class AgentReplyText(AgentRequestText):
+    """
+    AgentReplyText encapsulates a text reply from an agent.
+
+    prompt: str : The text prompt sent to the agent
+
+    Inherits fields `text` and `type` from AgentRequestText.
+    """
+
+    prompt: str = ""
+
+    def __str__(self) -> str:
+        return self.text
+
+
+class AgentReplyImage(BaseModel):
+    """
+    AgentReplyImage encapsulates a text & image reply from an agent.
+
+    text: str  : This is the agent output text
+    prompt: str : The text prompt sent to the agent
+    image_data: str  : This should be base64 encoded string
+    name: str : name of the image
+    type: Literal["image"]
+    mime_type: str | None = None : Optional. The IANA standard MIME type of the image
+    """
+
+    text: str
+    prompt: str = ""
+    image_data: str
+    name: str
+    type: Literal["image"] = "image"
+    mime_type: str | None = None
+
+    def __str__(self) -> str:
+        return f"{self.text}. Image {self.name} is attached."
+
+
+type AgentRequest = Union[AgentRequestText, AgentRequestFile, AgentRequestImage, AgentRequestAny]
+type AgentReply = Union[AgentReplyText, AgentReplyImage]