agentkernel 0.9.2__tar.gz → 0.9.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.9.2
+Version: 0.9.3
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -140,7 +140,7 @@ 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
 - **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
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
@@ -165,6 +165,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

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

@@ -10,7 +10,7 @@ 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
 - **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
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
@@ -35,6 +35,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

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agentkernel"
-version = "0.9.2"
+version = "0.9.3"
 description = "Agent Kernel - Unified AI Agents Runtime"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -230,3 +230,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.2 → agentkernel-0.9.3}/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.3}/src/agentkernel/core/base.py

@@ -5,7 +5,7 @@ import copy
 import logging
 import pickle
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator, Iterator, Mapping
+from collections.abc import AsyncGenerator, Iterable, Iterator, Mapping
 from enum import Enum
 from typing import Any, ClassVar, Self, cast
 
@@ -362,6 +362,22 @@ class Runner(ABC):
             exc_info=error,
         )
 
+    @staticmethod
+    def _native_kwargs(options: Mapping[str, Any], **ak_owned: Any) -> dict[str, Any]:
+        """
+        Builds the keyword arguments for a native framework run call from an agent's declared run options.
+        The declared options are copied first and the keys Agent Kernel owns are written last, so a declared
+        option can never displace a value the adapter populates itself (the same rule as `ak_tool_context` in
+        ADK and `messages` in LangGraph). The copy is shallow and per call: adjusting a value for one run never
+        touches the declared mapping.
+        :param options: The agent's declared run options (`Agent.run_options`, or an adapter's filtered view of it).
+        :param ak_owned: The keyword arguments the adapter populates itself; these win over `options`.
+        :return: A new dict holding the merged keyword arguments.
+        """
+        kwargs = dict(options)
+        kwargs.update(ak_owned)
+        return kwargs
+
     @abstractmethod
     async def run(self, agent: Any, session: Session, requests: list[AgentRequest]) -> AgentReply:
         """
@@ -411,6 +427,13 @@ class Agent(ABC):
 
     current_agent: ClassVar[contextvars.ContextVar["Agent | None"]] = contextvars.ContextVar("current_agent", default=None)
 
+    RESERVED_RUN_OPTIONS: ClassVar[Mapping[str, str]] = {}
+    """
+    Native run-call keyword arguments this adapter populates itself or depends on for reply mapping, mapped to
+    the one-line reason a caller sees when declaring one through `Module.run_options`. Empty on the base class,
+    so a bring-your-own Agent reserves nothing.
+    """
+
     @classmethod
     def current(cls) -> "Agent | None":
         """
@@ -430,6 +453,7 @@ class Agent(ABC):
         self._runner: Runner = runner
         self._pre_hooks: list[PreHook] = []
         self._post_hooks: list[PostHook] = []
+        self._run_options: dict[str, Any] = {}
 
     def __repr__(self) -> str:
         """
@@ -466,6 +490,28 @@ class Agent(ABC):
         """
         return self._post_hooks
 
+    @property
+    def run_options(self) -> dict[str, Any]:
+        """
+        Returns the framework-native keyword arguments merged into every native run call for this agent.
+        A live, mutable dict (the same contract as `pre_hooks`), declared through `Module.run_options` and never
+        persisted. Mutating it directly skips the reservation check entirely: a reserved key the runner writes itself
+        is overwritten, but one the adapter passes positionally raises the SDK's duplicate-argument error, and one
+        reserved only because it breaks the reply mapping is forwarded as given.
+        """
+        return self._run_options
+
+    def validate_run_options(self, options: Mapping[str, Any]) -> None:
+        """
+        Rejects run options that name a key this adapter reserves.
+        :param options: The run options about to be declared for this agent.
+        :raises ValueError: Naming the adapter, the agent, and every reserved key present with its reason.
+        """
+        reserved = sorted(set(options) & set(self.RESERVED_RUN_OPTIONS))
+        if reserved:
+            details = "; ".join(f"'{key}': {self.RESERVED_RUN_OPTIONS[key]}" for key in reserved)
+            raise ValueError(f"Run option(s) reserved by the '{self.runner.name}' adapter for agent '{self.name}': {details}")
+
     @contextlib.contextmanager
     def _activate(self) -> Iterator[Self]:
         """
@@ -533,9 +579,76 @@ class Agent(ABC):
         """
         from agentkernel.core.tool import SystemToolFactory
 
