agentkernel 0.9.2__tar.gz → 0.9.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.2
+Version: 0.9.4
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -25,6 +25,10 @@ Requires-Dist: azure-functions>=1.24.0 ; extra == 'azure'
 Requires-Dist: azure-data-tables>=12.4.0 ; extra == 'azure'
 Requires-Dist: azure-core>=1.26.0 ; extra == 'azure'
 Requires-Dist: chromadb>=0.4.0 ; extra == 'chromadb'
+Requires-Dist: opentelemetry-sdk>=1.30.0 ; extra == 'cloudwatch'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30.0 ; extra == 'cloudwatch'
+Requires-Dist: botocore>=1.41.4 ; extra == 'cloudwatch'
+Requires-Dist: requests>=2.32.0 ; extra == 'cloudwatch'
 Requires-Dist: crewai>=1.15.0 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-crewai>=0.1.16 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-litellm>=0.1.28 ; extra == 'crewai'
@@ -37,6 +41,8 @@ Requires-Dist: google-auth-oauthlib>=1.0.0 ; extra == 'gmail'
 Requires-Dist: google-auth-httplib2>=0.2.0 ; extra == 'gmail'
 Requires-Dist: google-api-python-client>=2.0.0 ; extra == 'gmail'
 Requires-Dist: httpx>=0.27.0 ; extra == 'instagram'
+Requires-Dist: fastapi>=0.118.0 ; extra == 'instagram'
+Requires-Dist: typesafe-sdk>=0.7.2,<0.8 ; extra == 'jev'
 Requires-Dist: confluent-kafka>=2.15.0 ; extra == 'kafka'
 Requires-Dist: kubernetes>=29.0.0 ; extra == 'kubernetes'
 Requires-Dist: langfuse>=4.2.0 ; extra == 'langfuse'
@@ -49,6 +55,7 @@ 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'
 Requires-Dist: httpx>=0.27.0 ; extra == 'messenger'
+Requires-Dist: fastapi>=0.118.0 ; extra == 'messenger'
 Requires-Dist: litellm>=1.74.9 ; extra == 'multimodal'
 Requires-Dist: python-multipart>=0.0.12 ; extra == 'multimodal'
 Requires-Dist: nats-py>=2.15.0 ; extra == 'nats'
@@ -64,13 +71,17 @@ Requires-Dist: redis>=7.1.0 ; extra == 'redis'
 Requires-Dist: docker>=7.0.0 ; extra == 'sandbox-docker'
 Requires-Dist: slack-bolt==1.22.0 ; extra == 'slack'
 Requires-Dist: httpx>=0.27.0 ; extra == 'slack'
+Requires-Dist: fastapi>=0.118.0 ; extra == 'slack'
+Requires-Dist: aiohttp>=3.9.0 ; extra == 'slack'
 Requires-Dist: smolagents>=1.0.0 ; extra == 'smolagents'
 Requires-Dist: botbuilder-core>=4.17.0 ; extra == 'teams'
 Requires-Dist: botbuilder-schema>=4.17.0 ; extra == 'teams'
 Requires-Dist: aiohttp>=3.9.0 ; extra == 'teams'
 Requires-Dist: msal>=1.31.1 ; extra == 'teams'
 Requires-Dist: httpx>=0.27.0 ; extra == 'teams'
+Requires-Dist: fastapi>=0.118.0 ; extra == 'teams'
 Requires-Dist: httpx>=0.27.0 ; extra == 'telegram'
+Requires-Dist: fastapi>=0.118.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'
@@ -83,6 +94,7 @@ Requires-Dist: trino>=0.337.0 ; extra == 'trino'
 Requires-Dist: valkey>=6.0.0 ; extra == 'valkey'
 Requires-Dist: walledai>=4.9.3 ; extra == 'walledai'
 Requires-Dist: httpx>=0.27.0 ; extra == 'whatsapp'
