agentkernel 0.2.7__tar.gz → 0.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.2.7
+Version: 0.2.8
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -21,6 +21,7 @@ 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'
+Requires-Dist: httpx>=0.27.0 ; extra == 'instagram'
 Requires-Dist: langfuse>=3.9.2 ; extra == 'langfuse'
 Requires-Dist: nest-asyncio>=1.6.0 ; extra == 'langfuse'
 Requires-Dist: langgraph~=0.6.2 ; extra == 'langgraph'
@@ -34,6 +35,7 @@ Requires-Dist: openinference-instrumentation-openai-agents>=1.3.0 ; extra == 'op
 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: httpx>=0.27.0 ; extra == 'telegram'
 Requires-Dist: pytest>=8.4.1 ; extra == 'test'
 Requires-Dist: pytest-asyncio>=1.2.0 ; extra == 'test'
 Requires-Dist: pytest-cov>=6.2.1 ; extra == 'test'
@@ -48,6 +50,7 @@ Provides-Extra: api
 Provides-Extra: aws
 Provides-Extra: cli
 Provides-Extra: crewai
+Provides-Extra: instagram
 Provides-Extra: langfuse
 Provides-Extra: langgraph
 Provides-Extra: mcp
@@ -56,6 +59,7 @@ Provides-Extra: openai
 Provides-Extra: openllmetry
 Provides-Extra: redis
 Provides-Extra: slack
+Provides-Extra: telegram
 Provides-Extra: test
 Provides-Extra: whatsapp
 Description-Content-Type: text/markdown

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.2.7"
+version = "0.2.8"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -71,6 +71,12 @@ whatsapp = [
 messenger = [
     "httpx>=0.27.0"
 ]
+instagram = [
+    "httpx>=0.27.0"
+]
+telegram = [
+    "httpx>=0.27.0"
+]
 test = [
     "pytest>=8.4.1",
     "pytest-asyncio>=1.2.0",

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

@@ -0,0 +1,304 @@
+import base64
+import logging
+import traceback
+from abc import ABC, abstractmethod
+from http import HTTPStatus
+from typing import List, Optional
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from pydantic import BaseModel, ConfigDict
+
+from agentkernel.core.model import (
+    AgentReplyImage,
+    AgentReplyText,
+    AgentRequestAny,
+    AgentRequestFile,
+    AgentRequestImage,
+    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 FileData(BaseModel):
+        """Represents a file attachment"""
+
+        file_data: str  # base64 encoded string or URL
+        name: str
+        mime_type: Optional[str] = None
+
+    class ImageData(BaseModel):
+        """Represents an image attachment"""
+
+        image_data: str  # base64 encoded string
+        name: str
+        mime_type: Optional[str] = None
+
+    class RunRequest(BaseModel):
+        model_config = ConfigDict(extra="allow")
+
+        prompt: str
+        agent: Optional[str] = None
+        session_id: Optional[str] = None
+        files: Optional[List["AgentRESTRequestHandler.FileData"]] = None
+        images: Optional[List["AgentRESTRequestHandler.ImageData"]] = 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)
+
+        @router.post("/run-multipart")
+        async def run_multipart(
+            prompt: str = Form(...),
+            agent: Optional[str] = Form(None),
+            session_id: Optional[str] = Form(None),
+            files: Optional[List[UploadFile]] = File(None),
+            images: Optional[List[UploadFile]] = File(None),
+        ):
+            return await self.run_multipart(prompt, agent, session_id, files, images)
+
+        return router
+
+    async def run(self, req: RunRequest):
+        """
+        Async method to run the agent.
+        :param req: Request object containing the prompt, optional agent name, attachments, images, and additional properties.
+        """
+        requests = []
+        requests.append(AgentRequestText(text=req.prompt))
+        service = None
+        try:
+            # Process attachments (documents, PDFs, CSVs, etc.)
+            if req.files:
+                for file in req.files:
+                    self._log.debug(f"Adding file attachment: {file.name}")
+                    if not file.file_data.startswith(("http://", "https://", "data:", "s3://")) and not file.mime_type:
+                        raise ValueError("mime_type is missing for file input, either in the base64 or explicitly")
+                    requests.append(
+                        AgentRequestFile(
+                            file_data=file.file_data,
+                            name=file.name,
+                            mime_type=file.mime_type if file.mime_type else None,
+                        )
+                    )
+
+            # Process images (JPEG, PNG, etc.)
+            if req.images:
+                for image in req.images:
+                    self._log.debug(f"Adding image: {image.name}")
+                    if (
+                        not image.image_data.startswith(("http://", "https://", "data:", "s3://"))
+                        and not image.mime_type
+                    ):
+                        raise ValueError("mime_type is missing for image input, either in the base64 or explicitly")
+                    requests.append(
+                        AgentRequestImage(
+                            image_data=image.image_data,
+                            name=image.name,
+                            mime_type=image.mime_type if image.mime_type else None,
+                        )
+                    )
+
+            # Pack additional properties into AgentRequestAny
+            known_fields = {"prompt", "agent", "session_id", "files", "images"}
+            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()
+
+            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) if service is not None else 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) if service is not None else req.session_id,
+                },
+            )
+
+    async def run_multipart(
+        self,
+        prompt: str,
+        agent: Optional[str] = None,
+        session_id: Optional[str] = None,
+        files: Optional[List[UploadFile]] = None,
+        images: Optional[List[UploadFile]] = None,
+    ):
+        """
+        Async method to run the agent with multipart file uploads.
+        :param prompt: The text prompt for the agent.
+        :param agent: Optional agent name.
+        :param session_id: Optional session ID.
+        :param files: Optional list of uploaded files (documents, PDFs, CSVs, etc.).
+        :param images: Optional list of uploaded images (JPEG, PNG, etc.).
+        """
+        requests = []
+        requests.append(AgentRequestText(text=prompt))
+        service = None
+
+        try:
+            # Process file uploads
+            if files:
+                for file in files:
+                    self._log.debug(f"Processing uploaded file: {file.filename}")
+                    # Read file content
+                    content = await file.read()
+                    # Encode to base64
+                    file_data_base64 = base64.b64encode(content).decode("utf-8")
+
+                    # Get mime type from the upload
+                    mime_type = file.content_type
+
+                    self._log.debug(f"Adding file attachment: {file.filename} (type: {mime_type})")
+                    requests.append(
+                        AgentRequestFile(
+                            file_data=file_data_base64,
+                            name=file.filename or "unknown",
+                            mime_type=mime_type,
+                        )
+                    )
+
+            # Process image uploads
+            if images:
+                for image in images:
+                    self._log.debug(f"Processing uploaded image: {image.filename}")
+                    # Read image content
+                    content = await image.read()
+                    # Encode to base64
+                    image_data_base64 = base64.b64encode(content).decode("utf-8")
+
+                    # Get mime type from the upload
+                    mime_type = image.content_type
+
+                    # Validate it's an image mime type
+                    if mime_type and not mime_type.startswith("image/"):
+                        raise ValueError(f"Invalid image type: {mime_type} for file {image.filename}")
+
+                    self._log.debug(f"Adding image: {image.filename} (type: {mime_type})")
+                    requests.append(
+                        AgentRequestImage(
+                            image_data=image_data_base64,
+                            name=image.filename or "unknown",
+                            mime_type=mime_type,
+                        )
+                    )
+
+            service = AgentService()
+            service.select(session_id, 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"
+                ),
+                "session_id": service.get_response_session_id(session_id),
+            }
+
+        except HTTPException:
+            raise
+        except ValueError as e:
+            self._log.error(f"POST /run-multipart error: {e}\n{traceback.format_exc()}")
+            raise HTTPException(
+                status_code=HTTPStatus.BAD_REQUEST,
+                detail={
+                    "error": str(e),
+                    "session_id": service.get_response_session_id(session_id) if service is not None else session_id,
+                },
+            )
+        except Exception as e:
+            self._log.error(f"POST /run-multipart 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) if service is not None else session_id,
+                },
+            )