-        for tool in SystemToolFactory.get_all(self.name):
+        system_tools = SystemToolFactory.get_all(self.name)
+        self._warn_on_tool_name_collisions(system_tools)
+
+        for tool in system_tools:
             self.attach_tool(tool.func)
 
+    def _warn_on_tool_name_collisions(self, system_tools: list[Any]) -> None:
+        """
+        Warn when a system tool is about to shadow one the application already bound by hand.
+
+        Runs after the framework adapter has taken the built native agent, so tools the
+        application bound itself are already present and visible here. The collision is warned
+        about and then allowed: skipping would make newly enabling a capability silently do
+        nothing for this agent, which is the worse of the two failures. The cost is that both
+        tools reach the framework -- tolerated by some, rejected at bind time by others, with
+        this warning explaining why.
+
+        Entirely defensive: an adapter exposing no `tools` collection yields no warning, never
+        a raise.
+
+        :param system_tools: The SystemTool instances about to be attached.
+        :return: None.
+        """
+        native = getattr(self, "agent", None)
+        existing = {name for name in (self._native_tool_name(tool) for tool in self._native_tools(native)) if name}
+        colliding = sorted(existing.intersection(tool.name for tool in system_tools))
+        if colliding:
+            _log.warning(
+                "Agent '%s' already has tools named %s; Agent Kernel is attaching system tools with the same names. "
+                "The agent will carry both. If this agent was wired by hand, remove the manual binding or the configuration that enables it.",
+                self.name,
+                colliding,
+            )
+
+    @staticmethod
+    def _native_tools(native: Any) -> Iterable[Any]:
+        """
+        Return whatever the native agent holds its tools in, as something iterable.
+
+        Smolagents keys its tools by name -- `SmolagentsAgent._append_tools` writes
+        `agent.tools[name] = tool` -- so iterating the attribute directly yields names, not
+        tools. The keys are the names this warning is looking for, so the mapping is taken
+        through `keys()` and :meth:`_native_tool_name` accepts a bare string.
+
+        Anything that is neither a mapping nor a sequence yields nothing rather than raising,
+        which is what makes this method's caller safe against an adapter that means something
+        else entirely by `tools`.
+
+        :param native: The framework's own agent object, or None.
+        :return: The tools or tool names to inspect; empty when there are none to read.
+        """
+        tools = getattr(native, "tools", None)
+        if isinstance(tools, Mapping):
+            return tools.keys()
+        if isinstance(tools, (list, tuple, set, frozenset)):
+            return tools
+        return ()
+
+    @staticmethod
+    def _native_tool_name(tool: Any) -> str | None:
+        """
+        Name one tool the framework already holds.
+
+        :param tool: A tool object, or the name a mapping-shaped collection keyed it by.
+        :return: The tool's name, or None when it cannot be named.
+        """
+        if isinstance(tool, str):
+            return tool
+        return getattr(tool, "name", None) or getattr(tool, "__name__", None)
+
     @staticmethod
     def _append_tools(agent: Any, wrapped: list[Any]) -> None:
         """

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

@@ -406,6 +406,52 @@ class _ScheduleConfig(BaseModel):
     )
 
 
+class _OKFDatabaseConfig(BaseModel):
+    """One Open Knowledge Format bundle and the agents that may reach it.
+
+    Permission is per (agent, database): an agent may produce into one bundle and only consume
+    another, and both hold at once.
+
+    The three role lists default to None rather than an empty list, so an omitted role reads as
+    "not declared" rather than "declared empty". At least one of them must name an agent; that
+    rule is enforced in OKFRoleRegistry.from_config rather than here, because a field validator
+    cannot see which database key it belongs to and so could not name it in the error."""
+
+    type: str = Field(description="Document store for this bundle: 'local', 's3', or a dotted path to a DocumentStore subclass")
+    uri: str = Field(
+        description="Bundle location passed to the resolved store: a filesystem path, an s3://bucket/prefix URI, or the store's own location string"
+    )
+    description: Optional[str] = Field(
+        default=None,
+        description="Human-readable description of this bundle, surfaced to the agent in its instructions and through get_schemas",
+    )
+    refresh_seconds: Optional[float] = Field(
+        default=300.0,
+        description="How stale the bundle manifest may get before the next operation re-walks the store; null disables automatic refresh",
+    )
+    consumer: Optional[list[str]] = Field(default=None, description="Agent names granted read access to this bundle")
+    producer: Optional[list[str]] = Field(
+        default=None,
+        description="Agent names granted read and write access, instructed to add new knowledge to this bundle",
+    )
+    curator: Optional[list[str]] = Field(
+        default=None,
+        description="Agent names granted read and write access, instructed to review and maintain existing knowledge in this bundle",
+    )
+
+
+class _OKFConfig(BaseModel):
+    """Configuration for the Open Knowledge Format capability.
+
+    The presence of the block is the enablement signal; naming an agent in a role is the
+    deliberate opt-in, and the block does nothing without at least one."""
+
+    databases: dict[str, _OKFDatabaseConfig] = Field(
+        default_factory=dict,
+        description="OKF bundles keyed by backend name; the key is what agents pass as the 'backend' argument to the knowledge-base tools",
+    )
+
+
 class _TraceConfig(BaseModel):
     enabled: bool = Field(default=False, description="Enable tracing")
     type: str = Field(
@@ -914,6 +960,11 @@ class AKConfig(YamlBaseSettingsModified):
         description="Scheduling capability configurations (trigger provider, task store, tool scoping). Absent = the capability is disabled.",
     )
 
+    okf: Optional[_OKFConfig] = Field(
+        default=None,
+        description="Open Knowledge Format capability configurations (bundles and the agents that consume, produce, or curate them). Absent = the capability is disabled.",
+    )
+
     trace: _TraceConfig = Field(description="Tracing related configurations", default_factory=_TraceConfig)
     guardrail: _GuardrailConfig = Field(description="Guardrail related configurations", default_factory=_GuardrailConfig)
     sandbox: _SandboxConfig = Field(description="Sandbox capability configurations", default_factory=_SandboxConfig)

agentkernel-0.9.3/src/agentkernel/core/module.py

@@ -0,0 +1,138 @@
+from abc import ABC, abstractmethod
+from typing import Any, List, Self
+
+from ..core.hooks import PostHook, PreHook
+from .base import Agent
+from .runtime import Runtime
+
+
+class Module(ABC):
+    """
+    Module is the base class for all agent modules.
+
+    An agent module is a Python module containing a set of agents built using a supported agent
+    framework. Agent Kernel provides an implementation of the Module class for each supported agent
+    framework, allowing the agents to be registered and managed in a framework-agnostic manner.
+    """
+
+    def __init__(self):
+        """
+        Initializes a Module instance.
+        """
+        self._agents = []
+
+    @property
+    def agents(self) -> list[Agent]:
+        """
+        Returns the list of agents in the module.
+        """
+        return self._agents
+
+    def unload(self):
+        """
+        Unloads and deregisters all agents in the module
+        """
+        for agent in self._agents:
+            Runtime.current().deregister(agent)
+        self._agents.clear()
+
+    def get_agent(self, name: str) -> Agent | None:
+        """
+        Returns an agent by name from the module.
+        :param name: The name of the agent to retrieve.
+        :return: The agent with the specified name, or None if not found.
+        """
+        for agent in self._agents:
+            if agent.name == name:
+                return agent
+        return None
+
+    @abstractmethod
+    def _wrap(self, agent: Any, agents: List[Any]) -> Agent:
+        """
+        Wraps an agent in a framework-specific wrapper.
+        :param agent: The agent to wrap.
+        :return: The wrapped agent.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def load(self, agents: list[Any]) -> "Module":
+        """
+        Loads and registers all agents to the runtime by replacing the current agents.
+        :param agents: List of agents to load.
+        """
+        self.unload()
+        registered = []
+        for agent in agents:
+            try:
+                wrapped = self._wrap(agent, agents)
+                Runtime.current().register(wrapped)
+                registered.append(wrapped)
+            except Exception:
+                self._agents = registered
+                self.unload()
+                raise
+        self._agents = registered
+        return self
+
+    def pre_hook(self, agent: Any, hooks: list[PreHook]) -> Self:
+        """
+        Attaches pre-execution hooks to the agent. Chained like `post_hook` / `run_options`.
+        :param agent: The native framework agent to attach hooks to.
+        :param hooks: List of pre-execution hooks to attach.
+        :return: This module, for chaining.
+        :raises ValueError: If the agent is not loaded in this module.
+        """
+        self._wrapped(agent).pre_hooks.extend(hooks)
+        return self
+
+    def post_hook(self, agent: Any, hooks: list[PostHook]) -> Self:
+        """
+        Attaches post-execution hooks to the agent. Chained like `pre_hook` / `run_options`.
+        :param agent: The native framework agent to attach hooks to.
+        :param hooks: List of post-execution hooks to attach.
+        :return: This module, for chaining.
+        :raises ValueError: If the agent is not loaded in this module.
+        """
+        self._wrapped(agent).post_hooks.extend(hooks)
+        return self
+
+    def run_options(self, agent: Any, **options: Any) -> Self:
+        """
+        Declares framework-native run options for one loaded agent, merged into every native run call the
+        adapter makes for it (keyword arguments of the framework's own run API, such as OpenAI's `hooks`,
+        `run_config` and `max_turns`). Repeated calls merge, the later call winning per key. Chained like
+        `pre_hook` / `post_hook`.
+        :param agent: The native framework agent the options are for.
+        :param options: The framework-native keyword arguments to declare.
+        :return: This module, for chaining.
+        :raises ValueError: If the agent is not loaded in this module, or an option names a key the adapter reserves.
+        """
+        wrapped = self._wrapped(agent)
+        wrapped.validate_run_options(options)
+        wrapped.run_options.update(options)
+        return self
+
+    def _wrapped(self, agent: Any) -> Agent:
+        """
+        Returns the Agent Kernel agent wrapping a native framework agent loaded in this module.
+        :param agent: The native framework agent.
+        :return: The wrapped agent.
+        :raises ValueError: If the agent is not loaded in this module.
+        """
+        name = self._native_agent_name(agent)
+        wrapped = self.get_agent(name)
+        if wrapped is None:
+            raise ValueError(f"Agent '{name}' is not loaded in this module")
+        return wrapped
+
+    def _native_agent_name(self, agent: Any) -> str:
+        """
+        Returns the Agent Kernel agent name a native framework agent was registered under.
+        The default is the native agent's `name`; adapters whose rule differs override it (CrewAI names agents
+        by `role`, smolagents falls back to a fixed name).
+        :param agent: The native framework agent.
+        :return: The registered agent name.
+        """
+        return agent.name