+Requires-Dist: fastapi>=0.118.0 ; extra == 'whatsapp'
 Requires-Python: >=3.12, <3.14
 Provides-Extra: a2a
 Provides-Extra: adk
@@ -93,6 +105,7 @@ Provides-Extra: aws
 Provides-Extra: azure
 Provides-Extra: chromadb
 Provides-Extra: cli
+Provides-Extra: cloudwatch
 Provides-Extra: crewai
 Provides-Extra: cron
 Provides-Extra: daytona
@@ -100,6 +113,7 @@ Provides-Extra: e2b
 Provides-Extra: gcp
 Provides-Extra: gmail
 Provides-Extra: instagram
+Provides-Extra: jev
 Provides-Extra: kafka
 Provides-Extra: kubernetes
 Provides-Extra: langfuse
@@ -140,9 +154,11 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
 - **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
 - **Session Management**: Built-in session abstraction with pluggable storage backends
-- **Knowledge Bases**: Unified `KnowledgeBase` interface with ChromaDB, Neo4j, and Starburst/Trino backends via `KnowledgeBuilder`
+- **Knowledge Bases**: Unified, capability-declaring `KnowledgeBase` interface with ChromaDB, Neo4j, Starburst/Trino and Open Knowledge Format bundle (local directory or S3) backends via `KnowledgeBuilder`
 - **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `kubernetes`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, per-user identity, and a queue-decoupled broker for long-running executions
+- **Secret Resolution**: `SecretManager` resolves API keys and passwords environment-first, falling back to a pluggable provider (`env`, `aws_ssm` for AWS SSM Parameter Store, or your own) with a TTL'd process cache
 - **Scheduled Tasks**: Deferred and recurring chat execution (`schedule.at`/`schedule.cron`) with a management REST API, five agent-facing tools, and pluggable provider (`local`, `eventbridge`) and store (`in_memory`, `redis`, `valkey`, `dynamodb`) backends
+- **Human in the Loop**: Pause a run for a person's approval or answer and resume from their decision — `status: "PAUSED"` with HTTP 202, a `resume` block carrying `approved`/`denied`/`cancelled` decisions, supported on OpenAI Agents SDK, LangGraph, Pydantic AI and Google ADK over REST, streaming and AG-UI
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
 - **Pluggable Architecture**: Easy to extend with custom framework adapters
 - **MCP Server**: Built-in Model Context Protocol server for exposing agents as MCP tools and exposing any custom tool
@@ -165,6 +181,9 @@ pip install "agentkernel[neo4j]"
 pip install "agentkernel[trino]"
 ```
 
+Open Knowledge Format bundles need no extra - `pyyaml` is a core dependency. Serving a bundle from S3
+uses the `aws` extra: `pip install "agentkernel[aws]"`.
+
 For LLM-based thread naming with Conversation Thread Support:
 
 ```bash
@@ -188,6 +207,12 @@ pip install "agentkernel[daytona]"          # daytona cloud provider
 pip install "agentkernel[aws]"              # ec2_ssm provider (boto3)
 ```
 
+For the `aws_ssm` secret provider (AWS SSM Parameter Store):
+
+```bash
+pip install "agentkernel[aws]"
+```
+
 For cron parsing with the Scheduling capability (the `eventbridge` provider rides the `aws` extra):
 
 ```bash