{agentkernel-0.2.7 → agentkernel-0.2.8}/src/agentkernel/cli/cli.py

@@ -35,6 +35,7 @@ class CLI:
         self._print("!ld, !load <module_name> - Load agent module")
         self._print("!ls, !list - List available agents")
         self._print("!n, !new - Start a new session")
+        self._print("!c, !clear - Clear the current session memory")
         self._print("!s, !select <agent_name> - Select an agent to run the prompt")
         self._print("!q, !quit - Exit the program")
         self._print()
@@ -67,14 +68,16 @@ class CLI:
                     command = tokens[0]
                     if command in ["!h", "!help"]:
                         self.help()
-                    elif command in ["!ls", "!list"]:
-                        self.list()
+                    elif command in ["!c", "!clear"]:
+                        self._service.clear()
                     elif command in ["!ld", "!load"]:
                         if len(tokens) != 2:
                             self._print("Usage: !load <module_name>")
                             continue
                         session_id = self._service.session.id if self._service.session else None
                         self._service.load(name=tokens[1], session_id=session_id)
+                    elif command in ["!ls", "!list"]:
+                        self.list()
                     elif command in ["!n", "!new"]:
                         self._service.new()
                     elif command in ["!q", "!quit"]:

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

@@ -12,7 +12,7 @@ current_session = contextvars.ContextVar("session_id", default="")
 
 class Session:
     """
-    Session is the base class for a stacking state across related interactions with agents.
+    Session is the base class for a tracking state across related interactions with agents.
 
     Agent Kernel provides an implementation of the Session class for each supported agent framework,
     allowing the runtime to track and share state across multiple related agent logic invocations.
@@ -20,6 +20,15 @@ class Session:
     Sessions may be volatile (meaning that they are not persisted) or durable (meaning that they
     are persisted and are available across multiple invocations of the runtime). This is governed by
     the runtime configuration.
+
+    Session class stores framework-specific session data objects in a key-value store, allowing
+    different agent frameworks to store and retrieve their own session data without interfering with
+    each other.
+
+    In addition, there are two pre-defined key-value caches for storing data that is either volatile
+    (i.e., not persisted across runtime invocations) or non-volatile (i.e., persisted across runtime
+    invocations). These caches can be used by application code to store data that is not part of the
+    agent context but needs to be retained across multiple interactions within the same session.
     """
 
     VOLATILE_CACHE_KEY = "v_cache"
