agentkernel 0.2.13__tar.gz → 0.3.0__tar.gz

{agentkernel-0.2.13 → agentkernel-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.2.13
+Version: 0.3.0
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -38,6 +38,7 @@ Requires-Dist: langchain-community~=0.4.1 ; extra == 'langgraph'
 Requires-Dist: litellm~=1.74.9 ; extra == 'langgraph'
 Requires-Dist: fastmcp>=2.12.4 ; extra == 'mcp'
 Requires-Dist: httpx>=0.27.0 ; extra == 'messenger'
+Requires-Dist: litellm>=1.74.9 ; extra == 'multimodal'
 Requires-Dist: openai-agents>=0.6.5 ; extra == 'openai'
 Requires-Dist: openinference-instrumentation-openai-agents>=1.4.0 ; extra == 'openai'
 Requires-Dist: openai-guardrails>=0.2.1 ; extra == 'openai'
@@ -56,6 +57,7 @@ Requires-Dist: ragas>=0.4.1 ; extra == 'test'
 Requires-Dist: datasets>=2.14.0 ; extra == 'test'
 Requires-Dist: pandas>=2.0.0 ; extra == 'test'
 Requires-Dist: litellm>=1.74.9 ; extra == 'test'
+Requires-Dist: walledai>=4.9.3 ; extra == 'walledai'
 Requires-Dist: httpx>=0.27.0 ; extra == 'whatsapp'
 Requires-Python: >=3.12, <3.14
 Provides-Extra: a2a
@@ -72,12 +74,14 @@ Provides-Extra: langfuse
 Provides-Extra: langgraph
 Provides-Extra: mcp
 Provides-Extra: messenger
+Provides-Extra: multimodal
 Provides-Extra: openai
 Provides-Extra: openllmetry
 Provides-Extra: redis
 Provides-Extra: slack
 Provides-Extra: telegram
 Provides-Extra: test
+Provides-Extra: walledai
 Provides-Extra: whatsapp
 Description-Content-Type: text/markdown
 
@@ -261,6 +265,32 @@ OpenAIModule([assistant])
 handler = Lambda.handler
 ```
 
+**Note that this is just the simple serverless version. A more advanced serverless deployment mode, which uses queues for scalability, is also available. For queue-backed execution modes and response-store configuration, see the [AWS Serverless Deployment](https://github.com/yaalalabs/agent-kernel/tree/develop/docs/docs/deployment/aws-serverless.md) guide.**
+
+The AWS serverless handler accepts both a direct `BaseRunRequest` payload and the normalized `BaseRequest` envelope. If a flat run payload is provided, Agent Kernel generates a `request_id` and normalizes it before processing. 
+
+Accepted payloads:
+
+```json
+{
+  "prompt": "Hello agent",
+  "agent": "assistant",
+  "session_id": "user-123"
+}
+```
+
+```json
+{
+  "request_id": "req-123",
+  "user_id": "user-123",
+  "body": {
+    "prompt": "Hello agent",
+    "agent": "assistant",
+    "session_id": "user-123"
+  }
+}
+```
+
 ### Azure Functions Deployment
 
 Deploy your agents as Azure Functions using the built-in Azure handler.
@@ -282,11 +312,18 @@ handler = AzureFunctions.handler
 
 ```json
 {
-  "prompt": "Hello agent",
-  "agent": "assistant"
+  "request_id": "req-123",
+  "user_id": "user-123",
+  "body": {
+    "prompt": "Hello agent",
+    "agent": "assistant",
+    "session_id": "user-123"
+  }
 }
 ```
 
+Azure Functions also accepts the normalized envelope, and flat run payloads are normalized in the same way before the request reaches the agent runtime.
+
 **Response Format:**
 
 ```json
@@ -367,6 +404,72 @@ Required when `session.type=redis`:
   - **Description**: Key prefix for session storage
   - **Environment Variable**: `AK_SESSION__REDIS__PREFIX`
 
+#### Execution Configuration
+
+Configure queue-backed and serverless execution behavior.
+
+- **Execution Mode**
+  - **Field**: `execution.mode`
+  - **Options**: `rest_sync`, `rest_async`, `stream`, `async`
+  - **Default**: `None`
+  - **Description**: Selects the Lambda execution mode
+  - **Environment Variable**: `AK_EXECUTION__MODE`
+
+- **Queues**
+  - **Field**: `execution.queues`
+  - **Description**: Queue settings used by serverless execution modes
+
+  - **Input Queue URL**
+    - **Field**: `execution.queues.input.url`
+    - **Default**: `None`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__URL`
+
+  - **Output Queue URL**
+    - **Field**: `execution.queues.output.url`
+    - **Default**: `None`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__URL`
+
+  - **Input Queue Max Receive Count**
+    - **Field**: `execution.queues.input.max_receive_count`
+    - **Default**: `3`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__MAX_RECEIVE_COUNT`
+
+  - **Output Queue Max Receive Count**
+    - **Field**: `execution.queues.output.max_receive_count`
+    - **Default**: `3`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__MAX_RECEIVE_COUNT`
+
+- **Response Store**
+  - **Field**: `execution.response_store`
+  - **Description**: Response persistence settings used by the serverless response handler
+
+  - **Type**
+    - **Field**: `execution.response_store.type`
+    - **Description**: Response store backend selector configured in `config.yaml`; this value is not exported as an environment variable
+
+  - **Retry Count**
+    - **Field**: `execution.response_store.retry_count`
+    - **Default**: `5`
+    - **Description**: Number of lookup attempts when polling for a response
+    - **Environment Variable**: `AK_EXECUTION__RESPONSE_STORE__RETRY_COUNT`
+
+  - **Delay**
+    - **Field**: `execution.response_store.delay`
+    - **Default**: `5`
+    - **Description**: Delay in seconds between response lookup attempts
+    - **Environment Variable**: `AK_EXECUTION__RESPONSE_STORE__DELAY`
+
+  - **Redis Backend**
+    - **Field**: `execution.response_store.redis`
+    - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__REDIS__URL`, `AK_EXECUTION__RESPONSE_STORE__REDIS__PREFIX`, `AK_EXECUTION__RESPONSE_STORE__REDIS__TTL`
+
+  - **DynamoDB Backend**
+    - **Field**: `execution.response_store.dynamodb`
+    - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TABLE_NAME`, `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TTL`
+    - **Description**: DynamoDB-backed response storage with table name and TTL
+
+Use either Redis or DynamoDB for the response store backend. The runtime accepts `BaseRunRequest` payloads directly, normalizes them internally when queueing is required, and uses `request_id` plus optional `user_id` as SQS message attributes.
+
 #### API Configuration
 
 Configure the REST API server (if using the API module).
@@ -561,7 +664,7 @@ Configure input and output guardrails to validate agent requests and responses f
   - **Type**
     - **Field**: `guardrail.input.type`
     - **Default**: `openai`
-    - **Options**: `openai`, `bedrock`
+    - **Options**: `openai`, `bedrock`, `walledai`
     - **Description**: Guardrail provider type
     - **Environment Variable**: `AK_GUARDRAIL__INPUT__TYPE`
 
@@ -599,7 +702,7 @@ Configure input and output guardrails to validate agent requests and responses f
   - **Type**
     - **Field**: `guardrail.output.type`
     - **Default**: `openai`
-    - **Options**: `openai`, `bedrock`
+    - **Options**: `openai`, `bedrock`, `walledai`
     - **Description**: Guardrail provider type
     - **Environment Variable**: `AK_GUARDRAIL__OUTPUT__TYPE`
 
@@ -641,12 +744,20 @@ To use AWS Bedrock guardrails, install the AWS package:
 pip install agentkernel[aws]
 ```
 
+To use Walled AI guardrails, install the Walled AI package:
+
+```bash
+pip install agentkernel[walledai]
+```
+
 Create guardrail configuration:
 
 **For OpenAI:** Create configuration files following the [OpenAI Guardrails format](https://guardrails.openai.com/).
 
 **For Bedrock:** Create a guardrail in AWS Bedrock and note the guardrail ID and version.
 
+**For Walled AI:** Set `WALLED_API_KEY`, use guardrail type `walledai`, and control PII masking with `pii`.
+
 Configure guardrails in your configuration:
 
 **OpenAI Example:**
@@ -679,6 +790,19 @@ guardrail:
     version: "1"
 ```
 
+**Walled AI Example:**
+```yaml
+guardrail:
+  input:
+    enabled: true
+    type: walledai
+    pii: true
+  output:
+    enabled: true
+    type: walledai
+    pii: true
+```
+
 #### Messaging Platform Integrations
 
 Configure integrations with messaging platforms.
@@ -789,6 +913,11 @@ export AK_GUARDRAIL__OUTPUT__ENABLED=false
 export AK_GUARDRAIL__OUTPUT__TYPE=openai
 export AK_GUARDRAIL__OUTPUT__MODEL=gpt-4o-mini
 export AK_GUARDRAIL__OUTPUT__CONFIG_PATH=/path/to/guardrails_output.json
+# Walled AI guardrails
+export WALLED_API_KEY=your-walledai-api-key
+export AK_GUARDRAIL__INPUT__PII=true
+export AK_GUARDRAIL__OUTPUT__PII=true
+export AK_DEBUG=true
 # Messaging platforms (optional)
 export AK_SLACK__AGENT=my-agent
 export AK_WHATSAPP__AGENT=my-agent
@@ -834,6 +963,27 @@ session:
     url: redis://localhost:6379
     ttl: 604800
     prefix: "ak:sessions:"
+execution:
+  mode: rest_sync
+  queues:
+    input:
+      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      max_receive_count: 3
+    output:
+      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      max_receive_count: 3
+  response_store:
+    type: redis
+    retry_count: 5
+    delay: 5
+    redis: # if this is given, then dynamodb response store part cannot be given
+      url: redis://localhost:6379
+      prefix: "ak:responses:"
+      ttl: 3600
+    dynamodb: # if this is given, then redis response store part cannot be given
+      table_name: table-name
+      table_arn: table-arn
+      ttl: 3600
 api:
   host: 0.0.0.0
   port: 8000
@@ -862,13 +1012,17 @@ guardrail:
   input:
     enabled: false
     type: openai
+    pii: true
     model: gpt-4o-mini
     config_path: /path/to/guardrails_input.json
   output:
     enabled: false
     type: openai
+    pii: true
     model: gpt-4o-mini
     config_path: /path/to/guardrails_output.json
+  # For Walled AI, set type: walledai, WALLED_API_KEY,
+  # and optionally use input/output pii (default: true) to enable/disable PII masking.
 slack:
   agent: my-agent
   agent_acknowledgement: "Processing your request..."

{agentkernel-0.2.13 → agentkernel-0.3.0}/README.md

@@ -178,6 +178,32 @@ OpenAIModule([assistant])
 handler = Lambda.handler
 ```
 
+**Note that this is just the simple serverless version. A more advanced serverless deployment mode, which uses queues for scalability, is also available. For queue-backed execution modes and response-store configuration, see the [AWS Serverless Deployment](https://github.com/yaalalabs/agent-kernel/tree/develop/docs/docs/deployment/aws-serverless.md) guide.**
+
+The AWS serverless handler accepts both a direct `BaseRunRequest` payload and the normalized `BaseRequest` envelope. If a flat run payload is provided, Agent Kernel generates a `request_id` and normalizes it before processing. 
+
+Accepted payloads:
+
+```json
+{
+  "prompt": "Hello agent",
+  "agent": "assistant",
+  "session_id": "user-123"
+}
+```
+
+```json
+{
+  "request_id": "req-123",
+  "user_id": "user-123",
+  "body": {
+    "prompt": "Hello agent",
+    "agent": "assistant",
+    "session_id": "user-123"
+  }
+}
+```
+
 ### Azure Functions Deployment
 
 Deploy your agents as Azure Functions using the built-in Azure handler.
@@ -199,11 +225,18 @@ handler = AzureFunctions.handler
 
 ```json
 {
-  "prompt": "Hello agent",
-  "agent": "assistant"
+  "request_id": "req-123",
+  "user_id": "user-123",
+  "body": {
+    "prompt": "Hello agent",
+    "agent": "assistant",
+    "session_id": "user-123"
+  }
 }
 ```
 
+Azure Functions also accepts the normalized envelope, and flat run payloads are normalized in the same way before the request reaches the agent runtime.
+
 **Response Format:**
 
 ```json
@@ -284,6 +317,72 @@ Required when `session.type=redis`:
   - **Description**: Key prefix for session storage
   - **Environment Variable**: `AK_SESSION__REDIS__PREFIX`
 
+#### Execution Configuration
+
+Configure queue-backed and serverless execution behavior.
+
+- **Execution Mode**
+  - **Field**: `execution.mode`
+  - **Options**: `rest_sync`, `rest_async`, `stream`, `async`
+  - **Default**: `None`
+  - **Description**: Selects the Lambda execution mode
+  - **Environment Variable**: `AK_EXECUTION__MODE`
+
+- **Queues**
+  - **Field**: `execution.queues`
+  - **Description**: Queue settings used by serverless execution modes
+
+  - **Input Queue URL**
+    - **Field**: `execution.queues.input.url`
+    - **Default**: `None`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__URL`
+
+  - **Output Queue URL**
+    - **Field**: `execution.queues.output.url`
+    - **Default**: `None`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__URL`
+
+  - **Input Queue Max Receive Count**
+    - **Field**: `execution.queues.input.max_receive_count`
+    - **Default**: `3`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__MAX_RECEIVE_COUNT`
+
+  - **Output Queue Max Receive Count**
+    - **Field**: `execution.queues.output.max_receive_count`
+    - **Default**: `3`
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__MAX_RECEIVE_COUNT`
+
+- **Response Store**
+  - **Field**: `execution.response_store`
+  - **Description**: Response persistence settings used by the serverless response handler
+
+  - **Type**
+    - **Field**: `execution.response_store.type`
+    - **Description**: Response store backend selector configured in `config.yaml`; this value is not exported as an environment variable
+
+  - **Retry Count**
+    - **Field**: `execution.response_store.retry_count`
+    - **Default**: `5`
+    - **Description**: Number of lookup attempts when polling for a response
+    - **Environment Variable**: `AK_EXECUTION__RESPONSE_STORE__RETRY_COUNT`
+
+  - **Delay**
+    - **Field**: `execution.response_store.delay`
+    - **Default**: `5`
+    - **Description**: Delay in seconds between response lookup attempts
+    - **Environment Variable**: `AK_EXECUTION__RESPONSE_STORE__DELAY`
+
+  - **Redis Backend**
+    - **Field**: `execution.response_store.redis`
+    - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__REDIS__URL`, `AK_EXECUTION__RESPONSE_STORE__REDIS__PREFIX`, `AK_EXECUTION__RESPONSE_STORE__REDIS__TTL`
+
+  - **DynamoDB Backend**
+    - **Field**: `execution.response_store.dynamodb`
+    - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TABLE_NAME`, `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TTL`
+    - **Description**: DynamoDB-backed response storage with table name and TTL
+
+Use either Redis or DynamoDB for the response store backend. The runtime accepts `BaseRunRequest` payloads directly, normalizes them internally when queueing is required, and uses `request_id` plus optional `user_id` as SQS message attributes.
+
 #### API Configuration
 
 Configure the REST API server (if using the API module).
@@ -478,7 +577,7 @@ Configure input and output guardrails to validate agent requests and responses f
   - **Type**
     - **Field**: `guardrail.input.type`
     - **Default**: `openai`
-    - **Options**: `openai`, `bedrock`
+    - **Options**: `openai`, `bedrock`, `walledai`
     - **Description**: Guardrail provider type
     - **Environment Variable**: `AK_GUARDRAIL__INPUT__TYPE`
 
@@ -516,7 +615,7 @@ Configure input and output guardrails to validate agent requests and responses f
   - **Type**
     - **Field**: `guardrail.output.type`
     - **Default**: `openai`
-    - **Options**: `openai`, `bedrock`
+    - **Options**: `openai`, `bedrock`, `walledai`
     - **Description**: Guardrail provider type
     - **Environment Variable**: `AK_GUARDRAIL__OUTPUT__TYPE`
 
@@ -558,12 +657,20 @@ To use AWS Bedrock guardrails, install the AWS package:
 pip install agentkernel[aws]
 ```
 
+To use Walled AI guardrails, install the Walled AI package:
+
+```bash
+pip install agentkernel[walledai]
+```
+
 Create guardrail configuration:
 
 **For OpenAI:** Create configuration files following the [OpenAI Guardrails format](https://guardrails.openai.com/).
 
 **For Bedrock:** Create a guardrail in AWS Bedrock and note the guardrail ID and version.
 
+**For Walled AI:** Set `WALLED_API_KEY`, use guardrail type `walledai`, and control PII masking with `pii`.
+
 Configure guardrails in your configuration:
 
 **OpenAI Example:**
@@ -596,6 +703,19 @@ guardrail:
     version: "1"
 ```
 
+**Walled AI Example:**
+```yaml
+guardrail:
+  input:
+    enabled: true
+    type: walledai
+    pii: true
+  output:
+    enabled: true
+    type: walledai
+    pii: true
+```
+
 #### Messaging Platform Integrations
 
 Configure integrations with messaging platforms.
@@ -706,6 +826,11 @@ export AK_GUARDRAIL__OUTPUT__ENABLED=false
 export AK_GUARDRAIL__OUTPUT__TYPE=openai
 export AK_GUARDRAIL__OUTPUT__MODEL=gpt-4o-mini
 export AK_GUARDRAIL__OUTPUT__CONFIG_PATH=/path/to/guardrails_output.json
+# Walled AI guardrails
+export WALLED_API_KEY=your-walledai-api-key
+export AK_GUARDRAIL__INPUT__PII=true
+export AK_GUARDRAIL__OUTPUT__PII=true
+export AK_DEBUG=true
 # Messaging platforms (optional)
 export AK_SLACK__AGENT=my-agent
 export AK_WHATSAPP__AGENT=my-agent
@@ -751,6 +876,27 @@ session:
     url: redis://localhost:6379
     ttl: 604800
     prefix: "ak:sessions:"
+execution:
+  mode: rest_sync
+  queues:
+    input:
+      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      max_receive_count: 3
+    output:
+      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      max_receive_count: 3
+  response_store:
+    type: redis
+    retry_count: 5
+    delay: 5
+    redis: # if this is given, then dynamodb response store part cannot be given
+      url: redis://localhost:6379
+      prefix: "ak:responses:"
+      ttl: 3600
+    dynamodb: # if this is given, then redis response store part cannot be given
+      table_name: table-name
+      table_arn: table-arn
+      ttl: 3600
 api:
   host: 0.0.0.0
   port: 8000
@@ -779,13 +925,17 @@ guardrail:
   input:
     enabled: false
     type: openai
+    pii: true
     model: gpt-4o-mini
     config_path: /path/to/guardrails_input.json
   output:
     enabled: false
     type: openai
+    pii: true
     model: gpt-4o-mini
     config_path: /path/to/guardrails_output.json
+  # For Walled AI, set type: walledai, WALLED_API_KEY,
+  # and optionally use input/output pii (default: true) to enable/disable PII masking.
 slack:
   agent: my-agent
   agent_acknowledgement: "Processing your request..."

{agentkernel-0.2.13 → agentkernel-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.2.13"
+version = "0.3.0"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -67,6 +67,9 @@ adk = [
     "litellm~=1.74.3",
     "openinference-instrumentation-google-adk>=0.1.6",
 ]
+walledai = [
+    "walledai>=4.9.3"
+]
 api = [
     "fastapi>=0.118.0",
     "uvicorn>=0.37.0",
@@ -112,6 +115,12 @@ a2a = [
 mcp = [
     "fastmcp>=2.12.4",
 ]
+multimodal = [
+    "litellm>=1.74.9",
+]
+
+[project.scripts]
+ak = "agentkernel.cli.ak:main"
 
 [dependency-groups]
 dev = [

{agentkernel-0.2.13 → agentkernel-0.3.0}/src/agentkernel/api/handler.py

@@ -15,6 +15,7 @@ from agentkernel.core.model import (
     AgentRequestFile,
     AgentRequestImage,
     AgentRequestText,
+    BaseRunRequest,
 )
 
 from ..core import AgentService, Config
@@ -67,12 +68,9 @@ class AgentRESTRequestHandler(RESTRequestHandler):
         name: str
         mime_type: Optional[str] = None
 
-    class RunRequest(BaseModel):
+    class RunRequest(BaseRunRequest):
         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
 

{agentkernel-0.2.13 → agentkernel-0.3.0}/src/agentkernel/auth/handler.py

@@ -1,10 +1,6 @@
-import base64
-import hashlib
-import hmac
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional
 
-import jwt
 from pydantic import BaseModel
 
 
@@ -43,6 +39,10 @@ class AuthValidator(ABC):
         :param algorithm: Hash algorithm to use (default: sha256)
         :return: True if signature is valid, False otherwise
         """
+        import base64
+        import hashlib
+        import hmac
+
         mac = hmac.new(key=secret.encode(), msg=message, digestmod=getattr(hashlib, algorithm))
         expected = base64.b64encode(mac.digest()).decode()
         return hmac.compare_digest(expected, signature)
@@ -59,6 +59,8 @@ class AuthValidator(ABC):
         :return: Decoded JWT claims dictionary
         :raises: jwt exceptions if token is invalid
         """
+        import jwt
+
         return jwt.decode(
             token,
             public_key,

agentkernel-0.3.0/src/agentkernel/auth.py

@@ -0,0 +1 @@
+from .auth import *