{agentkernel-0.9.2 → agentkernel-0.9.3}/src/agentkernel/core/tool.py

@@ -205,6 +205,15 @@ class SystemToolFactory:
 
             tools.extend(get_schedule_tools())
 
+        # Deliberately not passed through _agent_allowed: that helper reads a flat `agents`
+        # list, and OKF's scoping is per (agent, database) and lives in its own role registry.
+        # Passing the block would silently allow every agent, since it has no `agents` field.
+        okf_config = getattr(AKConfig.get(), "okf", None)
+        if okf_config is not None:
+            from ..knowledgebase.okf.tools import OKFToolFactory
+
+            tools.extend(OKFToolFactory.get_tools(agent_name))
+
         agui_config = getattr(AKConfig.get(), "agui", None)
         state_config = getattr(agui_config, "state", None)
         if state_config and state_config.enabled and SystemToolFactory._agent_allowed(state_config, agent_name):
@@ -220,24 +229,48 @@ class SystemToolFactory:
 
         return tools
 
+    @staticmethod
+    def get_prompt_sections(agent_name: str | None = None) -> list[str]:
+        """
+        Collect the prompt sections capabilities contribute directly, outside any tool.
+
+        A capability whose instructions describe the capability itself rather than one of its
+        tools belongs here: the text is written into the agent's system prompt instead of being
+        carried on a `SystemTool.description`, which the frameworks never read.
+
+        :param agent_name: When given, sections are scoped to that agent.
+        :return: The non-empty sections, in the order they are appended to the prompt.
+        """
+        sections: list[str] = []
+
+        # Lazily imported behind the same enabled-check the tools branch uses, so a process
+        # with no `okf` block never pays for the knowledgebase tier.
+        okf_config = getattr(AKConfig.get(), "okf", None)
+        if okf_config is not None:
+            from ..knowledgebase.okf.prompts import OKFPromptComposer
+
+            sections.append(OKFPromptComposer.for_agent(agent_name))
+
+        return [section for section in sections if section]
+
     @staticmethod
     def get_system_prompt_suffix(agent_name: str | None = None) -> str:
         """
-        Generate the system prompt suffix based on enabled tools.
+        Generate the system prompt suffix from the enabled capabilities.
 
-        This method retrieves all enabled system tools and constructs a suffix string
-        containing their descriptions, which can be appended to the system prompt for agents.
+        Two sources are concatenated: the descriptions of the enabled system tools, and the
+        sections capabilities contribute directly via :meth:`get_prompt_sections`.
 
         :param agent_name: When given, capabilities restricted via their `agents` config
                            list contribute to the suffix only for the named agent.
-        :return: A string containing the concatenated descriptions of all enabled tools,
-                 or an empty string if no tools are enabled.
+        :return: A string containing the concatenated sections, or an empty string when no
+                 capability contributes anything.
         """
 
         tools: List[SystemTool] = SystemToolFactory.get_all(agent_name)
 