@@ -804,6 +829,41 @@ sort key; the AWS Terraform modules create it when `create_dynamodb_schedule_tab
   - **Description**: DynamoDB item TTL in seconds
   - **Environment Variable**: `AK_SCHEDULE__STORE__DYNAMODB__TTL`
 
+#### Secret Resolution
+
+`SecretManager.current().get("OPENAI_API_KEY")` resolves a secret by the same environment-variable-style
+name the SDKs already read (`^[A-Z][A-Z0-9_]*$`). Resolution order is fixed: a set, non-empty environment
+variable always wins, then the process cache, then the configured provider. A resolved value is returned to
+the caller and never written back to the environment, so hand it to the SDK explicitly
+(`set_default_openai_key(...)`). A miss raises `SecretNotFoundError` unless a `default` is passed; a provider
+failure raises `SecretError` even with a `default`. The capability is always available — there is no
+`enabled` flag; selecting a provider other than `env` is the only opt-in. See `examples/cli/openai-secret`.
+
+- **Provider Type**
+  - **Field**: `secret.provider.type`
+  - **Type**: string
+  - **Default**: `env`
+  - **Options**: `env` (the process environment), `aws_ssm` (AWS SSM Parameter Store; requires
+    `secret.prefix` and the `aws` extra — `OPENAI_API_KEY` is read from `/ak/<prefix>/openai_api_key`), or a
+    dotted path to a `SecretProvider` subclass
+  - **Environment Variable**: `AK_SECRET__PROVIDER__TYPE`
+
+- **Prefix**
+  - **Field**: `secret.prefix`
+  - **Type**: string
+  - **Default**: `""`
+  - **Description**: Deployment scope providers namespace secrets under; a single path segment. Required by
+    `aws_ssm`, ignored by `env`. Injected by the AWS Terraform modules when `ssm_enabled = true`
+  - **Environment Variable**: `AK_SECRET__PREFIX`
+
+- **Cache TTL**
+  - **Field**: `secret.cache_ttl`
+  - **Type**: integer
+  - **Default**: `300`
+  - **Description**: Seconds a provider hit is served from the process cache (`0` disables caching); the
+    rotation-pickup window for values read per call
+  - **Environment Variable**: `AK_SECRET__CACHE_TTL`
+
 #### Execution Configuration
 
 Configure queue-backed and serverless execution behavior.
@@ -1174,7 +1234,7 @@ Configure tracing and observability for monitoring agent execution.
 
 - **Type**
   - **Field**: `trace.type`
-  - **Options**: `langfuse`, `openllmetry`, `logfire`
+  - **Options**: `langfuse`, `openllmetry`, `logfire`, `cloudwatch`
   - **Default**: `langfuse`
   - **Description**: Type of tracing provider to use
   - **Environment Variable**: `AK_TRACE__TYPE`
@@ -1249,6 +1309,32 @@ trace:
   type: logfire
 ```
 
+**AWS CloudWatch Setup:**
+
+To send traces to Amazon CloudWatch (via AWS X-Ray, searchable in Transaction Search), install the cloudwatch extra:
+
+```bash
+pip install agentkernel[cloudwatch]
+```
+
+Spans are exported over OTLP to the X-Ray endpoint of your region, signed with the standard AWS credential
+chain (environment, profile, SSO, or instance/task role). Enable CloudWatch Transaction Search once in the
+account, and give the agent's role the `AWSXrayWriteOnlyAccess` managed policy:
+
+```bash
+export AWS_REGION=us-east-1
+# Optional: export through the CloudWatch agent or an OpenTelemetry collector instead
+# export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+Enable tracing in your configuration:
+
+```yaml
+trace:
+  enabled: true
+  type: cloudwatch
+```
+
 #### Test Configuration
 
 Configure test comparison modes for automated testing. Test configuration is separate from the application configuration: it is **not** part of `config.yaml`. It lives in its own `test-config.yaml` file and is only loaded when the testing utilities (`agentkernel.test`) are used — see the [Test Configuration (test-config.yaml)](#test-configuration-test-configyaml) section for file resolution, environment variables, and migration notes.
@@ -1263,7 +1349,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval`, `opik` or `jev`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1285,8 +1371,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`: `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
+- `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]"`; built-in `jev` has no score mode)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`; built-in `jev`: a TypeSafe JEV yes/no Noul question) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1637,7 +1723,7 @@ export AK_API__PORT=8000
 export AK_A2A__ENABLED=true
 export AK_MCP__ENABLED=false
 export AK_TRACE__ENABLED=true
-export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
+export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire, cloudwatch
 # For Langfuse:
 # export LANGFUSE_PUBLIC_KEY=pk-lf-...
 # export LANGFUSE_SECRET_KEY=sk-lf-...
@@ -1646,9 +1732,11 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export TRACELOOP_API_KEY=your-api-key
 # For Logfire:
 # export LOGFIRE_TOKEN=your-write-token
+# For CloudWatch:
+# export AWS_REGION=us-east-1
 # 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 (deepeval or opik), or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval, opik or jev), 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
@@ -1692,7 +1780,7 @@ AK_API__PORT=8080
 AK_A2A__ENABLED=true
 AK_A2A__URL=http://localhost:8080/a2a
 AK_TRACE__ENABLED=true
-AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
+AK_TRACE__TYPE=langfuse  # or openllmetry, logfire, cloudwatch
 # Langfuse credentials (if using langfuse):
 # LANGFUSE_PUBLIC_KEY=pk-lf-...
 # LANGFUSE_SECRET_KEY=sk-lf-...
@@ -1701,6 +1789,8 @@ AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # TRACELOOP_API_KEY=your-api-key
 # Logfire credentials (if using logfire):
 # LOGFIRE_TOKEN=your-write-token
+# CloudWatch region (if using cloudwatch; credentials come from the AWS credential chain):
+# AWS_REGION=us-east-1
 ```
 
 #### config.yaml