@@ -28,8 +37,8 @@ class Session:
     @classmethod
     def get_current_session_id(cls) -> str:
         """
-        Returns the current session ID from the context variable.
-        :return: The current session ID.
+        Returns the current session identifier from the context variable.
+        :return: The current session identifier.
         """
         return current_session.get()
 
@@ -56,7 +65,8 @@ 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
+        # 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())
 
@@ -72,13 +82,13 @@ class Session:
 
     def get(self, key: str) -> Any:
         """
-        Retrieves a framework-specific session object from the session data.
-        :param key: The key to retrieve the session object for.
-        :return: The framework-specific session object associated with the key, or None if the key
-        does not exist.
+        Retrieves the specified session data object.
+        :param key: The key of the session data object.
+        :return: The matching session object associated with the key, or None
+        if there is no data object with the specified key.
         """
         result = self._data.get(key)
-        self._log.debug(f"Retrieved session object for key {key}: {result}")
+        self._log.debug(f"Retrieved session {self._id} data object for key {key}: {result}")
         return result
 
     def get_all_keys(self):
@@ -90,14 +100,35 @@ class Session:
 
     def set(self, key: str, value: Any) -> Any:
         """
-        Sets a framework-specific session object in the session data.
-        :param key: The key to set the session object for.
-        :param value: The framework-specific session object to set.
+        Sets a session data object for the specified key.
+        :param key: The key of the session data object.
+        :param value: The session data object.
         """
-        self._log.debug(f"Setting session object for key {key}: {value}")
+        self._log.debug(f"Setting session {self._id} data object for key {key}: {value}")
         self._data[key] = value
         return value
 
+    def delete(self, key: str) -> None:
+        """
+        Deletes the session data object for the specified key.
+        :param key: The key of the session data object to be deleted.
+        """
+        if key in self._data:
+            self._log.debug(f"Deleting session {self._id} data object for key {key}")
+            del self._data[key]
+
+    def clear(self) -> None:
+        """
+        Clears all session data objects.
+        """
+        self._log.debug(f"Clearing session {self._id} data objects")
+        self._data = {
+            self.VOLATILE_CACHE_KEY: self.get_volatile_cache(),
+            self.NON_VOLATILE_CACHE_KEY: self.get_non_volatile_cache(),
+        }
+        self.get_volatile_cache().clear()
+        self.get_non_volatile_cache().clear()
+
     def set_context(self):
         """
         Sets the current session context variable to this session's ID.

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

@@ -92,6 +92,22 @@ class _MessengerConfig(BaseModel):
     api_version: str = Field(default="v24.0", description="Facebook Graph API version")
 
 
+class _InstagramConfig(BaseModel):
+    agent: str = Field(default="", description="Default agent to use for Instagram interactions")
+    verify_token: str = Field(default="", description="Instagram webhook verify token")
+    access_token: str = Field(default="", description="Instagram Business access token")
+    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")
+
+
+class _TelegramConfig(BaseModel):
+    agent: str = Field(default="", description="Default agent to use for Telegram")
+    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")
+
+
 class _TraceConfig(BaseModel):
     enabled: bool = Field(default=False, description="Enable tracing")
     type: str = Field(default="langfuse", pattern="^(langfuse|openllmetry)$")
@@ -114,6 +130,12 @@ class AKConfig(YamlBaseSettingsModified):
     messenger: _MessengerConfig = Field(
         description="Facebook Messenger related configurations", default_factory=_MessengerConfig
     )
+    instagram: _InstagramConfig = Field(
+        description="Instagram Business API related configurations", default_factory=_InstagramConfig
+    )
+    telegram: _TelegramConfig = Field(
+        description="Telegram Bot related configurations", default_factory=_TelegramConfig
+    )
     trace: _TraceConfig = Field(description="Tracing related configurations", default_factory=_TraceConfig)
     library_version: str = Field(default=_get_ak_version(), description="Library version")
 

{agentkernel-0.2.7 → agentkernel-0.2.8}/src/agentkernel/core/service.py

@@ -94,6 +94,16 @@ class AgentService:
         self._log.info(f"Starting new session: {session_id}")
         self._session = self._runtime.sessions().new(session_id)
 
+    def clear(self):
+        """
+        Clears the current session data.
+        """
+        if self._session:
+            self._log.info(f"Clearing session: {self._session.id}")
+            self._session.clear()
+        else:
+            self._log.warning("No session available to clear.")
+
     def load(self, session_id: str, name: str):
         """
         Loads an agent module by name.