-        if tools is None or len(tools) == 0:
-            return ""
         # A capability may carry its whole prompt section on one tool and leave the
         # others' descriptions empty (the sandbox pattern) — skip the empties.
-        return "\n".join(tool.description for tool in tools if tool.description)
+        sections = [tool.description for tool in tools or [] if tool.description]
+        sections.extend(SystemToolFactory.get_prompt_sections(agent_name))
+        return "\n".join(sections)

{agentkernel-0.9.2 → agentkernel-0.9.3}/src/agentkernel/core/util/driver/__init__.py

@@ -1,6 +1,6 @@
 """
-Shared database connection drivers for the Session, Multimodal, Response Store,
-and Thread backends.
+Shared connection drivers for the Session, Multimodal, Response Store, Thread,
+and Knowledge Base backends.
 
 Drivers own the connection lifecycle (client creation, lazy connect, retry,
 health-check/reconnect, TTL plumbing) and a generic command surface; data
@@ -9,7 +9,7 @@ never read AKConfig — all connection parameters are explicit constructor
 arguments.
 
 This package intentionally has no eager imports: ``redis``, ``valkey``,
-``azure-data-tables``, and ``google-cloud-firestore`` are optional
+``boto3``, ``azure-data-tables``, and ``google-cloud-firestore`` are optional
 dependencies, so consumers import the concrete module directly, e.g.
 ``from agentkernel.core.util.driver.redis import RedisDriver``.
 """