@@ -1918,7 +2008,7 @@ 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.
+The `evaluator` field accepts three 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 `jev` (`pip install "agentkernel[jev]"`, hosted [TypeSafe JEV](https://docs.typesafe.ai) judge; `mode: llm` only, needs `TYPESAFE_API_KEY`, and sends the comparison text to `api.typesafe.ai`) — or a dotted path to your own `AKEvaluator` subclass.
 
 **test-config.yaml:**
 

{agentkernel-0.9.2 → agentkernel-0.9.4}/README.md

@@ -10,9 +10,11 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
 - **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
 - **Session Management**: Built-in session abstraction with pluggable storage backends
-- **Knowledge Bases**: Unified `KnowledgeBase` interface with ChromaDB, Neo4j, and Starburst/Trino backends via `KnowledgeBuilder`
+- **Knowledge Bases**: Unified, capability-declaring `KnowledgeBase` interface with ChromaDB, Neo4j, Starburst/Trino and Open Knowledge Format bundle (local directory or S3) backends via `KnowledgeBuilder`
 - **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `kubernetes`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, per-user identity, and a queue-decoupled broker for long-running executions
+- **Secret Resolution**: `SecretManager` resolves API keys and passwords environment-first, falling back to a pluggable provider (`env`, `aws_ssm` for AWS SSM Parameter Store, or your own) with a TTL'd process cache
 - **Scheduled Tasks**: Deferred and recurring chat execution (`schedule.at`/`schedule.cron`) with a management REST API, five agent-facing tools, and pluggable provider (`local`, `eventbridge`) and store (`in_memory`, `redis`, `valkey`, `dynamodb`) backends
+- **Human in the Loop**: Pause a run for a person's approval or answer and resume from their decision — `status: "PAUSED"` with HTTP 202, a `resume` block carrying `approved`/`denied`/`cancelled` decisions, supported on OpenAI Agents SDK, LangGraph, Pydantic AI and Google ADK over REST, streaming and AG-UI
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
 - **Pluggable Architecture**: Easy to extend with custom framework adapters
 - **MCP Server**: Built-in Model Context Protocol server for exposing agents as MCP tools and exposing any custom tool
@@ -35,6 +37,9 @@ pip install "agentkernel[neo4j]"
 pip install "agentkernel[trino]"
 ```
 
+Open Knowledge Format bundles need no extra - `pyyaml` is a core dependency. Serving a bundle from S3
+uses the `aws` extra: `pip install "agentkernel[aws]"`.
+
 For LLM-based thread naming with Conversation Thread Support:
 
 ```bash
@@ -58,6 +63,12 @@ pip install "agentkernel[daytona]"          # daytona cloud provider
 pip install "agentkernel[aws]"              # ec2_ssm provider (boto3)
 ```
 
+For the `aws_ssm` secret provider (AWS SSM Parameter Store):
+
+```bash
+pip install "agentkernel[aws]"
+```
+
 For cron parsing with the Scheduling capability (the `eventbridge` provider rides the `aws` extra):
 
 ```bash
@@ -674,6 +685,41 @@ sort key; the AWS Terraform modules create it when `create_dynamodb_schedule_tab
   - **Description**: DynamoDB item TTL in seconds
   - **Environment Variable**: `AK_SCHEDULE__STORE__DYNAMODB__TTL`
 
+#### Secret Resolution
+
+`SecretManager.current().get("OPENAI_API_KEY")` resolves a secret by the same environment-variable-style
+name the SDKs already read (`^[A-Z][A-Z0-9_]*$`). Resolution order is fixed: a set, non-empty environment
+variable always wins, then the process cache, then the configured provider. A resolved value is returned to
+the caller and never written back to the environment, so hand it to the SDK explicitly
+(`set_default_openai_key(...)`). A miss raises `SecretNotFoundError` unless a `default` is passed; a provider
+failure raises `SecretError` even with a `default`. The capability is always available — there is no
+`enabled` flag; selecting a provider other than `env` is the only opt-in. See `examples/cli/openai-secret`.
+
+- **Provider Type**
+  - **Field**: `secret.provider.type`
+  - **Type**: string
+  - **Default**: `env`
+  - **Options**: `env` (the process environment), `aws_ssm` (AWS SSM Parameter Store; requires
+    `secret.prefix` and the `aws` extra — `OPENAI_API_KEY` is read from `/ak/<prefix>/openai_api_key`), or a
+    dotted path to a `SecretProvider` subclass
+  - **Environment Variable**: `AK_SECRET__PROVIDER__TYPE`
+
+- **Prefix**
+  - **Field**: `secret.prefix`
+  - **Type**: string
+  - **Default**: `""`
+  - **Description**: Deployment scope providers namespace secrets under; a single path segment. Required by
+    `aws_ssm`, ignored by `env`. Injected by the AWS Terraform modules when `ssm_enabled = true`
+  - **Environment Variable**: `AK_SECRET__PREFIX`
+
+- **Cache TTL**
+  - **Field**: `secret.cache_ttl`
+  - **Type**: integer
+  - **Default**: `300`
+  - **Description**: Seconds a provider hit is served from the process cache (`0` disables caching); the
+    rotation-pickup window for values read per call
+  - **Environment Variable**: `AK_SECRET__CACHE_TTL`
+
 #### Execution Configuration
 
 Configure queue-backed and serverless execution behavior.
@@ -1044,7 +1090,7 @@ Configure tracing and observability for monitoring agent execution.
 
 - **Type**
   - **Field**: `trace.type`
-  - **Options**: `langfuse`, `openllmetry`, `logfire`
+  - **Options**: `langfuse`, `openllmetry`, `logfire`, `cloudwatch`
   - **Default**: `langfuse`
   - **Description**: Type of tracing provider to use
   - **Environment Variable**: `AK_TRACE__TYPE`
@@ -1119,6 +1165,32 @@ trace:
   type: logfire
 ```
 
+**AWS CloudWatch Setup:**
+
+To send traces to Amazon CloudWatch (via AWS X-Ray, searchable in Transaction Search), install the cloudwatch extra:
+
+```bash
+pip install agentkernel[cloudwatch]
+```
+
+Spans are exported over OTLP to the X-Ray endpoint of your region, signed with the standard AWS credential
+chain (environment, profile, SSO, or instance/task role). Enable CloudWatch Transaction Search once in the
+account, and give the agent's role the `AWSXrayWriteOnlyAccess` managed policy:
+
+```bash
+export AWS_REGION=us-east-1
+# Optional: export through the CloudWatch agent or an OpenTelemetry collector instead
+# export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+Enable tracing in your configuration:
+
+```yaml
+trace:
+  enabled: true
+  type: cloudwatch
+```
+
 #### Test Configuration
 
 Configure test comparison modes for automated testing. Test configuration is separate from the application configuration: it is **not** part of `config.yaml`. It lives in its own `test-config.yaml` file and is only loaded when the testing utilities (`agentkernel.test`) are used — see the [Test Configuration (test-config.yaml)](#test-configuration-test-configyaml) section for file resolution, environment variables, and migration notes.
@@ -1133,7 +1205,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
 - **Evaluator**
   - **Field**: `evaluator`
   - **Default**: `deepeval`
-  - **Description**: Built-in evaluator short name (`deepeval` or `opik`), or a dotted path to your own `AKEvaluator` subclass
+  - **Description**: Built-in evaluator short name (`deepeval`, `opik` or `jev`), or a dotted path to your own `AKEvaluator` subclass
   - **Environment Variable**: `AK_TEST__EVALUATOR`
 
 - **Llm Model**
@@ -1155,8 +1227,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`: `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
+- `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]"`; built-in `jev` has no score mode)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`; built-in `jev`: a TypeSafe JEV yes/no Noul question) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
@@ -1507,7 +1579,7 @@ export AK_API__PORT=8000
 export AK_A2A__ENABLED=true
 export AK_MCP__ENABLED=false
 export AK_TRACE__ENABLED=true
-export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
+export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire, cloudwatch
 # For Langfuse:
 # export LANGFUSE_PUBLIC_KEY=pk-lf-...
 # export LANGFUSE_SECRET_KEY=sk-lf-...
@@ -1516,9 +1588,11 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # export TRACELOOP_API_KEY=your-api-key
 # For Logfire:
 # export LOGFIRE_TOKEN=your-write-token
+# For CloudWatch:
+# export AWS_REGION=us-east-1
 # 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 (deepeval or opik), or a dotted path to your own AKEvaluator subclass
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name (deepeval, opik or jev), 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
@@ -1562,7 +1636,7 @@ AK_API__PORT=8080
 AK_A2A__ENABLED=true
 AK_A2A__URL=http://localhost:8080/a2a
 AK_TRACE__ENABLED=true
-AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
+AK_TRACE__TYPE=langfuse  # or openllmetry, logfire, cloudwatch
 # Langfuse credentials (if using langfuse):
 # LANGFUSE_PUBLIC_KEY=pk-lf-...
 # LANGFUSE_SECRET_KEY=sk-lf-...
@@ -1571,6 +1645,8 @@ AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # TRACELOOP_API_KEY=your-api-key
 # Logfire credentials (if using logfire):
 # LOGFIRE_TOKEN=your-write-token
+# CloudWatch region (if using cloudwatch; credentials come from the AWS credential chain):
+# AWS_REGION=us-east-1
 ```
 
 #### config.yaml
@@ -1788,7 +1864,7 @@ 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.
+The `evaluator` field accepts three 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 `jev` (`pip install "agentkernel[jev]"`, hosted [TypeSafe JEV](https://docs.typesafe.ai) judge; `mode: llm` only, needs `TYPESAFE_API_KEY`, and sends the comparison text to `api.typesafe.ai`) — or a dotted path to your own `AKEvaluator` subclass.
 
 **test-config.yaml:**
 

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.2"
+version = "0.9.4"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -34,6 +34,12 @@ openllmetry = [
 logfire = [
     "logfire>=3.0",
 ]
+cloudwatch = [
+    "opentelemetry-sdk>=1.30.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.30.0",
+    "botocore>=1.41.4",
+    "requests>=2.32.0",
+]
 crewai = [
     "crewai>=1.15.0",
     "openinference-instrumentation-crewai>=0.1.16",
@@ -125,19 +131,25 @@ api = [
 ]
 slack = [
     "slack-bolt==1.22.0",
-    "httpx>=0.27.0"
+    "httpx>=0.27.0",
+    "fastapi>=0.118.0",
+    "aiohttp>=3.9.0",
 ]
 whatsapp = [
-    "httpx>=0.27.0"
+    "httpx>=0.27.0",
+    "fastapi>=0.118.0",
 ]
 messenger = [
-    "httpx>=0.27.0"
+    "httpx>=0.27.0",
+    "fastapi>=0.118.0",
 ]
 instagram = [
-    "httpx>=0.27.0"
+    "httpx>=0.27.0",
+    "fastapi>=0.118.0",
 ]
 telegram = [
-    "httpx>=0.27.0"
+    "httpx>=0.27.0",
+    "fastapi>=0.118.0",
 ]
 teams = [
     "botbuilder-core>=4.17.0",
@@ -145,6 +157,7 @@ teams = [
     "aiohttp>=3.9.0",
     "msal>=1.31.1",
     "httpx>=0.27.0",
+    "fastapi>=0.118.0",
 ]
 gmail = [
     "google-auth>=2.0.0",
@@ -191,6 +204,9 @@ kubernetes = [
 opik = [
     "opik>=1.7.0",
 ]
+jev = [
+    "typesafe-sdk>=0.7.2,<0.8",
+]
 
 [project.scripts]
 ak = "agentkernel.cli.ak:main"
@@ -230,3 +246,6 @@ target-version = ["py312"]
 
 [tool.pytest.ini_options]
 addopts = "--cov=src --cov-report=term --cov-report=html --html=report.html"
+# CI runs everything; `-m "not slow"` is for a local run that should not spend a minute
+# materialising a 10,000-concept bundle.
+markers = ["slow: builds a large fixture on disk or otherwise takes tens of seconds"]

agentkernel-0.9.4/src/agentkernel/api/__init__.py

@@ -0,0 +1,42 @@
+"""
+Agent Kernel REST package.
+
+This package contains the REST API implementation for exposing Agent Kernel over HTTP.
+
+Exports are lazy (the ``agentkernel.integration.adapter`` pattern) so importing one piece never
+drags in another's dependencies: a webhook host on Lambda imports ``api.handler`` and has no use
+for ``api.http``'s uvicorn server.
+"""
+
+import importlib
+import importlib.metadata
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__ = importlib.metadata.version("agentkernel")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.1.0"
+
+_LAZY_EXPORTS = {
+    "AgentRESTRequestHandler": ".handler",
+    "RESTRequestHandler": ".handler",
+    "RESTAPI": ".http",
+}
+
+__all__ = sorted(_LAZY_EXPORTS)
+
+if TYPE_CHECKING:  # pragma: no cover: static resolution only, preserves laziness at runtime
+    from .handler import AgentRESTRequestHandler, RESTRequestHandler
+    from .http import RESTAPI
+
+
+def __getattr__(name: str) -> Any:
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(module_path, __name__)
+    return getattr(module, name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

{agentkernel-0.9.2 → agentkernel-0.9.4}/src/agentkernel/cli/cli.py

@@ -87,8 +87,8 @@ class CLI:
                 if not prompt.strip():
                     continue
                 if prompt.startswith("!"):
-                    tokens = prompt.lower().split()
-                    command = tokens[0]
+                    tokens = prompt.split()
+                    command = tokens[0].lower()  # only the command is case-insensitive; arguments are names
                     if command in ["!h", "!help"]:
                         self.help()
                     elif command in ["!c", "!clear"]:

{agentkernel-0.9.2 → agentkernel-0.9.4}/src/agentkernel/core/__init__.py

@@ -11,7 +11,7 @@ try:
 except importlib.metadata.PackageNotFoundError:
     __version__ = "0.1.0"
 
-from .base import Agent, Runner, Session
+from .base import Agent, Runner, RunOptionsFactory, Session
 from .event import (
     MessageEnd,
     MessageStart,