API Reference

Auto-generated API documentation for the XYBEROS public surface.

---

xyberos — Top-level facade

xyberos.assistant

XYBEROS — unified facade for the cognitive platform.

Provides a single entry point for interacting with the full XYBEROS cognitive stack: chat, reasoning, planning, memory, and actions.

Usage::

from xyberos import xyberos

response = xyberos.chat("What is the weather?")
result = xyberos.reason("If A > B and B > C, what follows?")
memories = xyberos.remember("past conversations about weather")

XYBEROS

Unified facade for the XYBEROS cognitive platform.

Lazy-initialises all subsystems on first use so you can create an XYBEROS with no arguments and start using it immediately.

Usage::

from xyberos import xyberos

ctx = xyberos.chat("Hello!")
print(ctx.action.metadata)

Source code in xyberos\assistant.py

class XYBEROS:
    """
    Unified facade for the XYBEROS cognitive platform.

    Lazy-initialises all subsystems on first use so you can create
    an ``XYBEROS`` with no arguments and start using it immediately.

    Usage::

        from xyberos import xyberos

        ctx = xyberos.chat("Hello!")
        print(ctx.action.metadata)
    """

    def __init__(
        self,
        brain: Brain | None = None,
        memory: MemoryManager | None = None,
        reasoning: CognitiveReasoningEngine | None = None,
        config: XyberosConfig | None = None,
    ) -> None:
        self._brain = brain
        self._memory = memory
        self._reasoning = reasoning
        self._config = config or XyberosConfig.load()
        self._context: CognitiveContext | None = None

    def configure(self, config: XyberosConfig) -> None:
        """Reconfigure the instance with a new *config*.

        Resets lazy-initialised subsystems so they pick up the new
        configuration on next access.
        """
        self._config = config
        self._brain = None
        self._memory = None
        self._reasoning = None
        self._context = None

    # ── Lazy properties ────────────────────────────────────────

    @property
    def brain(self) -> Brain:
        if self._brain is None:
            cfg = self._config
            self._brain = Brain(
                safety_config_path=cfg.safety_config_path or None,
            )
        return self._brain

    @property
    def memory(self) -> MemoryManager:
        if self._memory is None:
            mm = MemoryManager()
            mm.register_defaults()
            self._memory = mm
        return self._memory

    @property
    def reasoning(self) -> CognitiveReasoningEngine:
        if self._reasoning is None:
            self._reasoning = CognitiveReasoningEngine()
        return self._reasoning

    # ── Core API ───────────────────────────────────────────────

    def chat(self, message: str) -> CognitiveContext:
        """
        Send a message through the full cognitive pipeline.

        Returns the ``CognitiveContext`` with the complete cycle
        result (observation, thought, goal, plan, decision, action).
        """
        ctx = self.brain.process(message)
        self._context = ctx
        return ctx

    async def achat(self, message: str) -> CognitiveContext:
        """Async variant of :meth:`chat` — runs in a thread pool."""
        return await asyncio.to_thread(self.chat, message)

    def reason(
        self,
        observation: str,
        context: str = "",
        strategy: str | None = None,
    ) -> str:
        """
        Run reasoning directly without the full cognitive loop.

        Parameters
        ----------
        observation:
            The observation or question to reason about.
        context:
            Optional context to inform reasoning.
        strategy:
            Reasoning strategy to use (default ``"deductive"``).

        Returns
        -------
        str
            The reasoned conclusion.
        """
        inp = ReasoningInput(observation=observation, context=context)
        self._ensure_strategies()
        try:
            result = self.reasoning.reason(inp, strategy=strategy)
            return str(result.inference.conclusion)
        except Exception as exc:
            return f"Reasoning unavailable: {exc}"

    def plan(self, goal_description: str) -> list[str]:
        """
        Generate a plan to achieve a goal.

        Parameters
        ----------
        goal_description:
            Description of the goal.

        Returns
        -------
        list[str]
            Ordered steps in the plan.
        """
        goal = Goal(description=goal_description)
        loop = self.brain.loop
        if isinstance(loop, DefaultCognitiveLoop):
            plan = loop.plan(goal)
            return list(plan.steps)
        return [f"Execute: {goal_description}"]

    def remember(
        self,
        query: str,
        limit: int = 5,
    ) -> list[str]:
        """
        Retrieve relevant memories across all tiers.

        Parameters
        ----------
        query:
            Natural language query.
        limit:
            Maximum results.

        Returns
        -------
        list[str]
            Memory content strings.
        """
        result = self.memory.query(MemoryQuery(text=query, limit=limit))
        return [str(item.content) for item in result.items]

    def store_memory(
        self,
        key: str,
        content: Any,
        tier: str = "working",
        **metadata: Any,
    ) -> None:
        """Store a value in the specified memory tier."""
        item = MemoryItem(key=key, content=content, metadata=metadata)
        self.memory.store(item, tier=tier)

    def _ensure_strategies(self) -> None:
        """Register default reasoning strategies and an LLM provider."""
        if self.reasoning.strategies.exists('deductive'):
            return
        from xyberos.strategies.deductive import DeductiveStrategy
        from xyberos.strategies.inductive import InductiveStrategy
        from xyberos.strategies.abductive import AbductiveStrategy
        from xyberos.strategies.analogical import AnalogicalStrategy
        from xyberos.strategies.probabilistic import ProbabilisticStrategy
        from xyberos.providers.llm import LLMReasoningProvider
        from xyberos.providers.llm_backends import get_backend
        self.reasoning.strategies.register('deductive', DeductiveStrategy(), default=True)
        self.reasoning.strategies.register('inductive', InductiveStrategy())
        self.reasoning.strategies.register('abductive', AbductiveStrategy())
        self.reasoning.strategies.register('analogical', AnalogicalStrategy())
        self.reasoning.strategies.register('probabilistic', ProbabilisticStrategy())
        if not self.reasoning.providers.exists('llm'):
            cfg = self._config
            backend = get_backend(cfg.llm_backend)
            provider = LLMReasoningProvider(backend=backend)
            self.reasoning.providers.register('llm', provider, default=True)

    def execute(self, action_name: str, **params: Any) -> Any:
        """
        Execute a direct action.

        Parameters
        ----------
        action_name:
            The action provider name (e.g. ``"shell"``, ``"calculator"``).
        **params:
            Parameters passed to the action provider.

        Returns
        -------
        Any
            The action result.
        """
        from xyberos.brain.action.models import ActionContext
        from xyberos.brain.loop.cognitive_loop import DefaultCognitiveLoop
        act_ctx = ActionContext(timeout=30.0)
        try:
            loop = self.brain.loop
            if not isinstance(loop, DefaultCognitiveLoop):
                return "Execution not available with current cognitive loop."
            result = loop.executor.execute(action_name, act_ctx, **params)
            return result.value if result.success else result.error
        except Exception as exc:
            msg = str(exc)
            if 'registered' in msg:
                return f"No provider registered for action '{action_name}'."
            return f"Execution failed: {exc}"

    @property
    def context(self) -> CognitiveContext | None:
        """The context from the most recent chat call."""
        return self._context

context property

The context from the most recent chat call.

achat(message) async

Async variant of :meth:chat — runs in a thread pool.

Source code in xyberos\assistant.py

async def achat(self, message: str) -> CognitiveContext:
    """Async variant of :meth:`chat` — runs in a thread pool."""
    return await asyncio.to_thread(self.chat, message)

chat(message)

Send a message through the full cognitive pipeline.

Returns the CognitiveContext with the complete cycle result (observation, thought, goal, plan, decision, action).

Source code in xyberos\assistant.py

def chat(self, message: str) -> CognitiveContext:
    """
    Send a message through the full cognitive pipeline.

    Returns the ``CognitiveContext`` with the complete cycle
    result (observation, thought, goal, plan, decision, action).
    """
    ctx = self.brain.process(message)
    self._context = ctx
    return ctx

configure(config)

Reconfigure the instance with a new config.

Resets lazy-initialised subsystems so they pick up the new configuration on next access.

Source code in xyberos\assistant.py

def configure(self, config: XyberosConfig) -> None:
    """Reconfigure the instance with a new *config*.

    Resets lazy-initialised subsystems so they pick up the new
    configuration on next access.
    """
    self._config = config
    self._brain = None
    self._memory = None
    self._reasoning = None
    self._context = None

execute(action_name, **params)

Execute a direct action.

Parameters

action_name: The action provider name (e.g. "shell", "calculator"). **params: Parameters passed to the action provider.

Returns

Any The action result.

Source code in xyberos\assistant.py

def execute(self, action_name: str, **params: Any) -> Any:
    """
    Execute a direct action.

    Parameters
    ----------
    action_name:
        The action provider name (e.g. ``"shell"``, ``"calculator"``).
    **params:
        Parameters passed to the action provider.

    Returns
    -------
    Any
        The action result.
    """
    from xyberos.brain.action.models import ActionContext
    from xyberos.brain.loop.cognitive_loop import DefaultCognitiveLoop
    act_ctx = ActionContext(timeout=30.0)
    try:
        loop = self.brain.loop
        if not isinstance(loop, DefaultCognitiveLoop):
            return "Execution not available with current cognitive loop."
        result = loop.executor.execute(action_name, act_ctx, **params)
        return result.value if result.success else result.error
    except Exception as exc:
        msg = str(exc)
        if 'registered' in msg:
            return f"No provider registered for action '{action_name}'."
        return f"Execution failed: {exc}"

plan(goal_description)

Generate a plan to achieve a goal.

Parameters

goal_description: Description of the goal.

Returns

list[str] Ordered steps in the plan.

Source code in xyberos\assistant.py

def plan(self, goal_description: str) -> list[str]:
    """
    Generate a plan to achieve a goal.

    Parameters
    ----------
    goal_description:
        Description of the goal.

    Returns
    -------
    list[str]
        Ordered steps in the plan.
    """
    goal = Goal(description=goal_description)
    loop = self.brain.loop
    if isinstance(loop, DefaultCognitiveLoop):
        plan = loop.plan(goal)
        return list(plan.steps)
    return [f"Execute: {goal_description}"]

reason(observation, context='', strategy=None)

Run reasoning directly without the full cognitive loop.

Parameters

observation: The observation or question to reason about. context: Optional context to inform reasoning. strategy: Reasoning strategy to use (default "deductive").

Returns

str The reasoned conclusion.

Source code in xyberos\assistant.py

def reason(
    self,
    observation: str,
    context: str = "",
    strategy: str | None = None,
) -> str:
    """
    Run reasoning directly without the full cognitive loop.

    Parameters
    ----------
    observation:
        The observation or question to reason about.
    context:
        Optional context to inform reasoning.
    strategy:
        Reasoning strategy to use (default ``"deductive"``).

    Returns
    -------
    str
        The reasoned conclusion.
    """
    inp = ReasoningInput(observation=observation, context=context)
    self._ensure_strategies()
    try:
        result = self.reasoning.reason(inp, strategy=strategy)
        return str(result.inference.conclusion)
    except Exception as exc:
        return f"Reasoning unavailable: {exc}"

remember(query, limit=5)

Retrieve relevant memories across all tiers.

Parameters

query: Natural language query. limit: Maximum results.

Returns

list[str] Memory content strings.

Source code in xyberos\assistant.py

def remember(
    self,
    query: str,
    limit: int = 5,
) -> list[str]:
    """
    Retrieve relevant memories across all tiers.

    Parameters
    ----------
    query:
        Natural language query.
    limit:
        Maximum results.

    Returns
    -------
    list[str]
        Memory content strings.
    """
    result = self.memory.query(MemoryQuery(text=query, limit=limit))
    return [str(item.content) for item in result.items]

store_memory(key, content, tier='working', **metadata)

Store a value in the specified memory tier.

Source code in xyberos\assistant.py

def store_memory(
    self,
    key: str,
    content: Any,
    tier: str = "working",
    **metadata: Any,
) -> None:
    """Store a value in the specified memory tier."""
    item = MemoryItem(key=key, content=content, metadata=metadata)
    self.memory.store(item, tier=tier)

xyberos.plugins — Plugin system

xyberos.plugins

XYBEROS Plugin System — a unified module for discoverable, composable plugins.

Architecture

• Plugin — An :class:ABC that every plugin implements. Declares what it contributes via :meth:Plugin.components and provides optional :meth:Plugin.initialize / :meth:Plugin.shutdown hooks.

• Component — A lightweight dataclass representing a single unit a plugin contributes (a tool, a skill, an agent, a provider, …).

• PluginRegistry — Tracks loaded plugins and provides component-aware queries (e.g. "which plugins contribute tools?").

• PluginManager — The central orchestrator. Discovers plugins via entry points, loads them, routes their components to the correct type-specific registries, and manages unload.

• PluginLoader — Dynamically loads plugin classes from dotted module paths or discovers them via Python entry points.

• PluginManifest — Metadata describing a plugin (name, version, dependencies, etc.).

Plugin

Bases: ABC

Base class for all runtime plugins.

Subclasses must implement :meth:components to declare what they contribute. Lifecycle hooks (:meth:initialize / :meth:shutdown) are optional.

Identity is provided via properties so that both attribute-style (self.name in __init__) and property-style (@property def name) subclasses work seamlessly::

# Attribute-style (Skill, custom plugins)
class MyPlugin(Plugin):
    def __init__(self) -> None:
        self.name = "my-plugin"
        self.version = "2.0.0"

# Property-style (Tool)
class MyToolPlugin(Plugin):
    @property
    def name(self) -> str:
        return "my-tool"

Usage::

class MyPlugin(Plugin):
    def components(self) -> list[Component]:
        return [
            Component(kind="tool", name="web_search", instance=WebSearchTool()),
        ]

    async def initialize(self) -> None:
        await self.db.connect()

Source code in xyberos\plugins\plugin.py

class Plugin(ABC):
    """
    Base class for all runtime plugins.

    Subclasses must implement :meth:`components` to declare what they
    contribute.  Lifecycle hooks (:meth:`initialize` / :meth:`shutdown`)
    are optional.

    **Identity** is provided via properties so that both attribute-style
    (``self.name`` in ``__init__``) and property-style
    (``@property def name``) subclasses work seamlessly::

        # Attribute-style (Skill, custom plugins)
        class MyPlugin(Plugin):
            def __init__(self) -> None:
                self.name = "my-plugin"
                self.version = "2.0.0"

        # Property-style (Tool)
        class MyToolPlugin(Plugin):
            @property
            def name(self) -> str:
                return "my-tool"

    Usage::

        class MyPlugin(Plugin):
            def components(self) -> list[Component]:
                return [
                    Component(kind="tool", name="web_search", instance=WebSearchTool()),
                ]

            async def initialize(self) -> None:
                await self.db.connect()
    """

    # ── Identity (overridable as attributes or properties) ──────

    _name: str = ""
    _version: str = ""
    _description: str = ""

    @property
    def name(self) -> str:
        """Plugin name.  Defaults to the class name."""
        return self._name or type(self).__name__

    @name.setter
    def name(self, value: str) -> None:
        self._name = value

    @property
    def version(self) -> str:
        """Plugin version string."""
        return self._version or "1.0.0"

    @version.setter
    def version(self, value: str) -> None:
        self._version = value

    @property
    def description(self) -> str:
        """Human-readable description."""
        return self._description or ""

    @description.setter
    def description(self, value: str) -> None:
        self._description = value

    # ── Component contract ──────────────────────────────────────

    @abstractmethod
    def components(self) -> list[Component]:
        """
        Return the components this plugin contributes.

        Each component is a (kind, name, instance) triple that the
        :class:`PluginManager` will route to the correct registry.

        Returns
        -------
        list[Component]
            An empty list is valid — the plugin may only need
            lifecycle hooks.
        """

    # ── Lifecycle hooks ─────────────────────────────────────────

    async def initialize(self) -> None:
        """
        Called once when the plugin is loaded.

        Use this to set up connections, validate configuration,
        or register non-component resources.
        """

    async def shutdown(self) -> None:
        """
        Called once when the plugin is unloaded.

        Use this to release connections, flush buffers, or
        clean up temporary resources.
        """

description property writable

Human-readable description.

name property writable

Plugin name. Defaults to the class name.

version property writable

Plugin version string.

components() abstractmethod

Return the components this plugin contributes.

Each component is a (kind, name, instance) triple that the :class:PluginManager will route to the correct registry.

Returns

list[Component] An empty list is valid — the plugin may only need lifecycle hooks.

Source code in xyberos\plugins\plugin.py

@abstractmethod
def components(self) -> list[Component]:
    """
    Return the components this plugin contributes.

    Each component is a (kind, name, instance) triple that the
    :class:`PluginManager` will route to the correct registry.

    Returns
    -------
    list[Component]
        An empty list is valid — the plugin may only need
        lifecycle hooks.
    """

initialize() async

Called once when the plugin is loaded.

Use this to set up connections, validate configuration, or register non-component resources.

Source code in xyberos\plugins\plugin.py

async def initialize(self) -> None:
    """
    Called once when the plugin is loaded.

    Use this to set up connections, validate configuration,
    or register non-component resources.
    """

shutdown() async

Called once when the plugin is unloaded.

Use this to release connections, flush buffers, or clean up temporary resources.

Source code in xyberos\plugins\plugin.py

async def shutdown(self) -> None:
    """
    Called once when the plugin is unloaded.

    Use this to release connections, flush buffers, or
    clean up temporary resources.
    """

Component dataclass

A named, typed unit contributed by a plugin.

Attributes

kind: The component type identifier, e.g. "tool", "skill", "agent", "provider", "processor". name: Unique name for this component within its kind. instance: The actual runtime object (a Tool, Skill, etc.). metadata: Optional key-value metadata describing the component (version, tags, dependencies, etc.).

Source code in xyberos\plugins\component.py

@dataclass
class Component:
    """
    A named, typed unit contributed by a plugin.

    Attributes
    ----------
    kind:
        The component type identifier, e.g. ``"tool"``, ``"skill"``,
        ``"agent"``, ``"provider"``, ``"processor"``.
    name:
        Unique name for this component within its kind.
    instance:
        The actual runtime object (a ``Tool``, ``Skill``, etc.).
    metadata:
        Optional key-value metadata describing the component
        (version, tags, dependencies, etc.).
    """

    kind: str
    name: str
    instance: Any
    metadata: dict[str, object] = field(default_factory=lambda: {})

PluginRegistry

Bases: RuntimeRegistry[Plugin]

Registry of loaded plugins.

In addition to standard :class:RuntimeRegistry operations, this registry provides helpers to query plugins by the components they contribute.

Source code in xyberos\plugins\registry.py

class PluginRegistry(RuntimeRegistry[Plugin]):
    """
    Registry of loaded plugins.

    In addition to standard :class:`RuntimeRegistry` operations, this
    registry provides helpers to query plugins by the components they
    contribute.
    """

    def get_plugins_by_component_kind(self, kind: str) -> list[Plugin]:
        """
        Return all plugins that contribute a component of *kind*.

        Parameters
        ----------
        kind :
            Component type to filter by (e.g. ``"tool"``, ``"skill"``).

        Returns
        -------
        list[Plugin]
            Plugins whose :meth:`Plugin.components` contain at least
            one component with the matching *kind*.
        """
        return [
            p for p in self.values()
            if any(c.kind == kind for c in p.components())
        ]

    def get_components_by_kind(self, kind: str) -> list[Component]:
        """
        Return all components of *kind* across all loaded plugins.

        Parameters
        ----------
        kind :
            Component type to collect (e.g. ``"tool"``, ``"skill"``).

        Returns
        -------
        list[Component]
            All matching components across every loaded plugin.
        """
        result: list[Component] = []
        for plugin in self.values():
            for component in plugin.components():
                if component.kind == kind:
                    result.append(component)
        return result

    def get_component_names_by_kind(self, kind: str) -> list[str]:
        """
        Return names of all components of *kind* across all plugins.

        Parameters
        ----------
        kind :
            Component type to query.

        Returns
        -------
        list[str]
            Sorted unique component names.
        """
        return sorted({
            c.name
            for p in self.values()
            for c in p.components()
            if c.kind == kind
        })

get_component_names_by_kind(kind)

Return names of all components of kind across all plugins.

Parameters

kind : Component type to query.

Returns

list[str] Sorted unique component names.

Source code in xyberos\plugins\registry.py

def get_component_names_by_kind(self, kind: str) -> list[str]:
    """
    Return names of all components of *kind* across all plugins.

    Parameters
    ----------
    kind :
        Component type to query.

    Returns
    -------
    list[str]
        Sorted unique component names.
    """
    return sorted({
        c.name
        for p in self.values()
        for c in p.components()
        if c.kind == kind
    })

get_components_by_kind(kind)

Return all components of kind across all loaded plugins.

Parameters

kind : Component type to collect (e.g. "tool", "skill").

Returns

list[Component] All matching components across every loaded plugin.

Source code in xyberos\plugins\registry.py

def get_components_by_kind(self, kind: str) -> list[Component]:
    """
    Return all components of *kind* across all loaded plugins.

    Parameters
    ----------
    kind :
        Component type to collect (e.g. ``"tool"``, ``"skill"``).

    Returns
    -------
    list[Component]
        All matching components across every loaded plugin.
    """
    result: list[Component] = []
    for plugin in self.values():
        for component in plugin.components():
            if component.kind == kind:
                result.append(component)
    return result

get_plugins_by_component_kind(kind)

Return all plugins that contribute a component of kind.

Parameters

kind : Component type to filter by (e.g. "tool", "skill").

Returns

list[Plugin] Plugins whose :meth:Plugin.components contain at least one component with the matching kind.

Source code in xyberos\plugins\registry.py

def get_plugins_by_component_kind(self, kind: str) -> list[Plugin]:
    """
    Return all plugins that contribute a component of *kind*.

    Parameters
    ----------
    kind :
        Component type to filter by (e.g. ``"tool"``, ``"skill"``).

    Returns
    -------
    list[Plugin]
        Plugins whose :meth:`Plugin.components` contain at least
        one component with the matching *kind*.
    """
    return [
        p for p in self.values()
        if any(c.kind == kind for c in p.components())
    ]

PluginManager

Central orchestrator for the plugin system.

Responsibilities:

1. Discover plugin classes via entry points (xyberos.plugins).
2. Load and instantiate plugins.
3. Initialize plugins (lifecycle hook).
4. Route each plugin's :meth:Plugin.components to the appropriate type-specific registries (tool registry, skill registry, agent registry, etc.).
5. Unload plugins cleanly (remove components, call shutdown).

Usage::

# Wire up component registries
manager = PluginManager()
manager.register_component_registry("tool", tool_registry)
manager.register_component_registry("skill", skill_registry)

# Load everything
await manager.load_all()

# Or load one at a time
await manager.load_plugin("my_package:MyPlugin")

# Use the components via their own registries
tool_registry.get("web_search").run(...)

Source code in xyberos\plugins\manager.py

class PluginManager:
    """
    Central orchestrator for the plugin system.

    Responsibilities:

    1. **Discover** plugin classes via entry points (``xyberos.plugins``).
    2. **Load** and **instantiate** plugins.
    3. **Initialize** plugins (lifecycle hook).
    4. **Route** each plugin's :meth:`Plugin.components` to the
       appropriate type-specific registries (tool registry, skill
       registry, agent registry, etc.).
    5. **Unload** plugins cleanly (remove components, call shutdown).

    Usage::

        # Wire up component registries
        manager = PluginManager()
        manager.register_component_registry("tool", tool_registry)
        manager.register_component_registry("skill", skill_registry)

        # Load everything
        await manager.load_all()

        # Or load one at a time
        await manager.load_plugin("my_package:MyPlugin")

        # Use the components via their own registries
        tool_registry.get("web_search").run(...)
    """

    def __init__(
        self,
        registry: PluginRegistry | None = None,
        loader: PluginLoader | None = None,
    ) -> None:
        self._registry: PluginRegistry = registry or PluginRegistry()
        self._loader: PluginLoader = loader or PluginLoader()

        # Maps component kind → registry for routing
        self._component_registries: dict[str, Any] = {}

    # ── Properties ──────────────────────────────────────────────

    @property
    def registry(self) -> PluginRegistry:
        """The underlying plugin registry."""
        return self._registry

    @property
    def loader(self) -> PluginLoader:
        """The underlying plugin loader."""
        return self._loader

    # ── Component-registry wiring ───────────────────────────────

    def register_component_registry(
        self,
        kind: str,
        registry: Any,
    ) -> None:
        """
        Register a target registry for a component *kind*.

        When a plugin is loaded, every component whose ``kind`` matches
        will be registered into the corresponding registry.

        The *registry* can be any object with ``register(name, instance)``
        and ``unregister(name)`` methods — typically a
        :class:`~xyberos.runtime.core.registry.RuntimeRegistry` or
        :class:`~xyberos.common.registry.ProviderRegistry` subclass.

        Parameters
        ----------
        kind:
            Component type identifier (e.g. ``"tool"``, ``"skill"``).
        registry:
            The registry that manages instances of this kind.
        """
        self._component_registries[kind] = registry
        logger.debug(
            "Registered component registry for kind '%s': %s",
            kind, type(registry).__name__,
        )

    def get_component_registry(self, kind: str) -> Any:
        """
        Return the registry registered for component *kind*, or ``None``.
        """
        return self._component_registries.get(kind)

    @property
    def component_kinds(self) -> list[str]:
        """Return the list of registered component kind identifiers."""
        return list(self._component_registries.keys())

    # ── Loading ─────────────────────────────────────────────────

    async def load_plugin(
        self,
        plugin_cls: type[Plugin],
    ) -> Plugin:
        """
        Instantiate, initialize, and register a plugin.

        All components declared by the plugin are routed to their
        respective type-specific registries.

        Parameters
        ----------
        plugin_cls:
            The plugin class to instantiate (must be a ``Plugin``
            subclass).

        Returns
        -------
        Plugin
            The initialized plugin instance.
        """
        plugin = plugin_cls()
        self._registry.register(plugin.name, plugin)

        # Initialize first
        await plugin.initialize()

        # Route components
        for component in plugin.components():
            self._route_component(component, plugin)

        logger.info(
            "Loaded plugin '%s' v%s — %d component(s)",
            plugin.name,
            plugin.version,
            len(plugin.components()),
        )
        return plugin

    async def load_all(
        self,
        group: str = ENTRY_POINT_GROUP,
    ) -> list[Plugin]:
        """
        Discover and load all plugins registered via entry points.

        Parameters
        ----------
        group:
            Entry-point group to scan (default ``xyberos.plugins``).

        Returns
        -------
        list[Plugin]
            All successfully loaded plugin instances.
        """
        discovered = self._loader.discover(group)
        loaded: list[Plugin] = []

        for name, cls in discovered.items():
            try:
                plugin = await self.load_plugin(cls)
                loaded.append(plugin)
            except Exception as exc:
                logger.error(
                    "Failed to load plugin '%s' (%s): %s",
                    name, cls.__name__, exc,
                )

        logger.info(
            "Loaded %d / %d discovered plugin(s)",
            len(loaded), len(discovered),
        )
        return loaded

    # ── Unloading ───────────────────────────────────────────────

    async def unload_plugin(self, name: str) -> None:
        """
        Unload a previously loaded plugin by *name*.

        Removes all components from their type-specific registries
        and calls :meth:`Plugin.shutdown`.

        Parameters
        ----------
        name:
            The registered name of the plugin to unload.
        """
        plugin = self._registry.get(name)
        if plugin is None:
            logger.warning("No plugin registered under '%s' — nothing to unload", name)
            return

        # Remove components from their registries
        for component in plugin.components():
            self._unroute_component(component)

        # Shutdown
        await plugin.shutdown()

        # Remove from plugin registry
        self._registry.unregister(name)

        logger.info("Unloaded plugin '%s' v%s", plugin.name, plugin.version)

    async def unload_all(self) -> None:
        """Unload every loaded plugin."""
        for name in list(self._registry.names()):
            await self.unload_plugin(name)

    # ── Internal routing ────────────────────────────────────────

    def _route_component(self, component: Component, plugin: Plugin) -> None:
        """Register a component into its kind-specific registry."""
        registry = self._component_registries.get(component.kind)
        if registry is None:
            logger.warning(
                "Plugin '%s' contributes component '%s' (kind='%s'), "
                "but no registry is registered for that kind. "
                "Use register_component_registry('%s', ...) to wire one up.",
                plugin.name, component.name, component.kind, component.kind,
            )
            return
        registry.register(component.name, component.instance)
        logger.debug(
            "Routed component '%s' (kind='%s') from plugin '%s' → %s",
            component.name, component.kind, plugin.name,
            type(registry).__name__,
        )

    def _unroute_component(self, component: Component) -> None:
        """Remove a component from its kind-specific registry."""
        registry = self._component_registries.get(component.kind)
        if registry is not None:
            registry.unregister(component.name)

component_kinds property

Return the list of registered component kind identifiers.

loader property

The underlying plugin loader.

registry property

The underlying plugin registry.

get_component_registry(kind)

Return the registry registered for component kind, or None.

Source code in xyberos\plugins\manager.py

def get_component_registry(self, kind: str) -> Any:
    """
    Return the registry registered for component *kind*, or ``None``.
    """
    return self._component_registries.get(kind)

load_all(group=ENTRY_POINT_GROUP) async

Discover and load all plugins registered via entry points.

Parameters

group: Entry-point group to scan (default xyberos.plugins).

Returns

list[Plugin] All successfully loaded plugin instances.

Source code in xyberos\plugins\manager.py

async def load_all(
    self,
    group: str = ENTRY_POINT_GROUP,
) -> list[Plugin]:
    """
    Discover and load all plugins registered via entry points.

    Parameters
    ----------
    group:
        Entry-point group to scan (default ``xyberos.plugins``).

    Returns
    -------
    list[Plugin]
        All successfully loaded plugin instances.
    """
    discovered = self._loader.discover(group)
    loaded: list[Plugin] = []

    for name, cls in discovered.items():
        try:
            plugin = await self.load_plugin(cls)
            loaded.append(plugin)
        except Exception as exc:
            logger.error(
                "Failed to load plugin '%s' (%s): %s",
                name, cls.__name__, exc,
            )

    logger.info(
        "Loaded %d / %d discovered plugin(s)",
        len(loaded), len(discovered),
    )
    return loaded

load_plugin(plugin_cls) async

Instantiate, initialize, and register a plugin.

All components declared by the plugin are routed to their respective type-specific registries.

Parameters

plugin_cls: The plugin class to instantiate (must be a Plugin subclass).

Returns

Plugin The initialized plugin instance.

Source code in xyberos\plugins\manager.py

async def load_plugin(
    self,
    plugin_cls: type[Plugin],
) -> Plugin:
    """
    Instantiate, initialize, and register a plugin.

    All components declared by the plugin are routed to their
    respective type-specific registries.

    Parameters
    ----------
    plugin_cls:
        The plugin class to instantiate (must be a ``Plugin``
        subclass).

    Returns
    -------
    Plugin
        The initialized plugin instance.
    """
    plugin = plugin_cls()
    self._registry.register(plugin.name, plugin)

    # Initialize first
    await plugin.initialize()

    # Route components
    for component in plugin.components():
        self._route_component(component, plugin)

    logger.info(
        "Loaded plugin '%s' v%s — %d component(s)",
        plugin.name,
        plugin.version,
        len(plugin.components()),
    )
    return plugin

register_component_registry(kind, registry)

Register a target registry for a component kind.

When a plugin is loaded, every component whose kind matches will be registered into the corresponding registry.

The registry can be any object with register(name, instance) and unregister(name) methods — typically a :class:~xyberos.runtime.core.registry.RuntimeRegistry or :class:~xyberos.common.registry.ProviderRegistry subclass.

Parameters

kind: Component type identifier (e.g. "tool", "skill"). registry: The registry that manages instances of this kind.

Source code in xyberos\plugins\manager.py

def register_component_registry(
    self,
    kind: str,
    registry: Any,
) -> None:
    """
    Register a target registry for a component *kind*.

    When a plugin is loaded, every component whose ``kind`` matches
    will be registered into the corresponding registry.

    The *registry* can be any object with ``register(name, instance)``
    and ``unregister(name)`` methods — typically a
    :class:`~xyberos.runtime.core.registry.RuntimeRegistry` or
    :class:`~xyberos.common.registry.ProviderRegistry` subclass.

    Parameters
    ----------
    kind:
        Component type identifier (e.g. ``"tool"``, ``"skill"``).
    registry:
        The registry that manages instances of this kind.
    """
    self._component_registries[kind] = registry
    logger.debug(
        "Registered component registry for kind '%s': %s",
        kind, type(registry).__name__,
    )

unload_all() async

Unload every loaded plugin.

Source code in xyberos\plugins\manager.py

async def unload_all(self) -> None:
    """Unload every loaded plugin."""
    for name in list(self._registry.names()):
        await self.unload_plugin(name)

unload_plugin(name) async

Unload a previously loaded plugin by name.

Removes all components from their type-specific registries and calls :meth:Plugin.shutdown.

Parameters

name: The registered name of the plugin to unload.

Source code in xyberos\plugins\manager.py

async def unload_plugin(self, name: str) -> None:
    """
    Unload a previously loaded plugin by *name*.

    Removes all components from their type-specific registries
    and calls :meth:`Plugin.shutdown`.

    Parameters
    ----------
    name:
        The registered name of the plugin to unload.
    """
    plugin = self._registry.get(name)
    if plugin is None:
        logger.warning("No plugin registered under '%s' — nothing to unload", name)
        return

    # Remove components from their registries
    for component in plugin.components():
        self._unroute_component(component)

    # Shutdown
    await plugin.shutdown()

    # Remove from plugin registry
    self._registry.unregister(name)

    logger.info("Unloaded plugin '%s' v%s", plugin.name, plugin.version)

PluginLoader

Dynamically loads plugin classes.

Supports two modes:

• Explicit loading — load a single plugin class from a module_path:ClassName string.
• Entry-point discovery — scan the installed packages for plugins registered via a given entry-point group.

Entry-point group (pyproject.toml)::

[project.entry-points."xyberos.plugins"]
my_plugin = "my_package:MyPlugin"

Source code in xyberos\plugins\loader.py

class PluginLoader:
    """
    Dynamically loads plugin classes.

    Supports two modes:

    * **Explicit loading** — load a single plugin class from a
      ``module_path:ClassName`` string.
    * **Entry-point discovery** — scan the installed packages for
      plugins registered via a given entry-point group.

    Entry-point group (``pyproject.toml``)::

        [project.entry-points."xyberos.plugins"]
        my_plugin = "my_package:MyPlugin"
    """

    # ── Explicit loading ────────────────────────────────────────

    def load(self, spec: str) -> Type[Plugin]:
        """
        Load a single plugin class from a dotted spec.

        Parameters
        ----------
        spec:
            Either ``"module_path:ClassName"`` or ``"module_path.ClassName"``.

        Returns
        -------
        Type[Plugin]
            The plugin class.

        Raises
        ------
        TypeError
            If the resolved class does not inherit from ``Plugin``.
        """
        module_path, _, class_name = spec.replace(":", ".").rpartition(".")
        if not module_path or not class_name:
            raise ValueError(
                f"Invalid plugin spec '{spec}' — expected 'module_path:ClassName'"
            )

        module = importlib.import_module(module_path)
        plugin_cls = getattr(module, class_name)

        if not isinstance(plugin_cls, type) or not issubclass(plugin_cls, Plugin):
            raise TypeError(
                f"'{class_name}' in '{module_path}' is not a Plugin subclass."
            )

        return plugin_cls

    # ── Entry-point discovery ───────────────────────────────────

    def discover(
        self,
        group: str = "xyberos.plugins",
    ) -> Dict[str, Type[Plugin]]:
        """
        Discover plugin classes registered via Python entry points.

        Parameters
        ----------
        group:
            Entry-point group name (default ``"xyberos.plugins"``).

        Returns
        -------
        dict[str, Type[Plugin]]
            Mapping of entry-point name → plugin class.  Entries that
            fail to load or are not ``Plugin`` subclasses are skipped
            with a warning.
        """
        discovered: dict[str, Type[Plugin]] = {}

        try:
            eps = importlib.metadata.entry_points(group=group)
        except TypeError:
            # Python <3.12 fallback
            all_eps = importlib.metadata.entry_points()
            eps = [ep for ep in all_eps if ep.group == group]

        for ep in eps:
            try:
                cls = ep.load()
                if not (isinstance(cls, type) and issubclass(cls, Plugin)):
                    logger.warning(
                        "Entry point '%s' in group '%s' does not point to a Plugin subclass",
                        ep.name, group,
                    )
                    continue
                discovered[ep.name] = cls
                logger.debug("Discovered plugin '%s' → %s", ep.name, cls.__name__)
            except Exception as exc:
                logger.warning(
                    "Failed to load entry point '%s' from group '%s': %s",
                    ep.name, group, exc,
                )

        return discovered

discover(group='xyberos.plugins')

Discover plugin classes registered via Python entry points.

Parameters

group: Entry-point group name (default "xyberos.plugins").

Returns

dict[str, Type[Plugin]] Mapping of entry-point name → plugin class. Entries that fail to load or are not Plugin subclasses are skipped with a warning.

Source code in xyberos\plugins\loader.py

def discover(
    self,
    group: str = "xyberos.plugins",
) -> Dict[str, Type[Plugin]]:
    """
    Discover plugin classes registered via Python entry points.

    Parameters
    ----------
    group:
        Entry-point group name (default ``"xyberos.plugins"``).

    Returns
    -------
    dict[str, Type[Plugin]]
        Mapping of entry-point name → plugin class.  Entries that
        fail to load or are not ``Plugin`` subclasses are skipped
        with a warning.
    """
    discovered: dict[str, Type[Plugin]] = {}

    try:
        eps = importlib.metadata.entry_points(group=group)
    except TypeError:
        # Python <3.12 fallback
        all_eps = importlib.metadata.entry_points()
        eps = [ep for ep in all_eps if ep.group == group]

    for ep in eps:
        try:
            cls = ep.load()
            if not (isinstance(cls, type) and issubclass(cls, Plugin)):
                logger.warning(
                    "Entry point '%s' in group '%s' does not point to a Plugin subclass",
                    ep.name, group,
                )
                continue
            discovered[ep.name] = cls
            logger.debug("Discovered plugin '%s' → %s", ep.name, cls.__name__)
        except Exception as exc:
            logger.warning(
                "Failed to load entry point '%s' from group '%s': %s",
                ep.name, group, exc,
            )

    return discovered

load(spec)

Load a single plugin class from a dotted spec.

Parameters

spec: Either "module_path:ClassName" or "module_path.ClassName".

Returns

Type[Plugin] The plugin class.

Raises

TypeError If the resolved class does not inherit from Plugin.

Source code in xyberos\plugins\loader.py

def load(self, spec: str) -> Type[Plugin]:
    """
    Load a single plugin class from a dotted spec.

    Parameters
    ----------
    spec:
        Either ``"module_path:ClassName"`` or ``"module_path.ClassName"``.

    Returns
    -------
    Type[Plugin]
        The plugin class.

    Raises
    ------
    TypeError
        If the resolved class does not inherit from ``Plugin``.
    """
    module_path, _, class_name = spec.replace(":", ".").rpartition(".")
    if not module_path or not class_name:
        raise ValueError(
            f"Invalid plugin spec '{spec}' — expected 'module_path:ClassName'"
        )

    module = importlib.import_module(module_path)
    plugin_cls = getattr(module, class_name)

    if not isinstance(plugin_cls, type) or not issubclass(plugin_cls, Plugin):
        raise TypeError(
            f"'{class_name}' in '{module_path}' is not a Plugin subclass."
        )

    return plugin_cls

xyberos.tools — Tool system

xyberos.tools

XYBEROS Platform — Pluggable Tools module.

Pluggable tools that can be invoked by agents and LLMs to interact with external systems and perform specific operations (web search, file I/O, code execution, database queries, etc.).

Every tool implements :class:Tool (a :class:~xyberos.common.provider.Provider subclass) and is registered in the :class:ToolRegistry. The :class:ToolManager orchestrates execution, entry-point discovery, and LLM function-calling integration.

Entry-point group: xyberos.tools::

[project.entry-points."xyberos.tools"]
my_tool = "my_package:MyTool"

Usage::

from xyberos.tools import ToolManager, CalculatorTool
manager = ToolManager()
manager.register("calc", CalculatorTool())
result = manager.run("calc", expression="2 + 2")
print(result.value)  # 4

Tool

Bases: Provider, Plugin, ABC

Base class for all pluggable tools.

A Tool is a self-contained function that an agent or LLM can invoke to perform a specific operation (web search, file I/O, code execution, database query, etc.).

Tools implement both the :class:Provider and :class:Plugin interfaces — each tool contributes itself as a "tool" component.

Subclasses must implement :meth:run.

Source code in xyberos\tools\base.py

class Tool(Provider, Plugin, ABC):
    """
    Base class for all pluggable tools.

    A Tool is a self-contained function that an agent or LLM can invoke
    to perform a specific operation (web search, file I/O, code execution,
    database query, etc.).

    Tools implement both the :class:`Provider` and :class:`Plugin`
    interfaces — each tool contributes itself as a ``"tool"`` component.

    Subclasses must implement :meth:`run`.
    """

    # ── Plugin contract ─────────────────────────────────────────

    def components(self) -> list[Component]:
        """
        Each tool contributes itself as a single ``"tool"`` component.
        """
        return [
            Component(kind="tool", name=self.name, instance=self),
        ]

    # ── Provider capability ─────────────────────────────────────

    @property
    def capability(self) -> ProviderCapability:
        """Self-declared capability. Override in subclasses as needed."""
        return deterministic_capability(
            description=self.description or self.name,
        )

    # ── Tool contract ───────────────────────────────────────────

    @abstractmethod
    def run(self, **kwargs: Any) -> ToolResult:
        """
        Execute the tool with the given parameters.

        Parameters
        ----------
        **kwargs:
            Tool-specific keyword arguments.

        Returns
        -------
        ToolResult
            The outcome of the execution.
        """

    def execute(self, input: ToolInput) -> ToolResult:
        """
        Execute the tool from a :class:`ToolInput` wrapper.

        Parameters
        ----------
        input:
            Structured input including parameters and context.

        Returns
        -------
        ToolResult
            The outcome of the execution.
        """
        return self.run(**input.params)

    def to_spec(self) -> ToolSpec:
        """
        Return a :class:`ToolSpec` describing this tool for LLM
        function-calling integration.

        Override in subclasses to provide a custom parameter schema.
        """
        return ToolSpec(
            name=self.name,
            description=self.description,
            parameters={
                "type": "object",
                "properties": {},
            },
        )

capability property

Self-declared capability. Override in subclasses as needed.

components()

Each tool contributes itself as a single "tool" component.

Source code in xyberos\tools\base.py

def components(self) -> list[Component]:
    """
    Each tool contributes itself as a single ``"tool"`` component.
    """
    return [
        Component(kind="tool", name=self.name, instance=self),
    ]

execute(input)

Execute the tool from a :class:ToolInput wrapper.

Parameters

input: Structured input including parameters and context.

Returns

ToolResult The outcome of the execution.

Source code in xyberos\tools\base.py

def execute(self, input: ToolInput) -> ToolResult:
    """
    Execute the tool from a :class:`ToolInput` wrapper.

    Parameters
    ----------
    input:
        Structured input including parameters and context.

    Returns
    -------
    ToolResult
        The outcome of the execution.
    """
    return self.run(**input.params)

run(**kwargs) abstractmethod

Execute the tool with the given parameters.

Parameters

**kwargs: Tool-specific keyword arguments.

Returns

ToolResult The outcome of the execution.

Source code in xyberos\tools\base.py

@abstractmethod
def run(self, **kwargs: Any) -> ToolResult:
    """
    Execute the tool with the given parameters.

    Parameters
    ----------
    **kwargs:
        Tool-specific keyword arguments.

    Returns
    -------
    ToolResult
        The outcome of the execution.
    """

to_spec()

Return a :class:ToolSpec describing this tool for LLM function-calling integration.

Override in subclasses to provide a custom parameter schema.

Source code in xyberos\tools\base.py

def to_spec(self) -> ToolSpec:
    """
    Return a :class:`ToolSpec` describing this tool for LLM
    function-calling integration.

    Override in subclasses to provide a custom parameter schema.
    """
    return ToolSpec(
        name=self.name,
        description=self.description,
        parameters={
            "type": "object",
            "properties": {},
        },
    )

ToolRegistry

Bases: ProviderRegistry[Tool]

Registry of pluggable tools.

Each tool is registered by name and can be looked up at runtime for execution or LLM function-calling integration.

Usage::

registry = ToolRegistry()
registry.register("web_search", WebSearchTool(), default=True)
registry.register("read_file", ReadFileTool())

Source code in xyberos\tools\registry.py

class ToolRegistry(BaseProviderRegistry[Tool]):
    """
    Registry of pluggable tools.

    Each tool is registered by name and can be looked up at runtime
    for execution or LLM function-calling integration.

    Usage::

        registry = ToolRegistry()
        registry.register("web_search", WebSearchTool(), default=True)
        registry.register("read_file", ReadFileTool())
    """

ToolManager

Orchestrates tool lifecycle, discovery, and execution.

When connected to a :class:PluginManager, tools are registered as "tool" components and loaded through the unified plugin pipeline. The manager can also operate standalone for backward compatibility.

Standalone usage::

manager = ToolManager()
result = manager.run("web_search", query="latest news")
print(result.value)

Plugin-managed usage::

plugin_manager = PluginManager()
tool_manager = ToolManager(plugin_manager=plugin_manager)
await plugin_manager.load_all()  # discovers & routes tool components

Source code in xyberos\tools\manager.py

class ToolManager:
    """
    Orchestrates tool lifecycle, discovery, and execution.

    When connected to a :class:`PluginManager`, tools are registered
    as ``"tool"`` components and loaded through the unified plugin
    pipeline.  The manager can also operate standalone for backward
    compatibility.

    Standalone usage::

        manager = ToolManager()
        result = manager.run("web_search", query="latest news")
        print(result.value)

    Plugin-managed usage::

        plugin_manager = PluginManager()
        tool_manager = ToolManager(plugin_manager=plugin_manager)
        await plugin_manager.load_all()  # discovers & routes tool components
    """

    def __init__(
        self,
        registry: ToolRegistry | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        self._registry = registry or ToolRegistry()
        self._plugin_manager = plugin_manager

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("tool", self._registry)
            logger.info(
                "ToolManager connected to PluginManager — "
                "tool discovery delegated to plugin pipeline"
            )
        else:
            # Standalone mode: discover via entry points directly
            self._discover_entry_points()

    # ── Registry access ─────────────────────────────────────────

    @property
    def registry(self) -> ToolRegistry:
        """The underlying tool registry."""
        return self._registry

    def register(self, name: str, tool: Tool, *, default: bool = False) -> None:
        """Register a tool instance."""
        self._registry.register(name, tool, default=default)
        logger.info("Registered tool '%s' (%s)", name, type(tool).__name__)

    def get_tool(self, name: str) -> Tool:
        """Look up a tool by name. Raises ``ToolNotFoundError`` if missing."""
        try:
            return self._registry.get(name)
        except KeyError:
            raise ToolNotFoundError(f"Tool '{name}' is not registered")

    def list_tools(self) -> dict[str, Tool]:
        """Return all registered tools keyed by name."""
        return {name: self._registry.get(name) for name in self._registry.names()}

    # ── Execution ───────────────────────────────────────────────

    def run(
        self,
        tool_name: str,
        timeout: float = 30.0,
        **params: Any,
    ) -> ToolResult:
        """
        Execute a tool by name with the given parameters.

        Parameters
        ----------
        tool_name:
            Name of the registered tool.
        timeout:
            Maximum execution time in seconds.
        **params:
            Tool-specific keyword arguments.

        Returns
        -------
        ToolResult
            The outcome of the execution.
        """
        tool = self.get_tool(tool_name)

        import signal

        original_handler: Any = None
        start = time.perf_counter()
        try:
            if hasattr(signal, "SIGALRM"):

                def _handler(signum: int, _frame: Any) -> None:
                    raise TimeoutError(f"Tool '{tool_name}' timed out after {timeout}s")

                original_handler = signal.signal(signal.SIGALRM, _handler)  # type: ignore[attr-defined]
                signal.alarm(max(1, int(timeout)))  # type: ignore[attr-defined]

            result = tool.run(**params)
        except TimeoutError as exc:
            elapsed = (time.perf_counter() - start) * 1000
            if hasattr(signal, "SIGALRM") and original_handler is not None:
                signal.alarm(0)  # type: ignore[attr-defined]
                signal.signal(signal.SIGALRM, original_handler)  # type: ignore[attr-defined]
            return ToolResult.fail(str(exc), duration_ms=elapsed)
        except Exception as exc:
            elapsed = (time.perf_counter() - start) * 1000
            logger.exception("Tool '%s' failed: %s", tool_name, exc)
            return ToolResult.fail(exc, duration_ms=elapsed)
        finally:
            if hasattr(signal, "SIGALRM") and original_handler is not None:
                signal.alarm(0)  # type: ignore[attr-defined]
                signal.signal(signal.SIGALRM, original_handler)  # type: ignore[attr-defined]

        elapsed = (time.perf_counter() - start) * 1000
        result.duration_ms = elapsed
        return result

    async def run_async(
        self,
        tool_name: str,
        timeout: float = 30.0,
        **params: Any,
    ) -> ToolResult:
        """
        Execute a tool asynchronously (if the tool supports async).

        Falls back to synchronous execution if the tool's ``run``
        is not a coroutine function.
        """
        import asyncio
        import inspect

        tool = self.get_tool(tool_name)

        start = time.perf_counter()
        try:
            if inspect.iscoroutinefunction(tool.run):
                result = await asyncio.wait_for(
                    tool.run(**params),
                    timeout=timeout,
                )
            else:
                result = await asyncio.get_event_loop().run_in_executor(
                    None,
                    lambda: tool.run(**params),
                )
        except asyncio.TimeoutError:
            elapsed = (time.perf_counter() - start) * 1000
            return ToolResult.fail(
                f"Tool '{tool_name}' timed out after {timeout}s",
                duration_ms=elapsed,
            )
        except Exception as exc:
            elapsed = (time.perf_counter() - start) * 1000
            logger.exception("Tool '%s' failed: %s", tool_name, exc)
            return ToolResult.fail(exc, duration_ms=elapsed)
        else:
            elapsed = (time.perf_counter() - start) * 1000
            result.duration_ms = elapsed
            return result

    # ── LLM integration ─────────────────────────────────────────

    def to_specs(self) -> list[ToolSpec]:
        """
        Return a list of :class:`ToolSpec` for all registered tools.

        Useful for integrating with LLM function-calling APIs.
        """
        return [
            tool.to_spec()
            for tool in self._registry.all()
        ]

    # ── Entry-point discovery ───────────────────────────────────

    def _discover_entry_points(self) -> None:
        """Discover tools from ``xyberos.tools`` entry points."""
        try:
            registered = discover_and_register(
                self._registry,
                ENTRY_POINT_GROUP,
            )
            if registered:
                logger.info(
                    "Discovered %d tool(s) via entry points: %s",
                    len(registered),
                    registered,
                )
            else:
                logger.debug("No tools discovered via entry points")
        except Exception:
            logger.exception("Failed to discover tools from entry points")

registry property

The underlying tool registry.

get_tool(name)

Look up a tool by name. Raises ToolNotFoundError if missing.

Source code in xyberos\tools\manager.py

def get_tool(self, name: str) -> Tool:
    """Look up a tool by name. Raises ``ToolNotFoundError`` if missing."""
    try:
        return self._registry.get(name)
    except KeyError:
        raise ToolNotFoundError(f"Tool '{name}' is not registered")

list_tools()

Return all registered tools keyed by name.

Source code in xyberos\tools\manager.py

def list_tools(self) -> dict[str, Tool]:
    """Return all registered tools keyed by name."""
    return {name: self._registry.get(name) for name in self._registry.names()}

register(name, tool, *, default=False)

Register a tool instance.

Source code in xyberos\tools\manager.py

def register(self, name: str, tool: Tool, *, default: bool = False) -> None:
    """Register a tool instance."""
    self._registry.register(name, tool, default=default)
    logger.info("Registered tool '%s' (%s)", name, type(tool).__name__)

run(tool_name, timeout=30.0, **params)

Execute a tool by name with the given parameters.

Parameters

tool_name: Name of the registered tool. timeout: Maximum execution time in seconds. **params: Tool-specific keyword arguments.

Returns

ToolResult The outcome of the execution.

Source code in xyberos\tools\manager.py

def run(
    self,
    tool_name: str,
    timeout: float = 30.0,
    **params: Any,
) -> ToolResult:
    """
    Execute a tool by name with the given parameters.

    Parameters
    ----------
    tool_name:
        Name of the registered tool.
    timeout:
        Maximum execution time in seconds.
    **params:
        Tool-specific keyword arguments.

    Returns
    -------
    ToolResult
        The outcome of the execution.
    """
    tool = self.get_tool(tool_name)

    import signal

    original_handler: Any = None
    start = time.perf_counter()
    try:
        if hasattr(signal, "SIGALRM"):

            def _handler(signum: int, _frame: Any) -> None:
                raise TimeoutError(f"Tool '{tool_name}' timed out after {timeout}s")

            original_handler = signal.signal(signal.SIGALRM, _handler)  # type: ignore[attr-defined]
            signal.alarm(max(1, int(timeout)))  # type: ignore[attr-defined]

        result = tool.run(**params)
    except TimeoutError as exc:
        elapsed = (time.perf_counter() - start) * 1000
        if hasattr(signal, "SIGALRM") and original_handler is not None:
            signal.alarm(0)  # type: ignore[attr-defined]
            signal.signal(signal.SIGALRM, original_handler)  # type: ignore[attr-defined]
        return ToolResult.fail(str(exc), duration_ms=elapsed)
    except Exception as exc:
        elapsed = (time.perf_counter() - start) * 1000
        logger.exception("Tool '%s' failed: %s", tool_name, exc)
        return ToolResult.fail(exc, duration_ms=elapsed)
    finally:
        if hasattr(signal, "SIGALRM") and original_handler is not None:
            signal.alarm(0)  # type: ignore[attr-defined]
            signal.signal(signal.SIGALRM, original_handler)  # type: ignore[attr-defined]

    elapsed = (time.perf_counter() - start) * 1000
    result.duration_ms = elapsed
    return result

run_async(tool_name, timeout=30.0, **params) async

Execute a tool asynchronously (if the tool supports async).

Falls back to synchronous execution if the tool's run is not a coroutine function.

Source code in xyberos\tools\manager.py

async def run_async(
    self,
    tool_name: str,
    timeout: float = 30.0,
    **params: Any,
) -> ToolResult:
    """
    Execute a tool asynchronously (if the tool supports async).

    Falls back to synchronous execution if the tool's ``run``
    is not a coroutine function.
    """
    import asyncio
    import inspect

    tool = self.get_tool(tool_name)

    start = time.perf_counter()
    try:
        if inspect.iscoroutinefunction(tool.run):
            result = await asyncio.wait_for(
                tool.run(**params),
                timeout=timeout,
            )
        else:
            result = await asyncio.get_event_loop().run_in_executor(
                None,
                lambda: tool.run(**params),
            )
    except asyncio.TimeoutError:
        elapsed = (time.perf_counter() - start) * 1000
        return ToolResult.fail(
            f"Tool '{tool_name}' timed out after {timeout}s",
            duration_ms=elapsed,
        )
    except Exception as exc:
        elapsed = (time.perf_counter() - start) * 1000
        logger.exception("Tool '%s' failed: %s", tool_name, exc)
        return ToolResult.fail(exc, duration_ms=elapsed)
    else:
        elapsed = (time.perf_counter() - start) * 1000
        result.duration_ms = elapsed
        return result

to_specs()

Return a list of :class:ToolSpec for all registered tools.

Useful for integrating with LLM function-calling APIs.

Source code in xyberos\tools\manager.py

def to_specs(self) -> list[ToolSpec]:
    """
    Return a list of :class:`ToolSpec` for all registered tools.

    Useful for integrating with LLM function-calling APIs.
    """
    return [
        tool.to_spec()
        for tool in self._registry.all()
    ]

ToolResult dataclass

Outcome of a tool execution.

Attributes

success: Whether the tool completed successfully. value: The return value (output, response data, ...). error: Error message if the tool failed. duration_ms: Execution duration in milliseconds. metadata: Arbitrary key-value metadata.

Source code in xyberos\tools\models.py

@dataclass(slots=True)
class ToolResult:
    """
    Outcome of a tool execution.

    Attributes
    ----------
    success:
        Whether the tool completed successfully.
    value:
        The return value (output, response data, ...).
    error:
        Error message if the tool failed.
    duration_ms:
        Execution duration in milliseconds.
    metadata:
        Arbitrary key-value metadata.
    """

    success: bool
    value: Any = None
    error: str | None = None
    duration_ms: float = 0.0
    metadata: dict[str, Any] = field(default_factory=lambda: {})

    @classmethod
    def ok(
        cls,
        value: Any = None,
        duration_ms: float = 0.0,
        metadata: dict[str, Any] | None = None,
        **extra: Any,
    ) -> ToolResult:
        """Create a successful result."""
        merged = dict(metadata or {})
        merged.update(extra)
        return cls(
            success=True,
            value=value,
            duration_ms=duration_ms,
            metadata=merged,
        )

    @classmethod
    def fail(
        cls,
        error: str | Exception,
        duration_ms: float = 0.0,
        metadata: dict[str, Any] | None = None,
        **extra: Any,
    ) -> ToolResult:
        """Create a failure result."""
        merged = dict(metadata or {})
        merged.update(extra)
        return cls(
            success=False,
            error=str(error) if isinstance(error, Exception) else error,
            duration_ms=duration_ms,
            metadata=merged,
        )

fail(error, duration_ms=0.0, metadata=None, **extra) classmethod

Create a failure result.

Source code in xyberos\tools\models.py

@classmethod
def fail(
    cls,
    error: str | Exception,
    duration_ms: float = 0.0,
    metadata: dict[str, Any] | None = None,
    **extra: Any,
) -> ToolResult:
    """Create a failure result."""
    merged = dict(metadata or {})
    merged.update(extra)
    return cls(
        success=False,
        error=str(error) if isinstance(error, Exception) else error,
        duration_ms=duration_ms,
        metadata=merged,
    )

ok(value=None, duration_ms=0.0, metadata=None, **extra) classmethod

Create a successful result.

Source code in xyberos\tools\models.py

@classmethod
def ok(
    cls,
    value: Any = None,
    duration_ms: float = 0.0,
    metadata: dict[str, Any] | None = None,
    **extra: Any,
) -> ToolResult:
    """Create a successful result."""
    merged = dict(metadata or {})
    merged.update(extra)
    return cls(
        success=True,
        value=value,
        duration_ms=duration_ms,
        metadata=merged,
    )

ToolSpec dataclass

Declarative specification of a tool for LLM function-calling.

Serialises to JSON-compatible dicts for provider integration (OpenAI tool format, Anthropic tool format, etc.).

Attributes

name: The tool's unique name. description: Human-readable description of what the tool does. parameters: JSON Schema dict describing the expected parameters.

Source code in xyberos\tools\models.py

@dataclass(slots=True)
class ToolSpec:
    """
    Declarative specification of a tool for LLM function-calling.

    Serialises to JSON-compatible dicts for provider integration
    (OpenAI tool format, Anthropic tool format, etc.).

    Attributes
    ----------
    name:
        The tool's unique name.
    description:
        Human-readable description of what the tool does.
    parameters:
        JSON Schema dict describing the expected parameters.
    """

    name: str
    description: str = ""
    parameters: dict[str, Any] = field(default_factory=lambda: {})

xyberos.skills — Skill system

xyberos.skills

Skill

Bases: Plugin

Base class for all runtime skills.

A skill is a reusable capability that an agent can invoke. Skills implement the :class:Plugin interface — each skill contributes itself as a "skill" component.

Subclasses must implement :meth:execute.

Source code in xyberos\skills\base.py

class Skill(Plugin):
    """
    Base class for all runtime skills.

    A skill is a reusable capability that an agent can invoke.
    Skills implement the :class:`Plugin` interface — each skill
    contributes itself as a ``"skill"`` component.

    Subclasses must implement :meth:`execute`.
    """

    def __init__(
        self,
        *,
        name: str,
        description: str = "",
        version: str = "1.0.0",
    ) -> None:
        self.name = name
        self.description = description
        self.version = version

    # ── Plugin contract ─────────────────────────────────────────

    def components(self) -> list[Component]:
        """
        Each skill contributes itself as a single ``"skill"`` component.
        """
        return [
            Component(kind="skill", name=self.name, instance=self),
        ]

    # ── Skill contract ──────────────────────────────────────────

    @abstractmethod
    async def execute(
        self,
        **kwargs: Any,
    ) -> Any:
        """
        Execute the skill.
        """

    async def initialize(self) -> None:
        """
        Optional initialization hook.
        """

    async def shutdown(self) -> None:
        """
        Optional shutdown hook.
        """

components()

Each skill contributes itself as a single "skill" component.

Source code in xyberos\skills\base.py

def components(self) -> list[Component]:
    """
    Each skill contributes itself as a single ``"skill"`` component.
    """
    return [
        Component(kind="skill", name=self.name, instance=self),
    ]

execute(**kwargs) abstractmethod async

Execute the skill.

Source code in xyberos\skills\base.py

@abstractmethod
async def execute(
    self,
    **kwargs: Any,
) -> Any:
    """
    Execute the skill.
    """

initialize() async

Optional initialization hook.

Source code in xyberos\skills\base.py

async def initialize(self) -> None:
    """
    Optional initialization hook.
    """

shutdown() async

Optional shutdown hook.

Source code in xyberos\skills\base.py

async def shutdown(self) -> None:
    """
    Optional shutdown hook.
    """

SkillRegistry

Bases: RuntimeRegistry[Skill]

Registry for runtime skills.

Source code in xyberos\skills\registry.py

class SkillRegistry(RuntimeRegistry[Skill]):
    """
    Registry for runtime skills.
    """

SkillManager

Bases: RuntimeManager[Skill]

Runtime manager for skills.

When connected to a :class:PluginManager, skills are registered as "skill" components and loaded through the unified plugin pipeline. The manager can also operate standalone for backward compatibility.

Standalone usage::

manager = SkillManager()
manager.register("my_skill", MySkill())

Plugin-managed usage::

plugin_manager = PluginManager()
skill_manager = SkillManager(plugin_manager=plugin_manager)
await plugin_manager.load_all()  # discovers & routes skill components

Source code in xyberos\skills\manager.py

class SkillManager(RuntimeManager[Skill]):
    """
    Runtime manager for skills.

    When connected to a :class:`PluginManager`, skills are registered
    as ``"skill"`` components and loaded through the unified plugin
    pipeline.  The manager can also operate standalone for backward
    compatibility.

    Standalone usage::

        manager = SkillManager()
        manager.register("my_skill", MySkill())

    Plugin-managed usage::

        plugin_manager = PluginManager()
        skill_manager = SkillManager(plugin_manager=plugin_manager)
        await plugin_manager.load_all()  # discovers & routes skill components
    """

    def __init__(
        self,
        registry: SkillRegistry | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        super().__init__(registry or SkillRegistry())
        self._plugin_manager = plugin_manager

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("skill", self._registry)
            logger.info(
                "SkillManager connected to PluginManager — "
                "skill discovery delegated to plugin pipeline"
            )
        else:
            # Standalone mode: discover via entry points directly
            self._discover_entry_points()

    def _discover_entry_points(self) -> None:
        """Discover skills from ``xyberos.skills`` entry points."""
        # Import skill classes and instantiate via the base registry
        from .base import Skill
        from xyberos.common.registry import discover_entry_points
        classes = discover_entry_points("xyberos.skills")
        registered: list[str] = []
        for name, cls in classes.items():
            try:
                instance = cls()
                if isinstance(instance, Skill):
                    self._registry.register(name, instance)
                    registered.append(name)
            except Exception:
                logger.exception("Failed to instantiate skill '%s'", name)
        if registered:
            logger.info("Discovered %d skill(s) via entry points: %s", len(registered), registered)
        else:
            logger.debug("No skills discovered via entry points")

xyberos.agents — Multi-agent system

xyberos.agents

Multi-Agent Runtime — agents with communication, shared memory, and collaboration.

Agent dataclass

Base runtime agent with inter-agent communication, shared memory, and collaborative intelligence.

Agents can

• Send/receive messages via the shared :class:MessageBus
• Read/write to shared memory via :attr:shared_memory
• Collaborate via :attr:collaboration (voting, knowledge sharing, collective problem solving)

Specialized agents extend this class and override :meth:handle_message.

Usage::

class ResearcherAgent(Agent):
    async def handle_message(self, msg):
        # Access shared memory
        await self.shared_memory.store("finding:x", value, agent_id=self.id)
        # Collaborate with other agents
        result = await self.collaboration.conduct_vote(...)

Source code in xyberos\agents\agent.py

@dataclass(slots=True)
class Agent:
    """
    Base runtime agent with inter-agent communication, shared memory,
    and collaborative intelligence.

    Agents can:
        - Send/receive messages via the shared :class:`MessageBus`
        - Read/write to shared memory via :attr:`shared_memory`
        - Collaborate via :attr:`collaboration`
          (voting, knowledge sharing, collective problem solving)

    Specialized agents extend this class and override :meth:`handle_message`.

    Usage::

        class ResearcherAgent(Agent):
            async def handle_message(self, msg):
                # Access shared memory
                await self.shared_memory.store("finding:x", value, agent_id=self.id)
                # Collaborate with other agents
                result = await self.collaboration.conduct_vote(...)
    """

    id: str
    name: str
    description: str = ""
    metadata: dict[str, Any] = field(default_factory=lambda: {})

    # Communication (set by AgentManager on registration)
    _bus: MessageBus | None = None
    _queue: asyncio.Queue[Message] | None = None
    _running: bool = False
    _shared_memory: Any = None  # SharedMemory
    _collaboration: Any = None  # CollaborationEngine

    # ── Shared Memory ──────────────────────────────────────────

    @property
    def shared_memory(self) -> SharedMemory:
        """Access the shared memory space shared by all agents."""
        if self._shared_memory is None:
            raise RuntimeError(
                f"Agent '{self.id}' is not connected to shared memory. "
                "Ensure it is registered via AgentManager."
            )
        return self._shared_memory

    @property
    def collaboration(self) -> CollaborationEngine:
        """Access the collaboration engine for voting and collective problem solving."""
        if self._collaboration is None:
            raise RuntimeError(
                f"Agent '{self.id}' is not connected to collaboration engine. "
                "Ensure it is registered via AgentManager."
            )
        return self._collaboration

    # ── Lifecycle ──────────────────────────────────────────────

    async def start(self) -> None:
        """Called when the agent starts. Subscribes to the message bus."""
        self._running = True
        if self._bus:
            self._queue = await self._bus.subscribe(self.id)
            asyncio.create_task(self._message_loop())
        logger.info("Agent '%s' (%s) started", self.name, self.id)

    async def stop(self) -> None:
        """Called when the agent stops."""
        self._running = False
        if self._bus:
            await self._bus.unsubscribe(self.id)
        logger.info("Agent '%s' (%s) stopped", self.name, self.id)

    # ── Communication ──────────────────────────────────────────

    async def send_message(
        self,
        receiver: str,
        content: Any,
        *,
        msg_type: str = "message",
        correlation_id: str = "",
    ) -> None:
        """Send a message to another agent."""
        if not self._bus:
            logger.warning("Agent '%s': not connected to message bus", self.id)
            return
        msg = Message(
            sender=self.id,
            receiver=receiver,
            content=content,
            msg_type=msg_type,
            correlation_id=correlation_id,
        )
        await self._bus.send(msg)

    async def broadcast(self, content: Any, *, msg_type: str = "broadcast") -> None:
        """Broadcast a message to all agents."""
        await self.send_message("*", content, msg_type=msg_type)

    async def request(
        self,
        receiver: str,
        content: Any,
        *,
        timeout: float = 10.0,
    ) -> Message | None:
        """Send a request and wait for a reply."""
        if not self._bus:
            return None
        return await self._bus.request(self.id, receiver, content, timeout=timeout)

    async def reply_to(self, original: Message, content: Any) -> None:
        """Reply to an incoming request message."""
        if self._bus:
            await self._bus.reply(original, content)

    # ── Collaborative Intelligence ─────────────────────────────

    async def share_knowledge(
        self,
        topic: str,
        content: Any,
        *,
        tags: list[str] | None = None,
    ) -> None:
        """Share knowledge on a *topic* with all agents via shared memory."""
        if self._collaboration:
            await self._collaboration.share_knowledge(self, topic, content, tags=tags)

    async def query_knowledge(self, topic: str, *, limit: int = 10) -> list[Any]:
        """Query shared knowledge on a *topic* from all agents."""
        if self._collaboration:
            return await self._collaboration.query_knowledge(topic, limit=limit)
        return []

    async def vote_on(
        self,
        question: str,
        agents: list[Agent],
        options: list[str],
    ) -> Any:
        """Conduct a vote among *agents* on a *question*."""
        if self._collaboration:
            return await self._collaboration.conduct_vote(question, agents, options)
        return None

    # ── Message Handling ───────────────────────────────────────

    async def handle_message(self, message: Message) -> None:
        """
        Handle an incoming message. Override in subclasses.

        Default behavior: log the message.
        """
        logger.info("Agent '%s' received: %s", self.id, str(message.content)[:100])

    async def _message_loop(self) -> None:
        """Continuously process incoming messages."""
        while self._running and self._queue is not None:
            try:
                message = await asyncio.wait_for(self._queue.get(), timeout=1.0)
                await self.handle_message(message)
            except asyncio.TimeoutError:
                continue
            except Exception as exc:
                logger.error("Agent '%s' message handler error: %s", self.id, exc)

collaboration property

Access the collaboration engine for voting and collective problem solving.

shared_memory property

Access the shared memory space shared by all agents.

broadcast(content, *, msg_type='broadcast') async

Broadcast a message to all agents.

Source code in xyberos\agents\agent.py

async def broadcast(self, content: Any, *, msg_type: str = "broadcast") -> None:
    """Broadcast a message to all agents."""
    await self.send_message("*", content, msg_type=msg_type)

handle_message(message) async

Handle an incoming message. Override in subclasses.

Default behavior: log the message.

Source code in xyberos\agents\agent.py

async def handle_message(self, message: Message) -> None:
    """
    Handle an incoming message. Override in subclasses.

    Default behavior: log the message.
    """
    logger.info("Agent '%s' received: %s", self.id, str(message.content)[:100])

query_knowledge(topic, *, limit=10) async

Query shared knowledge on a topic from all agents.

Source code in xyberos\agents\agent.py

async def query_knowledge(self, topic: str, *, limit: int = 10) -> list[Any]:
    """Query shared knowledge on a *topic* from all agents."""
    if self._collaboration:
        return await self._collaboration.query_knowledge(topic, limit=limit)
    return []

reply_to(original, content) async

Reply to an incoming request message.

Source code in xyberos\agents\agent.py

async def reply_to(self, original: Message, content: Any) -> None:
    """Reply to an incoming request message."""
    if self._bus:
        await self._bus.reply(original, content)

request(receiver, content, *, timeout=10.0) async

Send a request and wait for a reply.

Source code in xyberos\agents\agent.py

async def request(
    self,
    receiver: str,
    content: Any,
    *,
    timeout: float = 10.0,
) -> Message | None:
    """Send a request and wait for a reply."""
    if not self._bus:
        return None
    return await self._bus.request(self.id, receiver, content, timeout=timeout)

send_message(receiver, content, *, msg_type='message', correlation_id='') async

Send a message to another agent.

Source code in xyberos\agents\agent.py

async def send_message(
    self,
    receiver: str,
    content: Any,
    *,
    msg_type: str = "message",
    correlation_id: str = "",
) -> None:
    """Send a message to another agent."""
    if not self._bus:
        logger.warning("Agent '%s': not connected to message bus", self.id)
        return
    msg = Message(
        sender=self.id,
        receiver=receiver,
        content=content,
        msg_type=msg_type,
        correlation_id=correlation_id,
    )
    await self._bus.send(msg)

share_knowledge(topic, content, *, tags=None) async

Share knowledge on a topic with all agents via shared memory.

Source code in xyberos\agents\agent.py

async def share_knowledge(
    self,
    topic: str,
    content: Any,
    *,
    tags: list[str] | None = None,
) -> None:
    """Share knowledge on a *topic* with all agents via shared memory."""
    if self._collaboration:
        await self._collaboration.share_knowledge(self, topic, content, tags=tags)

start() async

Called when the agent starts. Subscribes to the message bus.

Source code in xyberos\agents\agent.py

async def start(self) -> None:
    """Called when the agent starts. Subscribes to the message bus."""
    self._running = True
    if self._bus:
        self._queue = await self._bus.subscribe(self.id)
        asyncio.create_task(self._message_loop())
    logger.info("Agent '%s' (%s) started", self.name, self.id)

stop() async

Called when the agent stops.

Source code in xyberos\agents\agent.py

async def stop(self) -> None:
    """Called when the agent stops."""
    self._running = False
    if self._bus:
        await self._bus.unsubscribe(self.id)
    logger.info("Agent '%s' (%s) stopped", self.name, self.id)

vote_on(question, agents, options) async

Conduct a vote among agents on a question.

Source code in xyberos\agents\agent.py

async def vote_on(
    self,
    question: str,
    agents: list[Agent],
    options: list[str],
) -> Any:
    """Conduct a vote among *agents* on a *question*."""
    if self._collaboration:
        return await self._collaboration.conduct_vote(question, agents, options)
    return None

AgentPlugin

Bases: Plugin

Adapter that wraps a single :class:Agent as a :class:Plugin.

Lifecycle mapping:

• AgentPlugin.initialize() → Agent.start()
• AgentPlugin.shutdown() → Agent.stop()

The plugin's name/description are taken from the agent's own fields. Subclass to provide a custom version or additional components.

Usage::

# Wrap an existing agent
plugin = AgentPlugin(my_agent)

# Or subclass for custom metadata
class MyResearcherPlugin(AgentPlugin):
    def __init__(self) -> None:
        super().__init__(
            Agent(id="researcher-1", name="Researcher"),
        )
        self.version = "2.0.0"

Source code in xyberos\agents\plugin.py

class AgentPlugin(Plugin):
    """
    Adapter that wraps a single :class:`Agent` as a :class:`Plugin`.

    Lifecycle mapping:

    * ``AgentPlugin.initialize()`` → ``Agent.start()``
    * ``AgentPlugin.shutdown()``   → ``Agent.stop()``

    The plugin's ``name``/``description`` are taken from the agent's
    own fields.  Subclass to provide a custom ``version`` or additional
    components.

    Usage::

        # Wrap an existing agent
        plugin = AgentPlugin(my_agent)

        # Or subclass for custom metadata
        class MyResearcherPlugin(AgentPlugin):
            def __init__(self) -> None:
                super().__init__(
                    Agent(id="researcher-1", name="Researcher"),
                )
                self.version = "2.0.0"
    """

    def __init__(self, agent: Agent) -> None:
        self._agent = agent
        self.name = agent.name
        self.version = "1.0.0"
        self.description = agent.description

    # ── Accessor ───────────────────────────────────────────────

    @property
    def agent(self) -> Agent:
        """The wrapped agent instance."""
        return self._agent

    # ── Plugin contract ────────────────────────────────────────

    def components(self) -> list[Component]:
        """
        Contribute the wrapped agent as a single ``"agent"`` component.

        The component name is the agent's ``name`` field so that
        lookups via ``agent_registry.get(agent_name)`` work naturally.
        """
        return [
            Component(
                kind="agent",
                name=self._agent.name,
                instance=self._agent,
                metadata={"agent_id": self._agent.id},
            ),
        ]

    async def initialize(self) -> None:
        """Map to ``Agent.start()``."""
        await self._agent.start()

    async def shutdown(self) -> None:
        """Map to ``Agent.stop()``."""
        await self._agent.stop()

agent property

The wrapped agent instance.

components()

Contribute the wrapped agent as a single "agent" component.

The component name is the agent's name field so that lookups via agent_registry.get(agent_name) work naturally.

Source code in xyberos\agents\plugin.py

def components(self) -> list[Component]:
    """
    Contribute the wrapped agent as a single ``"agent"`` component.

    The component name is the agent's ``name`` field so that
    lookups via ``agent_registry.get(agent_name)`` work naturally.
    """
    return [
        Component(
            kind="agent",
            name=self._agent.name,
            instance=self._agent,
            metadata={"agent_id": self._agent.id},
        ),
    ]

initialize() async

Map to Agent.start().

Source code in xyberos\agents\plugin.py

async def initialize(self) -> None:
    """Map to ``Agent.start()``."""
    await self._agent.start()

shutdown() async

Map to Agent.stop().

Source code in xyberos\agents\plugin.py

async def shutdown(self) -> None:
    """Map to ``Agent.stop()``."""
    await self._agent.stop()

AgentManager

Bases: RuntimeManager[Agent]

Runtime manager for agents.

Manages agent lifecycle (start/stop), inter-agent communication via :class:MessageBus, shared memory via :class:SharedMemory, and collaborative intelligence via :class:CollaborationEngine.

When connected to a :class:PluginManager, agents are registered as "agent" components and loaded through the unified plugin pipeline. The manager can also operate standalone for backward compatibility.

Standalone usage::

manager = AgentManager()
manager.start_all()
await manager.send("agent_a", "agent_b", "Hello!")

Plugin-managed usage::

plugin_manager = PluginManager()
agent_manager = AgentManager(plugin_manager=plugin_manager)
await plugin_manager.load_all()

Source code in xyberos\agents\manager.py

class AgentManager(RuntimeManager[Agent]):
    """
    Runtime manager for agents.

    Manages agent lifecycle (start/stop), inter-agent communication
    via :class:`MessageBus`, shared memory via :class:`SharedMemory`,
    and collaborative intelligence via :class:`CollaborationEngine`.

    When connected to a :class:`PluginManager`, agents are registered
    as ``"agent"`` components and loaded through the unified plugin
    pipeline.  The manager can also operate standalone for backward
    compatibility.

    Standalone usage::

        manager = AgentManager()
        manager.start_all()
        await manager.send("agent_a", "agent_b", "Hello!")

    Plugin-managed usage::

        plugin_manager = PluginManager()
        agent_manager = AgentManager(plugin_manager=plugin_manager)
        await plugin_manager.load_all()
    """

    def __init__(
        self,
        registry: AgentRegistry | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        super().__init__(registry or AgentRegistry())
        self._bus = MessageBus()
        self._shared_memory = SharedMemory()
        self._collaboration = CollaborationEngine(shared_memory=self._shared_memory)
        self._plugin_manager = plugin_manager

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("agent", self._registry)
            logger.info(
                "AgentManager connected to PluginManager — "
                "agent discovery delegated to plugin pipeline"
            )
        else:
            # Standalone mode: discover via entry points directly
            self._discover_entry_points()

    @property
    def bus(self) -> MessageBus:
        """The shared message bus for inter-agent communication."""
        return self._bus

    @property
    def shared_memory(self) -> SharedMemory:
        """The shared memory space accessible by all agents."""
        return self._shared_memory

    @property
    def collaboration(self) -> CollaborationEngine:
        """The collaboration engine for voting and collective problem solving."""
        return self._collaboration

    def register(self, name: str, agent: Agent) -> None:  # type: ignore[override]
        """Register an agent and connect it to message bus, shared memory, and collaboration."""
        agent._bus = self._bus  # type: ignore[attr-defined]
        agent._shared_memory = self._shared_memory  # type: ignore[attr-defined]
        agent._collaboration = self._collaboration  # type: ignore[attr-defined]
        super().register(name, agent)  # type: ignore[arg-type]

    async def start_all(self) -> None:  # type: ignore[override]
        """Start all registered agents."""
        for name in self.registry.names():
            agent = self.registry.get(name)
            if agent is None:
                continue
            try:
                await agent.start()
                logger.info("Started agent: %s", name)
            except Exception as exc:
                logger.error("Failed to start agent '%s': %s", name, exc)

    async def stop_all(self) -> None:  # type: ignore[override]
        """Stop all registered agents."""
        for name in self.registry.names():
            agent = self.registry.get(name)
            if agent is None:
                continue
            try:
                await agent.stop()
            except Exception as exc:
                logger.error("Failed to stop agent '%s': %s", name, exc)

    async def send(
        self,
        sender_id: str,
        receiver_id: str,
        content: str,
    ) -> None:
        """Send a message from one agent to another."""
        from .message_bus import Message
        msg = Message(sender=sender_id, receiver=receiver_id, content=content)
        await self._bus.send(msg)

    def _discover_entry_points(self) -> None:
        """Discover agents from ``xyberos.agents`` entry points."""
        eps = discover_entry_points(_ENTRY_POINT_GROUP)
        for name, cls in eps.items():
            try:
                instance = cls()  # type: ignore[operator]
                self.register(name, instance)
                logger.info("Discovered agent '%s'", name)
            except Exception as exc:
                logger.warning("Failed to register agent '%s': %s", name, exc)

bus property

The shared message bus for inter-agent communication.

collaboration property

The collaboration engine for voting and collective problem solving.

shared_memory property

The shared memory space accessible by all agents.

register(name, agent)

Register an agent and connect it to message bus, shared memory, and collaboration.

Source code in xyberos\agents\manager.py

def register(self, name: str, agent: Agent) -> None:  # type: ignore[override]
    """Register an agent and connect it to message bus, shared memory, and collaboration."""
    agent._bus = self._bus  # type: ignore[attr-defined]
    agent._shared_memory = self._shared_memory  # type: ignore[attr-defined]
    agent._collaboration = self._collaboration  # type: ignore[attr-defined]
    super().register(name, agent)  # type: ignore[arg-type]

send(sender_id, receiver_id, content) async

Send a message from one agent to another.

Source code in xyberos\agents\manager.py

async def send(
    self,
    sender_id: str,
    receiver_id: str,
    content: str,
) -> None:
    """Send a message from one agent to another."""
    from .message_bus import Message
    msg = Message(sender=sender_id, receiver=receiver_id, content=content)
    await self._bus.send(msg)

start_all() async

Start all registered agents.

Source code in xyberos\agents\manager.py

async def start_all(self) -> None:  # type: ignore[override]
    """Start all registered agents."""
    for name in self.registry.names():
        agent = self.registry.get(name)
        if agent is None:
            continue
        try:
            await agent.start()
            logger.info("Started agent: %s", name)
        except Exception as exc:
            logger.error("Failed to start agent '%s': %s", name, exc)

stop_all() async

Stop all registered agents.

Source code in xyberos\agents\manager.py

async def stop_all(self) -> None:  # type: ignore[override]
    """Stop all registered agents."""
    for name in self.registry.names():
        agent = self.registry.get(name)
        if agent is None:
            continue
        try:
            await agent.stop()
        except Exception as exc:
            logger.error("Failed to stop agent '%s': %s", name, exc)

AgentRegistry

Bases: RuntimeRegistry[Agent]

Registry for runtime agents.

Source code in xyberos\agents\registry.py

class AgentRegistry(RuntimeRegistry[Agent]):
    """
    Registry for runtime agents.
    """

    pass

MessageBus

Publish/subscribe message bus for inter-agent communication.

Agents subscribe to receive messages. Messages can be sent to a specific agent or broadcast to all subscribers.

Source code in xyberos\agents\message_bus.py

class MessageBus:
    """
    Publish/subscribe message bus for inter-agent communication.

    Agents subscribe to receive messages.  Messages can be sent to
    a specific agent or broadcast to all subscribers.
    """

    def __init__(self) -> None:
        self._queues: dict[str, asyncio.Queue[Message]] = {}
        self._lock = asyncio.Lock()

    async def subscribe(self, agent_id: str) -> asyncio.Queue[Message]:
        """Register an agent to receive messages. Returns the agent's queue."""
        async with self._lock:
            if agent_id not in self._queues:
                self._queues[agent_id] = asyncio.Queue()
            return self._queues[agent_id]

    async def unsubscribe(self, agent_id: str) -> None:
        """Remove an agent from the bus."""
        async with self._lock:
            self._queues.pop(agent_id, None)

    async def send(self, message: Message) -> None:
        """
        Send a message to a specific agent or broadcast to all.

        If ``message.receiver`` is ``"*"``, delivers to all subscribers.
        """
        message.timestamp = datetime.now(timezone.utc)
        async with self._lock:
            if message.receiver == "*":
                for q in self._queues.values():
                    await q.put(message)
                logger.debug("Broadcast: %s -> * (%d recipients)", message.sender, len(self._queues))
            elif message.receiver in self._queues:
                await self._queues[message.receiver].put(message)
                logger.debug("Message: %s -> %s", message.sender, message.receiver)
            else:
                logger.warning("Message: %s -> %s (not found)", message.sender, message.receiver)

    async def request(
        self,
        sender: str,
        receiver: str,
        content: Any,
        *,
        msg_type: str = "request",
        timeout: float = 10.0,
    ) -> Message | None:
        """
        Send a request and wait for a reply.

        Returns the reply message, or ``None`` on timeout.
        """
        correlation_id = f"{sender}_{datetime.now(timezone.utc).timestamp()}"
        req = Message(
            sender=sender,
            receiver=receiver,
            content=content,
            msg_type=msg_type,
            correlation_id=correlation_id,
        )

        # Subscribe for the reply
        reply_queue = await self.subscribe(f"{sender}_reply_{correlation_id}")

        await self.send(req)

        try:
            reply = await asyncio.wait_for(reply_queue.get(), timeout=timeout)
            return reply
        except asyncio.TimeoutError:
            logger.warning("Request %s -> %s timed out after %.1fs", sender, receiver, timeout)
            return None
        finally:
            await self.unsubscribe(f"{sender}_reply_{correlation_id}")

    async def reply(self, original: Message, content: Any, **kwargs: Any) -> None:
        """Send a reply to an original request message."""
        reply = Message(
            sender=original.receiver,
            receiver=f"{original.sender}_reply_{original.correlation_id}",
            content=content,
            msg_type="reply",
            correlation_id=original.correlation_id,
            **kwargs,
        )
        await self.send(reply)

    @property
    def subscriber_count(self) -> int:
        """Number of currently subscribed agents."""
        return len(self._queues)

subscriber_count property

Number of currently subscribed agents.

reply(original, content, **kwargs) async

Send a reply to an original request message.

Source code in xyberos\agents\message_bus.py

async def reply(self, original: Message, content: Any, **kwargs: Any) -> None:
    """Send a reply to an original request message."""
    reply = Message(
        sender=original.receiver,
        receiver=f"{original.sender}_reply_{original.correlation_id}",
        content=content,
        msg_type="reply",
        correlation_id=original.correlation_id,
        **kwargs,
    )
    await self.send(reply)

request(sender, receiver, content, *, msg_type='request', timeout=10.0) async

Send a request and wait for a reply.

Returns the reply message, or None on timeout.

Source code in xyberos\agents\message_bus.py

async def request(
    self,
    sender: str,
    receiver: str,
    content: Any,
    *,
    msg_type: str = "request",
    timeout: float = 10.0,
) -> Message | None:
    """
    Send a request and wait for a reply.

    Returns the reply message, or ``None`` on timeout.
    """
    correlation_id = f"{sender}_{datetime.now(timezone.utc).timestamp()}"
    req = Message(
        sender=sender,
        receiver=receiver,
        content=content,
        msg_type=msg_type,
        correlation_id=correlation_id,
    )

    # Subscribe for the reply
    reply_queue = await self.subscribe(f"{sender}_reply_{correlation_id}")

    await self.send(req)

    try:
        reply = await asyncio.wait_for(reply_queue.get(), timeout=timeout)
        return reply
    except asyncio.TimeoutError:
        logger.warning("Request %s -> %s timed out after %.1fs", sender, receiver, timeout)
        return None
    finally:
        await self.unsubscribe(f"{sender}_reply_{correlation_id}")

send(message) async

Send a message to a specific agent or broadcast to all.

If message.receiver is "*", delivers to all subscribers.

Source code in xyberos\agents\message_bus.py

async def send(self, message: Message) -> None:
    """
    Send a message to a specific agent or broadcast to all.

    If ``message.receiver`` is ``"*"``, delivers to all subscribers.
    """
    message.timestamp = datetime.now(timezone.utc)
    async with self._lock:
        if message.receiver == "*":
            for q in self._queues.values():
                await q.put(message)
            logger.debug("Broadcast: %s -> * (%d recipients)", message.sender, len(self._queues))
        elif message.receiver in self._queues:
            await self._queues[message.receiver].put(message)
            logger.debug("Message: %s -> %s", message.sender, message.receiver)
        else:
            logger.warning("Message: %s -> %s (not found)", message.sender, message.receiver)

subscribe(agent_id) async

Register an agent to receive messages. Returns the agent's queue.

Source code in xyberos\agents\message_bus.py

async def subscribe(self, agent_id: str) -> asyncio.Queue[Message]:
    """Register an agent to receive messages. Returns the agent's queue."""
    async with self._lock:
        if agent_id not in self._queues:
            self._queues[agent_id] = asyncio.Queue()
        return self._queues[agent_id]

unsubscribe(agent_id) async

Remove an agent from the bus.

Source code in xyberos\agents\message_bus.py

async def unsubscribe(self, agent_id: str) -> None:
    """Remove an agent from the bus."""
    async with self._lock:
        self._queues.pop(agent_id, None)

SharedMemory

A shared knowledge space accessible by all agents.

Supports storing, retrieving, searching, and watching entries. Entries are tagged with the originating agent for provenance.

Usage::

memory = SharedMemory()
await memory.store("goal:1", "Build a web app", agent_id="planner")
entry = await memory.retrieve("goal:1")
results = await memory.search("web app")

Source code in xyberos\agents\shared_memory.py

class SharedMemory:
    """
    A shared knowledge space accessible by all agents.

    Supports storing, retrieving, searching, and watching entries.
    Entries are tagged with the originating agent for provenance.

    Usage::

        memory = SharedMemory()
        await memory.store("goal:1", "Build a web app", agent_id="planner")
        entry = await memory.retrieve("goal:1")
        results = await memory.search("web app")
    """

    def __init__(self, max_entries: int = 10000) -> None:
        self._entries: OrderedDict[str, SharedEntry] = OrderedDict()
        self._max_entries = max_entries
        self._watch_callbacks: dict[str, list[Callable[[str, SharedEntry], Awaitable[None]]]] = {}

    # ── CRUD ───────────────────────────────────────────────────

    async def store(
        self,
        key: str,
        value: Any,
        agent_id: str = "",
        *,
        tags: list[str] | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> SharedEntry:
        """
        Store a value in shared memory.

        If *key* already exists, it is overwritten and the timestamp
        is updated.
        """
        self._evict_if_needed()
        entry = SharedEntry(
            key=key,
            value=value,
            agent_id=agent_id,
            timestamp=datetime.now(timezone.utc),
            tags=tags or [],
            metadata=metadata or {},
        )
        self._entries[key] = entry
        self._entries.move_to_end(key)
        logger.debug("SharedMemory: %s stored by %s", key, agent_id)

        # Notify watchers
        await self._notify_watchers(key, entry)
        return entry

    async def retrieve(self, key: str) -> SharedEntry | None:
        """Retrieve an entry by key. Returns ``None`` if not found."""
        entry = self._entries.get(key)
        if entry:
            self._entries.move_to_end(key)
        return entry

    async def delete(self, key: str) -> bool:
        """Delete an entry. Returns ``True`` if it existed."""
        if key in self._entries:
            del self._entries[key]
            return True
        return False

    async def clear(self) -> None:
        """Remove all entries."""
        self._entries.clear()

    # ── Search ─────────────────────────────────────────────────

    async def search(
        self,
        query: str,
        *,
        limit: int = 10,
        agent_id: str | None = None,
        tags: list[str] | None = None,
    ) -> list[SharedEntry]:
        """
        Search entries by keyword matching against key, value, and tags.

        Parameters
        ----------
        query:
            Keywords to search for.
        limit:
            Maximum results.
        agent_id:
            If set, only return entries from this agent.
        tags:
            If set, only return entries with at least one matching tag.

        Returns
        -------
        list[SharedEntry]
            Matching entries sorted by recency.
        """
        query_lower = query.lower()
        query_words = query_lower.split()
        results: list[SharedEntry] = []

        for entry in reversed(list(self._entries.values())):
            if agent_id and entry.agent_id != agent_id:
                continue
            if tags and not any(t in entry.tags for t in tags):
                continue

            # Match against key, value, and tags
            key_match = any(w in entry.key.lower() for w in query_words)
            value_match = any(w in str(entry.value).lower() for w in query_words)
            tag_match = any(w in " ".join(entry.tags).lower() for w in query_words)

            if key_match or value_match or tag_match:
                results.append(entry)
                if len(results) >= limit:
                    break

        return results

    async def list_by_agent(self, agent_id: str) -> list[SharedEntry]:
        """Return all entries written by a specific agent."""
        return [e for e in self._entries.values() if e.agent_id == agent_id]

    async def list_by_tag(self, tag: str) -> list[SharedEntry]:
        """Return all entries with a specific tag."""
        return [e for e in self._entries.values() if tag in e.tags]

    @property
    def count(self) -> int:
        """Number of entries currently stored."""
        return len(self._entries)

    @property
    def agent_ids(self) -> set[str]:
        """Set of all agent IDs that have written to shared memory."""
        return {e.agent_id for e in self._entries.values() if e.agent_id}

    # ── Watch / Notify ─────────────────────────────────────────

    async def watch(self, key_pattern: str, callback: Callable[[str, SharedEntry], Awaitable[None]]) -> None:
        """
        Register a callback that fires when an entry matching *key_pattern*
        is stored or updated.  The pattern supports simple ``*`` wildcard.

        The callback receives ``(key, SharedEntry)``.
        """
        if key_pattern not in self._watch_callbacks:
            self._watch_callbacks[key_pattern] = []
        self._watch_callbacks[key_pattern].append(callback)

    async def _notify_watchers(self, key: str, entry: SharedEntry) -> None:
        """Notify all watchers whose pattern matches *key*."""
        import fnmatch
        for pattern, callbacks in self._watch_callbacks.items():
            if fnmatch.fnmatch(key, pattern):
                for cb in callbacks:
                    try:
                        await cb(key, entry)
                    except Exception as exc:
                        logger.warning("Watcher callback failed for '%s': %s", key, exc)

    # ── Internals ──────────────────────────────────────────────

    def _evict_if_needed(self) -> None:
        """Evict oldest entries when max_entries exceeded."""
        while len(self._entries) >= self._max_entries:
            self._entries.popitem(last=False)

    def __contains__(self, key: str) -> bool:
        return key in self._entries

    def __len__(self) -> int:
        return len(self._entries)

agent_ids property

Set of all agent IDs that have written to shared memory.

count property

Number of entries currently stored.

clear() async

Remove all entries.

Source code in xyberos\agents\shared_memory.py

async def clear(self) -> None:
    """Remove all entries."""
    self._entries.clear()

delete(key) async

Delete an entry. Returns True if it existed.

Source code in xyberos\agents\shared_memory.py

async def delete(self, key: str) -> bool:
    """Delete an entry. Returns ``True`` if it existed."""
    if key in self._entries:
        del self._entries[key]
        return True
    return False

list_by_agent(agent_id) async

Return all entries written by a specific agent.

Source code in xyberos\agents\shared_memory.py

async def list_by_agent(self, agent_id: str) -> list[SharedEntry]:
    """Return all entries written by a specific agent."""
    return [e for e in self._entries.values() if e.agent_id == agent_id]

list_by_tag(tag) async

Return all entries with a specific tag.

Source code in xyberos\agents\shared_memory.py

async def list_by_tag(self, tag: str) -> list[SharedEntry]:
    """Return all entries with a specific tag."""
    return [e for e in self._entries.values() if tag in e.tags]

retrieve(key) async

Retrieve an entry by key. Returns None if not found.

Source code in xyberos\agents\shared_memory.py

async def retrieve(self, key: str) -> SharedEntry | None:
    """Retrieve an entry by key. Returns ``None`` if not found."""
    entry = self._entries.get(key)
    if entry:
        self._entries.move_to_end(key)
    return entry

search(query, *, limit=10, agent_id=None, tags=None) async

Search entries by keyword matching against key, value, and tags.

Parameters

query: Keywords to search for. limit: Maximum results. agent_id: If set, only return entries from this agent. tags: If set, only return entries with at least one matching tag.

Returns

list[SharedEntry] Matching entries sorted by recency.

Source code in xyberos\agents\shared_memory.py

async def search(
    self,
    query: str,
    *,
    limit: int = 10,
    agent_id: str | None = None,
    tags: list[str] | None = None,
) -> list[SharedEntry]:
    """
    Search entries by keyword matching against key, value, and tags.

    Parameters
    ----------
    query:
        Keywords to search for.
    limit:
        Maximum results.
    agent_id:
        If set, only return entries from this agent.
    tags:
        If set, only return entries with at least one matching tag.

    Returns
    -------
    list[SharedEntry]
        Matching entries sorted by recency.
    """
    query_lower = query.lower()
    query_words = query_lower.split()
    results: list[SharedEntry] = []

    for entry in reversed(list(self._entries.values())):
        if agent_id and entry.agent_id != agent_id:
            continue
        if tags and not any(t in entry.tags for t in tags):
            continue

        # Match against key, value, and tags
        key_match = any(w in entry.key.lower() for w in query_words)
        value_match = any(w in str(entry.value).lower() for w in query_words)
        tag_match = any(w in " ".join(entry.tags).lower() for w in query_words)

        if key_match or value_match or tag_match:
            results.append(entry)
            if len(results) >= limit:
                break

    return results

store(key, value, agent_id='', *, tags=None, metadata=None) async

Store a value in shared memory.

If key already exists, it is overwritten and the timestamp is updated.

Source code in xyberos\agents\shared_memory.py

async def store(
    self,
    key: str,
    value: Any,
    agent_id: str = "",
    *,
    tags: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
) -> SharedEntry:
    """
    Store a value in shared memory.

    If *key* already exists, it is overwritten and the timestamp
    is updated.
    """
    self._evict_if_needed()
    entry = SharedEntry(
        key=key,
        value=value,
        agent_id=agent_id,
        timestamp=datetime.now(timezone.utc),
        tags=tags or [],
        metadata=metadata or {},
    )
    self._entries[key] = entry
    self._entries.move_to_end(key)
    logger.debug("SharedMemory: %s stored by %s", key, agent_id)

    # Notify watchers
    await self._notify_watchers(key, entry)
    return entry

watch(key_pattern, callback) async

Register a callback that fires when an entry matching key_pattern is stored or updated. The pattern supports simple * wildcard.

The callback receives (key, SharedEntry).

Source code in xyberos\agents\shared_memory.py

async def watch(self, key_pattern: str, callback: Callable[[str, SharedEntry], Awaitable[None]]) -> None:
    """
    Register a callback that fires when an entry matching *key_pattern*
    is stored or updated.  The pattern supports simple ``*`` wildcard.

    The callback receives ``(key, SharedEntry)``.
    """
    if key_pattern not in self._watch_callbacks:
        self._watch_callbacks[key_pattern] = []
    self._watch_callbacks[key_pattern].append(callback)

CollaborationEngine

Orchestrates collaborative intelligence among agents.

Provides voting, consensus-building, and knowledge-sharing primitives that agents can use to work together.

Usage::

engine = CollaborationEngine(shared_memory=memory)
result = await engine.conduct_vote(
    question="What approach should we take?",
    agents=[agent_a, agent_b, agent_c],
    options=["approach_a", "approach_b"],
)

Source code in xyberos\agents\collaboration.py

class CollaborationEngine:
    """
    Orchestrates collaborative intelligence among agents.

    Provides voting, consensus-building, and knowledge-sharing
    primitives that agents can use to work together.

    Usage::

        engine = CollaborationEngine(shared_memory=memory)
        result = await engine.conduct_vote(
            question="What approach should we take?",
            agents=[agent_a, agent_b, agent_c],
            options=["approach_a", "approach_b"],
        )
    """

    def __init__(self, shared_memory: SharedMemory) -> None:
        self._memory = shared_memory

    @property
    def memory(self) -> SharedMemory:
        """The shared memory instance used by all agents."""
        return self._memory

    # ── Voting ─────────────────────────────────────────────────

    async def conduct_vote(
        self,
        question: str,
        agents: list[Agent],
        options: list[str],
        *,
        timeout: float = 10.0,
        consensus_threshold: float = 0.6,
    ) -> VoteResult:
        """
        Conduct a vote among *agents* on a *question* with given *options*.

        Each agent is asked to choose an option and provide a confidence.
        The winner is the option with the highest weighted confidence sum.
        """
        votes: list[Vote] = []

        async def ask_agent(agent: Agent) -> None:
            try:
                reply = await agent.request(
                    "__coordinator__",
                    {
                        "type": "vote",
                        "question": question,
                        "options": options,
                    },
                    timeout=timeout,
                )
                if reply:
                    content = _as_dict(reply.content)
                    if content:
                        votes.append(Vote(
                            agent_id=agent.id,
                            choice=content.get("choice", options[0]),
                            confidence=float(content.get("confidence", 0.5)),
                            rationale=str(content.get("rationale", "")),
                        ))
            except Exception as exc:
                logger.warning("Agent '%s' failed to vote: %s", agent.id, exc)

        # Ask all agents in parallel
        await asyncio.gather(*[ask_agent(a) for a in agents])

        if not votes:
            return VoteResult(winner=options[0] if options else "", votes=[])

        # Weighted aggregation
        scores: dict[str, float] = {opt: 0.0 for opt in options}
        total_weight = 0.0
        for vote in votes:
            scores[vote.choice] = scores.get(vote.choice, 0.0) + vote.confidence
            total_weight += vote.confidence

        winner = max(scores, key=scores.__getitem__)
        max_score = scores[winner]
        # Consensus if winner's share of total weight >= threshold
        consensus = (max_score / total_weight) >= consensus_threshold if total_weight > 0 else False

        result = VoteResult(
            winner=winner,
            votes=votes,
            total_weight=total_weight,
            consensus=consensus,
        )

        # Store result in shared memory
        await self._memory.store(
            key=f"vote:{question[:50]}",
            value={
                "question": question,
                "winner": winner,
                "scores": scores,
                "consensus": consensus,
                "total_votes": len(votes),
            },
            agent_id="__coordinator__",
            tags=["vote", "decision"],
        )

        return result

    # ── Knowledge Sharing ──────────────────────────────────────

    async def share_knowledge(
        self,
        agent: Agent,
        topic: str,
        content: Any,
        *,
        tags: list[str] | None = None,
    ) -> None:
        """
        Share knowledge from *agent* on a *topic* to all other agents.

        The knowledge is stored in shared memory and a broadcast
        notification is sent to all agents.
        """
        key = f"knowledge:{topic}:{agent.id}"
        _ = await self._memory.store(
            key=key,
            value=content,
            agent_id=agent.id,
            tags=["knowledge"] + (tags or []),
        )

        await agent.broadcast({
            "type": "knowledge_shared",
            "topic": topic,
            "agent_id": agent.id,
            "key": key,
        }, msg_type="knowledge")

    async def query_knowledge(
        self,
        topic: str,
        *,
        limit: int = 10,
    ) -> list[Any]:
        """Query shared memory for knowledge on a *topic*."""
        entries = await self._memory.search(topic, limit=limit, tags=["knowledge"])
        return [e.value for e in entries]

    # ── Collective Problem Solving ─────────────────────────────

    async def solve_collectively(
        self,
        problem: str,
        coordinator: Agent,
        agents: list[Agent],
        *,
        sub_problems: list[str] | None = None,
        timeout: float = 15.0,
    ) -> dict[str, Any]:
        """
        Solve a problem collectively.

        1. Coordinator decomposes *problem* into *sub_problems*
        2. Each sub-problem is assigned to an agent (or the coordinator)
        3. Results are collected and merged
        4. Final answer stored in shared memory
        """
        if sub_problems is None:
            sub_problems = [f"{problem} — part {i+1}" for i in range(len(agents))]

        results: dict[str, Any] = {}

        async def solve_sub_problem(sub_problem: str, agent: Agent) -> None:
            try:
                reply = await coordinator.request(
                    agent.id,
                    {
                        "type": "sub_problem",
                        "problem": sub_problem,
                        "context": problem,
                    },
                    timeout=timeout,
                )
                if reply:
                    results[agent.id] = reply.content
                    # Store partial result in shared memory
                    await self._memory.store(
                        key=f"sub_problem:{sub_problem[:40]}:{agent.id}",
                        value=reply.content,
                        agent_id=agent.id,
                        tags=["sub_problem", "collective"],
                    )
            except Exception as exc:
                logger.warning("Agent '%s' failed sub-problem: %s", agent.id, exc)
                results[agent.id] = {"error": str(exc)}

        # Assign sub-problems to agents (round-robin if more sub-problems than agents)
        coros = [solve_sub_problem(sub, agents[i % len(agents)]) for i, sub in enumerate(sub_problems)]
        await asyncio.gather(*coros)

        # Merge results
        merged: dict[str, Any] = {
            "problem": problem,
            "sub_problems": sub_problems,
            "agent_results": results,
            "total_agents": len(agents),
            "successful": sum(1 for r in results.values() if isinstance(r, dict) and "error" not in r),
        }

        # Store final result in shared memory
        await self._memory.store(
            key=f"collective:{problem[:50]}",
            value=merged,
            agent_id=coordinator.id,
            tags=["collective", "solution"],
        )

        return merged

memory property

The shared memory instance used by all agents.

conduct_vote(question, agents, options, *, timeout=10.0, consensus_threshold=0.6) async

Conduct a vote among agents on a question with given options.

Each agent is asked to choose an option and provide a confidence. The winner is the option with the highest weighted confidence sum.

Source code in xyberos\agents\collaboration.py

async def conduct_vote(
    self,
    question: str,
    agents: list[Agent],
    options: list[str],
    *,
    timeout: float = 10.0,
    consensus_threshold: float = 0.6,
) -> VoteResult:
    """
    Conduct a vote among *agents* on a *question* with given *options*.

    Each agent is asked to choose an option and provide a confidence.
    The winner is the option with the highest weighted confidence sum.
    """
    votes: list[Vote] = []

    async def ask_agent(agent: Agent) -> None:
        try:
            reply = await agent.request(
                "__coordinator__",
                {
                    "type": "vote",
                    "question": question,
                    "options": options,
                },
                timeout=timeout,
            )
            if reply:
                content = _as_dict(reply.content)
                if content:
                    votes.append(Vote(
                        agent_id=agent.id,
                        choice=content.get("choice", options[0]),
                        confidence=float(content.get("confidence", 0.5)),
                        rationale=str(content.get("rationale", "")),
                    ))
        except Exception as exc:
            logger.warning("Agent '%s' failed to vote: %s", agent.id, exc)

    # Ask all agents in parallel
    await asyncio.gather(*[ask_agent(a) for a in agents])

    if not votes:
        return VoteResult(winner=options[0] if options else "", votes=[])

    # Weighted aggregation
    scores: dict[str, float] = {opt: 0.0 for opt in options}
    total_weight = 0.0
    for vote in votes:
        scores[vote.choice] = scores.get(vote.choice, 0.0) + vote.confidence
        total_weight += vote.confidence

    winner = max(scores, key=scores.__getitem__)
    max_score = scores[winner]
    # Consensus if winner's share of total weight >= threshold
    consensus = (max_score / total_weight) >= consensus_threshold if total_weight > 0 else False

    result = VoteResult(
        winner=winner,
        votes=votes,
        total_weight=total_weight,
        consensus=consensus,
    )

    # Store result in shared memory
    await self._memory.store(
        key=f"vote:{question[:50]}",
        value={
            "question": question,
            "winner": winner,
            "scores": scores,
            "consensus": consensus,
            "total_votes": len(votes),
        },
        agent_id="__coordinator__",
        tags=["vote", "decision"],
    )

    return result

query_knowledge(topic, *, limit=10) async

Query shared memory for knowledge on a topic.

Source code in xyberos\agents\collaboration.py

async def query_knowledge(
    self,
    topic: str,
    *,
    limit: int = 10,
) -> list[Any]:
    """Query shared memory for knowledge on a *topic*."""
    entries = await self._memory.search(topic, limit=limit, tags=["knowledge"])
    return [e.value for e in entries]

share_knowledge(agent, topic, content, *, tags=None) async

Share knowledge from agent on a topic to all other agents.

The knowledge is stored in shared memory and a broadcast notification is sent to all agents.

Source code in xyberos\agents\collaboration.py

async def share_knowledge(
    self,
    agent: Agent,
    topic: str,
    content: Any,
    *,
    tags: list[str] | None = None,
) -> None:
    """
    Share knowledge from *agent* on a *topic* to all other agents.

    The knowledge is stored in shared memory and a broadcast
    notification is sent to all agents.
    """
    key = f"knowledge:{topic}:{agent.id}"
    _ = await self._memory.store(
        key=key,
        value=content,
        agent_id=agent.id,
        tags=["knowledge"] + (tags or []),
    )

    await agent.broadcast({
        "type": "knowledge_shared",
        "topic": topic,
        "agent_id": agent.id,
        "key": key,
    }, msg_type="knowledge")

solve_collectively(problem, coordinator, agents, *, sub_problems=None, timeout=15.0) async

Solve a problem collectively.

1. Coordinator decomposes problem into sub_problems
2. Each sub-problem is assigned to an agent (or the coordinator)
3. Results are collected and merged
4. Final answer stored in shared memory

Source code in xyberos\agents\collaboration.py

async def solve_collectively(
    self,
    problem: str,
    coordinator: Agent,
    agents: list[Agent],
    *,
    sub_problems: list[str] | None = None,
    timeout: float = 15.0,
) -> dict[str, Any]:
    """
    Solve a problem collectively.

    1. Coordinator decomposes *problem* into *sub_problems*
    2. Each sub-problem is assigned to an agent (or the coordinator)
    3. Results are collected and merged
    4. Final answer stored in shared memory
    """
    if sub_problems is None:
        sub_problems = [f"{problem} — part {i+1}" for i in range(len(agents))]

    results: dict[str, Any] = {}

    async def solve_sub_problem(sub_problem: str, agent: Agent) -> None:
        try:
            reply = await coordinator.request(
                agent.id,
                {
                    "type": "sub_problem",
                    "problem": sub_problem,
                    "context": problem,
                },
                timeout=timeout,
            )
            if reply:
                results[agent.id] = reply.content
                # Store partial result in shared memory
                await self._memory.store(
                    key=f"sub_problem:{sub_problem[:40]}:{agent.id}",
                    value=reply.content,
                    agent_id=agent.id,
                    tags=["sub_problem", "collective"],
                )
        except Exception as exc:
            logger.warning("Agent '%s' failed sub-problem: %s", agent.id, exc)
            results[agent.id] = {"error": str(exc)}

    # Assign sub-problems to agents (round-robin if more sub-problems than agents)
    coros = [solve_sub_problem(sub, agents[i % len(agents)]) for i, sub in enumerate(sub_problems)]
    await asyncio.gather(*coros)

    # Merge results
    merged: dict[str, Any] = {
        "problem": problem,
        "sub_problems": sub_problems,
        "agent_results": results,
        "total_agents": len(agents),
        "successful": sum(1 for r in results.values() if isinstance(r, dict) and "error" not in r),
    }

    # Store final result in shared memory
    await self._memory.store(
        key=f"collective:{problem[:50]}",
        value=merged,
        agent_id=coordinator.id,
        tags=["collective", "solution"],
    )

    return merged

xyberos.ml — Machine learning

xyberos.ml

XYBEROS ML — Machine Learning module for training, optimization, evaluation, and pipeline orchestration.

Provides the ML interfaces consumed by :class:~xyberos.brain.learning.Learner and the :class:MLService that connects to the plugin system.

Entry-point group: xyberos.ml::

[project.entry-points."xyberos.ml"]
my_model = "my_package:MyModelPlugin"

MLService

Central orchestrator for ML capabilities.

Manages registries for trainers, evaluators, optimizers, and pipelines. When connected to a :class:PluginManager, the service registers the "ml" component kind so that plugins can contribute ML components.

Usage::

# Standalone
service = MLService()
service.register_trainer("classifier", MyTrainer())
report = service.evaluate("classifier", predictions=[...], ground_truth=[...])

# Plugin-managed
plugin_manager = PluginManager()
service = MLService(plugin_manager=plugin_manager)
await plugin_manager.load_all()  # discovers ML plugins

Source code in xyberos\ml\service.py

class MLService:
    """
    Central orchestrator for ML capabilities.

    Manages registries for trainers, evaluators, optimizers, and
    pipelines.  When connected to a :class:`PluginManager`, the
    service registers the ``"ml"`` component kind so that plugins
    can contribute ML components.

    Usage::

        # Standalone
        service = MLService()
        service.register_trainer("classifier", MyTrainer())
        report = service.evaluate("classifier", predictions=[...], ground_truth=[...])

        # Plugin-managed
        plugin_manager = PluginManager()
        service = MLService(plugin_manager=plugin_manager)
        await plugin_manager.load_all()  # discovers ML plugins
    """

    def __init__(
        self,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        self._trainers: RuntimeRegistry[Trainer] = RuntimeRegistry()
        self._evaluators: RuntimeRegistry[MLEvaluator] = RuntimeRegistry()
        self._optimizers: RuntimeRegistry[Optimizer] = RuntimeRegistry()
        self._pipelines: RuntimeRegistry[MLPipeline] = RuntimeRegistry()

        # Register defaults
        self._evaluators.register("default", DefaultMLEvaluator())

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("ml", self._pipelines)
            logger.info("MLService connected to PluginManager")

    # ── Trainer registry ────────────────────────────────────────

    @property
    def trainers(self) -> RuntimeRegistry[Trainer]:
        """Registry of registered trainers."""
        return self._trainers

    def register_trainer(self, name: str, trainer: Trainer) -> None:
        """Register a trainer by name."""
        self._trainers.register(name, trainer)
        logger.info("Registered trainer '%s' (%s)", name, type(trainer).__name__)

    def get_trainer(self, name: str) -> Trainer | None:
        """Look up a trainer by name."""
        return self._trainers.get(name)

    # ── Evaluator registry ──────────────────────────────────────

    @property
    def evaluators(self) -> RuntimeRegistry[MLEvaluator]:
        """Registry of registered evaluators."""
        return self._evaluators

    def register_evaluator(self, name: str, evaluator: MLEvaluator) -> None:
        """Register an evaluator by name."""
        self._evaluators.register(name, evaluator)
        logger.info("Registered evaluator '%s' (%s)", name, type(evaluator).__name__)

    def get_evaluator(self, name: str) -> MLEvaluator | None:
        """Look up an evaluator by name."""
        return self._evaluators.get(name)

    # ── Optimizer registry ──────────────────────────────────────

    @property
    def optimizers(self) -> RuntimeRegistry[Optimizer]:
        """Registry of registered optimizers."""
        return self._optimizers

    def register_optimizer(self, name: str, optimizer: Optimizer) -> None:
        """Register an optimizer by name."""
        self._optimizers.register(name, optimizer)
        logger.info("Registered optimizer '%s' (%s)", name, type(optimizer).__name__)

    def get_optimizer(self, name: str) -> Optimizer | None:
        """Look up an optimizer by name."""
        return self._optimizers.get(name)

    # ── Pipeline registry ───────────────────────────────────────

    @property
    def pipelines(self) -> RuntimeRegistry[MLPipeline]:
        """Registry of registered ML pipelines."""
        return self._pipelines

    def register_pipeline(self, name: str, pipeline: MLPipeline) -> None:
        """Register an ML pipeline by name."""
        self._pipelines.register(name, pipeline)
        logger.info("Registered pipeline '%s'", name)

    def get_pipeline(self, name: str) -> MLPipeline | None:
        """Look up an ML pipeline by name."""
        return self._pipelines.get(name)

    # ── Convenience methods ─────────────────────────────────────

    def evaluate(
        self,
        model_name: str,
        *,
        predictions: Sequence[Any],
        ground_truth: Sequence[Any],
        evaluator_name: str = "default",
        **metadata: Any,
    ) -> EvaluationReport:
        """
        Evaluate predictions against ground truth using a named evaluator.

        Parameters
        ----------
        model_name:
            Identifier for the model.
        predictions:
            Model output values.
        ground_truth:
            Expected target values.
        evaluator_name:
            Name of the registered evaluator to use (default ``"default"``).
        **metadata:
            Extra metadata for the report.

        Returns
        -------
        EvaluationReport
        """
        evaluator = self._evaluators.get(evaluator_name)
        if evaluator is None:
            raise KeyError(f"No evaluator registered under '{evaluator_name}'")
        return evaluator.evaluate(
            model_name=model_name,
            predictions=predictions,
            ground_truth=ground_truth,
            **metadata,
        )

    def run_pipeline(
        self,
        name: str,
        *,
        train_data: Sequence[Any],
        val_data: Sequence[Any] | None = None,
        **metadata: Any,
    ) -> PipelineResult:
        """
        Run a registered ML pipeline by name.

        Parameters
        ----------
        name:
            Pipeline name (as registered).
        train_data:
            Training dataset.
        val_data:
            Optional validation dataset.

        Returns
        -------
        PipelineResult
        """
        pipeline = self._pipelines.get(name)
        if pipeline is None:
            raise KeyError(f"No pipeline registered under '{name}'")
        return pipeline.run(
            train_data=train_data,
            val_data=val_data,
            **metadata,
        )

evaluators property

Registry of registered evaluators.

optimizers property

Registry of registered optimizers.

pipelines property

Registry of registered ML pipelines.

trainers property

Registry of registered trainers.

evaluate(model_name, *, predictions, ground_truth, evaluator_name='default', **metadata)

Evaluate predictions against ground truth using a named evaluator.

Parameters

model_name: Identifier for the model. predictions: Model output values. ground_truth: Expected target values. evaluator_name: Name of the registered evaluator to use (default "default"). **metadata: Extra metadata for the report.

Returns

EvaluationReport

Source code in xyberos\ml\service.py

def evaluate(
    self,
    model_name: str,
    *,
    predictions: Sequence[Any],
    ground_truth: Sequence[Any],
    evaluator_name: str = "default",
    **metadata: Any,
) -> EvaluationReport:
    """
    Evaluate predictions against ground truth using a named evaluator.

    Parameters
    ----------
    model_name:
        Identifier for the model.
    predictions:
        Model output values.
    ground_truth:
        Expected target values.
    evaluator_name:
        Name of the registered evaluator to use (default ``"default"``).
    **metadata:
        Extra metadata for the report.

    Returns
    -------
    EvaluationReport
    """
    evaluator = self._evaluators.get(evaluator_name)
    if evaluator is None:
        raise KeyError(f"No evaluator registered under '{evaluator_name}'")
    return evaluator.evaluate(
        model_name=model_name,
        predictions=predictions,
        ground_truth=ground_truth,
        **metadata,
    )

get_evaluator(name)

Look up an evaluator by name.

Source code in xyberos\ml\service.py

def get_evaluator(self, name: str) -> MLEvaluator | None:
    """Look up an evaluator by name."""
    return self._evaluators.get(name)

get_optimizer(name)

Look up an optimizer by name.

Source code in xyberos\ml\service.py

def get_optimizer(self, name: str) -> Optimizer | None:
    """Look up an optimizer by name."""
    return self._optimizers.get(name)

get_pipeline(name)

Look up an ML pipeline by name.

Source code in xyberos\ml\service.py

def get_pipeline(self, name: str) -> MLPipeline | None:
    """Look up an ML pipeline by name."""
    return self._pipelines.get(name)

get_trainer(name)

Look up a trainer by name.

Source code in xyberos\ml\service.py

def get_trainer(self, name: str) -> Trainer | None:
    """Look up a trainer by name."""
    return self._trainers.get(name)

register_evaluator(name, evaluator)

Register an evaluator by name.

Source code in xyberos\ml\service.py

def register_evaluator(self, name: str, evaluator: MLEvaluator) -> None:
    """Register an evaluator by name."""
    self._evaluators.register(name, evaluator)
    logger.info("Registered evaluator '%s' (%s)", name, type(evaluator).__name__)

register_optimizer(name, optimizer)

Register an optimizer by name.

Source code in xyberos\ml\service.py

def register_optimizer(self, name: str, optimizer: Optimizer) -> None:
    """Register an optimizer by name."""
    self._optimizers.register(name, optimizer)
    logger.info("Registered optimizer '%s' (%s)", name, type(optimizer).__name__)

register_pipeline(name, pipeline)

Register an ML pipeline by name.

Source code in xyberos\ml\service.py

def register_pipeline(self, name: str, pipeline: MLPipeline) -> None:
    """Register an ML pipeline by name."""
    self._pipelines.register(name, pipeline)
    logger.info("Registered pipeline '%s'", name)

register_trainer(name, trainer)

Register a trainer by name.

Source code in xyberos\ml\service.py

def register_trainer(self, name: str, trainer: Trainer) -> None:
    """Register a trainer by name."""
    self._trainers.register(name, trainer)
    logger.info("Registered trainer '%s' (%s)", name, type(trainer).__name__)

run_pipeline(name, *, train_data, val_data=None, **metadata)

Run a registered ML pipeline by name.

Parameters

name: Pipeline name (as registered). train_data: Training dataset. val_data: Optional validation dataset.

Returns

PipelineResult

Source code in xyberos\ml\service.py

def run_pipeline(
    self,
    name: str,
    *,
    train_data: Sequence[Any],
    val_data: Sequence[Any] | None = None,
    **metadata: Any,
) -> PipelineResult:
    """
    Run a registered ML pipeline by name.

    Parameters
    ----------
    name:
        Pipeline name (as registered).
    train_data:
        Training dataset.
    val_data:
        Optional validation dataset.

    Returns
    -------
    PipelineResult
    """
    pipeline = self._pipelines.get(name)
    if pipeline is None:
        raise KeyError(f"No pipeline registered under '{name}'")
    return pipeline.run(
        train_data=train_data,
        val_data=val_data,
        **metadata,
    )

MLPipeline

Composable ML pipeline that chains preprocessing → training → evaluation.

Usage::

pipeline = MLPipeline(
    name="text-classifier",
    trainer=MyTrainer(),
    evaluator=DefaultMLEvaluator(),
)
pipeline.add_step(TokenizerStep())
pipeline.add_step(FeatureExtractor())

result = pipeline.run(
    train_data=[...],
    val_data=[...],
)
print(result.evaluation.classification.accuracy)

Source code in xyberos\ml\pipeline.py

class MLPipeline:
    """
    Composable ML pipeline that chains preprocessing → training → evaluation.

    Usage::

        pipeline = MLPipeline(
            name="text-classifier",
            trainer=MyTrainer(),
            evaluator=DefaultMLEvaluator(),
        )
        pipeline.add_step(TokenizerStep())
        pipeline.add_step(FeatureExtractor())

        result = pipeline.run(
            train_data=[...],
            val_data=[...],
        )
        print(result.evaluation.classification.accuracy)
    """

    def __init__(
        self,
        name: str,
        trainer: Trainer,
        evaluator: MLEvaluator,
    ) -> None:
        self.name = name
        self._trainer = trainer
        self._evaluator = evaluator
        self._steps: list[PipelineStep[Any]] = []

    # ── Step composition ────────────────────────────────────────

    def add_step(self, step: PipelineStep[Any]) -> None:
        """Append a preprocessing or post-processing step."""
        self._steps.append(step)

    @property
    def steps(self) -> list[PipelineStep[Any]]:
        """Registered pipeline steps (read-only view)."""
        return list(self._steps)

    # ── Execution ───────────────────────────────────────────────

    def run(
        self,
        *,
        train_data: Sequence[Any],
        val_data: Sequence[Any] | None = None,
        **metadata: Any,
    ) -> PipelineResult:
        """
        Execute the full pipeline.

        Parameters
        ----------
        train_data:
            Training dataset.
        val_data:
            Optional validation dataset.  If provided, evaluation
            will use it; otherwise evaluation runs on training data.
        **metadata:
            Extra metadata attached to the result.

        Returns
        -------
        PipelineResult
            Outcome including evaluation report.
        """
        try:
            data: Any = train_data

            # 1. Preprocessing steps
            steps_completed = 0
            for step in self._steps:
                data = step.run(data)
                steps_completed += 1

            # 2. Train
            self._trainer.train(data)
            steps_completed += 1

            # 3. Evaluate
            eval_data = val_data if val_data is not None else train_data
            evaluation = self._evaluator.evaluate(
                model_name=self.name,
                predictions=eval_data,
                ground_truth=train_data,
                **metadata,
            )
            steps_completed += 1

            return PipelineResult(
                success=True,
                model_name=self.name,
                evaluation=evaluation,
                steps_completed=steps_completed,
                metadata=metadata,
            )

        except Exception as exc:
            return PipelineResult(
                success=False,
                model_name=self.name,
                error=str(exc),
                metadata=metadata,
            )

steps property

Registered pipeline steps (read-only view).

add_step(step)

Append a preprocessing or post-processing step.

Source code in xyberos\ml\pipeline.py

def add_step(self, step: PipelineStep[Any]) -> None:
    """Append a preprocessing or post-processing step."""
    self._steps.append(step)

run(*, train_data, val_data=None, **metadata)

Execute the full pipeline.

Parameters

train_data: Training dataset. val_data: Optional validation dataset. If provided, evaluation will use it; otherwise evaluation runs on training data. **metadata: Extra metadata attached to the result.

Returns

PipelineResult Outcome including evaluation report.

Source code in xyberos\ml\pipeline.py

def run(
    self,
    *,
    train_data: Sequence[Any],
    val_data: Sequence[Any] | None = None,
    **metadata: Any,
) -> PipelineResult:
    """
    Execute the full pipeline.

    Parameters
    ----------
    train_data:
        Training dataset.
    val_data:
        Optional validation dataset.  If provided, evaluation
        will use it; otherwise evaluation runs on training data.
    **metadata:
        Extra metadata attached to the result.

    Returns
    -------
    PipelineResult
        Outcome including evaluation report.
    """
    try:
        data: Any = train_data

        # 1. Preprocessing steps
        steps_completed = 0
        for step in self._steps:
            data = step.run(data)
            steps_completed += 1

        # 2. Train
        self._trainer.train(data)
        steps_completed += 1

        # 3. Evaluate
        eval_data = val_data if val_data is not None else train_data
        evaluation = self._evaluator.evaluate(
            model_name=self.name,
            predictions=eval_data,
            ground_truth=train_data,
            **metadata,
        )
        steps_completed += 1

        return PipelineResult(
            success=True,
            model_name=self.name,
            evaluation=evaluation,
            steps_completed=steps_completed,
            metadata=metadata,
        )

    except Exception as exc:
        return PipelineResult(
            success=False,
            model_name=self.name,
            error=str(exc),
            metadata=metadata,
        )

MLEvaluator

Bases: ABC

Evaluates ML model predictions against ground truth.

Subclasses implement :meth:evaluate to produce an :class:EvaluationReport with the relevant metrics.

Source code in xyberos\ml\evaluator.py

class MLEvaluator(ABC):
    """
    Evaluates ML model predictions against ground truth.

    Subclasses implement :meth:`evaluate` to produce an
    :class:`EvaluationReport` with the relevant metrics.
    """

    @abstractmethod
    def evaluate(
        self,
        *,
        model_name: str,
        predictions: Sequence[Any],
        ground_truth: Sequence[Any],
        **metadata: Any,
    ) -> EvaluationReport:
        """
        Evaluate predictions against ground truth.

        Parameters
        ----------
        model_name:
            Identifier for the model being evaluated.
        predictions:
            Model output values.
        ground_truth:
            Expected target values.
        **metadata:
            Extra metadata to attach to the report.

        Returns
        -------
        EvaluationReport
            Computed metrics and predictions.
        """

evaluate(*, model_name, predictions, ground_truth, **metadata) abstractmethod

Evaluate predictions against ground truth.

Parameters

model_name: Identifier for the model being evaluated. predictions: Model output values. ground_truth: Expected target values. **metadata: Extra metadata to attach to the report.

Returns

EvaluationReport Computed metrics and predictions.

Source code in xyberos\ml\evaluator.py

@abstractmethod
def evaluate(
    self,
    *,
    model_name: str,
    predictions: Sequence[Any],
    ground_truth: Sequence[Any],
    **metadata: Any,
) -> EvaluationReport:
    """
    Evaluate predictions against ground truth.

    Parameters
    ----------
    model_name:
        Identifier for the model being evaluated.
    predictions:
        Model output values.
    ground_truth:
        Expected target values.
    **metadata:
        Extra metadata to attach to the report.

    Returns
    -------
    EvaluationReport
        Computed metrics and predictions.
    """

DefaultMLEvaluator

Bases: MLEvaluator

Default evaluator that infers metric type from data.

• If ground_truth contains only {0, 1} or {True, False} → computes :class:ClassificationMetrics.
• If ground_truth contains int or float values beyond 0/1 → computes :class:RegressionMetrics.
• Otherwise → empty report.

Source code in xyberos\ml\evaluator.py

class DefaultMLEvaluator(MLEvaluator):
    """
    Default evaluator that infers metric type from data.

    - If ground_truth contains only ``{0, 1}`` or ``{True, False}`` →
      computes :class:`ClassificationMetrics`.
    - If ground_truth contains ``int`` or ``float`` values beyond 0/1 →
      computes :class:`RegressionMetrics`.
    - Otherwise → empty report.
    """

    def evaluate(
        self,
        *,
        model_name: str,
        predictions: Sequence[Any],
        ground_truth: Sequence[Any],
        **metadata: Any,
    ) -> EvaluationReport:
        preds = list(predictions)
        truth = list(ground_truth)
        support = min(len(preds), len(truth))

        if not support:
            return EvaluationReport(model_name=model_name, metadata=metadata)

        unique = {t for t in truth if isinstance(t, (int, float, bool))}

        if unique <= {0, 1, True, False}:
            cls = self._compute_classification(preds, truth, support)
            return EvaluationReport(
                model_name=model_name,
                classification=cls,
                predictions=preds,
                ground_truth=truth,
                metadata=metadata,
            )

        if all(isinstance(t, (int, float)) for t in truth):
            reg = self._compute_regression(preds, truth, support)
            return EvaluationReport(
                model_name=model_name,
                regression=reg,
                predictions=preds,
                ground_truth=truth,
                metadata=metadata,
            )

        return EvaluationReport(model_name=model_name, metadata=metadata)

    # ── Metric helpers ──────────────────────────────────────────

    @staticmethod
    def _compute_classification(
        preds: list[Any],
        truth: list[Any],
        support: int,
    ) -> ClassificationMetrics:
        correct = sum(
            1 for p, t in zip(preds[:support], truth[:support])
            if bool(p) == bool(t)
        )
        tp = sum(
            1 for p, t in zip(preds[:support], truth[:support])
            if bool(p) is True and bool(t) is True
        )
        fp = sum(
            1 for p, t in zip(preds[:support], truth[:support])
            if bool(p) is True and bool(t) is False
        )
        fn = sum(
            1 for p, t in zip(preds[:support], truth[:support])
            if bool(p) is False and bool(t) is True
        )

        accuracy = correct / support if support else 0.0
        precision = tp / (tp + fp) if (tp + fp) else 0.0
        recall = tp / (tp + fn) if (tp + fn) else 0.0
        f1 = (
            2 * precision * recall / (precision + recall)
            if (precision + recall) > 0
            else 0.0
        )

        return ClassificationMetrics(
            accuracy=round(accuracy, 4),
            precision=round(precision, 4),
            recall=round(recall, 4),
            f1_score=round(f1, 4),
            support=support,
        )

    @staticmethod
    def _compute_regression(
        preds: list[Any],
        truth: list[Any],
        support: int,
    ) -> RegressionMetrics:
        errors = [
            float(p) - float(t)
            for p, t in zip(preds[:support], truth[:support])
        ]
        n = support
        mae = sum(abs(e) for e in errors) / n if n else 0.0
        mse = sum(e * e for e in errors) / n if n else 0.0
        rmse = mse ** 0.5
        mean_truth = sum(float(t) for t in truth[:support]) / n if n else 0.0
        ss_res = sum(e * e for e in errors)
        ss_tot = sum(
            (float(t) - mean_truth) ** 2
            for t in truth[:support]
        )
        r2 = 1.0 - (ss_res / ss_tot) if ss_tot > 0 else 0.0

        return RegressionMetrics(
            mae=round(mae, 4),
            mse=round(mse, 4),
            rmse=round(rmse, 4),
            r2=round(r2, 4),
            support=n,
        )

ClassificationMetrics dataclass

Standard classification metrics.

Source code in xyberos\ml\evaluator.py

@dataclass(frozen=True)
class ClassificationMetrics:
    """Standard classification metrics."""

    accuracy: float = 0.0
    precision: float = 0.0
    recall: float = 0.0
    f1_score: float = 0.0
    support: int = 0

RegressionMetrics dataclass

Standard regression metrics.

Source code in xyberos\ml\evaluator.py

@dataclass(frozen=True)
class RegressionMetrics:
    """Standard regression metrics."""

    mae: float = 0.0      # Mean Absolute Error
    mse: float = 0.0      # Mean Squared Error
    rmse: float = 0.0     # Root Mean Squared Error
    r2: float = 0.0       # R-squared
    support: int = 0

EvaluationReport dataclass

Full evaluation report for a model.

Contains classification metrics, regression metrics (whichever is relevant), plus optional raw predictions and metadata.

Source code in xyberos\ml\evaluator.py

@dataclass
class EvaluationReport:
    """
    Full evaluation report for a model.

    Contains classification metrics, regression metrics (whichever is
    relevant), plus optional raw predictions and metadata.
    """

    model_name: str
    classification: ClassificationMetrics | None = None
    regression: RegressionMetrics | None = None
    predictions: list[Any] | None = None
    ground_truth: list[Any] | None = None
    metadata: dict[str, object] = field(default_factory=lambda: {})

Trainer

Bases: ABC

Base interface for training cognitive models.

Source code in xyberos\ml\trainer.py

class Trainer(ABC):
    """
    Base interface for training cognitive models.
    """

    @abstractmethod
    def train(
        self,
        experiences: Sequence[Experience],
    ) -> None:
        """
        Train using a collection of experiences.
        """
        raise NotImplementedError

train(experiences) abstractmethod

Train using a collection of experiences.

Source code in xyberos\ml\trainer.py

@abstractmethod
def train(
    self,
    experiences: Sequence[Experience],
) -> None:
    """
    Train using a collection of experiences.
    """
    raise NotImplementedError

Optimizer

Bases: ABC

Base interface for optimization strategies.

Optimizers improve cognitive components such as prompts, policies, models, or routing decisions based on accumulated experience.

Source code in xyberos\ml\optimizer.py

class Optimizer(ABC):
    """
    Base interface for optimization strategies.

    Optimizers improve cognitive components such as
    prompts, policies, models, or routing decisions
    based on accumulated experience.
    """

    @abstractmethod
    def optimize(
        self,
        experience: Experience,
    ) -> None:
        """
        Optimize the system using an experience.
        """
        raise NotImplementedError

optimize(experience) abstractmethod

Optimize the system using an experience.

Source code in xyberos\ml\optimizer.py

@abstractmethod
def optimize(
    self,
    experience: Experience,
) -> None:
    """
    Optimize the system using an experience.
    """
    raise NotImplementedError

xyberos.security — Security subsystem

xyberos.security

XYBEROS Security — first-class authentication, authorization, and safety subsystem.

Sub-modules

• providers — Pluggable backends (RBAC, OAuth, LDAP, …)
• guardian — Central decision engine (Guardian)
• risk — Action risk scoring (0–100)
• audit — Structured audit trail
• capability— Agent capability management
• policy — Rule-based policy evaluation
• approval — Human-in-the-loop approval workflow
• governor — Resource consumption limits

Usage::

from xyberos.security import SecurityService, Principal, Permission, Role
from xyberos.security.providers import DefaultSecurityProvider

svc = SecurityService(provider=DefaultSecurityProvider())
svc.authenticate(principal)
svc.authorize(principal, "files.read")

With Guardian::

from xyberos.security import SecurityService
from xyberos.security.guardian import GuardianEngine
from xyberos.security.risk import RiskEngine
from xyberos.security.audit import AuditService

svc = SecurityService(
    provider=DefaultSecurityProvider(),
    guardian=GuardianEngine(),
    risk=RiskEngine(),
    audit=AuditService(),
)
decision = svc.guard("tool:delete_file", principal)

SecurityService

Bases: ISecurityService

Unified security orchestrator.

Wraps a :class:SecurityProvider with evaluators, and optionally connects to the Guardian Engine, Risk Engine, Audit Service, and Capability Manager for richer decision-making.

Usage::

service = SecurityService(provider=DefaultSecurityProvider())
service.authenticate(principal)
service.authorize(principal, "files.read")

With Guardian integration::

service = SecurityService(
    provider=...,
    guardian=guardian_engine,
    audit=audit_service,
)
decision = service.guard(action="tool:delete_file", principal=principal)

Source code in xyberos\security\service.py

class SecurityService(ISecurityService):
    """
    Unified security orchestrator.

    Wraps a :class:`SecurityProvider` with evaluators, and optionally
    connects to the Guardian Engine, Risk Engine, Audit Service, and
    Capability Manager for richer decision-making.

    Usage::

        service = SecurityService(provider=DefaultSecurityProvider())
        service.authenticate(principal)
        service.authorize(principal, "files.read")

    With Guardian integration::

        service = SecurityService(
            provider=...,
            guardian=guardian_engine,
            audit=audit_service,
        )
        decision = service.guard(action="tool:delete_file", principal=principal)
    """

    def __init__(
        self,
        provider: SecurityProvider | None = None,
        *,
        guardian: GuardianEngine | None = None,
        audit: AuditService | None = None,
        capability: CapabilityManager | None = None,
        risk: RiskEngine | None = None,
    ) -> None:
        self._provider = provider
        self._guardian = guardian
        self._audit = audit
        self._capability = capability
        self._risk = risk

        self.permission_evaluator = PermissionEvaluator()
        self.policy_evaluator = PolicyEvaluator()

    # ── Provider access ─────────────────────────────────────────

    @property
    def provider(self) -> SecurityProvider | None:
        """The active security provider."""
        return self._provider

    @provider.setter
    def provider(self, p: SecurityProvider) -> None:
        self._provider = p

    # ── Sub-engine access ───────────────────────────────────────

    @property
    def guardian(self) -> GuardianEngine | None:
        return self._guardian

    @property
    def audit(self) -> AuditService | None:
        return self._audit

    @property
    def capability(self) -> CapabilityManager | None:
        return self._capability

    @property
    def risk(self) -> RiskEngine | None:
        return self._risk

    # ── Authentication ──────────────────────────────────────────

    def authenticate(self, principal: Principal) -> bool:
        if self._provider is None:
            logger.warning("No security provider configured — denying authentication")
            return False

        result = self._provider.authenticate(principal)

        if self._audit:
            self._audit.record(
                principal=principal,
                action="authenticate",
                decision="ALLOW" if result else "DENY",
                reason="provider decision",
            )

        return result

    # ── Authorization ───────────────────────────────────────────

    def authorize(self, principal: Principal, permission: str) -> bool:
        if self._provider is None:
            logger.warning("No security provider configured — denying authorization")
            return False

        result = self._provider.authorize(principal, permission)

        if self._audit:
            self._audit.record(
                principal=principal,
                action=f"authorize:{permission}",
                decision="ALLOW" if result else "DENY",
                reason="provider decision",
            )

        return result

    # ── Permission checks ───────────────────────────────────────

    def has_permission(self, principal: Principal, permission: str) -> bool:
        if self._provider is None:
            return False

        provider_result = self._provider.has_permission(principal, permission)
        return self.permission_evaluator.check(
            principal=principal,
            permission=permission,
            provider_check=provider_result,
        )

    def has_role(self, principal: Principal, role: str) -> bool:
        if self._provider is None:
            return False

        provider_result = self._provider.has_role(principal, role)
        return self.policy_evaluator.evaluate(
            principal=principal,
            role=role,
            provider_check=provider_result,
        )

    # ── Registration ────────────────────────────────────────────

    def register_permission(self, permission: Permission) -> None:
        if self._provider:
            self._provider.register_permission(permission)

    def unregister_permission(self, name: str) -> None:
        if self._provider:
            self._provider.unregister_permission(name)

    def register_role(self, role: Role) -> None:
        if self._provider:
            self._provider.register_role(role)

    def unregister_role(self, name: str) -> None:
        if self._provider:
            self._provider.unregister_role(name)

    def grant(self, role: str, permission: str) -> None:
        if self._provider:
            self._provider.grant(role, permission)

    def revoke(self, role: str, permission: str) -> None:
        if self._provider:
            self._provider.revoke(role, permission)

    # ── Guardian integration ────────────────────────────────────

    def guard(
        self,
        action: str,
        principal: Principal,
        *,
        resource: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> str:
        """
        Run the full Guardian decision pipeline.

        Returns one of ``ALLOW``, ``DENY``, ``APPROVE``, ``SANDBOX``,
        or ``ESCALATE``.

        Requires :attr:`guardian` to be configured.
        """
        if self._guardian is None:
            logger.warning("Guardian engine not configured — defaulting to DENY")
            return "DENY"

        from .models import SecurityContext

        meta: dict[str, Any] = metadata if metadata is not None else {}
        ctx = SecurityContext(principal=principal, metadata=meta)
        decision = self._guardian.evaluate(action=action, context=ctx, security=self)

        if self._audit:
            self._audit.record(
                principal=principal,
                action=action,
                decision=decision.value if hasattr(decision, "value") else str(decision),
                reason="GuardianEngine evaluation",
                metadata={
                    "resource": resource,
                    **(metadata or {}),
                },
            )

        return decision.value if hasattr(decision, "value") else str(decision)

provider property writable

The active security provider.

guard(action, principal, *, resource=None, metadata=None)

Run the full Guardian decision pipeline.

Returns one of ALLOW, DENY, APPROVE, SANDBOX, or ESCALATE.

Requires :attr:guardian to be configured.

Source code in xyberos\security\service.py

def guard(
    self,
    action: str,
    principal: Principal,
    *,
    resource: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> str:
    """
    Run the full Guardian decision pipeline.

    Returns one of ``ALLOW``, ``DENY``, ``APPROVE``, ``SANDBOX``,
    or ``ESCALATE``.

    Requires :attr:`guardian` to be configured.
    """
    if self._guardian is None:
        logger.warning("Guardian engine not configured — defaulting to DENY")
        return "DENY"

    from .models import SecurityContext

    meta: dict[str, Any] = metadata if metadata is not None else {}
    ctx = SecurityContext(principal=principal, metadata=meta)
    decision = self._guardian.evaluate(action=action, context=ctx, security=self)

    if self._audit:
        self._audit.record(
            principal=principal,
            action=action,
            decision=decision.value if hasattr(decision, "value") else str(decision),
            reason="GuardianEngine evaluation",
            metadata={
                "resource": resource,
                **(metadata or {}),
            },
        )

    return decision.value if hasattr(decision, "value") else str(decision)

ISecurityService

Bases: ABC

Public interface for the XYBEROS security subsystem.

Source code in xyberos\security\interface.py

class ISecurityService(ABC):
    """
    Public interface for the XYBEROS security subsystem.
    """

    @abstractmethod
    def authenticate(self, principal: Principal) -> bool:
        """Authenticate a principal."""

    @abstractmethod
    def authorize(self, principal: Principal, permission: str) -> bool:
        """Check whether a principal has a permission."""

    @abstractmethod
    def has_permission(self, principal: Principal, permission: str) -> bool:
        """Check whether a principal has a permission (delegated)."""

    @abstractmethod
    def has_role(self, principal: Principal, role: str) -> bool:
        """Check whether a principal has a role."""

    @abstractmethod
    def register_permission(self, permission: Permission) -> None:
        """Register a permission."""

    @abstractmethod
    def unregister_permission(self, name: str) -> None:
        """Remove a registered permission."""

    @abstractmethod
    def register_role(self, role: Role) -> None:
        """Register a new role."""

    @abstractmethod
    def unregister_role(self, name: str) -> None:
        """Remove a registered role."""

    @abstractmethod
    def grant(self, role: str, permission: str) -> None:
        """Grant a permission to a role."""

    @abstractmethod
    def revoke(self, role: str, permission: str) -> None:
        """Revoke a permission from a role."""

authenticate(principal) abstractmethod

Authenticate a principal.

Source code in xyberos\security\interface.py

@abstractmethod
def authenticate(self, principal: Principal) -> bool:
    """Authenticate a principal."""

authorize(principal, permission) abstractmethod

Check whether a principal has a permission.

Source code in xyberos\security\interface.py

@abstractmethod
def authorize(self, principal: Principal, permission: str) -> bool:
    """Check whether a principal has a permission."""

grant(role, permission) abstractmethod

Grant a permission to a role.

Source code in xyberos\security\interface.py

@abstractmethod
def grant(self, role: str, permission: str) -> None:
    """Grant a permission to a role."""

has_permission(principal, permission) abstractmethod

Check whether a principal has a permission (delegated).

Source code in xyberos\security\interface.py

@abstractmethod
def has_permission(self, principal: Principal, permission: str) -> bool:
    """Check whether a principal has a permission (delegated)."""

has_role(principal, role) abstractmethod

Check whether a principal has a role.

Source code in xyberos\security\interface.py

@abstractmethod
def has_role(self, principal: Principal, role: str) -> bool:
    """Check whether a principal has a role."""

register_permission(permission) abstractmethod

Register a permission.

Source code in xyberos\security\interface.py

@abstractmethod
def register_permission(self, permission: Permission) -> None:
    """Register a permission."""

register_role(role) abstractmethod

Register a new role.

Source code in xyberos\security\interface.py

@abstractmethod
def register_role(self, role: Role) -> None:
    """Register a new role."""

revoke(role, permission) abstractmethod

Revoke a permission from a role.

Source code in xyberos\security\interface.py

@abstractmethod
def revoke(self, role: str, permission: str) -> None:
    """Revoke a permission from a role."""

unregister_permission(name) abstractmethod

Remove a registered permission.

Source code in xyberos\security\interface.py

@abstractmethod
def unregister_permission(self, name: str) -> None:
    """Remove a registered permission."""

unregister_role(name) abstractmethod

Remove a registered role.

Source code in xyberos\security\interface.py

@abstractmethod
def unregister_role(self, name: str) -> None:
    """Remove a registered role."""

Principal dataclass

An authenticated identity (user, agent, service, …).

tenant_id scopes the principal to an organization. When empty, the principal is treated as a global/system principal.

Source code in xyberos\security\models.py

@dataclass(slots=True)
class Principal:
    """
    An authenticated identity (user, agent, service, …).

    *tenant_id* scopes the principal to an organization.  When empty,
    the principal is treated as a global/system principal.
    """

    id: str
    name: str
    type: PrincipalType = PrincipalType.USER
    roles: set[str] = field(default_factory=set[str])
    tenant_id: str = ""

PrincipalType

Bases: str, Enum

Types of principals recognized by the security system.

Source code in xyberos\security\models.py

class PrincipalType(str, Enum):
    """
    Types of principals recognized by the security system.
    """

    USER = "user"
    AGENT = "agent"
    SERVICE = "service"
    PLUGIN = "plugin"
    SESSION = "session"

Role dataclass

A security role — a named collection of permissions.

Source code in xyberos\security\models.py

@dataclass(slots=True)
class Role:
    """
    A security role — a named collection of permissions.
    """

    name: str
    permissions: set[Permission] = field(default_factory=set[Permission])

Permission dataclass

A single, immutable permission.

Source code in xyberos\security\models.py

@dataclass(slots=True, frozen=True)
class Permission:
    """
    A single, immutable permission.
    """

    name: str
    description: str = ""

SecurityContext dataclass

Security context for a single action or execution scope.

Carries the authenticated principal, optional tenant affiliation, plus arbitrary metadata (e.g. IP address, session id, request id).

Source code in xyberos\security\models.py

@dataclass(slots=True)
class SecurityContext:
    """
    Security context for a single action or execution scope.

    Carries the authenticated principal, optional tenant affiliation,
    plus arbitrary metadata (e.g. IP address, session id, request id).
    """

    principal: Principal
    metadata: dict[str, Any] = field(default_factory=dict[str, Any])

    @property
    def principal_id(self) -> str:
        return self.principal.id

    @property
    def principal_name(self) -> str:
        return self.principal.name

    @property
    def tenant_id(self) -> str:
        """Convenience — tenant from principal or metadata."""
        pid = self.principal.tenant_id
        if pid:
            return pid
        return str(self.metadata.get("tenant_id", ""))

tenant_id property

Convenience — tenant from principal or metadata.

PermissionEvaluator

Evaluates whether a principal has a specific permission.

Fires an optional on_check callback with structured context for metrics, tracing, or audit integration.

Source code in xyberos\security\evaluator.py

class PermissionEvaluator:
    """
    Evaluates whether a principal has a specific permission.

    Fires an optional *on_check* callback with structured context
    for metrics, tracing, or audit integration.
    """

    def __init__(self, on_check: Observer | None = None) -> None:
        self._on_check = on_check

    def check(
        self,
        principal: Principal,
        permission: str,
        provider_check: bool,
    ) -> bool:
        """
        Evaluate a permission check.

        Parameters
        ----------
        principal:
            The principal being checked.
        permission:
            The permission name to evaluate.
        provider_check:
            The result from the underlying SecurityProvider.

        Returns
        -------
        bool
            Whether the permission is granted.
        """
        if self._on_check:
            self._on_check("permission.check", {
                "principal_id": principal.id,
                "permission": permission,
                "granted": provider_check,
            })
        return provider_check

check(principal, permission, provider_check)

Evaluate a permission check.

Parameters

principal: The principal being checked. permission: The permission name to evaluate. provider_check: The result from the underlying SecurityProvider.

Returns

bool Whether the permission is granted.

Source code in xyberos\security\evaluator.py

def check(
    self,
    principal: Principal,
    permission: str,
    provider_check: bool,
) -> bool:
    """
    Evaluate a permission check.

    Parameters
    ----------
    principal:
        The principal being checked.
    permission:
        The permission name to evaluate.
    provider_check:
        The result from the underlying SecurityProvider.

    Returns
    -------
    bool
        Whether the permission is granted.
    """
    if self._on_check:
        self._on_check("permission.check", {
            "principal_id": principal.id,
            "permission": permission,
            "granted": provider_check,
        })
    return provider_check

PolicyEvaluator

Evaluates role-based policy membership.

Fires an optional on_evaluate callback for observability.

Source code in xyberos\security\evaluator.py

class PolicyEvaluator:
    """
    Evaluates role-based policy membership.

    Fires an optional *on_evaluate* callback for observability.
    """

    def __init__(self, on_evaluate: Observer | None = None) -> None:
        self._on_evaluate = on_evaluate

    def evaluate(
        self,
        principal: Principal,
        role: str,
        provider_check: bool,
    ) -> bool:
        """
        Evaluate a role-based policy.

        Parameters
        ----------
        principal:
            The principal being evaluated.
        role:
            The role name to evaluate.
        provider_check:
            The result from the underlying SecurityProvider.

        Returns
        -------
        bool
            Whether the policy allows access.
        """
        if self._on_evaluate:
            self._on_evaluate("policy.evaluate", {
                "principal_id": principal.id,
                "role": role,
                "allowed": provider_check,
            })
        return provider_check

evaluate(principal, role, provider_check)

Evaluate a role-based policy.

Parameters

principal: The principal being evaluated. role: The role name to evaluate. provider_check: The result from the underlying SecurityProvider.

Returns

bool Whether the policy allows access.

Source code in xyberos\security\evaluator.py

def evaluate(
    self,
    principal: Principal,
    role: str,
    provider_check: bool,
) -> bool:
    """
    Evaluate a role-based policy.

    Parameters
    ----------
    principal:
        The principal being evaluated.
    role:
        The role name to evaluate.
    provider_check:
        The result from the underlying SecurityProvider.

    Returns
    -------
    bool
        Whether the policy allows access.
    """
    if self._on_evaluate:
        self._on_evaluate("policy.evaluate", {
            "principal_id": principal.id,
            "role": role,
            "allowed": provider_check,
        })
    return provider_check

SecurityError

Bases: Exception

Base security exception.

Source code in xyberos\security\exceptions.py

class SecurityError(Exception):
    """Base security exception."""

AuthenticationError

Bases: SecurityError

Authentication failed.

Source code in xyberos\security\exceptions.py

class AuthenticationError(SecurityError):
    """Authentication failed."""

AuthorizationError

Bases: SecurityError

Authorization failed.

Source code in xyberos\security\exceptions.py

class AuthorizationError(SecurityError):
    """Authorization failed."""

RoleNotFound

Bases: SecurityError

Unknown role.

Source code in xyberos\security\exceptions.py

class RoleNotFound(SecurityError):
    """Unknown role."""

PermissionNotFound

Bases: SecurityError

Unknown permission.

Source code in xyberos\security\exceptions.py

class PermissionNotFound(SecurityError):
    """Unknown permission."""

xyberos.security.guardian — Guardian Engine

xyberos.security.guardian

Guardian Engine — central decision orchestrator.

GuardianEngine

Central decision engine for the security subsystem.

Every action flows here. The engine chains:

1. Authentication — is the principal known?
2. Capability — does the agent possess this action?
3. Permission — is the principal allowed?
4. Risk scoring — how dangerous is this action?
5. Policy check — what does policy say at this risk level?
6. Resource limits — within budget / rate limits?
7. Approval — does this need human sign-off?
8. Sandbox — should this be isolated?

Usage::

engine = GuardianEngine()
decision = engine.evaluate("tool:delete_file", context, security_service)

Source code in xyberos\security\guardian\engine.py

class GuardianEngine:
    """
    Central decision engine for the security subsystem.

    Every action flows here. The engine chains:

    1. Authentication  — is the principal known?
    2. Capability      — does the agent possess this action?
    3. Permission      — is the principal allowed?
    4. Risk scoring    — how dangerous is this action?
    5. Policy check    — what does policy say at this risk level?
    6. Resource limits — within budget / rate limits?
    7. Approval        — does this need human sign-off?
    8. Sandbox         — should this be isolated?

    Usage::

        engine = GuardianEngine()
        decision = engine.evaluate("tool:delete_file", context, security_service)
    """

    def evaluate(
        self,
        action: str,
        context: SecurityContext,
        security: SecurityService,
    ) -> Decision:
        """
        Run the full decision pipeline for *action*.

        Parameters
        ----------
        action:
            The action being evaluated (e.g. ``"tool:delete_file"``).
        context:
            Security context with the principal and metadata.
        security:
            The SecurityService for auth, capability, risk lookups.

        Returns
        -------
        Decision
        """
        principal = context.principal

        # 1. Authentication
        if not security.authenticate(principal):
            return Decision.DENY

        # 2. Capability check (if configured)
        if security.capability:
            # Extract agent id from metadata or principal id
            agent_id = context.metadata.get("agent_id", principal.id)
            if not security.capability.possesses(agent_id, action):
                return Decision.DENY

        # 3. Permission check
        if not security.authorize(principal, action):
            return Decision.DENY

        # 4. Risk scoring (if configured)
        risk_score = 0
        if security.risk:
            risk = security.risk.score(action, context)
            risk_score = risk.level

        # 5. Policy check / risk-based decisions
        if risk_score >= 90:
            return Decision.DENY
        if risk_score >= 70:
            return Decision.APPROVE
        if risk_score >= 40:
            return Decision.SANDBOX

        return Decision.ALLOW

evaluate(action, context, security)

Run the full decision pipeline for action.

Parameters

action: The action being evaluated (e.g. "tool:delete_file"). context: Security context with the principal and metadata. security: The SecurityService for auth, capability, risk lookups.

Returns

Decision

Source code in xyberos\security\guardian\engine.py

def evaluate(
    self,
    action: str,
    context: SecurityContext,
    security: SecurityService,
) -> Decision:
    """
    Run the full decision pipeline for *action*.

    Parameters
    ----------
    action:
        The action being evaluated (e.g. ``"tool:delete_file"``).
    context:
        Security context with the principal and metadata.
    security:
        The SecurityService for auth, capability, risk lookups.

    Returns
    -------
    Decision
    """
    principal = context.principal

    # 1. Authentication
    if not security.authenticate(principal):
        return Decision.DENY

    # 2. Capability check (if configured)
    if security.capability:
        # Extract agent id from metadata or principal id
        agent_id = context.metadata.get("agent_id", principal.id)
        if not security.capability.possesses(agent_id, action):
            return Decision.DENY

    # 3. Permission check
    if not security.authorize(principal, action):
        return Decision.DENY

    # 4. Risk scoring (if configured)
    risk_score = 0
    if security.risk:
        risk = security.risk.score(action, context)
        risk_score = risk.level

    # 5. Policy check / risk-based decisions
    if risk_score >= 90:
        return Decision.DENY
    if risk_score >= 70:
        return Decision.APPROVE
    if risk_score >= 40:
        return Decision.SANDBOX

    return Decision.ALLOW

Decision

Bases: str, Enum

Possible outcomes of a Guardian evaluation.

Source code in xyberos\security\guardian\engine.py

class Decision(str, Enum):
    """Possible outcomes of a Guardian evaluation."""

    ALLOW = "ALLOW"
    DENY = "DENY"
    APPROVE = "APPROVE"  # human-in-the-loop required
    SANDBOX = "SANDBOX"  # run in isolated environment
    ESCALATE = "ESCALATE"  # needs higher authority

xyberos.security.risk — Risk Engine

xyberos.security.risk

Risk Engine — scores actions on a 0–100 scale.

RiskEngine

Scores actions on a 0–100 risk scale.

Built-in baseline table covers common actions. Callers or plugins can extend the table via :meth:register_action_risk or provide a custom risk_table at construction.

Usage::

engine = RiskEngine()
score = engine.score("tool:delete_file", context)
if score.level > 70:
    ...  # require approval

Source code in xyberos\security\risk\engine.py

class RiskEngine:
    """
    Scores actions on a 0–100 risk scale.

    Built-in baseline table covers common actions.  Callers or plugins
    can extend the table via :meth:`register_action_risk` or provide
    a custom *risk_table* at construction.

    Usage::

        engine = RiskEngine()
        score = engine.score("tool:delete_file", context)
        if score.level > 70:
            ...  # require approval
    """

    # Default risk baseline — higher = more dangerous
    _DEFAULT_TABLE: dict[str, int] = {
        "tool:read_file": 5,
        "tool:web_search": 10,
        "tool:list_directory": 5,
        "tool:write_file": 35,
        "tool:append_file": 25,
        "tool:delete_file": 80,
        "tool:execute_shell": 95,
        "tool:install_package": 60,
        "tool:send_email": 30,
        "tool:http_request": 20,
        "tool:database_query": 25,
        "tool:database_write": 50,
        "tool:database_delete": 85,
        "skill:execute": 40,
        "agent:spawn": 45,
        "agent:terminate": 70,
        "system:shutdown": 100,
        "system:config_change": 55,
        "system:log_read": 5,
        "filesystem:delete": 80,
        "filesystem:chmod": 60,
        "network:open_port": 75,
        "identity:impersonate": 100,
    }

    def __init__(self, risk_table: dict[str, int] | None = None) -> None:
        self._table = dict(self._DEFAULT_TABLE)
        if risk_table:
            self._table.update(risk_table)

    # ── Public API ──────────────────────────────────────────────

    def score(self, action: str, context: SecurityContext | None = None) -> RiskScore:
        """
        Score an action.

        Parameters
        ----------
        action:
            The action identifier (e.g. ``"tool:delete_file"``).
        context:
            Optional security context for context-aware scoring.

        Returns
        -------
        RiskScore
        """
        base = self._table.get(action, 50)  # unknown actions default to medium risk
        factors: list[RiskFactor] = [
            RiskFactor(name="baseline", weight=base, reason=f"Built-in risk for '{action}'"),
        ]

        # Context-aware adjustments
        if context:
            self._apply_context_adjustments(action, context, base, factors)

        # Start from baseline, apply adjustments additively
        total = base
        for f in factors[1:]:  # skip the baseline factor itself
            total = max(0, min(100, total + f.weight))
        return RiskScore(level=total, factors=factors)

    def register_action_risk(self, action: str, level: int) -> None:
        """
        Register or override the baseline risk for an action.

        Parameters
        ----------
        action:
            Action identifier.
        level:
            Risk level (0–100).
        """
        self._table[action] = max(0, min(100, level))

    def get_action_risk(self, action: str) -> int:
        """Return the baseline risk for *action* (50 if unknown)."""
        return self._table.get(action, 50)

    # ── Internals ───────────────────────────────────────────────

    def _apply_context_adjustments(
        self,
        action: str,
        context: SecurityContext,
        base: int,
        factors: list[RiskFactor],
    ) -> None:
        """Apply context-aware modifiers (principal type, metadata, …)."""
        from ..models import PrincipalType

        # Agents get a slight discount on tool actions (they're expected)
        if context.principal.type == PrincipalType.AGENT and action.startswith("tool:"):
            discount = -5
            factors.append(RiskFactor(
                name="agent_discount", weight=discount,
                reason="Agent performing a tool action (expected behaviour)",
            ))

        # Session principals are ephemeral — slightly higher risk
        if context.principal.type == PrincipalType.SESSION:
            penalty = 10
            factors.append(RiskFactor(
                name="session_penalty", weight=penalty,
                reason="Ephemeral session principal",
            ))

get_action_risk(action)

Return the baseline risk for action (50 if unknown).

Source code in xyberos\security\risk\engine.py

def get_action_risk(self, action: str) -> int:
    """Return the baseline risk for *action* (50 if unknown)."""
    return self._table.get(action, 50)

register_action_risk(action, level)

Register or override the baseline risk for an action.

Parameters

action: Action identifier. level: Risk level (0–100).

Source code in xyberos\security\risk\engine.py

def register_action_risk(self, action: str, level: int) -> None:
    """
    Register or override the baseline risk for an action.

    Parameters
    ----------
    action:
        Action identifier.
    level:
        Risk level (0–100).
    """
    self._table[action] = max(0, min(100, level))

score(action, context=None)

Score an action.

Parameters

action: The action identifier (e.g. "tool:delete_file"). context: Optional security context for context-aware scoring.

Returns

RiskScore

Source code in xyberos\security\risk\engine.py

def score(self, action: str, context: SecurityContext | None = None) -> RiskScore:
    """
    Score an action.

    Parameters
    ----------
    action:
        The action identifier (e.g. ``"tool:delete_file"``).
    context:
        Optional security context for context-aware scoring.

    Returns
    -------
    RiskScore
    """
    base = self._table.get(action, 50)  # unknown actions default to medium risk
    factors: list[RiskFactor] = [
        RiskFactor(name="baseline", weight=base, reason=f"Built-in risk for '{action}'"),
    ]

    # Context-aware adjustments
    if context:
        self._apply_context_adjustments(action, context, base, factors)

    # Start from baseline, apply adjustments additively
    total = base
    for f in factors[1:]:  # skip the baseline factor itself
        total = max(0, min(100, total + f.weight))
    return RiskScore(level=total, factors=factors)

RiskScore dataclass

Result of a risk assessment.

Attributes

level: Overall risk level (0–100). factors: Contributing factors with individual weights and reasons.

Source code in xyberos\security\risk\engine.py

@dataclass(slots=True)
class RiskScore:
    """
    Result of a risk assessment.

    Attributes
    ----------
    level:
        Overall risk level (0–100).
    factors:
        Contributing factors with individual weights and reasons.
    """

    level: int = 0
    factors: list[RiskFactor] = field(default_factory=lambda: [])

RiskFactor dataclass

A single contributing factor to a risk score.

Source code in xyberos\security\risk\engine.py

@dataclass(slots=True)
class RiskFactor:
    """A single contributing factor to a risk score."""

    name: str
    weight: int
    reason: str

xyberos.security.audit — Audit Service

xyberos.security.audit

Audit Service — structured, queryable audit trail.

AuditService

Structured audit trail for security decisions.

Stores entries in-memory by default. Callers can subscribe via on_record for persistence, streaming, or external sinks.

Usage::

audit = AuditService()
audit.record(principal=alice, action="tool:delete_file", decision="DENY", reason="Risk 92")
recent = audit.query(limit=10)

Source code in xyberos\security\audit\service.py

class AuditService:
    """
    Structured audit trail for security decisions.

    Stores entries in-memory by default.  Callers can subscribe via
    *on_record* for persistence, streaming, or external sinks.

    Usage::

        audit = AuditService()
        audit.record(principal=alice, action="tool:delete_file", decision="DENY", reason="Risk 92")
        recent = audit.query(limit=10)
    """

    def __init__(self, on_record: Any = None) -> None:
        self._entries: list[AuditEntry] = []
        self._counter = 0
        self._on_record = on_record  # optional callback (entry) → None

    # ── Recording ───────────────────────────────────────────────

    def record(
        self,
        principal: Principal,
        action: str,
        decision: str,
        reason: str,
        *,
        risk_level: int = 0,
        policies: list[str] | None = None,
        duration_ms: float = 0.0,
        result: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> AuditEntry:
        """
        Record a security decision in the audit trail.

        Parameters
        ----------
        principal:
            The principal who performed (or attempted) the action.
        action:
            The action identifier.
        decision:
            The decision outcome.
        reason:
            Why the decision was made.
        risk_level:
            Risk score at the time of decision.
        policies:
            Policy identifiers that matched.
        duration_ms:
            How long evaluation took.
        result:
            What actually happened after the decision.
        metadata:
            Additional structured context.

        Returns
        -------
        AuditEntry
            The newly created entry.
        """
        self._counter += 1
        entry = AuditEntry(
            id=f"audit-{self._counter}",
            timestamp=datetime.now(timezone.utc),
            principal=principal.id,
            principal_name=principal.name,
            action=action,
            decision=decision,
            reason=reason,
            risk_level=risk_level,
            policies=policies or [],
            duration_ms=duration_ms,
            result=result,
            metadata=metadata or {},
        )
        self._entries.append(entry)

        if self._on_record:
            self._on_record(entry)

        return entry

    # ── Queries ─────────────────────────────────────────────────

    def query(
        self,
        *,
        limit: int = 50,
        offset: int = 0,
        principal_id: str | None = None,
        action: str | None = None,
        decision: str | None = None,
        min_risk: int = 0,
    ) -> list[AuditEntry]:
        """
        Query the audit trail with optional filters.

        Returns entries sorted newest-first.
        """
        results = list(reversed(self._entries))

        if principal_id:
            results = [e for e in results if e.principal == principal_id]
        if action:
            results = [e for e in results if e.action == action]
        if decision:
            results = [e for e in results if e.decision == decision]
        if min_risk > 0:
            results = [e for e in results if e.risk_level >= min_risk]

        return results[offset:offset + limit]

    def count(self) -> int:
        """Total number of audit entries recorded."""
        return len(self._entries)

    def clear(self) -> None:
        """Clear all audit entries."""
        self._entries.clear()
        self._counter = 0

clear()

Clear all audit entries.

Source code in xyberos\security\audit\service.py

def clear(self) -> None:
    """Clear all audit entries."""
    self._entries.clear()
    self._counter = 0

count()

Total number of audit entries recorded.

Source code in xyberos\security\audit\service.py

def count(self) -> int:
    """Total number of audit entries recorded."""
    return len(self._entries)

query(*, limit=50, offset=0, principal_id=None, action=None, decision=None, min_risk=0)

Query the audit trail with optional filters.

Returns entries sorted newest-first.

Source code in xyberos\security\audit\service.py

def query(
    self,
    *,
    limit: int = 50,
    offset: int = 0,
    principal_id: str | None = None,
    action: str | None = None,
    decision: str | None = None,
    min_risk: int = 0,
) -> list[AuditEntry]:
    """
    Query the audit trail with optional filters.

    Returns entries sorted newest-first.
    """
    results = list(reversed(self._entries))

    if principal_id:
        results = [e for e in results if e.principal == principal_id]
    if action:
        results = [e for e in results if e.action == action]
    if decision:
        results = [e for e in results if e.decision == decision]
    if min_risk > 0:
        results = [e for e in results if e.risk_level >= min_risk]

    return results[offset:offset + limit]

record(principal, action, decision, reason, *, risk_level=0, policies=None, duration_ms=0.0, result=None, metadata=None)

Record a security decision in the audit trail.

Parameters

principal: The principal who performed (or attempted) the action. action: The action identifier. decision: The decision outcome. reason: Why the decision was made. risk_level: Risk score at the time of decision. policies: Policy identifiers that matched. duration_ms: How long evaluation took. result: What actually happened after the decision. metadata: Additional structured context.

Returns

AuditEntry The newly created entry.

Source code in xyberos\security\audit\service.py

def record(
    self,
    principal: Principal,
    action: str,
    decision: str,
    reason: str,
    *,
    risk_level: int = 0,
    policies: list[str] | None = None,
    duration_ms: float = 0.0,
    result: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> AuditEntry:
    """
    Record a security decision in the audit trail.

    Parameters
    ----------
    principal:
        The principal who performed (or attempted) the action.
    action:
        The action identifier.
    decision:
        The decision outcome.
    reason:
        Why the decision was made.
    risk_level:
        Risk score at the time of decision.
    policies:
        Policy identifiers that matched.
    duration_ms:
        How long evaluation took.
    result:
        What actually happened after the decision.
    metadata:
        Additional structured context.

    Returns
    -------
    AuditEntry
        The newly created entry.
    """
    self._counter += 1
    entry = AuditEntry(
        id=f"audit-{self._counter}",
        timestamp=datetime.now(timezone.utc),
        principal=principal.id,
        principal_name=principal.name,
        action=action,
        decision=decision,
        reason=reason,
        risk_level=risk_level,
        policies=policies or [],
        duration_ms=duration_ms,
        result=result,
        metadata=metadata or {},
    )
    self._entries.append(entry)

    if self._on_record:
        self._on_record(entry)

    return entry

AuditEntry dataclass

A single audit record.

Captures the full context of a security decision so that every action is fully explainable post-hoc.

Source code in xyberos\security\audit\models.py

@dataclass(slots=True)
class AuditEntry:
    """
    A single audit record.

    Captures the full context of a security decision so that
    every action is fully explainable post-hoc.
    """

    id: str
    timestamp: datetime
    principal: str  # principal.id for quick filtering
    principal_name: str
    action: str
    decision: str  # ALLOW | DENY | APPROVE | SANDBOX | ESCALATE
    reason: str
    risk_level: int = 0
    policies: list[str] = field(default_factory=lambda: [])
    duration_ms: float = 0.0
    result: str | None = None
    metadata: dict[str, Any] = field(default_factory=lambda: {})

xyberos.security.capability — Capability Manager

xyberos.security.capability

Capability Manager — what an agent can do vs. what it's allowed to do.

CapabilityManager

Manages agent→capability mappings.

Usage::

manager = CapabilityManager()
manager.register("weather-agent", "web.search")
manager.register("weather-agent", "forecast")
assert manager.possesses("weather-agent", "web.search")  # True
assert manager.possesses("weather-agent", "execute_shell")  # False

Source code in xyberos\security\capability\manager.py

class CapabilityManager:
    """
    Manages agent→capability mappings.

    Usage::

        manager = CapabilityManager()
        manager.register("weather-agent", "web.search")
        manager.register("weather-agent", "forecast")
        assert manager.possesses("weather-agent", "web.search")  # True
        assert manager.possesses("weather-agent", "execute_shell")  # False
    """

    def __init__(self) -> None:
        self._registry: dict[str, set[str]] = {}

    def register(self, agent_id: str, capability: str) -> None:
        self._registry.setdefault(agent_id, set()).add(capability)

    def register_many(self, agent_id: str, capabilities: list[str]) -> None:
        self._registry.setdefault(agent_id, set()).update(capabilities)

    def unregister(self, agent_id: str, capability: str) -> None:
        caps = self._registry.get(agent_id)
        if caps:
            caps.discard(capability)

    def unregister_all(self, agent_id: str) -> None:
        self._registry.pop(agent_id, None)

    def possesses(self, agent_id: str, capability: str) -> bool:
        caps = self._registry.get(agent_id)
        return caps is not None and capability in caps

    def capabilities(self, agent_id: str) -> set[str]:
        return set(self._registry.get(agent_id, set()))

    def agents_with_capability(self, capability: str) -> list[str]:
        return [aid for aid, caps in self._registry.items() if capability in caps]

    def all_agents(self) -> list[str]:
        return list(self._registry.keys())

Capability dataclass

A named capability an agent can possess.

Source code in xyberos\security\capability\models.py

@dataclass(slots=True)
class Capability:
    """A named capability an agent can possess."""

    name: str
    description: str = ""

xyberos.security.policy — Policy Engine

xyberos.security.policy

Policy Engine — rule evaluation for security decisions.

Policies are composed of rules that map actions + conditions to effects.

PolicyEngine

Evaluates actions against a set of policies.

Rules are sorted by priority (descending). The first matching rule determines the result. If no rule matches, the default effect is DENY.

Usage::

engine = PolicyEngine()
engine.add_rule(PolicyRule(
    effect=PolicyEffect.ALLOW,
    action_pattern="tool:read_file",
    role="developer",
))
result = engine.evaluate("tool:read_file", context)

Source code in xyberos\security\policy\engine.py

class PolicyEngine:
    """
    Evaluates actions against a set of policies.

    Rules are sorted by priority (descending).  The first matching
    rule determines the result.  If no rule matches, the default
    effect is **DENY**.

    Usage::

        engine = PolicyEngine()
        engine.add_rule(PolicyRule(
            effect=PolicyEffect.ALLOW,
            action_pattern="tool:read_file",
            role="developer",
        ))
        result = engine.evaluate("tool:read_file", context)
    """

    def __init__(self) -> None:
        self._policies: dict[str, Policy] = {}

    # ── Policy management ───────────────────────────────────────

    def add_policy(self, policy: Policy) -> None:
        """Add or replace a policy by name."""
        self._policies[policy.name] = policy

    def add_rule(self, rule: PolicyRule, policy_name: str = "default") -> None:
        """Add a rule to a policy, creating the policy if needed."""
        if policy_name not in self._policies:
            self._policies[policy_name] = Policy(name=policy_name)
        self._policies[policy_name].rules.append(rule)

    def remove_policy(self, name: str) -> None:
        """Remove a policy by name."""
        self._policies.pop(name, None)

    def clear(self) -> None:
        """Remove all policies."""
        self._policies.clear()

    # ── Evaluation ──────────────────────────────────────────────

    def evaluate(
        self,
        action: str,
        context: SecurityContext | None = None,
        risk_level: int = 0,
    ) -> PolicyResult:
        """
        Evaluate *action* against all policies.

        Returns the first matching rule's effect, or **DENY** if no
        rule matches.
        """
        # Collect all rules sorted by priority descending
        all_rules: list[tuple[PolicyRule, str]] = []
        for pname, policy in self._policies.items():
            for rule in policy.rules:
                all_rules.append((rule, pname))

        all_rules.sort(key=lambda x: x[0].priority, reverse=True)

        for rule, pname in all_rules:
            if self._matches(rule, action, context, risk_level):
                return PolicyResult(
                    effect=rule.effect,
                    matched_rule=rule,
                    policy_name=pname,
                )

        return PolicyResult(effect=PolicyEffect.DENY)

    # ── Matching logic ──────────────────────────────────────────

    def _matches(
        self,
        rule: PolicyRule,
        action: str,
        context: SecurityContext | None,
        risk_level: int,
    ) -> bool:
        """Check whether *rule* matches the given action and context."""
        # Action pattern
        if not fnmatch(action, rule.action_pattern):
            return False

        # Risk bounds
        if risk_level < rule.min_risk or risk_level > rule.max_risk:
            return False

        # Role check
        if rule.role and context:
            roles = getattr(context.principal, "roles", None) or set()
            if rule.role not in roles:
                return False

        return True

add_policy(policy)

Add or replace a policy by name.

Source code in xyberos\security\policy\engine.py

def add_policy(self, policy: Policy) -> None:
    """Add or replace a policy by name."""
    self._policies[policy.name] = policy

add_rule(rule, policy_name='default')

Add a rule to a policy, creating the policy if needed.

Source code in xyberos\security\policy\engine.py

def add_rule(self, rule: PolicyRule, policy_name: str = "default") -> None:
    """Add a rule to a policy, creating the policy if needed."""
    if policy_name not in self._policies:
        self._policies[policy_name] = Policy(name=policy_name)
    self._policies[policy_name].rules.append(rule)

clear()

Remove all policies.

Source code in xyberos\security\policy\engine.py

def clear(self) -> None:
    """Remove all policies."""
    self._policies.clear()

evaluate(action, context=None, risk_level=0)

Evaluate action against all policies.

Returns the first matching rule's effect, or DENY if no rule matches.

Source code in xyberos\security\policy\engine.py

def evaluate(
    self,
    action: str,
    context: SecurityContext | None = None,
    risk_level: int = 0,
) -> PolicyResult:
    """
    Evaluate *action* against all policies.

    Returns the first matching rule's effect, or **DENY** if no
    rule matches.
    """
    # Collect all rules sorted by priority descending
    all_rules: list[tuple[PolicyRule, str]] = []
    for pname, policy in self._policies.items():
        for rule in policy.rules:
            all_rules.append((rule, pname))

    all_rules.sort(key=lambda x: x[0].priority, reverse=True)

    for rule, pname in all_rules:
        if self._matches(rule, action, context, risk_level):
            return PolicyResult(
                effect=rule.effect,
                matched_rule=rule,
                policy_name=pname,
            )

    return PolicyResult(effect=PolicyEffect.DENY)

remove_policy(name)

Remove a policy by name.

Source code in xyberos\security\policy\engine.py

def remove_policy(self, name: str) -> None:
    """Remove a policy by name."""
    self._policies.pop(name, None)

Policy dataclass

A named collection of policy rules.

Source code in xyberos\security\policy\engine.py

@dataclass(slots=True)
class Policy:
    """
    A named collection of policy rules.
    """

    name: str
    rules: list[PolicyRule] = field(default_factory=lambda: [])
    description: str = ""

PolicyRule dataclass

A single policy rule.

Parameters

effect: What to do when this rule matches. action_pattern: Glob-style action pattern (e.g. "tool:*", "tool:read_file"). role: Optional — only applies to principals with this role. min_risk: Optional — only applies when risk >= this threshold. max_risk: Optional — only applies when risk <= this threshold. priority: Higher priority rules are evaluated first (default 0).

Source code in xyberos\security\policy\engine.py

@dataclass(slots=True)
class PolicyRule:
    """
    A single policy rule.

    Parameters
    ----------
    effect:
        What to do when this rule matches.
    action_pattern:
        Glob-style action pattern (e.g. ``"tool:*"``, ``"tool:read_file"``).
    role:
        Optional — only applies to principals with this role.
    min_risk:
        Optional — only applies when risk >= this threshold.
    max_risk:
        Optional — only applies when risk <= this threshold.
    priority:
        Higher priority rules are evaluated first (default 0).
    """

    effect: PolicyEffect
    action_pattern: str = "*"
    role: str | None = None
    min_risk: int = 0
    max_risk: int = 100
    priority: int = 0
    description: str = ""

PolicyEffect

Bases: str, Enum

The outcome when a policy rule matches.

Source code in xyberos\security\policy\engine.py

class PolicyEffect(str, Enum):
    """The outcome when a policy rule matches."""

    ALLOW = "ALLOW"
    DENY = "DENY"
    APPROVE = "APPROVE"
    SANDBOX = "SANDBOX"
    ESCALATE = "ESCALATE"

PolicyResult dataclass

The result of evaluating a set of policies.

Source code in xyberos\security\policy\engine.py

@dataclass(slots=True)
class PolicyResult:
    """
    The result of evaluating a set of policies.
    """

    effect: PolicyEffect
    matched_rule: PolicyRule | None = None
    policy_name: str = ""

xyberos.security.approval — Approval Engine

xyberos.security.approval

Approval Engine — human-in-the-loop for high-risk actions.

ApprovalEngine

Manages human-in-the-loop approval workflows.

High-risk actions can require explicit approval before execution. The engine tracks pending requests and resolves them.

Usage::

engine = ApprovalEngine()
req = engine.request(principal, "tool:delete_file", risk_level=85)
# … external UI prompts human …
engine.approve(req.id, "admin-user")
# or
engine.deny(req.id, "admin-user")

Source code in xyberos\security\approval\engine.py

class ApprovalEngine:
    """
    Manages human-in-the-loop approval workflows.

    High-risk actions can require explicit approval before execution.
    The engine tracks pending requests and resolves them.

    Usage::

        engine = ApprovalEngine()
        req = engine.request(principal, "tool:delete_file", risk_level=85)
        # … external UI prompts human …
        engine.approve(req.id, "admin-user")
        # or
        engine.deny(req.id, "admin-user")
    """

    def __init__(self) -> None:
        self._requests: dict[str, ApprovalRequest] = {}
        self._counter = 0

    # ── Request lifecycle ───────────────────────────────────────

    def request(
        self,
        principal: Principal,
        action: str,
        *,
        reason: str = "",
        risk_level: int = 0,
        metadata: dict[str, Any] | None = None,
    ) -> ApprovalRequest:
        """
        Create a new approval request.

        Returns the pending request so callers can display or
        forward it to the appropriate approver.
        """
        self._counter += 1
        req = ApprovalRequest(
            id=f"approval-{self._counter}",
            principal_id=principal.id,
            action=action,
            reason=reason or f"Approval required for '{action}' (risk {risk_level})",
            risk_level=risk_level,
            metadata=metadata or {},
        )
        self._requests[req.id] = req
        return req

    def approve(self, request_id: str, approver: str) -> ApprovalRequest:
        """Approve a pending request."""
        req = self._get(request_id)
        req.status = "approved"
        req.resolved_at = datetime.now(timezone.utc)
        req.resolved_by = approver
        return req

    def deny(self, request_id: str, approver: str) -> ApprovalRequest:
        """Deny a pending request."""
        req = self._get(request_id)
        req.status = "denied"
        req.resolved_at = datetime.now(timezone.utc)
        req.resolved_by = approver
        return req

    # ── Queries ─────────────────────────────────────────────────

    def get(self, request_id: str) -> ApprovalRequest | None:
        """Look up an approval request by ID."""
        return self._requests.get(request_id)

    def pending(self) -> list[ApprovalRequest]:
        """Return all pending approval requests."""
        return [r for r in self._requests.values() if r.status == "pending"]

    def is_pending(self, request_id: str) -> bool:
        """Check whether a request is still pending."""
        req = self._requests.get(request_id)
        return req is not None and req.status == "pending"

    def is_approved(self, request_id: str) -> bool:
        """Check whether a request has been approved."""
        req = self._requests.get(request_id)
        return req is not None and req.status == "approved"

    # ── Internals ───────────────────────────────────────────────

    def _get(self, request_id: str) -> ApprovalRequest:
        if request_id not in self._requests:
            raise KeyError(f"Unknown approval request: {request_id}")
        return self._requests[request_id]

approve(request_id, approver)

Approve a pending request.

Source code in xyberos\security\approval\engine.py

def approve(self, request_id: str, approver: str) -> ApprovalRequest:
    """Approve a pending request."""
    req = self._get(request_id)
    req.status = "approved"
    req.resolved_at = datetime.now(timezone.utc)
    req.resolved_by = approver
    return req

deny(request_id, approver)

Deny a pending request.

Source code in xyberos\security\approval\engine.py

def deny(self, request_id: str, approver: str) -> ApprovalRequest:
    """Deny a pending request."""
    req = self._get(request_id)
    req.status = "denied"
    req.resolved_at = datetime.now(timezone.utc)
    req.resolved_by = approver
    return req

get(request_id)

Look up an approval request by ID.

Source code in xyberos\security\approval\engine.py

def get(self, request_id: str) -> ApprovalRequest | None:
    """Look up an approval request by ID."""
    return self._requests.get(request_id)

is_approved(request_id)

Check whether a request has been approved.

Source code in xyberos\security\approval\engine.py

def is_approved(self, request_id: str) -> bool:
    """Check whether a request has been approved."""
    req = self._requests.get(request_id)
    return req is not None and req.status == "approved"

is_pending(request_id)

Check whether a request is still pending.

Source code in xyberos\security\approval\engine.py

def is_pending(self, request_id: str) -> bool:
    """Check whether a request is still pending."""
    req = self._requests.get(request_id)
    return req is not None and req.status == "pending"

pending()

Return all pending approval requests.

Source code in xyberos\security\approval\engine.py

def pending(self) -> list[ApprovalRequest]:
    """Return all pending approval requests."""
    return [r for r in self._requests.values() if r.status == "pending"]

request(principal, action, *, reason='', risk_level=0, metadata=None)

Create a new approval request.

Returns the pending request so callers can display or forward it to the appropriate approver.

Source code in xyberos\security\approval\engine.py

def request(
    self,
    principal: Principal,
    action: str,
    *,
    reason: str = "",
    risk_level: int = 0,
    metadata: dict[str, Any] | None = None,
) -> ApprovalRequest:
    """
    Create a new approval request.

    Returns the pending request so callers can display or
    forward it to the appropriate approver.
    """
    self._counter += 1
    req = ApprovalRequest(
        id=f"approval-{self._counter}",
        principal_id=principal.id,
        action=action,
        reason=reason or f"Approval required for '{action}' (risk {risk_level})",
        risk_level=risk_level,
        metadata=metadata or {},
    )
    self._requests[req.id] = req
    return req

ApprovalRequest dataclass

A pending approval request.

Source code in xyberos\security\approval\engine.py

@dataclass(slots=True)
class ApprovalRequest:
    """
    A pending approval request.
    """

    id: str
    principal_id: str
    action: str
    reason: str
    risk_level: int
    status: str = "pending"  # pending | approved | denied | expired
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    resolved_at: datetime | None = None
    resolved_by: str | None = None
    metadata: dict[str, Any] = field(default_factory=lambda: {})

xyberos.security.governor — Resource Governor

xyberos.security.governor

Resource Governor — actively manages resource consumption and limits.

ResourceGovernor

Enforces resource limits per principal.

Usage::

gov = ResourceGovernor()
gov.set_limits("alice", ResourceLimits(max_actions=100))
ok, reason = gov.check("alice")
if ok:
    gov.consume("alice", action_count=1)

Source code in xyberos\security\governor\governor.py

class ResourceGovernor:
    """
    Enforces resource limits per principal.

    Usage::

        gov = ResourceGovernor()
        gov.set_limits("alice", ResourceLimits(max_actions=100))
        ok, reason = gov.check("alice")
        if ok:
            gov.consume("alice", action_count=1)
    """

    def __init__(self) -> None:
        self._limits: dict[str, ResourceLimits] = {}
        self._budgets: dict[str, ResourceBudget] = {}
        self._concurrent: dict[str, int] = {}

    def set_limits(self, principal_id: str, limits: ResourceLimits) -> None:
        self._limits[principal_id] = limits

    def get_limits(self, principal_id: str) -> ResourceLimits:
        return self._limits.get(principal_id, ResourceLimits())

    def check(
        self,
        principal: Principal,
        *,
        cpu_delta: float = 0,
        memory_delta: float = 0,
        action_count: int = 1,
        tokens: int = 0,
        api_calls: int = 0,
    ) -> tuple[bool, str]:
        budget = self._get_budget(principal.id)
        limits = self.get_limits(principal.id)

        if budget.cpu_seconds + cpu_delta > limits.max_cpu_seconds:
            return False, "CPU limit exceeded"
        if budget.memory_mb + memory_delta > limits.max_memory_mb:
            return False, "Memory limit exceeded"
        if budget.action_count + action_count > limits.max_actions:
            return False, "Action limit exceeded"
        if budget.token_count + tokens > limits.max_tokens:
            return False, "Token limit exceeded"
        if budget.api_call_count + api_calls > limits.max_api_calls:
            return False, "API call limit exceeded"
        concurrent = self._concurrent.get(principal.id, 0)
        if concurrent >= limits.max_concurrent_actions:
            return False, "Concurrent action limit exceeded"
        return True, "OK"

    def consume(
        self,
        principal: Principal,
        *,
        cpu_seconds: float = 0,
        memory_mb: float = 0,
        action_count: int = 0,
        tokens: int = 0,
        api_calls: int = 0,
    ) -> None:
        budget = self._get_budget(principal.id)
        budget.cpu_seconds += cpu_seconds
        budget.memory_mb += memory_mb
        budget.action_count += action_count
        budget.token_count += tokens
        budget.api_call_count += api_calls

    def acquire(self, principal_id: str) -> bool:
        limits = self._limits.get(principal_id, ResourceLimits())
        current = self._concurrent.get(principal_id, 0)
        if current >= limits.max_concurrent_actions:
            return False
        self._concurrent[principal_id] = current + 1
        return True

    def release(self, principal_id: str) -> None:
        current = self._concurrent.get(principal_id, 0)
        if current > 0:
            self._concurrent[principal_id] = current - 1

    def reset_budget(self, principal_id: str) -> None:
        self._budgets.pop(principal_id, None)

    def reset_all(self) -> None:
        self._budgets.clear()

    def _get_budget(self, principal_id: str) -> ResourceBudget:
        if principal_id not in self._budgets:
            self._budgets[principal_id] = ResourceBudget()
        return self._budgets[principal_id]

ResourceLimits dataclass

Maximum resource consumption allowed for a principal or role.

Source code in xyberos\security\governor\models.py

@dataclass(slots=True)
class ResourceLimits:
    """
    Maximum resource consumption allowed for a principal or role.
    """

    max_cpu_seconds: float = 3600.0
    max_memory_mb: float = 512.0
    max_actions: int = 1000
    max_tokens: int = 100_000
    max_api_calls: int = 5000
    max_concurrent_actions: int = 5

ResourceBudget dataclass

Current resource consumption for a principal.

Resets according to reset_period (e.g. "hourly", "daily").

Source code in xyberos\security\governor\models.py

@dataclass(slots=True)
class ResourceBudget:
    """
    Current resource consumption for a principal.

    Resets according to *reset_period* (e.g. ``"hourly"``, ``"daily"``).
    """

    cpu_seconds: float = 0.0
    memory_mb: float = 0.0
    action_count: int = 0
    token_count: int = 0
    api_call_count: int = 0
    last_reset: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    reset_period: str = "daily"  # hourly | daily | unlimited

xyberos.security.kill_switch — Kill Switch

xyberos.security.kill_switch

Kill Switch — emergency stop for agents, plugins, workflows, sessions, and the runtime.

KillTarget = Callable[[], Any] module-attribute

KillSwitch

Emergency kill switch for the XYBEROS runtime.

Maintains a registry of KillTarget callables grouped by scope. Each target can be tripped individually or by scope. Once a target is tripped it is marked as killed and cannot be tripped again.

Source code in xyberos\security\kill_switch\engine.py

class KillSwitch:
    """
    Emergency kill switch for the XYBEROS runtime.

    Maintains a registry of ``KillTarget`` callables grouped by scope.
    Each target can be tripped individually or by scope.  Once a target
    is tripped it is marked as killed and cannot be tripped again.
    """

    def __init__(self, on_kill: Callable[[KillRecord], Any] | None = None) -> None:
        self._targets: dict[str, KillTarget] = {}
        self._scopes: dict[str, str] = {}  # target_id → scope
        self._killed: set[str] = set()
        self._history: list[KillRecord] = []
        self._on_kill = on_kill

    # ── Registration ────────────────────────────────────────────

    def register(
        self,
        target_id: str,
        target: KillTarget,
        *,
        scope: str = KillScope.ALL.value,
    ) -> None:
        """Register a killable target."""
        self._targets[target_id] = target
        self._scopes[target_id] = scope

    def unregister(self, target_id: str) -> None:
        """Remove a previously registered target."""
        self._targets.pop(target_id, None)
        self._scopes.pop(target_id, None)
        self._killed.discard(target_id)

    # ── Queries ─────────────────────────────────────────────────

    def is_registered(self, target_id: str) -> bool:
        return target_id in self._targets

    def is_killed(self, target_id: str) -> bool:
        return target_id in self._killed

    def list_targets(self, scope: str | None = None) -> list[str]:
        if scope is None:
            return list(self._targets.keys())
        return [tid for tid, s in self._scopes.items() if s == scope]

    def history(self) -> list[KillRecord]:
        return list(reversed(self._history))

    # ── Kill operations ─────────────────────────────────────────

    async def trip(self, target_id: str) -> KillRecord:
        """Kill a single target by ID."""
        if target_id not in self._targets:
            return KillRecord(
                target_id=target_id,
                scope=self._scopes.get(target_id, "unknown"),
                success=False,
                error=f"Unknown target: {target_id}",
            )

        if target_id in self._killed:
            return KillRecord(
                target_id=target_id,
                scope=self._scopes[target_id],
                success=True,
                error="Already killed (idempotent)",
            )

        target = self._targets[target_id]
        scope = self._scopes.get(target_id, "unknown")

        try:
            result = target()
            if hasattr(result, "__await__"):
                await result

            record = KillRecord(
                target_id=target_id,
                scope=scope,
                success=True,
            )
        except Exception as exc:
            record = KillRecord(
                target_id=target_id,
                scope=scope,
                success=False,
                error=str(exc),
            )

        self._killed.add(target_id)
        self._history.append(record)

        if self._on_kill:
            self._on_kill(record)

        return record

    async def trip_scope(self, scope: str) -> KillReport:
        """Kill all targets in a scope."""
        targets = self.list_targets(scope)
        report = KillReport(triggered_by=f"scope:{scope}")
        for tid in targets:
            record = await self.trip(tid)
            report.targets.append(record)
        return report

    # ── Convenience methods ─────────────────────────────────────

    async def trip_agents(self) -> KillReport:
        """Kill all agent-scoped targets."""
        return await self.trip_scope(KillScope.AGENT.value)

    async def trip_plugins(self) -> KillReport:
        """Kill all plugin-scoped targets."""
        return await self.trip_scope(KillScope.PLUGIN.value)

    async def trip_workflows(self) -> KillReport:
        """Kill all workflow-scoped targets."""
        return await self.trip_scope(KillScope.WORKFLOW.value)

    async def trip_sessions(self) -> KillReport:
        """Kill all session-scoped targets."""
        return await self.trip_scope(KillScope.SESSION.value)

    async def trip_runtime(self) -> KillReport:
        """Kill all runtime-scoped targets."""
        return await self.trip_scope(KillScope.RUNTIME.value)

    async def trip_all(self) -> KillReport:
        """Kill all registered targets regardless of scope."""
        targets = list(self._targets.keys())
        records: list[KillRecord] = []
        for tid in targets:
            record = await self.trip(tid)
            records.append(record)
        return KillReport(
            triggered_by="trip_all",
            targets=records,
        )

    # ── Reset ───────────────────────────────────────────────────

    def reset(self) -> None:
        """Reset the kill switch — clear all targets, killed set, and history."""
        self._targets.clear()
        self._scopes.clear()
        self._killed.clear()
        self._history.clear()

register(target_id, target, *, scope=KillScope.ALL.value)

Register a killable target.

Source code in xyberos\security\kill_switch\engine.py

def register(
    self,
    target_id: str,
    target: KillTarget,
    *,
    scope: str = KillScope.ALL.value,
) -> None:
    """Register a killable target."""
    self._targets[target_id] = target
    self._scopes[target_id] = scope

reset()

Reset the kill switch — clear all targets, killed set, and history.

Source code in xyberos\security\kill_switch\engine.py

def reset(self) -> None:
    """Reset the kill switch — clear all targets, killed set, and history."""
    self._targets.clear()
    self._scopes.clear()
    self._killed.clear()
    self._history.clear()

trip(target_id) async

Kill a single target by ID.

Source code in xyberos\security\kill_switch\engine.py

async def trip(self, target_id: str) -> KillRecord:
    """Kill a single target by ID."""
    if target_id not in self._targets:
        return KillRecord(
            target_id=target_id,
            scope=self._scopes.get(target_id, "unknown"),
            success=False,
            error=f"Unknown target: {target_id}",
        )

    if target_id in self._killed:
        return KillRecord(
            target_id=target_id,
            scope=self._scopes[target_id],
            success=True,
            error="Already killed (idempotent)",
        )

    target = self._targets[target_id]
    scope = self._scopes.get(target_id, "unknown")

    try:
        result = target()
        if hasattr(result, "__await__"):
            await result

        record = KillRecord(
            target_id=target_id,
            scope=scope,
            success=True,
        )
    except Exception as exc:
        record = KillRecord(
            target_id=target_id,
            scope=scope,
            success=False,
            error=str(exc),
        )

    self._killed.add(target_id)
    self._history.append(record)

    if self._on_kill:
        self._on_kill(record)

    return record

trip_agents() async

Kill all agent-scoped targets.

Source code in xyberos\security\kill_switch\engine.py

async def trip_agents(self) -> KillReport:
    """Kill all agent-scoped targets."""
    return await self.trip_scope(KillScope.AGENT.value)

trip_all() async

Kill all registered targets regardless of scope.

Source code in xyberos\security\kill_switch\engine.py

async def trip_all(self) -> KillReport:
    """Kill all registered targets regardless of scope."""
    targets = list(self._targets.keys())
    records: list[KillRecord] = []
    for tid in targets:
        record = await self.trip(tid)
        records.append(record)
    return KillReport(
        triggered_by="trip_all",
        targets=records,
    )

trip_plugins() async

Kill all plugin-scoped targets.

Source code in xyberos\security\kill_switch\engine.py

async def trip_plugins(self) -> KillReport:
    """Kill all plugin-scoped targets."""
    return await self.trip_scope(KillScope.PLUGIN.value)

trip_runtime() async

Kill all runtime-scoped targets.

Source code in xyberos\security\kill_switch\engine.py

async def trip_runtime(self) -> KillReport:
    """Kill all runtime-scoped targets."""
    return await self.trip_scope(KillScope.RUNTIME.value)

trip_scope(scope) async

Kill all targets in a scope.

Source code in xyberos\security\kill_switch\engine.py

async def trip_scope(self, scope: str) -> KillReport:
    """Kill all targets in a scope."""
    targets = self.list_targets(scope)
    report = KillReport(triggered_by=f"scope:{scope}")
    for tid in targets:
        record = await self.trip(tid)
        report.targets.append(record)
    return report

trip_sessions() async

Kill all session-scoped targets.

Source code in xyberos\security\kill_switch\engine.py

async def trip_sessions(self) -> KillReport:
    """Kill all session-scoped targets."""
    return await self.trip_scope(KillScope.SESSION.value)

trip_workflows() async

Kill all workflow-scoped targets.

Source code in xyberos\security\kill_switch\engine.py

async def trip_workflows(self) -> KillReport:
    """Kill all workflow-scoped targets."""
    return await self.trip_scope(KillScope.WORKFLOW.value)

unregister(target_id)

Remove a previously registered target.

Source code in xyberos\security\kill_switch\engine.py

def unregister(self, target_id: str) -> None:
    """Remove a previously registered target."""
    self._targets.pop(target_id, None)
    self._scopes.pop(target_id, None)
    self._killed.discard(target_id)

KillRecord dataclass

A record of a kill event.

Source code in xyberos\security\kill_switch\engine.py

@dataclass(slots=True)
class KillRecord:
    """
    A record of a kill event.
    """

    target_id: str
    scope: str
    success: bool
    error: str | None = None
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

KillReport dataclass

Summary of a kill operation (trip_all or trip_scope).

Source code in xyberos\security\kill_switch\engine.py

@dataclass(slots=True)
class KillReport:
    """
    Summary of a kill operation (``trip_all`` or ``trip_scope``).
    """

    triggered_by: str = "kill_switch"
    targets: list[KillRecord] = field(default_factory=lambda: [])
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

    @property
    def success_count(self) -> int:
        return sum(1 for t in self.targets if t.success)

    @property
    def failure_count(self) -> int:
        return sum(1 for t in self.targets if not t.success)

KillScope

Bases: str, Enum

Scopes that can be killed in bulk.

Source code in xyberos\security\kill_switch\engine.py

class KillScope(str, Enum):
    """Scopes that can be killed in bulk."""

    AGENT = "agent"
    PLUGIN = "plugin"
    WORKFLOW = "workflow"
    SESSION = "session"
    TENANT = "tenant"
    RUNTIME = "runtime"
    ALL = "all"

xyberos.security.secrets — Secrets Manager

xyberos.security.secrets

Secrets Manager — secure credential storage and retrieval.

Provides a pluggable secrets provider abstraction with built-in implementations for environment variables and HashiCorp Vault.

Usage::

from xyberos.security.secrets import SecretsManager, EnvSecretsProvider

mgr = SecretsManager(provider=EnvSecretsProvider())
api_key = mgr.get("OPENAI_API_KEY")

SecretsManager

Orchestrates secret retrieval with optional caching and TTL.

Usage::

mgr = SecretsManager(provider=VaultSecretsProvider(), cache_ttl=300)
key = mgr.get("OPENAI_API_KEY")

Source code in xyberos\security\secrets\manager.py

class SecretsManager:
    """Orchestrates secret retrieval with optional caching and TTL.

    Usage::

        mgr = SecretsManager(provider=VaultSecretsProvider(), cache_ttl=300)
        key = mgr.get("OPENAI_API_KEY")
    """

    def __init__(
        self,
        provider: SecretsProvider | None = None,
        *,
        cache_ttl: float = 0,
    ) -> None:
        self._provider = provider or EnvSecretsProvider()
        self._cache_ttl = cache_ttl
        self._cache: dict[str, CachedSecret] = {}

    @property
    def provider(self) -> SecretsProvider:
        return self._provider

    def get(self, key: str, *, default: str | None = None) -> str | None:
        """Retrieve a secret, respecting cache TTL."""
        now = time.monotonic()

        # Check cache
        cached = self._cache.get(key)
        if cached is not None and now < cached.expires_at:
            return cached.value

        # Fetch from provider
        value = self._provider.get(key, default=default)
        if value is not None and self._cache_ttl > 0:
            self._cache[key] = CachedSecret(
                value=value,
                expires_at=now + self._cache_ttl,
            )

        return value

    def set(self, key: str, value: str) -> None:
        """Store a secret and update cache."""
        self._provider.set(key, value)
        if self._cache_ttl > 0:
            self._cache[key] = CachedSecret(
                value=value,
                expires_at=time.monotonic() + self._cache_ttl,
            )

    def delete(self, key: str) -> bool:
        """Delete a secret and purge from cache."""
        self._cache.pop(key, None)
        return self._provider.delete(key)

    def list_keys(self) -> list[str]:
        return self._provider.list_keys()

    def invalidate(self, key: str) -> None:
        """Remove a single entry from the local cache."""
        self._cache.pop(key, None)

    def clear_cache(self) -> None:
        """Flush the entire local cache."""
        self._cache.clear()

clear_cache()

Flush the entire local cache.

Source code in xyberos\security\secrets\manager.py

def clear_cache(self) -> None:
    """Flush the entire local cache."""
    self._cache.clear()

delete(key)

Delete a secret and purge from cache.

Source code in xyberos\security\secrets\manager.py

def delete(self, key: str) -> bool:
    """Delete a secret and purge from cache."""
    self._cache.pop(key, None)
    return self._provider.delete(key)

get(key, *, default=None)

Retrieve a secret, respecting cache TTL.

Source code in xyberos\security\secrets\manager.py

def get(self, key: str, *, default: str | None = None) -> str | None:
    """Retrieve a secret, respecting cache TTL."""
    now = time.monotonic()

    # Check cache
    cached = self._cache.get(key)
    if cached is not None and now < cached.expires_at:
        return cached.value

    # Fetch from provider
    value = self._provider.get(key, default=default)
    if value is not None and self._cache_ttl > 0:
        self._cache[key] = CachedSecret(
            value=value,
            expires_at=now + self._cache_ttl,
        )

    return value

invalidate(key)

Remove a single entry from the local cache.

Source code in xyberos\security\secrets\manager.py

def invalidate(self, key: str) -> None:
    """Remove a single entry from the local cache."""
    self._cache.pop(key, None)

set(key, value)

Store a secret and update cache.

Source code in xyberos\security\secrets\manager.py

def set(self, key: str, value: str) -> None:
    """Store a secret and update cache."""
    self._provider.set(key, value)
    if self._cache_ttl > 0:
        self._cache[key] = CachedSecret(
            value=value,
            expires_at=time.monotonic() + self._cache_ttl,
        )

SecretsProvider

Bases: ABC

Abstract interface for a secrets storage backend.

Source code in xyberos\security\secrets\providers.py

class SecretsProvider(ABC):
    """Abstract interface for a secrets storage backend."""

    @abstractmethod
    def get(self, key: str, *, default: str | None = None) -> str | None:
        """Retrieve a secret by key. Returns *default* if not found."""
        ...

    @abstractmethod
    def set(self, key: str, value: str) -> None:
        """Store a secret (provider-dependent)."""
        ...

    @abstractmethod
    def delete(self, key: str) -> bool:
        """Delete a secret. Returns True if existed."""
        ...

    @abstractmethod
    def list_keys(self) -> list[str]:
        """List all known secret keys."""
        ...

delete(key) abstractmethod

Delete a secret. Returns True if existed.

Source code in xyberos\security\secrets\providers.py

@abstractmethod
def delete(self, key: str) -> bool:
    """Delete a secret. Returns True if existed."""
    ...

get(key, *, default=None) abstractmethod

Retrieve a secret by key. Returns default if not found.

Source code in xyberos\security\secrets\providers.py

@abstractmethod
def get(self, key: str, *, default: str | None = None) -> str | None:
    """Retrieve a secret by key. Returns *default* if not found."""
    ...

list_keys() abstractmethod

List all known secret keys.

Source code in xyberos\security\secrets\providers.py

@abstractmethod
def list_keys(self) -> list[str]:
    """List all known secret keys."""
    ...

set(key, value) abstractmethod

Store a secret (provider-dependent).

Source code in xyberos\security\secrets\providers.py

@abstractmethod
def set(self, key: str, value: str) -> None:
    """Store a secret (provider-dependent)."""
    ...

EnvSecretsProvider

Bases: SecretsProvider

Reads secrets from environment variables — zero-config default.

Source code in xyberos\security\secrets\providers.py

class EnvSecretsProvider(SecretsProvider):
    """Reads secrets from environment variables — zero-config default."""

    def get(self, key: str, *, default: str | None = None) -> str | None:
        return os.environ.get(key, default)

    def set(self, key: str, value: str) -> None:
        os.environ[key] = value

    def delete(self, key: str) -> bool:
        return os.environ.pop(key, None) is not None

    def list_keys(self) -> list[str]:
        return [k for k in os.environ if not k.startswith("_")]

VaultSecretsProvider

Bases: SecretsProvider

HashiCorp Vault integration via the hvac client.

Requires the hvac package and the following env vars:

• VAULT_ADDR — Vault server URL (default http://127.0.0.1:8200)
• VAULT_TOKEN — Authentication token
• VAULT_MOUNT_POINT — KV mount point (default secret)

If hvac is not installed or Vault is unreachable, falls back to environment variables.

Source code in xyberos\security\secrets\providers.py

class VaultSecretsProvider(SecretsProvider):
    """HashiCorp Vault integration via the ``hvac`` client.

    Requires the ``hvac`` package and the following env vars:

    * ``VAULT_ADDR`` — Vault server URL (default ``http://127.0.0.1:8200``)
    * ``VAULT_TOKEN`` — Authentication token
    * ``VAULT_MOUNT_POINT`` — KV mount point (default ``secret``)

    If ``hvac`` is not installed or Vault is unreachable, falls back
    to environment variables.
    """

    def __init__(
        self,
        *,
        url: str | None = None,
        token: str | None = None,
        mount_point: str = "secret",
        fallback_provider: SecretsProvider | None = None,
    ) -> None:
        self._url = url or os.environ.get("VAULT_ADDR", "http://127.0.0.1:8200")
        self._token = token or os.environ.get("VAULT_TOKEN", "")
        self._mount_point = os.environ.get("VAULT_MOUNT_POINT", mount_point)
        self._fallback = fallback_provider or EnvSecretsProvider()
        self._client: Any = None
        self._available = False

    def _ensure_client(self) -> bool:
        if self._client is not None:
            return self._available
        try:
            import hvac  # type: ignore[import-untyped]
            self._client = hvac.Client(url=self._url, token=self._token)
            self._available = self._client.is_authenticated()
            if not self._available:
                logger.warning(
                    "Vault at %s — authentication failed. Falling back to env.",
                    self._url,
                )
            else:
                logger.info("Connected to Vault at %s", self._url)
        except ImportError:
            logger.warning("hvac not installed. Falling back to env provider.")
            self._available = False
        except Exception as exc:
            logger.warning("Vault connection failed: %s. Falling back to env.", exc)
            self._available = False
        return self._available

    def get(self, key: str, *, default: str | None = None) -> str | None:
        if self._ensure_client():
            try:
                secret = self._client.secrets.kv.v1.read_secret(
                    path=key, mount_point=self._mount_point,
                )
                return secret.get("data", {}).get("data", {}).get(key, default)
            except Exception as exc:
                logger.debug("Vault read failed for '%s': %s", key, exc)
        return self._fallback.get(key, default=default)

    def set(self, key: str, value: str) -> None:
        if self._ensure_client():
            try:
                self._client.secrets.kv.v1.create_or_update_secret(
                    path=key,
                    secret={key: value},
                    mount_point=self._mount_point,
                )
                return
            except Exception as exc:
                logger.debug("Vault write failed for '%s': %s", key, exc)
        self._fallback.set(key, value)

    def delete(self, key: str) -> bool:
        if self._ensure_client():
            try:
                self._client.secrets.kv.v1.delete_secret(
                    path=key, mount_point=self._mount_point,
                )
                return True
            except Exception as exc:
                logger.debug("Vault delete failed for '%s': %s", key, exc)
        return self._fallback.delete(key)

    def list_keys(self) -> list[str]:
        if self._ensure_client():
            try:
                resp = self._client.secrets.kv.v1.list_secrets(
                    mount_point=self._mount_point,
                )
                return resp.get("data", {}).get("keys", [])
            except Exception:
                pass
        return self._fallback.list_keys()

xyberos.security.models — Security Models

xyberos.security.models

Security data models — Principal, Role, Permission, SecurityContext, Tenant.

These are the canonical definitions, moved from the kernel internals to a first-class :mod:xyberos.security module.

Tenant dataclass

A tenant — isolated organizational unit within the platform.

Each tenant has a unique identifier and may carry configuration specific to that organization (e.g. custom RBAC, resource quotas).

Source code in xyberos\security\models.py

@dataclass(slots=True)
class Tenant:
    """
    A tenant — isolated organizational unit within the platform.

    Each tenant has a unique identifier and may carry configuration
    specific to that organization (e.g. custom RBAC, resource quotas).
    """

    id: str
    name: str = ""
    settings: dict[str, Any] = field(default_factory=dict[str, Any])

resolve_tenant_id(tenant_id=None)

Resolve a tenant ID, falling back to env var then "default".

Source code in xyberos\security\models.py

def resolve_tenant_id(tenant_id: str | None = None) -> str:
    """Resolve a tenant ID, falling back to env var then ``"default"``."""
    if tenant_id:
        return tenant_id
    return os.environ.get("XYBEROS_DEFAULT_TENANT", "default")

xyberos.server — REST API Server

xyberos.server.auth — Authentication

xyberos.server.auth

Authentication & authorization middleware for the XYBEROS REST API.

Provides JWT token creation/validation, API key authentication, and FastAPI dependency injection helpers.

Usage::

from fastapi import Depends, FastAPI
from xyberos.server.auth import (
    create_access_token,
    get_current_principal,
    AuthMiddleware,
)

app = FastAPI()
app.add_middleware(AuthMiddleware)

@app.get("/secure")
async def secure_route(principal=Depends(get_current_principal)):
    return {"user": principal.id}

AuthMiddleware

FastAPI middleware that enriches request state with the current principal.

Add to your app::

from xyberos.server.auth import AuthMiddleware

app.add_middleware(AuthMiddleware)

Source code in xyberos\server\auth.py

class AuthMiddleware:
    """FastAPI middleware that enriches request state with the current principal.

    Add to your app::

        from xyberos.server.auth import AuthMiddleware

        app.add_middleware(AuthMiddleware)
    """

    def __init__(self, app: Any) -> None:
        self.app = app

    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
        from fastapi import Request

        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        request = Request(scope, receive)
        try:
            principal = await get_current_principal(
                credentials=None,
                request=request,
            )
            scope["principal"] = principal
        except HTTPException:
            scope["principal"] = Principal(id="anonymous", name="anonymous")

        await self.app(scope, receive, send)

create_access_token(principal_id, *, secret='', expires_minutes=60, tenant_id='', extra_claims=None)

Create a self-contained JWT access token (HS256).

Parameters

principal_id: Unique identifier for the principal. secret: Signing secret. Auto-generated from env XYBEROS_JWT_SECRET if empty (with a warning). expires_minutes: Token validity in minutes. tenant_id: Optional tenant scope. extra_claims: Additional claims to include in the payload.

Returns

str Encoded JWT string.

Source code in xyberos\server\auth.py

def create_access_token(
    principal_id: str,
    *,
    secret: str = "",
    expires_minutes: int = 60,
    tenant_id: str = "",
    extra_claims: dict[str, Any] | None = None,
) -> str:
    """Create a self-contained JWT access token (HS256).

    Parameters
    ----------
    principal_id:
        Unique identifier for the principal.
    secret:
        Signing secret.  Auto-generated from env ``XYBEROS_JWT_SECRET``
        if empty (with a warning).
    expires_minutes:
        Token validity in minutes.
    tenant_id:
        Optional tenant scope.
    extra_claims:
        Additional claims to include in the payload.

    Returns
    -------
    str
        Encoded JWT string.
    """
    secret = secret or os.environ.get("XYBEROS_JWT_SECRET", "")
    if not secret:
        logger.warning("No JWT secret configured — using auto-generated key (not safe for production).")
        secret = hashlib.sha256(str(time.time()).encode()).hexdigest()

    algorithm = os.environ.get("XYBEROS_JWT_ALGORITHM", "HS256")
    now = int(time.time())

    header = {"alg": algorithm, "typ": "JWT"}
    payload = {
        "sub": principal_id,
        "iat": now,
        "exp": now + expires_minutes * 60,
        "iss": "xyberos",
    }
    if tenant_id:
        payload["tenant_id"] = tenant_id
    if extra_claims:
        payload.update(extra_claims)

    # Simple HS256 JWT without external dependencies
    segments = [
        _base64url_encode(json_dumps(header).encode()),
        _base64url_encode(json_dumps(payload).encode()),
    ]
    signing_input = ".".join(segments).encode()
    signature = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
    segments.append(_base64url_encode(signature))

    return ".".join(segments)

decode_access_token(token, *, secret='')

Decode and verify a JWT access token.

Raises HTTPException(401) if the token is invalid or expired.

Source code in xyberos\server\auth.py

def decode_access_token(
    token: str,
    *,
    secret: str = "",
) -> dict[str, Any]:
    """Decode and verify a JWT access token.

    Raises ``HTTPException(401)`` if the token is invalid or expired.
    """
    secret = secret or os.environ.get("XYBEROS_JWT_SECRET", "")
    if not secret:
        secret = hashlib.sha256(str(time.time()).encode()).hexdigest()

    parts = token.split(".")
    if len(parts) != 3:
        raise HTTPException(status_code=401, detail="Invalid token format")

    # Verify signature
    signing_input = f"{parts[0]}.{parts[1]}".encode()
    expected_sig = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
    actual_sig = _base64url_decode(parts[2])
    if not hmac.compare_digest(expected_sig, actual_sig):
        raise HTTPException(status_code=401, detail="Invalid token signature")

    # Decode payload
    try:
        payload = json_loads(_base64url_decode(parts[1]))
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid token payload")

    # Check expiry
    if payload.get("exp", 0) < time.time():
        raise HTTPException(status_code=401, detail="Token expired")

    return payload

get_current_principal(credentials=None, request=None) async

FastAPI dependency — extract authenticated principal from request.

Checks (in order): 1. Authorization: Bearer <token> header (JWT) 2. X-API-Key header 3. Falls back to an anonymous principal if no auth is configured.

Source code in xyberos\server\auth.py

async def get_current_principal(
    credentials: HTTPAuthorizationCredentials | None = None,
    request: Request | None = None,
) -> Principal:
    """FastAPI dependency — extract authenticated principal from request.

    Checks (in order):
    1. ``Authorization: Bearer <token>`` header (JWT)
    2. ``X-API-Key`` header
    3. Falls back to an anonymous principal if no auth is configured.
    """
    # Attempt 1: Bearer token (JWT)
    if credentials and credentials.scheme.lower() == "bearer":
        try:
            payload = decode_access_token(credentials.credentials)
            return Principal(
                id=payload.get("sub", "anonymous"),
                name=payload.get("name", payload.get("sub", "anonymous")),
                type=PrincipalType(payload.get("type", "user")),
                tenant_id=payload.get("tenant_id", ""),
                roles=set(payload.get("roles", [])),
            )
        except HTTPException:
            raise
        except Exception as exc:
            logger.debug("Bearer token decode failed: %s", exc)

    # Attempt 2: API key
    if request:
        api_key_header = os.environ.get("XYBEROS_API_KEY_HEADER", "X-API-Key")
        api_key = request.headers.get(api_key_header)
        if api_key:
            return Principal(
                id=api_key[:16],
                name=f"api-key-{api_key[:8]}",
                type=PrincipalType.SERVICE,
            )

    # Fallback: anonymous
    return Principal(
        id="anonymous",
        name="anonymous",
        type=PrincipalType.SESSION,
        tenant_id=os.environ.get("XYBEROS_DEFAULT_TENANT", "default"),
    )

get_security_context(principal=None, request=None) async

FastAPI dependency — build a SecurityContext from the request.

Source code in xyberos\server\auth.py

async def get_security_context(
    principal: Principal = None,  # type: ignore[assignment]
    request: Request | None = None,
) -> SecurityContext:
    """FastAPI dependency — build a SecurityContext from the request."""
    p = principal or Principal(id="anonymous", name="anonymous")
    meta: dict[str, Any] = {}
    if request:
        meta["path"] = request.url.path
        meta["method"] = request.method
        meta["client_host"] = request.client.host if request.client else ""
    return SecurityContext(principal=p, metadata=meta)

xyberos.server.models — API Models

xyberos.server.models

Pydantic models for the XYBEROS REST API.

ChatRequest

Bases: BaseModel

Request body for POST /chat.

Source code in xyberos\server\models.py

class ChatRequest(BaseModel):
    """Request body for ``POST /chat``."""
    text: str = Field(..., description="The user message to process")
    stream: bool = Field(False, description="Enable SSE streaming")

ChatResponse

Bases: BaseModel

Response from POST /chat.

Source code in xyberos\server\models.py

class ChatResponse(BaseModel):
    """Response from ``POST /chat``."""
    success: bool
    observation: str | None = None
    thought: str | None = None
    goal: str | None = None
    plan: list[str] | None = None
    decision: str | None = None
    action: str | None = None
    action_result: Any = None
    cycle_duration_ms: float = 0.0
    error: str | None = None

ReasonRequest

Bases: BaseModel

Request body for POST /reason.

Source code in xyberos\server\models.py

class ReasonRequest(BaseModel):
    """Request body for ``POST /reason``."""
    observation: str = Field(..., description="The observation or question")
    context: str = Field("", description="Optional context")
    strategy: str | None = Field(None, description="Reasoning strategy name")

ReasonResponse

Bases: BaseModel

Response from POST /reason.

Source code in xyberos\server\models.py

class ReasonResponse(BaseModel):
    """Response from ``POST /reason``."""
    success: bool
    conclusion: str = ""
    error: str | None = None

PlanRequest

Bases: BaseModel

Request body for POST /plan.

Source code in xyberos\server\models.py

class PlanRequest(BaseModel):
    """Request body for ``POST /plan``."""
    goal: str = Field(..., description="The goal to plan for")

PlanResponse

Bases: BaseModel

Response from POST /plan.

Source code in xyberos\server\models.py

class PlanResponse(BaseModel):
    """Response from ``POST /plan``."""
    success: bool
    steps: list[str] = []
    error: str | None = None

MemoryQueryRequest

Bases: BaseModel

Request body for GET /memory (query params).

Source code in xyberos\server\models.py

class MemoryQueryRequest(BaseModel):
    """Request body for ``GET /memory`` (query params)."""
    query: str = Field(..., description="Search query")
    limit: int = Field(5, description="Max results", ge=1, le=100)

MemoryStoreRequest

Bases: BaseModel

Request body for POST /memory.

Source code in xyberos\server\models.py

class MemoryStoreRequest(BaseModel):
    """Request body for ``POST /memory``."""
    key: str = Field(..., description="Memory key")
    content: Any = Field(..., description="Content to store")
    tier: str = Field("working", description="Memory tier name")
    metadata: dict[str, Any] = Field(default_factory=dict)

ActionRequest

Bases: BaseModel

Request body for POST /action.

Source code in xyberos\server\models.py

class ActionRequest(BaseModel):
    """Request body for ``POST /action``."""
    name: str = Field(..., description="Action provider name")
    params: dict[str, Any] = Field(default_factory=dict)

ActionResponse

Bases: BaseModel

Response from POST /action.

Source code in xyberos\server\models.py

class ActionResponse(BaseModel):
    """Response from ``POST /action``."""
    success: bool
    result: Any = None
    error: str | None = None

ToolInfo

Bases: BaseModel

Tool metadata.

Source code in xyberos\server\models.py

class ToolInfo(BaseModel):
    """Tool metadata."""
    name: str
    description: str
    version: str = "1.0.0"

ErrorResponse

Bases: BaseModel

Standard error payload.

Source code in xyberos\server\models.py

class ErrorResponse(BaseModel):
    """Standard error payload."""
    error: str
    code: str = "internal_error"
    detail: str | None = None

xyberos.storage.tenant — Tenant Storage

xyberos.storage.tenant

Tenant-aware storage provider wrapper. Isolates data by prefixing storage keys with {tenant_id}:.

TenantStorageWrapper

Bases: IStorageProvider

Wraps a storage provider with tenant key isolation.

Source code in xyberos\storage\tenant.py

class TenantStorageWrapper(IStorageProvider):
    """Wraps a storage provider with tenant key isolation."""

    def __init__(self, provider: IStorageProvider, *, tenant_id: str) -> None:
        self._provider = provider
        self._prefix = f"{tenant_id}:"

    def _tenant_key(self, key: str) -> str:
        return f"{self._prefix}{key}"

    @property
    def name(self) -> str:
        return f"{self._provider.name}_{self._prefix.rstrip(':')}"

    @property
    def priority(self) -> int:
        return self._provider.priority

    @property
    def enabled(self) -> bool:
        return self._provider.enabled

    @property
    def capacity(self) -> int | None:
        return self._provider.capacity

    def save(self, item: StorageItem) -> None:
        prefixed = StorageItem(
            key=self._tenant_key(item.key),
            content=item.content,
            metadata=item.metadata,
            timestamp=item.timestamp,
            ttl_seconds=item.ttl_seconds,
        )
        self._provider.save(prefixed)

    def load(self, query: StorageQuery) -> StorageResult:
        scoped = StorageQuery(
            key=f"{self._prefix}{query.key}" if query.key else "",
            prefix=f"{self._prefix}{query.prefix}" if query.prefix else "",
            filters=query.filters,
            limit=query.limit,
            include_expired=query.include_expired,
        )
        return self._provider.load(scoped)

    def delete(self, key: str) -> bool:
        return self._provider.delete(self._tenant_key(key))

    def clear(self) -> None:
        for k in self.list_keys():
            self._provider.delete(self._tenant_key(k))

    def count(self) -> int:
        return len(self.list_keys())

    def exists(self, key: str) -> bool:
        return self._provider.exists(self._tenant_key(key))

    def list_keys(self) -> list[str]:
        plen = len(self._prefix)
        return [k[plen:] for k in self._provider.list_keys() if k.startswith(self._prefix)]

    @property
    def provider(self) -> IStorageProvider:
        return self._provider

    @property
    def tenant_id(self) -> str:
        return self._prefix.rstrip(":")

xyberos.memory — Memory system

xyberos.memory

XYBEROS Memory subsystem (Phase 4).

Multi-tier memory with fallback chain:

Working → Episodic → Semantic → Procedural → Vector → Knowledge Graph

Every tier implements IMemoryStore(Provider) and is registered in the MemoryRegistry. The MemoryManager orchestrates queries across all tiers, promoting results back to working memory.

MemoryManager

Orchestrates memory across all tiers using the Fallback Chain pattern:

1. Query working memory (fastest)
2. If miss → query episodic + semantic (parallel)
3. If still miss → query vector store
4. Last resort → knowledge graph
5. Promote results back to working memory for fast future access

Usage::

manager = MemoryManager()
manager.register_defaults()

manager.store(MemoryItem(key="k1", content="hello"))
result = manager.query(MemoryQuery(text="hello"))

Source code in xyberos\memory\manager.py

class MemoryManager:
    """
    Orchestrates memory across all tiers using the **Fallback Chain**
    pattern:

    1. Query working memory (fastest)
    2. If miss → query episodic + semantic (parallel)
    3. If still miss → query vector store
    4. Last resort → knowledge graph
    5. Promote results back to working memory for fast future access

    Usage::

        manager = MemoryManager()
        manager.register_defaults()

        manager.store(MemoryItem(key="k1", content="hello"))
        result = manager.query(MemoryQuery(text="hello"))
    """

    def __init__(
        self,
        registry: MemoryRegistry | None = None,
        monitor: CognitiveMonitor | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        self._registry = registry or MemoryRegistry()
        self._monitor = monitor or CognitiveMonitor.instance()
        self._fallback_order: list[str] = [
            "working",
            "episodic",
            "semantic",
            "procedural",
            "vector",
            "knowledge_graph",
        ]

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("memory", self._registry)
            logger.info("MemoryManager connected to PluginManager")

    @property
    def registry(self) -> MemoryRegistry:
        return self._registry

    # ------------------------------------------------------------------
    # Registration helpers
    # ------------------------------------------------------------------

    def register_defaults(self) -> None:
        """Register all built-in memory tier providers.

        Discovers tiers from ``xyberos.memory`` entry points first, then
        falls back to hardcoded imports for built-in tiers that are
        not yet registered via entry points.
        """
        # Discover from entry points
        from xyberos.common.registry import discover_entry_points
        eps = discover_entry_points("xyberos.memory")
        for name, cls in eps.items():
            try:
                instance = cls()
                if self._registry.exists(name):
                    continue
                self._registry.register(name, instance, default=name == "working")
            except Exception:
                pass

        # Hardcoded fallback for built-in tiers not discovered via entry points
        if not self._registry.exists("working"):
            from xyberos.memory.working import WorkingMemoryProvider
            self._registry.register("working", WorkingMemoryProvider(), default=True)
        if not self._registry.exists("episodic"):
            from xyberos.memory.episodic import EpisodicMemoryProvider
            self._registry.register("episodic", EpisodicMemoryProvider())
        if not self._registry.exists("semantic"):
            from xyberos.memory.semantic import SemanticMemoryProvider
            self._registry.register("semantic", SemanticMemoryProvider())
        if not self._registry.exists("procedural"):
            from xyberos.memory.procedural import ProceduralMemoryProvider
            self._registry.register("procedural", ProceduralMemoryProvider())
        if not self._registry.exists("vector"):
            from xyberos.memory.vector import VectorMemoryProvider
            self._registry.register("vector", VectorMemoryProvider())
        if not self._registry.exists("knowledge_graph"):
            from xyberos.memory.knowledge import KnowledgeGraphProvider
            self._registry.register("knowledge_graph", KnowledgeGraphProvider())

    def register_tier(self, name: str, provider: IMemoryStore, *, default: bool = False) -> None:
        """Register a custom memory tier."""
        self._registry.register(name, provider, default=default)
        if name not in self._fallback_order:
            self._fallback_order.append(name)

    # ------------------------------------------------------------------
    # Store
    # ------------------------------------------------------------------

    def store(self, item: MemoryItem, tier: str | None = None) -> None:
        """Store *item* in the specified *tier*, or in all tiers if ``None``."""
        if tier:
            provider = self._get_tier(tier)
            try:
                provider.store(item)
            except Exception as exc:
                raise StorageError(f"Failed to store in tier '{tier}': {exc}") from exc
            return

        for name in self._fallback_order:
            try:
                provider = self._get_tier(name)
                provider.store(item)
            except Exception as exc:
                logger.warning("Failed to store in tier '%s': %s", name, exc)

    # ------------------------------------------------------------------
    # Query (fallback chain)
    # ------------------------------------------------------------------

    def query(self, query: MemoryQuery, strategy: str = "hybrid") -> MemoryResult:
        """
        Execute the fallback chain.

        1. Query working memory (fastest)
        2. If miss → query episodic + semantic
        3. If still miss → procedural
        4. If still miss → vector store
        5. Last resort → knowledge graph
        6. Promote best results to working memory
        """
        start = time.perf_counter()
        self._monitor.emit(_events().PERCEPTION_STARTED, query=str(query.text)[:100])  # type: ignore[attr-defined]

        all_items: list[tuple[float, MemoryItem, str]] = []
        queried_tiers: list[str] = []

        for tier_name in self._fallback_order:
            try:
                provider = self._get_tier(tier_name)
            except TierNotAvailableError:
                continue

            try:
                result = provider.retrieve(query)
            except Exception as exc:
                logger.warning("Query failed on tier '%s': %s", tier_name, exc)
                continue

            queried_tiers.append(tier_name)
            for item in result.items:
                all_items.append((1.0 / (1.0 + len(all_items)), item, tier_name))

            if tier_name in ("working", "episodic", "semantic") and len(all_items) >= query.limit:
                break

        scorer = HybridStrategy()
        scored = [(scorer.score(item, query), item, tier) for _, item, tier in all_items]
        scored.sort(key=lambda x: x[0], reverse=True)
        top = scored[: query.limit]

        try:
            working = self._get_tier("working")
            for _, item, _ in top:
                working.store(item)
        except Exception:
            pass

        duration_ms = (time.perf_counter() - start) * 1000
        self._monitor.emit(  # type: ignore[attr-defined]
            _events().PERCEPTION_COMPLETED,
            tiers=queried_tiers,
            results=len(top),
            duration_ms=duration_ms,
        )

        return MemoryResult(
            items=[item for _, item, _ in top],
            total_count=len(scored),
            tier="+".join(queried_tiers) if queried_tiers else "none",
        )

    # ------------------------------------------------------------------
    # Direct tier access
    # ------------------------------------------------------------------

    def retrieve(self, query: MemoryQuery, tier: str = "working") -> MemoryResult:
        """Query a specific tier directly, skipping the fallback chain."""
        provider = self._get_tier(tier)
        try:
            return provider.retrieve(query)
        except Exception as exc:
            raise RetrievalError(f"Retrieval failed on tier '{tier}': {exc}") from exc

    def delete(self, key: str, tier: str | None = None) -> bool:
        """Delete from a specific tier, or all tiers if ``None``."""
        if tier:
            return self._get_tier(tier).delete(key)
        deleted = False
        for name in self._fallback_order:
            try:
                if self._get_tier(name).delete(key):
                    deleted = True
            except Exception:
                pass
        return deleted

    def clear(self, tier: str | None = None) -> None:
        """Clear a specific tier, or all tiers if ``None``."""
        if tier:
            self._get_tier(tier).clear()
        else:
            for name in self._fallback_order:
                try:
                    self._get_tier(name).clear()
                except Exception as exc:
                    logger.warning("Failed to clear tier '%s': %s", name, exc)

    def count(self, tier: str | None = None) -> int:
        """Count items in a specific tier, or sum across all."""
        if tier:
            return self._get_tier(tier).count()
        total = 0
        for name in self._fallback_order:
            try:
                total += self._get_tier(name).count()
            except Exception:
                pass
        return total

    # ------------------------------------------------------------------
    # Internals
    # ------------------------------------------------------------------

    def _get_tier(self, name: str) -> IMemoryStore:
        try:
            return self._registry.get(name)
        except KeyError as exc:
            raise TierNotAvailableError(f"Memory tier '{name}' is not registered") from exc

clear(tier=None)

Clear a specific tier, or all tiers if None.

Source code in xyberos\memory\manager.py

def clear(self, tier: str | None = None) -> None:
    """Clear a specific tier, or all tiers if ``None``."""
    if tier:
        self._get_tier(tier).clear()
    else:
        for name in self._fallback_order:
            try:
                self._get_tier(name).clear()
            except Exception as exc:
                logger.warning("Failed to clear tier '%s': %s", name, exc)

count(tier=None)

Count items in a specific tier, or sum across all.

Source code in xyberos\memory\manager.py

def count(self, tier: str | None = None) -> int:
    """Count items in a specific tier, or sum across all."""
    if tier:
        return self._get_tier(tier).count()
    total = 0
    for name in self._fallback_order:
        try:
            total += self._get_tier(name).count()
        except Exception:
            pass
    return total

delete(key, tier=None)

Delete from a specific tier, or all tiers if None.

Source code in xyberos\memory\manager.py

def delete(self, key: str, tier: str | None = None) -> bool:
    """Delete from a specific tier, or all tiers if ``None``."""
    if tier:
        return self._get_tier(tier).delete(key)
    deleted = False
    for name in self._fallback_order:
        try:
            if self._get_tier(name).delete(key):
                deleted = True
        except Exception:
            pass
    return deleted

query(query, strategy='hybrid')

Execute the fallback chain.

1. Query working memory (fastest)
2. If miss → query episodic + semantic
3. If still miss → procedural
4. If still miss → vector store
5. Last resort → knowledge graph
6. Promote best results to working memory

Source code in xyberos\memory\manager.py

def query(self, query: MemoryQuery, strategy: str = "hybrid") -> MemoryResult:
    """
    Execute the fallback chain.

    1. Query working memory (fastest)
    2. If miss → query episodic + semantic
    3. If still miss → procedural
    4. If still miss → vector store
    5. Last resort → knowledge graph
    6. Promote best results to working memory
    """
    start = time.perf_counter()
    self._monitor.emit(_events().PERCEPTION_STARTED, query=str(query.text)[:100])  # type: ignore[attr-defined]

    all_items: list[tuple[float, MemoryItem, str]] = []
    queried_tiers: list[str] = []

    for tier_name in self._fallback_order:
        try:
            provider = self._get_tier(tier_name)
        except TierNotAvailableError:
            continue

        try:
            result = provider.retrieve(query)
        except Exception as exc:
            logger.warning("Query failed on tier '%s': %s", tier_name, exc)
            continue

        queried_tiers.append(tier_name)
        for item in result.items:
            all_items.append((1.0 / (1.0 + len(all_items)), item, tier_name))

        if tier_name in ("working", "episodic", "semantic") and len(all_items) >= query.limit:
            break

    scorer = HybridStrategy()
    scored = [(scorer.score(item, query), item, tier) for _, item, tier in all_items]
    scored.sort(key=lambda x: x[0], reverse=True)
    top = scored[: query.limit]

    try:
        working = self._get_tier("working")
        for _, item, _ in top:
            working.store(item)
    except Exception:
        pass

    duration_ms = (time.perf_counter() - start) * 1000
    self._monitor.emit(  # type: ignore[attr-defined]
        _events().PERCEPTION_COMPLETED,
        tiers=queried_tiers,
        results=len(top),
        duration_ms=duration_ms,
    )

    return MemoryResult(
        items=[item for _, item, _ in top],
        total_count=len(scored),
        tier="+".join(queried_tiers) if queried_tiers else "none",
    )

register_defaults()

Register all built-in memory tier providers.

Discovers tiers from xyberos.memory entry points first, then falls back to hardcoded imports for built-in tiers that are not yet registered via entry points.

Source code in xyberos\memory\manager.py

def register_defaults(self) -> None:
    """Register all built-in memory tier providers.

    Discovers tiers from ``xyberos.memory`` entry points first, then
    falls back to hardcoded imports for built-in tiers that are
    not yet registered via entry points.
    """
    # Discover from entry points
    from xyberos.common.registry import discover_entry_points
    eps = discover_entry_points("xyberos.memory")
    for name, cls in eps.items():
        try:
            instance = cls()
            if self._registry.exists(name):
                continue
            self._registry.register(name, instance, default=name == "working")
        except Exception:
            pass

    # Hardcoded fallback for built-in tiers not discovered via entry points
    if not self._registry.exists("working"):
        from xyberos.memory.working import WorkingMemoryProvider
        self._registry.register("working", WorkingMemoryProvider(), default=True)
    if not self._registry.exists("episodic"):
        from xyberos.memory.episodic import EpisodicMemoryProvider
        self._registry.register("episodic", EpisodicMemoryProvider())
    if not self._registry.exists("semantic"):
        from xyberos.memory.semantic import SemanticMemoryProvider
        self._registry.register("semantic", SemanticMemoryProvider())
    if not self._registry.exists("procedural"):
        from xyberos.memory.procedural import ProceduralMemoryProvider
        self._registry.register("procedural", ProceduralMemoryProvider())
    if not self._registry.exists("vector"):
        from xyberos.memory.vector import VectorMemoryProvider
        self._registry.register("vector", VectorMemoryProvider())
    if not self._registry.exists("knowledge_graph"):
        from xyberos.memory.knowledge import KnowledgeGraphProvider
        self._registry.register("knowledge_graph", KnowledgeGraphProvider())

register_tier(name, provider, *, default=False)

Register a custom memory tier.

Source code in xyberos\memory\manager.py

def register_tier(self, name: str, provider: IMemoryStore, *, default: bool = False) -> None:
    """Register a custom memory tier."""
    self._registry.register(name, provider, default=default)
    if name not in self._fallback_order:
        self._fallback_order.append(name)

retrieve(query, tier='working')

Query a specific tier directly, skipping the fallback chain.

Source code in xyberos\memory\manager.py

def retrieve(self, query: MemoryQuery, tier: str = "working") -> MemoryResult:
    """Query a specific tier directly, skipping the fallback chain."""
    provider = self._get_tier(tier)
    try:
        return provider.retrieve(query)
    except Exception as exc:
        raise RetrievalError(f"Retrieval failed on tier '{tier}': {exc}") from exc

store(item, tier=None)

Store item in the specified tier, or in all tiers if None.

Source code in xyberos\memory\manager.py

def store(self, item: MemoryItem, tier: str | None = None) -> None:
    """Store *item* in the specified *tier*, or in all tiers if ``None``."""
    if tier:
        provider = self._get_tier(tier)
        try:
            provider.store(item)
        except Exception as exc:
            raise StorageError(f"Failed to store in tier '{tier}': {exc}") from exc
        return

    for name in self._fallback_order:
        try:
            provider = self._get_tier(name)
            provider.store(item)
        except Exception as exc:
            logger.warning("Failed to store in tier '%s': %s", name, exc)

MemoryItem dataclass

A single unit of memory.

Attributes

key: Unique identifier for this memory item. content: The stored data (text, embedding vector, structured dict, …). metadata: Arbitrary key-value tags (timestamp, source, priority, …). embedding: Optional embedding vector for similarity search. timestamp: When this item was created. access_count: How many times this item has been retrieved. ttl_seconds: Time-to-live in seconds. None = permanent.

Source code in xyberos\memory\models.py

@dataclass(slots=True)
class MemoryItem:
    """
    A single unit of memory.

    Attributes
    ----------
    key:
        Unique identifier for this memory item.
    content:
        The stored data (text, embedding vector, structured dict, …).
    metadata:
        Arbitrary key-value tags (timestamp, source, priority, …).
    embedding:
        Optional embedding vector for similarity search.
    timestamp:
        When this item was created.
    access_count:
        How many times this item has been retrieved.
    ttl_seconds:
        Time-to-live in seconds.  ``None`` = permanent.
    """

    key: str
    content: Any
    metadata: dict[str, Any] = field(default_factory=lambda: {})
    embedding: list[float] | None = None
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    access_count: int = 0
    ttl_seconds: float | None = None

    @property
    def is_expired(self) -> bool:
        """Check whether this item has exceeded its TTL."""
        if self.ttl_seconds is None:
            return False
        age = (datetime.now(timezone.utc) - self.timestamp).total_seconds()
        return age > self.ttl_seconds

is_expired property

Check whether this item has exceeded its TTL.

MemoryQuery dataclass

Query for memory retrieval.

Attributes

text: Natural-language query string. embedding: Optional embedding vector for similarity search. keys: If set, only retrieve items with these keys. limit: Maximum number of results. min_score: Minimum relevance score threshold. filters: Key-value pairs that metadata must match.

Source code in xyberos\memory\models.py

@dataclass(slots=True)
class MemoryQuery:
    """
    Query for memory retrieval.

    Attributes
    ----------
    text:
        Natural-language query string.
    embedding:
        Optional embedding vector for similarity search.
    keys:
        If set, only retrieve items with these keys.
    limit:
        Maximum number of results.
    min_score:
        Minimum relevance score threshold.
    filters:
        Key-value pairs that metadata must match.
    """

    text: str = ""
    embedding: list[float] | None = None
    keys: list[str] | None = None
    limit: int = 10
    min_score: float = 0.0
    filters: dict[str, Any] = field(default_factory=lambda: {})

MemoryResult dataclass

Result of a memory retrieval.

Attributes

items: Retrieved items, ordered by relevance (highest first). total_count: Total matching items (useful for pagination). tier: Which tier produced this result.

Source code in xyberos\memory\models.py

@dataclass(slots=True)
class MemoryResult:
    """
    Result of a memory retrieval.

    Attributes
    ----------
    items:
        Retrieved items, ordered by relevance (highest first).
    total_count:
        Total matching items (useful for pagination).
    tier:
        Which tier produced this result.
    """

    items: list[MemoryItem] = field(default_factory=lambda: [])
    total_count: int = 0
    tier: str = "unknown"

    @classmethod
    def empty(cls, tier: str = "unknown") -> "MemoryResult":
        return cls(items=[], total_count=0, tier=tier)

xyberos.storage — Storage system

xyberos.storage

XYBEROS Storage subsystem.

Pluggable storage with fallback chain:

Memory → Local Filesystem → (S3 / GCS / SQL … via entry points)

Every backend implements IStorageProvider(Provider) and is registered in the StorageRegistry. The StorageManager orchestrates reads across all backends with automatic fallback and promotion.

StorageManager

Orchestrates storage across multiple providers using the Fallback Chain pattern:

1. Try the default (highest-priority) provider first.
2. On failure, fall through to the next available provider.
3. Promote successful results to the default provider for fast access.

Usage::

manager = StorageManager()
manager.register_defaults()

manager.save(StorageItem(key="config.json", content={"theme": "dark"}))
result = manager.load(StorageQuery(key="config.json"))

Source code in xyberos\storage\manager.py

class StorageManager:
    """
    Orchestrates storage across multiple providers using the **Fallback
    Chain** pattern:

    1. Try the default (highest-priority) provider first.
    2. On failure, fall through to the next available provider.
    3. Promote successful results to the default provider for fast access.

    Usage::

        manager = StorageManager()
        manager.register_defaults()

        manager.save(StorageItem(key="config.json", content={"theme": "dark"}))
        result = manager.load(StorageQuery(key="config.json"))
    """

    def __init__(
        self,
        registry: StorageRegistry | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        self._registry = registry or StorageRegistry()
        self._fallback_order: list[str] = [
            "memory",
            "local",
        ]

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("storage", self._registry)
            logger.info("StorageManager connected to PluginManager")

    @property
    def registry(self) -> StorageRegistry:
        return self._registry

    # ------------------------------------------------------------------
    # Registration helpers
    # ------------------------------------------------------------------

    def register_defaults(self) -> None:
        """Register all built-in storage providers.

        Discovers providers from ``xyberos.storage`` entry points first,
        then falls back to hardcoded imports for built-in providers
        that are not yet registered via entry points.
        """
        # Discover from entry points
        from xyberos.common.registry import discover_entry_points

        eps = discover_entry_points("xyberos.storage")
        for name, cls in eps.items():
            try:
                instance = cls()
                if self._registry.exists(name):
                    continue
                self._registry.register(name, instance, default=name == "memory")
            except Exception:
                pass

        # Hardcoded fallback for built-in providers
        if not self._registry.exists("memory"):
            from xyberos.storage.memory import InMemoryStorageProvider

            self._registry.register("memory", InMemoryStorageProvider(), default=True)
        if not self._registry.exists("local"):
            from xyberos.storage.local import LocalFileStorageProvider

            self._registry.register("local", LocalFileStorageProvider())

    def register_provider(
        self,
        name: str,
        provider: IStorageProvider,
        *,
        default: bool = False,
    ) -> None:
        """Register a custom storage provider."""
        self._registry.register(name, provider, default=default)
        if name not in self._fallback_order:
            self._fallback_order.append(name)

    # ------------------------------------------------------------------
    # Save
    # ------------------------------------------------------------------

    def save(
        self,
        item: StorageItem,
        provider: str | None = None,
    ) -> None:
        """Persist *item*.

        If *provider* is specified, saves only to that provider.
        Otherwise saves to all available providers for redundancy.
        """
        if provider:
            prov = self._get_provider(provider)
            try:
                prov.save(item)
            except Exception as exc:
                raise SaveError(f"Failed to save in provider '{provider}': {exc}") from exc
            return

        errors: list[str] = []
        for name in reversed(self._fallback_order):  # most durable first
            try:
                prov = self._get_provider(name)
                prov.save(item)
            except Exception as exc:
                errors.append(f"{name}: {exc}")

        if errors:
            logger.warning("Save completed with warnings: %s", "; ".join(errors))

    # ------------------------------------------------------------------
    # Load (fallback chain)
    # ------------------------------------------------------------------

    def load(self, query: StorageQuery) -> StorageResult:
        """
        Execute the fallback chain.

        1. Try the default provider first (fastest).
        2. On miss or failure, try the next provider in order.
        3. Promote found results to the default provider.
        """
        all_items: list[tuple[StorageItem, str]] = []
        queried_providers: list[str] = []

        for provider_name in self._fallback_order:
            try:
                prov = self._get_provider(provider_name)
            except ProviderNotAvailableError:
                continue

            try:
                result = prov.load(query)
            except Exception as exc:
                logger.warning("Load failed on provider '%s': %s", provider_name, exc)
                continue

            queried_providers.append(provider_name)
            for item in result.items:
                all_items.append((item, provider_name))

            # If the default provider returned results, stop early
            if provider_name == self._registry.default_name() and all_items:
                break

        # Promote results to the default provider
        if all_items:
            try:
                default = self._registry.default()
                for item, _ in all_items[: query.limit]:
                    try:
                        default.save(item)
                    except Exception:
                        pass
            except Exception:
                pass

        deduplicated = self._deduplicate(all_items)
        return StorageResult(
            items=[item for item, _ in deduplicated[: query.limit]],
            total_count=len(deduplicated),
            provider="+".join(queried_providers) if queried_providers else "none",
        )

    # ------------------------------------------------------------------
    # Direct provider access
    # ------------------------------------------------------------------

    def get(self, key: str, provider: str | None = None) -> StorageResult:
        """Shorthand to load a single key from the fallback chain or a specific provider."""
        query = StorageQuery(key=key)
        if provider:
            prov = self._get_provider(provider)
            try:
                return prov.load(query)
            except Exception as exc:
                raise LoadError(f"Load failed on provider '{provider}': {exc}") from exc
        return self.load(query)

    def delete(self, key: str, provider: str | None = None) -> bool:
        """Delete from a specific provider, or all providers if ``None``."""
        if provider:
            return self._get_provider(provider).delete(key)
        deleted = False
        for name in reversed(self._fallback_order):
            try:
                if self._get_provider(name).delete(key):
                    deleted = True
            except Exception:
                pass
        return deleted

    def clear(self, provider: str | None = None) -> None:
        """Clear a specific provider, or all providers if ``None``."""
        if provider:
            self._get_provider(provider).clear()
        else:
            for name in self._fallback_order:
                try:
                    self._get_provider(name).clear()
                except Exception as exc:
                    logger.warning("Failed to clear provider '%s': %s", name, exc)

    def count(self, provider: str | None = None) -> int:
        """Count items in a specific provider, or sum across all."""
        if provider:
            return self._get_provider(provider).count()
        total = 0
        for name in self._fallback_order:
            try:
                total += self._get_provider(name).count()
            except Exception:
                pass
        return total

    def exists(self, key: str, provider: str | None = None) -> bool:
        """Check existence in a specific provider, or any provider if ``None``."""
        if provider:
            return self._get_provider(provider).exists(key)
        for name in self._fallback_order:
            try:
                if self._get_provider(name).exists(key):
                    return True
            except Exception:
                pass
        return False

    def list_keys(self, provider: str | None = None) -> list[str]:
        """List all keys from a specific provider, or aggregate across all."""
        if provider:
            return self._get_provider(provider).list_keys()
        keys: set[str] = set()
        for name in self._fallback_order:
            try:
                keys.update(self._get_provider(name).list_keys())
            except Exception:
                pass
        return sorted(keys)

    # ------------------------------------------------------------------
    # Internals
    # ------------------------------------------------------------------

    def _get_provider(self, name: str) -> IStorageProvider:
        try:
            return self._registry.get(name)
        except KeyError as exc:
            raise ProviderNotAvailableError(
                f"Storage provider '{name}' is not registered",
            ) from exc

    @staticmethod
    def _deduplicate(
        items: list[tuple[StorageItem, str]],
    ) -> list[tuple[StorageItem, str]]:
        seen: set[str] = set()
        unique: list[tuple[StorageItem, str]] = []
        for item, prov in items:
            if item.key not in seen:
                seen.add(item.key)
                unique.append((item, prov))
        return unique

clear(provider=None)

Clear a specific provider, or all providers if None.

Source code in xyberos\storage\manager.py

def clear(self, provider: str | None = None) -> None:
    """Clear a specific provider, or all providers if ``None``."""
    if provider:
        self._get_provider(provider).clear()
    else:
        for name in self._fallback_order:
            try:
                self._get_provider(name).clear()
            except Exception as exc:
                logger.warning("Failed to clear provider '%s': %s", name, exc)

count(provider=None)

Count items in a specific provider, or sum across all.

Source code in xyberos\storage\manager.py

def count(self, provider: str | None = None) -> int:
    """Count items in a specific provider, or sum across all."""
    if provider:
        return self._get_provider(provider).count()
    total = 0
    for name in self._fallback_order:
        try:
            total += self._get_provider(name).count()
        except Exception:
            pass
    return total

delete(key, provider=None)

Delete from a specific provider, or all providers if None.

Source code in xyberos\storage\manager.py

def delete(self, key: str, provider: str | None = None) -> bool:
    """Delete from a specific provider, or all providers if ``None``."""
    if provider:
        return self._get_provider(provider).delete(key)
    deleted = False
    for name in reversed(self._fallback_order):
        try:
            if self._get_provider(name).delete(key):
                deleted = True
        except Exception:
            pass
    return deleted

exists(key, provider=None)

Check existence in a specific provider, or any provider if None.

Source code in xyberos\storage\manager.py

def exists(self, key: str, provider: str | None = None) -> bool:
    """Check existence in a specific provider, or any provider if ``None``."""
    if provider:
        return self._get_provider(provider).exists(key)
    for name in self._fallback_order:
        try:
            if self._get_provider(name).exists(key):
                return True
        except Exception:
            pass
    return False

get(key, provider=None)

Shorthand to load a single key from the fallback chain or a specific provider.

Source code in xyberos\storage\manager.py

def get(self, key: str, provider: str | None = None) -> StorageResult:
    """Shorthand to load a single key from the fallback chain or a specific provider."""
    query = StorageQuery(key=key)
    if provider:
        prov = self._get_provider(provider)
        try:
            return prov.load(query)
        except Exception as exc:
            raise LoadError(f"Load failed on provider '{provider}': {exc}") from exc
    return self.load(query)

list_keys(provider=None)

List all keys from a specific provider, or aggregate across all.

Source code in xyberos\storage\manager.py

def list_keys(self, provider: str | None = None) -> list[str]:
    """List all keys from a specific provider, or aggregate across all."""
    if provider:
        return self._get_provider(provider).list_keys()
    keys: set[str] = set()
    for name in self._fallback_order:
        try:
            keys.update(self._get_provider(name).list_keys())
        except Exception:
            pass
    return sorted(keys)

load(query)

Execute the fallback chain.

1. Try the default provider first (fastest).
2. On miss or failure, try the next provider in order.
3. Promote found results to the default provider.

Source code in xyberos\storage\manager.py

def load(self, query: StorageQuery) -> StorageResult:
    """
    Execute the fallback chain.

    1. Try the default provider first (fastest).
    2. On miss or failure, try the next provider in order.
    3. Promote found results to the default provider.
    """
    all_items: list[tuple[StorageItem, str]] = []
    queried_providers: list[str] = []

    for provider_name in self._fallback_order:
        try:
            prov = self._get_provider(provider_name)
        except ProviderNotAvailableError:
            continue

        try:
            result = prov.load(query)
        except Exception as exc:
            logger.warning("Load failed on provider '%s': %s", provider_name, exc)
            continue

        queried_providers.append(provider_name)
        for item in result.items:
            all_items.append((item, provider_name))

        # If the default provider returned results, stop early
        if provider_name == self._registry.default_name() and all_items:
            break

    # Promote results to the default provider
    if all_items:
        try:
            default = self._registry.default()
            for item, _ in all_items[: query.limit]:
                try:
                    default.save(item)
                except Exception:
                    pass
        except Exception:
            pass

    deduplicated = self._deduplicate(all_items)
    return StorageResult(
        items=[item for item, _ in deduplicated[: query.limit]],
        total_count=len(deduplicated),
        provider="+".join(queried_providers) if queried_providers else "none",
    )

register_defaults()

Register all built-in storage providers.

Discovers providers from xyberos.storage entry points first, then falls back to hardcoded imports for built-in providers that are not yet registered via entry points.

Source code in xyberos\storage\manager.py

def register_defaults(self) -> None:
    """Register all built-in storage providers.

    Discovers providers from ``xyberos.storage`` entry points first,
    then falls back to hardcoded imports for built-in providers
    that are not yet registered via entry points.
    """
    # Discover from entry points
    from xyberos.common.registry import discover_entry_points

    eps = discover_entry_points("xyberos.storage")
    for name, cls in eps.items():
        try:
            instance = cls()
            if self._registry.exists(name):
                continue
            self._registry.register(name, instance, default=name == "memory")
        except Exception:
            pass

    # Hardcoded fallback for built-in providers
    if not self._registry.exists("memory"):
        from xyberos.storage.memory import InMemoryStorageProvider

        self._registry.register("memory", InMemoryStorageProvider(), default=True)
    if not self._registry.exists("local"):
        from xyberos.storage.local import LocalFileStorageProvider

        self._registry.register("local", LocalFileStorageProvider())

register_provider(name, provider, *, default=False)

Register a custom storage provider.

Source code in xyberos\storage\manager.py

def register_provider(
    self,
    name: str,
    provider: IStorageProvider,
    *,
    default: bool = False,
) -> None:
    """Register a custom storage provider."""
    self._registry.register(name, provider, default=default)
    if name not in self._fallback_order:
        self._fallback_order.append(name)

save(item, provider=None)

Persist item.

If provider is specified, saves only to that provider. Otherwise saves to all available providers for redundancy.

Source code in xyberos\storage\manager.py

def save(
    self,
    item: StorageItem,
    provider: str | None = None,
) -> None:
    """Persist *item*.

    If *provider* is specified, saves only to that provider.
    Otherwise saves to all available providers for redundancy.
    """
    if provider:
        prov = self._get_provider(provider)
        try:
            prov.save(item)
        except Exception as exc:
            raise SaveError(f"Failed to save in provider '{provider}': {exc}") from exc
        return

    errors: list[str] = []
    for name in reversed(self._fallback_order):  # most durable first
        try:
            prov = self._get_provider(name)
            prov.save(item)
        except Exception as exc:
            errors.append(f"{name}: {exc}")

    if errors:
        logger.warning("Save completed with warnings: %s", "; ".join(errors))

StorageItem dataclass

A single unit of stored data.

Attributes

key: Unique identifier for this storage item (e.g. a file path, object key, or database row ID). content: The stored data — bytes, string, dict, or any serialisable type. metadata: Arbitrary key-value tags (content_type, size, checksum, …). timestamp: When this item was created / last written. ttl_seconds: Time-to-live in seconds. None = permanent.

Source code in xyberos\storage\models.py

@dataclass(slots=True)
class StorageItem:
    """
    A single unit of stored data.

    Attributes
    ----------
    key:
        Unique identifier for this storage item (e.g. a file path,
        object key, or database row ID).
    content:
        The stored data — bytes, string, dict, or any serialisable type.
    metadata:
        Arbitrary key-value tags (content_type, size, checksum, …).
    timestamp:
        When this item was created / last written.
    ttl_seconds:
        Time-to-live in seconds.  ``None`` = permanent.
    """

    key: str
    content: Any
    metadata: dict[str, Any] = field(default_factory=lambda: {})
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    ttl_seconds: float | None = None

    @property
    def is_expired(self) -> bool:
        """Check whether this item has exceeded its TTL."""
        if self.ttl_seconds is None:
            return False
        age = (datetime.now(timezone.utc) - self.timestamp).total_seconds()
        return age > self.ttl_seconds

is_expired property

Check whether this item has exceeded its TTL.

StorageResult dataclass

Result of a storage retrieval.

Attributes

items: Retrieved items, ordered by key (sorted). total_count: Total matching items (useful for pagination). provider: Which provider produced this result.

Source code in xyberos\storage\models.py

@dataclass(slots=True)
class StorageResult:
    """
    Result of a storage retrieval.

    Attributes
    ----------
    items:
        Retrieved items, ordered by key (sorted).
    total_count:
        Total matching items (useful for pagination).
    provider:
        Which provider produced this result.
    """

    items: list[StorageItem] = field(default_factory=lambda: [])
    total_count: int = 0
    provider: str = "unknown"

    @classmethod
    def empty(cls, provider: str = "unknown") -> StorageResult:
        return cls(items=[], total_count=0, provider=provider)

xyberos.database — Database system

xyberos.database

XYBEROS Database subsystem.

Pluggable database backends with a unified interface:

Memory → SQLite → PostgreSQL → MySQL → (custom via entry points)

Every backend implements IDatabaseProvider(Provider) and is registered in the DatabaseRegistry. The DatabaseManager orchestrates connection lifecycle, query execution, transaction management, and schema migrations across named providers.

Sub-modules

• interfaces — IDatabaseProvider abstract base class.
• registry — DatabaseRegistry(ProviderRegistry[IDatabaseProvider]).
• manager — DatabaseManager with event-bus integration.
• service — DatabaseService(ProviderService[IDatabaseProvider]) for lightweight registry access.
• pool — ConnectionPool for reusable connection management.
• models — Data models: ConnectionConfig, Query, QueryResult, Migration, DatabaseStats.
• exceptions — Exception hierarchy.
• events — Event name constants for event-bus integration.
• providers — Built-in backends (memory, SQLite).

Typical usage::

from xyberos.database import DatabaseManager, ConnectionConfig

mgr = DatabaseManager()
mgr.register_defaults()

# Connect a SQLite database
mgr.connect(ConnectionConfig.for_sqlite("my_app.db"))

# Execute a query
result = mgr.execute("SELECT * FROM users")
for row in result.rows:
    print(row)

# Transactional block
with mgr.transaction():
    mgr.execute(
        "INSERT INTO users (name) VALUES (?)",
        params=("Alice",),
    )

DatabaseManager

Orchestrates database access across multiple providers.

The manager maintains a registry of database providers and supports:

• Named provider selection (connect to "default", "analytics", …)
• Connection lifecycle management
• Query execution with timing, monitoring, and event-bus integration
• Transaction context managers
• Schema migration orchestration

Usage::

mgr = DatabaseManager()
mgr.register_defaults()

# Connect the default provider
mgr.connect(ConnectionConfig.for_sqlite("app.db"))

# Execute a query
result = mgr.execute("SELECT * FROM users")

# Transaction context
with mgr.transaction():
    mgr.execute("INSERT INTO users (name) VALUES (?)", params=("Alice",))

Source code in xyberos\database\manager.py

class DatabaseManager:
    """
    Orchestrates database access across multiple providers.

    The manager maintains a registry of database providers and
    supports:

    * Named provider selection (connect to ``"default"``, ``"analytics"``, …)
    * Connection lifecycle management
    * Query execution with timing, monitoring, and event-bus integration
    * Transaction context managers
    * Schema migration orchestration

    Usage::

        mgr = DatabaseManager()
        mgr.register_defaults()

        # Connect the default provider
        mgr.connect(ConnectionConfig.for_sqlite("app.db"))

        # Execute a query
        result = mgr.execute("SELECT * FROM users")

        # Transaction context
        with mgr.transaction():
            mgr.execute("INSERT INTO users (name) VALUES (?)", params=("Alice",))
    """

    def __init__(
        self,
        registry: DatabaseRegistry | None = None,
        *,
        plugin_manager: PluginManager | None = None,
    ) -> None:
        self._registry = registry or DatabaseRegistry()
        self._default_name: str = "default"
        self._monitor = _monitor()
        self._event_bus = resolve_event_bus()

        # Wire into the plugin manager if provided
        if plugin_manager is not None:
            plugin_manager.register_component_registry("database", self._registry)
            logger.info("DatabaseManager connected to PluginManager")

    # ── Properties ───────────────────────────────────────────────

    @property
    def registry(self) -> DatabaseRegistry:
        """Return the underlying database provider registry."""
        return self._registry

    @property
    def default_name(self) -> str:
        """Return the name of the default provider alias."""
        return self._default_name

    @default_name.setter
    def default_name(self, value: str) -> None:
        self._default_name = value

    @property
    def event_bus(self) -> Any:
        """Return the event bus used for publishing database events.

        Returns the kernel ``EventBusService`` if available, otherwise
        a no-op ``_NullEventBus``.
        """
        return self._event_bus

    # ── Registration helpers ─────────────────────────────────────

    def register_defaults(self) -> None:
        """Register all built-in database providers.

        Discovers providers from ``xyberos.database`` entry points first,
        then falls back to hardcoded imports for built-in providers
        that are not yet registered via entry points.
        """
        # Discover from entry points
        from xyberos.common.registry import discover_entry_points

        eps = discover_entry_points("xyberos.database")
        for name, cls in eps.items():
            try:
                instance = cls()
                if self._registry.exists(name):
                    continue
                self._registry.register(name, instance, default=name == "sqlite")
            except Exception:
                pass

        # Hardcoded fallback for built-in providers
        if not self._registry.exists("memory"):
            from xyberos.database.providers.memory import InMemoryDatabaseProvider

            self._registry.register("memory", InMemoryDatabaseProvider())
        if not self._registry.exists("sqlite"):
            from xyberos.database.providers.sqlite import SQLiteProvider

            self._registry.register("sqlite", SQLiteProvider(), default=True)

    def register_provider(
        self,
        name: str,
        provider: IDatabaseProvider,
        *,
        default: bool = False,
    ) -> None:
        """Register a custom database provider."""
        self._registry.register(name, provider, default=default)

    # ── Connection lifecycle ─────────────────────────────────────

    def connect(
        self,
        config: ConnectionConfig,
        provider: str | None = None,
    ) -> None:
        """
        Open a connection on the specified *provider* (or the default).

        Parameters
        ----------
        config:
            Connection configuration.
        provider:
            Provider name to connect.  Uses ``self.default_name`` when
            ``None``.
        """
        name = provider or self._default_name
        prov = self._get_provider(name)
        self._event_bus.publish(
            _make_event(DATABASE_CONNECTING, source=name, dsn=config.dsn),
        )
        try:
            prov.connect(config)
            logger.info(
                "Connected to '%s' using provider '%s'",
                config.dsn, name,
            )
            self._event_bus.publish(
                _make_event(
                    DATABASE_CONNECTED,
                    source=name,
                    dsn=config.dsn,
                    database_type=config.database_type.value,
                ),
            )
        except Exception as exc:
            self._event_bus.publish(
                _make_event(
                    DATABASE_CONNECTED,
                    source=name,
                    dsn=config.dsn,
                    error=str(exc),
                ),
            )
            raise ConnectionError(
                f"Failed to connect provider '{name}': {exc}",
            ) from exc

    def disconnect(self, provider: str | None = None) -> None:
        """
        Close the connection on the specified *provider*.

        If *provider* is ``None``, disconnects all registered providers.
        """
        if provider:
            self._get_provider(provider).disconnect()
            self._event_bus.publish(
                _make_event(DATABASE_DISCONNECTED, source=provider),
            )
            return
        for name in self._registry.names():
            try:
                prov = self._registry.get(name)
                prov.disconnect()
                self._event_bus.publish(
                    _make_event(DATABASE_DISCONNECTED, source=name),
                )
            except Exception as exc:
                logger.warning("Error disconnecting provider '%s': %s", name, exc)

    def dispose(self, provider: str | None = None) -> None:
        """
        Dispose of all resources held by the specified *provider*.

        If *provider* is ``None``, disposes all registered providers.
        """
        if provider:
            self._get_provider(provider).dispose()
            return
        for name in self._registry.names():
            try:
                prov = self._registry.get(name)
                prov.dispose()
            except Exception as exc:
                logger.warning("Error disposing provider '%s': %s", name, exc)

    # ── Query execution ──────────────────────────────────────────

    def execute(
        self,
        statement: str,
        *,
        params: tuple[Any, ...] | dict[str, Any] | None = None,
        fetch: int = 0,
        timeout: float | None = None,
        provider: str | None = None,
    ) -> QueryResult:
        """
        Execute a SQL statement and return the result.

        Parameters
        ----------
        statement:
            SQL statement with ``?`` or ``%s`` placeholders.
        params:
            Positional or named parameters.
        fetch:
            Maximum rows to fetch (``0`` = all).
        timeout:
            Query timeout in seconds.
        provider:
            Provider to execute on.  Uses ``self.default_name`` when
            ``None``.

        Returns
        -------
        QueryResult
        """
        name = provider or self._default_name
        prov = self._get_provider(name)
        query = Query(
            statement=statement,
            params=params,
            timeout=timeout,
            fetch=fetch,
        )
        start = time.perf_counter()
        self._event_bus.publish(
            _make_event(
                DATABASE_QUERY_STARTED,
                source=name,
                statement=statement[:200],
            ),
        )
        try:
            result = prov.execute(query)
        except Exception as exc:
            elapsed = (time.perf_counter() - start) * 1000
            self._monitor.count("database.query.errors", 1)
            self._monitor.timing(
                "database.query.duration", elapsed,
                provider=name, status="error",
            )
            self._event_bus.publish(
                _make_event(
                    DATABASE_QUERY_FAILED,
                    source=name,
                    statement=statement[:200],
                    error=str(exc),
                    duration_ms=elapsed,
                ),
            )
            raise QueryError(
                f"Query failed on provider '{name}': {exc}",
            ) from exc
        else:
            elapsed = (time.perf_counter() - start) * 1000
            result.duration_ms = elapsed
            self._monitor.count("database.query.throughput", 1)
            self._monitor.timing(
                "database.query.duration", elapsed,
                provider=name, status="ok",
            )
            self._event_bus.publish(
                _make_event(
                    DATABASE_QUERY_COMPLETED,
                    source=name,
                    statement=statement[:200],
                    row_count=result.row_count,
                    duration_ms=elapsed,
                ),
            )
            return result

    def execute_many(
        self,
        statement: str,
        params: list[tuple[Any, ...]],
        *,
        provider: str | None = None,
    ) -> int:
        """
        Execute a statement with multiple parameter sets.

        Returns the total number of rows affected.
        """
        name = provider or self._default_name
        prov = self._get_provider(name)
        try:
            return prov.execute_many(statement, params)
        except Exception as exc:
            raise QueryError(
                f"Batch query failed on provider '{name}': {exc}",
            ) from exc

    def execute_script(
        self,
        sql: str,
        *,
        provider: str | None = None,
    ) -> None:
        """Execute a multi-statement SQL script."""
        name = provider or self._default_name
        prov = self._get_provider(name)
        try:
            prov.execute_script(sql)
        except Exception as exc:
            raise QueryError(
                f"Script execution failed on provider '{name}': {exc}",
            ) from exc

    # ── Transactions ─────────────────────────────────────────────

    @contextmanager
    def transaction(
        self,
        provider: str | None = None,
    ) -> Generator[DatabaseManager, None, None]:
        """
        Context manager for transactional execution.

        Usage::

            with mgr.transaction():
                mgr.execute("INSERT INTO users (name) VALUES (?)", params=("Alice",))
                mgr.execute("INSERT INTO logs (msg) VALUES (?)", params=("created",))
        """
        name = provider or self._default_name
        prov = self._get_provider(name)
        try:
            prov.begin()
            self._event_bus.publish(
                _make_event(DATABASE_TRANSACTION_STARTED, source=name),
            )
        except Exception as exc:
            raise DatabaseError(
                f"Failed to begin transaction on provider '{name}': {exc}",
            ) from exc

        try:
            yield self
        except Exception:
            try:
                prov.rollback()
                logger.info("Transaction rolled back on provider '%s'", name)
                self._event_bus.publish(
                    _make_event(DATABASE_TRANSACTION_FAILED, source=name),
                )
            except Exception as rb_exc:
                logger.warning(
                    "Rollback failed on provider '%s': %s", name, rb_exc,
                )
            raise
        else:
            try:
                prov.commit()
                self._event_bus.publish(
                    _make_event(DATABASE_TRANSACTION_COMPLETED, source=name),
                )
            except Exception as exc:
                raise DatabaseError(
                    f"Failed to commit transaction on provider '{name}': {exc}",
                ) from exc

    # ── Introspection ────────────────────────────────────────────

    def table_exists(
        self,
        table_name: str,
        *,
        provider: str | None = None,
    ) -> bool:
        """Check whether *table_name* exists."""
        name = provider or self._default_name
        prov = self._get_provider(name)
        return prov.table_exists(table_name)

    def list_tables(
        self,
        *,
        provider: str | None = None,
    ) -> list[str]:
        """Return all table names."""
        name = provider or self._default_name
        prov = self._get_provider(name)
        return prov.list_tables()

    def stats(
        self,
        *,
        provider: str | None = None,
    ) -> DatabaseStats:
        """Return runtime statistics for a provider."""
        name = provider or self._default_name
        prov = self._get_provider(name)
        return prov.stats()

    # ── Migrations ───────────────────────────────────────────────

    def migrate(
        self,
        migrations: list[Migration],
        *,
        provider: str | None = None,
    ) -> None:
        """Apply pending migrations on the specified provider."""
        name = provider or self._default_name
        prov = self._get_provider(name)
        self._event_bus.publish(
            _make_event(
                DATABASE_MIGRATION_STARTED,
                source=name,
                count=len(migrations),
                versions=[m.version for m in migrations],
            ),
        )
        try:
            prov.migrate(migrations)
            logger.info(
                "Applied %d migration(s) on provider '%s'",
                len(migrations), name,
            )
            self._event_bus.publish(
                _make_event(
                    DATABASE_MIGRATION_COMPLETED,
                    source=name,
                    count=len(migrations),
                ),
            )
        except Exception as exc:
            self._event_bus.publish(
                _make_event(
                    DATABASE_MIGRATION_FAILED,
                    source=name,
                    error=str(exc),
                ),
            )
            raise MigrationError(
                f"Migration failed on provider '{name}': {exc}",
            ) from exc

    # ── Internal ─────────────────────────────────────────────────

    def _get_provider(self, name: str) -> IDatabaseProvider:
        """Resolve a provider by name or raise."""
        if not self._registry.exists(name):
            raise ProviderNotAvailableError(
                f"Database provider '{name}' is not registered. "
                f"Available: {list(self._registry.names())}",
            )
        return self._registry.get(name)

    def __repr__(self) -> str:
        return (
            f"DatabaseManager(providers={list(self._registry.names())})"
        )

default_name property writable

Return the name of the default provider alias.

event_bus property

Return the event bus used for publishing database events.

Returns the kernel EventBusService if available, otherwise a no-op _NullEventBus.

registry property

Return the underlying database provider registry.

connect(config, provider=None)

Open a connection on the specified provider (or the default).

Parameters

config: Connection configuration. provider: Provider name to connect. Uses self.default_name when None.

Source code in xyberos\database\manager.py

def connect(
    self,
    config: ConnectionConfig,
    provider: str | None = None,
) -> None:
    """
    Open a connection on the specified *provider* (or the default).

    Parameters
    ----------
    config:
        Connection configuration.
    provider:
        Provider name to connect.  Uses ``self.default_name`` when
        ``None``.
    """
    name = provider or self._default_name
    prov = self._get_provider(name)
    self._event_bus.publish(
        _make_event(DATABASE_CONNECTING, source=name, dsn=config.dsn),
    )
    try:
        prov.connect(config)
        logger.info(
            "Connected to '%s' using provider '%s'",
            config.dsn, name,
        )
        self._event_bus.publish(
            _make_event(
                DATABASE_CONNECTED,
                source=name,
                dsn=config.dsn,
                database_type=config.database_type.value,
            ),
        )
    except Exception as exc:
        self._event_bus.publish(
            _make_event(
                DATABASE_CONNECTED,
                source=name,
                dsn=config.dsn,
                error=str(exc),
            ),
        )
        raise ConnectionError(
            f"Failed to connect provider '{name}': {exc}",
        ) from exc

disconnect(provider=None)

Close the connection on the specified provider.

If provider is None, disconnects all registered providers.

Source code in xyberos\database\manager.py

def disconnect(self, provider: str | None = None) -> None:
    """
    Close the connection on the specified *provider*.

    If *provider* is ``None``, disconnects all registered providers.
    """
    if provider:
        self._get_provider(provider).disconnect()
        self._event_bus.publish(
            _make_event(DATABASE_DISCONNECTED, source=provider),
        )
        return
    for name in self._registry.names():
        try:
            prov = self._registry.get(name)
            prov.disconnect()
            self._event_bus.publish(
                _make_event(DATABASE_DISCONNECTED, source=name),
            )
        except Exception as exc:
            logger.warning("Error disconnecting provider '%s': %s", name, exc)

dispose(provider=None)

Dispose of all resources held by the specified provider.

If provider is None, disposes all registered providers.

Source code in xyberos\database\manager.py

def dispose(self, provider: str | None = None) -> None:
    """
    Dispose of all resources held by the specified *provider*.

    If *provider* is ``None``, disposes all registered providers.
    """
    if provider:
        self._get_provider(provider).dispose()
        return
    for name in self._registry.names():
        try:
            prov = self._registry.get(name)
            prov.dispose()
        except Exception as exc:
            logger.warning("Error disposing provider '%s': %s", name, exc)

execute(statement, *, params=None, fetch=0, timeout=None, provider=None)

Execute a SQL statement and return the result.

Parameters

statement: SQL statement with ? or %s placeholders. params: Positional or named parameters. fetch: Maximum rows to fetch (0 = all). timeout: Query timeout in seconds. provider: Provider to execute on. Uses self.default_name when None.

Returns

QueryResult

Source code in xyberos\database\manager.py

def execute(
    self,
    statement: str,
    *,
    params: tuple[Any, ...] | dict[str, Any] | None = None,
    fetch: int = 0,
    timeout: float | None = None,
    provider: str | None = None,
) -> QueryResult:
    """
    Execute a SQL statement and return the result.

    Parameters
    ----------
    statement:
        SQL statement with ``?`` or ``%s`` placeholders.
    params:
        Positional or named parameters.
    fetch:
        Maximum rows to fetch (``0`` = all).
    timeout:
        Query timeout in seconds.
    provider:
        Provider to execute on.  Uses ``self.default_name`` when
        ``None``.

    Returns
    -------
    QueryResult
    """
    name = provider or self._default_name
    prov = self._get_provider(name)
    query = Query(
        statement=statement,
        params=params,
        timeout=timeout,
        fetch=fetch,
    )
    start = time.perf_counter()
    self._event_bus.publish(
        _make_event(
            DATABASE_QUERY_STARTED,
            source=name,
            statement=statement[:200],
        ),
    )
    try:
        result = prov.execute(query)
    except Exception as exc:
        elapsed = (time.perf_counter() - start) * 1000
        self._monitor.count("database.query.errors", 1)
        self._monitor.timing(
            "database.query.duration", elapsed,
            provider=name, status="error",
        )
        self._event_bus.publish(
            _make_event(
                DATABASE_QUERY_FAILED,
                source=name,
                statement=statement[:200],
                error=str(exc),
                duration_ms=elapsed,
            ),
        )
        raise QueryError(
            f"Query failed on provider '{name}': {exc}",
        ) from exc
    else:
        elapsed = (time.perf_counter() - start) * 1000
        result.duration_ms = elapsed
        self._monitor.count("database.query.throughput", 1)
        self._monitor.timing(
            "database.query.duration", elapsed,
            provider=name, status="ok",
        )
        self._event_bus.publish(
            _make_event(
                DATABASE_QUERY_COMPLETED,
                source=name,
                statement=statement[:200],
                row_count=result.row_count,
                duration_ms=elapsed,
            ),
        )
        return result

execute_many(statement, params, *, provider=None)

Execute a statement with multiple parameter sets.

Returns the total number of rows affected.

Source code in xyberos\database\manager.py

def execute_many(
    self,
    statement: str,
    params: list[tuple[Any, ...]],
    *,
    provider: str | None = None,
) -> int:
    """
    Execute a statement with multiple parameter sets.

    Returns the total number of rows affected.
    """
    name = provider or self._default_name
    prov = self._get_provider(name)
    try:
        return prov.execute_many(statement, params)
    except Exception as exc:
        raise QueryError(
            f"Batch query failed on provider '{name}': {exc}",
        ) from exc

execute_script(sql, *, provider=None)

Execute a multi-statement SQL script.

Source code in xyberos\database\manager.py

def execute_script(
    self,
    sql: str,
    *,
    provider: str | None = None,
) -> None:
    """Execute a multi-statement SQL script."""
    name = provider or self._default_name
    prov = self._get_provider(name)
    try:
        prov.execute_script(sql)
    except Exception as exc:
        raise QueryError(
            f"Script execution failed on provider '{name}': {exc}",
        ) from exc

list_tables(*, provider=None)

Return all table names.

Source code in xyberos\database\manager.py

def list_tables(
    self,
    *,
    provider: str | None = None,
) -> list[str]:
    """Return all table names."""
    name = provider or self._default_name
    prov = self._get_provider(name)
    return prov.list_tables()

migrate(migrations, *, provider=None)

Apply pending migrations on the specified provider.

Source code in xyberos\database\manager.py

def migrate(
    self,
    migrations: list[Migration],
    *,
    provider: str | None = None,
) -> None:
    """Apply pending migrations on the specified provider."""
    name = provider or self._default_name
    prov = self._get_provider(name)
    self._event_bus.publish(
        _make_event(
            DATABASE_MIGRATION_STARTED,
            source=name,
            count=len(migrations),
            versions=[m.version for m in migrations],
        ),
    )
    try:
        prov.migrate(migrations)
        logger.info(
            "Applied %d migration(s) on provider '%s'",
            len(migrations), name,
        )
        self._event_bus.publish(
            _make_event(
                DATABASE_MIGRATION_COMPLETED,
                source=name,
                count=len(migrations),
            ),
        )
    except Exception as exc:
        self._event_bus.publish(
            _make_event(
                DATABASE_MIGRATION_FAILED,
                source=name,
                error=str(exc),
            ),
        )
        raise MigrationError(
            f"Migration failed on provider '{name}': {exc}",
        ) from exc

register_defaults()

Register all built-in database providers.

Discovers providers from xyberos.database entry points first, then falls back to hardcoded imports for built-in providers that are not yet registered via entry points.

Source code in xyberos\database\manager.py

def register_defaults(self) -> None:
    """Register all built-in database providers.

    Discovers providers from ``xyberos.database`` entry points first,
    then falls back to hardcoded imports for built-in providers
    that are not yet registered via entry points.
    """
    # Discover from entry points
    from xyberos.common.registry import discover_entry_points

    eps = discover_entry_points("xyberos.database")
    for name, cls in eps.items():
        try:
            instance = cls()
            if self._registry.exists(name):
                continue
            self._registry.register(name, instance, default=name == "sqlite")
        except Exception:
            pass

    # Hardcoded fallback for built-in providers
    if not self._registry.exists("memory"):
        from xyberos.database.providers.memory import InMemoryDatabaseProvider

        self._registry.register("memory", InMemoryDatabaseProvider())
    if not self._registry.exists("sqlite"):
        from xyberos.database.providers.sqlite import SQLiteProvider

        self._registry.register("sqlite", SQLiteProvider(), default=True)

register_provider(name, provider, *, default=False)

Register a custom database provider.

Source code in xyberos\database\manager.py

def register_provider(
    self,
    name: str,
    provider: IDatabaseProvider,
    *,
    default: bool = False,
) -> None:
    """Register a custom database provider."""
    self._registry.register(name, provider, default=default)

stats(*, provider=None)

Return runtime statistics for a provider.

Source code in xyberos\database\manager.py

def stats(
    self,
    *,
    provider: str | None = None,
) -> DatabaseStats:
    """Return runtime statistics for a provider."""
    name = provider or self._default_name
    prov = self._get_provider(name)
    return prov.stats()

table_exists(table_name, *, provider=None)

Check whether table_name exists.

Source code in xyberos\database\manager.py

def table_exists(
    self,
    table_name: str,
    *,
    provider: str | None = None,
) -> bool:
    """Check whether *table_name* exists."""
    name = provider or self._default_name
    prov = self._get_provider(name)
    return prov.table_exists(table_name)

transaction(provider=None)

Context manager for transactional execution.

Usage::

with mgr.transaction():
    mgr.execute("INSERT INTO users (name) VALUES (?)", params=("Alice",))
    mgr.execute("INSERT INTO logs (msg) VALUES (?)", params=("created",))

Source code in xyberos\database\manager.py

@contextmanager
def transaction(
    self,
    provider: str | None = None,
) -> Generator[DatabaseManager, None, None]:
    """
    Context manager for transactional execution.

    Usage::

        with mgr.transaction():
            mgr.execute("INSERT INTO users (name) VALUES (?)", params=("Alice",))
            mgr.execute("INSERT INTO logs (msg) VALUES (?)", params=("created",))
    """
    name = provider or self._default_name
    prov = self._get_provider(name)
    try:
        prov.begin()
        self._event_bus.publish(
            _make_event(DATABASE_TRANSACTION_STARTED, source=name),
        )
    except Exception as exc:
        raise DatabaseError(
            f"Failed to begin transaction on provider '{name}': {exc}",
        ) from exc

    try:
        yield self
    except Exception:
        try:
            prov.rollback()
            logger.info("Transaction rolled back on provider '%s'", name)
            self._event_bus.publish(
                _make_event(DATABASE_TRANSACTION_FAILED, source=name),
            )
        except Exception as rb_exc:
            logger.warning(
                "Rollback failed on provider '%s': %s", name, rb_exc,
            )
        raise
    else:
        try:
            prov.commit()
            self._event_bus.publish(
                _make_event(DATABASE_TRANSACTION_COMPLETED, source=name),
            )
        except Exception as exc:
            raise DatabaseError(
                f"Failed to commit transaction on provider '{name}': {exc}",
            ) from exc

ConnectionConfig dataclass

Configuration for a database connection.

Attributes

database_type: The database engine type. host: Server hostname (not used for SQLite). port: Server port (not used for SQLite). database: Database name (for SQLite this is the file path). username: Authentication username. password: Authentication password. pool_size: Maximum connection pool size (0 = no pooling). pool_timeout: Seconds to wait for a connection from the pool. isolation_level: Default transaction isolation level. extra: Engine-specific keyword arguments (e.g. ssl_mode).

Source code in xyberos\database\models.py

@dataclass(slots=True)
class ConnectionConfig:
    """
    Configuration for a database connection.

    Attributes
    ----------
    database_type:
        The database engine type.
    host:
        Server hostname (not used for SQLite).
    port:
        Server port (not used for SQLite).
    database:
        Database name (for SQLite this is the file path).
    username:
        Authentication username.
    password:
        Authentication password.
    pool_size:
        Maximum connection pool size (0 = no pooling).
    pool_timeout:
        Seconds to wait for a connection from the pool.
    isolation_level:
        Default transaction isolation level.
    extra:
        Engine-specific keyword arguments (e.g. ``ssl_mode``).
    """

    database_type: DatabaseType = DatabaseType.SQLITE
    host: str = "localhost"
    port: int = 0
    database: str = ":memory:"
    username: str = ""
    password: str = ""
    pool_size: int = 5
    pool_timeout: float = 30.0
    isolation_level: IsolationLevel = IsolationLevel.READ_COMMITTED
    extra: dict[str, Any] = field(default_factory=lambda: {})

    @classmethod
    def for_sqlite(cls, path: str = ":memory:") -> ConnectionConfig:
        """Convenience factory for a SQLite config."""
        return cls(database_type=DatabaseType.SQLITE, database=path)

    @classmethod
    def for_postgres(
        cls,
        *,
        host: str = "localhost",
        port: int = 5432,
        database: str = "postgres",
        username: str = "postgres",
        password: str = "",
        pool_size: int = 10,
    ) -> ConnectionConfig:
        """Convenience factory for a PostgreSQL config."""
        return cls(
            database_type=DatabaseType.POSTGRESQL,
            host=host,
            port=port,
            database=database,
            username=username,
            password=password,
            pool_size=pool_size,
        )

    @property
    def dsn(self) -> str:
        """Return a DSN-style connection string."""
        if self.database_type == DatabaseType.SQLITE:
            return f"sqlite:///{self.database}"
        scheme = self.database_type.value
        creds = f"{self.username}:{self.password}@" if self.username else ""
        return f"{scheme}://{creds}{self.host}:{self.port}/{self.database}"

dsn property

Return a DSN-style connection string.

for_postgres(*, host='localhost', port=5432, database='postgres', username='postgres', password='', pool_size=10) classmethod

Convenience factory for a PostgreSQL config.

Source code in xyberos\database\models.py

@classmethod
def for_postgres(
    cls,
    *,
    host: str = "localhost",
    port: int = 5432,
    database: str = "postgres",
    username: str = "postgres",
    password: str = "",
    pool_size: int = 10,
) -> ConnectionConfig:
    """Convenience factory for a PostgreSQL config."""
    return cls(
        database_type=DatabaseType.POSTGRESQL,
        host=host,
        port=port,
        database=database,
        username=username,
        password=password,
        pool_size=pool_size,
    )

for_sqlite(path=':memory:') classmethod

Convenience factory for a SQLite config.

Source code in xyberos\database\models.py

@classmethod
def for_sqlite(cls, path: str = ":memory:") -> ConnectionConfig:
    """Convenience factory for a SQLite config."""
    return cls(database_type=DatabaseType.SQLITE, database=path)

QueryResult dataclass

Result of a query execution.

Attributes

rows: Fetched rows as a list of dicts (column name → value). row_count: Number of rows affected (for INSERT/UPDATE/DELETE). columns: Column names from the result set. duration_ms: Execution time in milliseconds. provider: Which provider produced this result.

Source code in xyberos\database\models.py

@dataclass(slots=True)
class QueryResult:
    """
    Result of a query execution.

    Attributes
    ----------
    rows:
        Fetched rows as a list of dicts (column name → value).
    row_count:
        Number of rows affected (for INSERT/UPDATE/DELETE).
    columns:
        Column names from the result set.
    duration_ms:
        Execution time in milliseconds.
    provider:
        Which provider produced this result.
    """

    rows: list[dict[str, Any]] = field(default_factory=lambda: [])
    row_count: int = 0
    columns: list[str] = field(default_factory=lambda: [])
    duration_ms: float = 0.0
    provider: str = "unknown"

    @classmethod
    def empty(cls, provider: str = "unknown") -> QueryResult:
        """Return an empty result."""
        return cls(rows=[], row_count=0, provider=provider)

empty(provider='unknown') classmethod

Return an empty result.

Source code in xyberos\database\models.py

@classmethod
def empty(cls, provider: str = "unknown") -> QueryResult:
    """Return an empty result."""
    return cls(rows=[], row_count=0, provider=provider)

xyberos.common — Common abstractions

xyberos.common

xyberos.common — Zero-dependency shared layer for the XYBEROS platform.

Provides the foundational abstractions used by every subsystem:

provider            — Provider(ABC) base class with name, priority, enabled,
                      capability, and can_handle
registry            — ProviderRegistry[T] generic registry with entry-point
                      discovery, capability-based selection, and graceful
                      degradation
service             — ProviderService[T] convenience wrapper around a registry
pipeline            — Pipeline[T] generic sequential processor chain
capabilities        — ProviderCapability dataclass + phase factory helpers
errors              — XyberosError base with contextual error information
types               — Factory helpers for slotted dataclass fields
guards              — Input validation helpers
plugin              — discover_entry_points, discover_and_register,
                      select_best_provider, fallback_execute

Provider

Bases: ABC

Base class for every provider in XYBEROS.

Every provider — whether for language detection, entity extraction, safety evaluation, or embedding — inherits from this class.

Subclasses must provide a unique name and may optionally override priority (higher = runs first), enabled, capability, and can_handle.

Source code in xyberos\common\provider.py

class Provider(ABC):
    """
    Base class for every provider in XYBEROS.

    Every provider — whether for language detection, entity extraction,
    safety evaluation, or embedding — inherits from this class.

    Subclasses must provide a unique *name* and may optionally override
    *priority* (higher = runs first), *enabled*, *capability*, and
    *can_handle*.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """
        Unique provider name (e.g. ``"regex"``, ``"lingua"``).
        """
        ...

    @name.setter
    def name(self, value: str) -> None:
        """Allow subclasses that also extend Plugin to share the backing field."""
        self._name = value

    @property
    def priority(self) -> int:
        """
        Execution priority. Higher values run first.
        """
        return 0

    @property
    def enabled(self) -> bool:
        """
        Whether this provider is currently active.
        """
        return True

    @property
    def capability(self) -> ProviderCapability:
        """
        Self-declared capability of this provider.

        Defaults to a Phase 1 deterministic capability.
        Override in subclasses to declare actual capabilities.
        """
        return deterministic_capability(description=f"{self.name} provider")

    def can_handle(self, input: Any) -> bool:
        """
        Determine whether this provider can process *input*.

        The default implementation returns ``True`` for any input.
        Override in subclasses to implement capability gating
        based on input content, size, language, or other criteria.

        Parameters
        ----------
        input :
            The input to check (e.g. a string, an Observation, etc.).
            The type depends on the specific provider interface.

        Returns
        -------
        bool
            ``True`` if this provider can handle *input*.
        """
        return True

capability property

Self-declared capability of this provider.

Defaults to a Phase 1 deterministic capability. Override in subclasses to declare actual capabilities.

enabled property

Whether this provider is currently active.

name abstractmethod property writable

Unique provider name (e.g. "regex", "lingua").

priority property

Execution priority. Higher values run first.

can_handle(input)

Determine whether this provider can process input.

The default implementation returns True for any input. Override in subclasses to implement capability gating based on input content, size, language, or other criteria.

Parameters

input : The input to check (e.g. a string, an Observation, etc.). The type depends on the specific provider interface.

Returns

bool True if this provider can handle input.

Source code in xyberos\common\provider.py

def can_handle(self, input: Any) -> bool:
    """
    Determine whether this provider can process *input*.

    The default implementation returns ``True`` for any input.
    Override in subclasses to implement capability gating
    based on input content, size, language, or other criteria.

    Parameters
    ----------
    input :
        The input to check (e.g. a string, an Observation, etc.).
        The type depends on the specific provider interface.

    Returns
    -------
    bool
        ``True`` if this provider can handle *input*.
    """
    return True

ProviderRegistry

Bases: Generic[T]

Generic registry for typed providers.

Manages a named collection of providers and tracks a default. Used throughout XYBEROS by every subsystem that supports pluggable backends.

Usage::

registry: ProviderRegistry[ILanguageProvider] = ProviderRegistry()
registry.register("lingua", LinguaLanguageProvider(), default=True)
provider = registry.default()

Source code in xyberos\common\registry.py

class ProviderRegistry(Generic[T]):
    """
    Generic registry for typed providers.

    Manages a named collection of providers and tracks a default.
    Used throughout XYBEROS by every subsystem that supports
    pluggable backends.

    Usage::

        registry: ProviderRegistry[ILanguageProvider] = ProviderRegistry()
        registry.register("lingua", LinguaLanguageProvider(), default=True)
        provider = registry.default()
    """

    def __init__(self) -> None:
        self._providers: dict[str, T] = {}
        self._default: str | None = None

    # ── Registration ────────────────────────────────────────────

    def register(
        self,
        name: str,
        provider: T,
        *,
        default: bool = False,
    ) -> None:
        """
        Register a provider under *name*.

        If *default* is ``True`` or no default has been set yet,
        this provider becomes the default.
        """
        self._providers[name] = provider
        if default or self._default is None:
            self._default = name

    def remove(
        self,
        name: str,
    ) -> None:
        """
        Unregister a provider.  No-op if *name* does not exist.
        """
        if name not in self._providers:
            return
        del self._providers[name]
        if self._default == name:
            self._default = (
                next(iter(self._providers))
                if self._providers
                else None
            )

    def clear(self) -> None:
        """Remove all registered providers."""
        self._providers.clear()
        self._default = None

    # ── Query ───────────────────────────────────────────────────

    def exists(self, name: str) -> bool:
        """Check whether a provider is registered under *name*."""
        return name in self._providers

    def get(self, name: str) -> T:
        """Retrieve a provider by *name*.  Raises ``KeyError`` if missing."""
        try:
            return self._providers[name]
        except KeyError as exc:
            raise KeyError(
                f"Provider '{name}' is not registered."
            ) from exc

    def names(self) -> tuple[str, ...]:
        """Return sorted provider names."""
        return tuple(sorted(self._providers.keys()))

    def all(self) -> list[T]:
        """Return all registered providers (in insertion order)."""
        return list(self._providers.values())

    # ── Default ─────────────────────────────────────────────────

    def default(self) -> T:
        """Return the default provider.  Raises ``RuntimeError`` if none."""
        if self._default is None:
            raise RuntimeError(
                "No default provider has been registered."
            )
        return self._providers[self._default]

    def default_name(self) -> str:
        """Return the name of the default provider."""
        if self._default is None:
            raise RuntimeError(
                "No default provider has been registered."
            )
        return self._default

    def set_default(self, name: str) -> None:
        """Set the default provider by *name*."""
        if name not in self._providers:
            raise KeyError(
                f"Provider '{name}' is not registered."
            )
        self._default = name

    # ── Entry-point discovery ───────────────────────────────────

    def discover(
        self,
        group: str,
        *,
        extra_groups: list[str] | None = None,
        default_name: str | None = None,
    ) -> list[str]:
        """
        Discover and register plugins via Python entry points.

        Parameters
        ----------
        group :
            Entry point group (e.g. ``"xyberos.providers"``).
        extra_groups :
            Additional groups for backward compatibility.
        default_name :
            If given, set this entry as the default.

        Returns
        -------
        list[str]
            Names of successfully registered providers.
        """
        return discover_and_register(
            self, group,
            extra_groups=extra_groups,
            default_name=default_name,
        )

    # ── Capability-based selection ──────────────────────────────

    def best(self, input: Any, *, max_phase: int | None = None, prefer_fast: bool = False) -> T | None:
        """
        Select the best registered provider for *input*.

        Uses :func:`select_best_provider` to evaluate all
        registered providers.

        Parameters
        ----------
        input :
            The input to check compatibility for.
        max_phase :
            Maximum capability phase to consider.
        prefer_fast :
            Prefer lower latency over higher priority.

        Returns
        -------
        T or None
        """
        return select_best_provider(
            self.all(), input,
            max_phase=max_phase,
            prefer_fast=prefer_fast,
        )

    # ── Graceful degradation ───────────────────────────────────

    def fallback(
        self,
        input: Any,
        method_name: str,
        *args: Any,
        max_phase: int | None = None,
        default_result: Any = None,
        **kwargs: Any,
    ) -> Any:
        """
        Execute *method_name* with graceful degradation across providers.

        Attempts each provider in priority order.  Falls through
        on failure.

        Parameters
        ----------
        input :
            Input to pass to ``can_handle()`` and the target method.
        method_name :
            Method to call on each provider (e.g. ``"detect"``).
        max_phase :
            Maximum capability phase to consider.
        default_result :
            Returned if all providers fail.
        args, kwargs :
            Additional arguments forwarded to the method.

        Returns
        -------
        Any
        """
        return fallback_execute(
            self.all(), input, method_name,
            *args,
            max_phase=max_phase,
            default_result=default_result,
            **kwargs,
        )

all()

Return all registered providers (in insertion order).

Source code in xyberos\common\registry.py

def all(self) -> list[T]:
    """Return all registered providers (in insertion order)."""
    return list(self._providers.values())

best(input, *, max_phase=None, prefer_fast=False)

Select the best registered provider for input.

Uses :func:select_best_provider to evaluate all registered providers.

Parameters

input : The input to check compatibility for. max_phase : Maximum capability phase to consider. prefer_fast : Prefer lower latency over higher priority.

Returns

T or None

Source code in xyberos\common\registry.py

def best(self, input: Any, *, max_phase: int | None = None, prefer_fast: bool = False) -> T | None:
    """
    Select the best registered provider for *input*.

    Uses :func:`select_best_provider` to evaluate all
    registered providers.

    Parameters
    ----------
    input :
        The input to check compatibility for.
    max_phase :
        Maximum capability phase to consider.
    prefer_fast :
        Prefer lower latency over higher priority.

    Returns
    -------
    T or None
    """
    return select_best_provider(
        self.all(), input,
        max_phase=max_phase,
        prefer_fast=prefer_fast,
    )

clear()

Remove all registered providers.

Source code in xyberos\common\registry.py

def clear(self) -> None:
    """Remove all registered providers."""
    self._providers.clear()
    self._default = None

default()

Return the default provider. Raises RuntimeError if none.

Source code in xyberos\common\registry.py

def default(self) -> T:
    """Return the default provider.  Raises ``RuntimeError`` if none."""
    if self._default is None:
        raise RuntimeError(
            "No default provider has been registered."
        )
    return self._providers[self._default]

default_name()

Return the name of the default provider.

Source code in xyberos\common\registry.py

def default_name(self) -> str:
    """Return the name of the default provider."""
    if self._default is None:
        raise RuntimeError(
            "No default provider has been registered."
        )
    return self._default

discover(group, *, extra_groups=None, default_name=None)

Discover and register plugins via Python entry points.

Parameters

group : Entry point group (e.g. "xyberos.providers"). extra_groups : Additional groups for backward compatibility. default_name : If given, set this entry as the default.

Returns

list[str] Names of successfully registered providers.

Source code in xyberos\common\registry.py

def discover(
    self,
    group: str,
    *,
    extra_groups: list[str] | None = None,
    default_name: str | None = None,
) -> list[str]:
    """
    Discover and register plugins via Python entry points.

    Parameters
    ----------
    group :
        Entry point group (e.g. ``"xyberos.providers"``).
    extra_groups :
        Additional groups for backward compatibility.
    default_name :
        If given, set this entry as the default.

    Returns
    -------
    list[str]
        Names of successfully registered providers.
    """
    return discover_and_register(
        self, group,
        extra_groups=extra_groups,
        default_name=default_name,
    )

exists(name)

Check whether a provider is registered under name.

Source code in xyberos\common\registry.py

def exists(self, name: str) -> bool:
    """Check whether a provider is registered under *name*."""
    return name in self._providers

fallback(input, method_name, *args, max_phase=None, default_result=None, **kwargs)

Execute method_name with graceful degradation across providers.

Attempts each provider in priority order. Falls through on failure.

Parameters

input : Input to pass to can_handle() and the target method. method_name : Method to call on each provider (e.g. "detect"). max_phase : Maximum capability phase to consider. default_result : Returned if all providers fail. args, kwargs : Additional arguments forwarded to the method.

Returns

Any

Source code in xyberos\common\registry.py

def fallback(
    self,
    input: Any,
    method_name: str,
    *args: Any,
    max_phase: int | None = None,
    default_result: Any = None,
    **kwargs: Any,
) -> Any:
    """
    Execute *method_name* with graceful degradation across providers.

    Attempts each provider in priority order.  Falls through
    on failure.

    Parameters
    ----------
    input :
        Input to pass to ``can_handle()`` and the target method.
    method_name :
        Method to call on each provider (e.g. ``"detect"``).
    max_phase :
        Maximum capability phase to consider.
    default_result :
        Returned if all providers fail.
    args, kwargs :
        Additional arguments forwarded to the method.

    Returns
    -------
    Any
    """
    return fallback_execute(
        self.all(), input, method_name,
        *args,
        max_phase=max_phase,
        default_result=default_result,
        **kwargs,
    )

get(name)

Retrieve a provider by name. Raises KeyError if missing.

Source code in xyberos\common\registry.py

def get(self, name: str) -> T:
    """Retrieve a provider by *name*.  Raises ``KeyError`` if missing."""
    try:
        return self._providers[name]
    except KeyError as exc:
        raise KeyError(
            f"Provider '{name}' is not registered."
        ) from exc

names()

Return sorted provider names.

Source code in xyberos\common\registry.py

def names(self) -> tuple[str, ...]:
    """Return sorted provider names."""
    return tuple(sorted(self._providers.keys()))

register(name, provider, *, default=False)

Register a provider under name.

If default is True or no default has been set yet, this provider becomes the default.

Source code in xyberos\common\registry.py

def register(
    self,
    name: str,
    provider: T,
    *,
    default: bool = False,
) -> None:
    """
    Register a provider under *name*.

    If *default* is ``True`` or no default has been set yet,
    this provider becomes the default.
    """
    self._providers[name] = provider
    if default or self._default is None:
        self._default = name

remove(name)

Unregister a provider. No-op if name does not exist.

Source code in xyberos\common\registry.py

def remove(
    self,
    name: str,
) -> None:
    """
    Unregister a provider.  No-op if *name* does not exist.
    """
    if name not in self._providers:
        return
    del self._providers[name]
    if self._default == name:
        self._default = (
            next(iter(self._providers))
            if self._providers
            else None
        )

set_default(name)

Set the default provider by name.

Source code in xyberos\common\registry.py

def set_default(self, name: str) -> None:
    """Set the default provider by *name*."""
    if name not in self._providers:
        raise KeyError(
            f"Provider '{name}' is not registered."
        )
    self._default = name

ProviderService

Bases: Generic[T]

Convenience base for services that manage a provider registry.

Wraps a :class:ProviderRegistry and exposes the most common operations directly so subclasses don't have to repeat delegation. Also surfaces capability-based selection and graceful degradation.

Usage::

class MyService(ProviderService[IMyProvider]):
    def do_something(self) -> None:
        provider = self.default()
        provider.run()

Source code in xyberos\common\service.py

class ProviderService(Generic[T]):
    """
    Convenience base for services that manage a provider registry.

    Wraps a :class:`ProviderRegistry` and exposes the most common
    operations directly so subclasses don't have to repeat delegation.
    Also surfaces capability-based selection and graceful degradation.

    Usage::

        class MyService(ProviderService[IMyProvider]):
            def do_something(self) -> None:
                provider = self.default()
                provider.run()
    """

    def __init__(
        self,
        *args: object,
        **kwargs: object,
    ) -> None:
        super().__init__(*args, **kwargs)
        self._registry: ProviderRegistry[T] = ProviderRegistry()

    # ── Registry access ─────────────────────────────────────────

    @property
    def registry(self) -> ProviderRegistry[T]:
        """Return the underlying provider registry."""
        return self._registry

    # ── Convenience methods ─────────────────────────────────────

    def register(
        self,
        name: str,
        provider: T,
        *,
        default: bool = False,
    ) -> None:
        """Register a provider (delegates to ``self.registry``)."""
        self._registry.register(name, provider, default=default)

    def provider(self, name: str) -> T:
        """Return a registered provider by *name*."""
        return self._registry.get(name)

    def default(self) -> T:
        """Return the default provider."""
        return self._registry.default()

    def default_name(self) -> str:
        """Return the name of the default provider."""
        return self._registry.default_name()

    def providers(self) -> tuple[str, ...]:
        """Return sorted names of all registered providers."""
        return self._registry.names()

    def has_provider(self, name: str) -> bool:
        """Check whether a provider is registered."""
        return self._registry.exists(name)

    def remove_provider(self, name: str) -> None:
        """Unregister a provider."""
        self._registry.remove(name)

    def set_default(self, name: str) -> None:
        """Set the default provider."""
        self._registry.set_default(name)

    def clear_providers(self) -> None:
        """Remove all providers."""
        self._registry.clear()

    # ── Phase 7: Entry-point discovery ──────────────────────────

    def discover(
        self,
        group: str,
        *,
        extra_groups: list[str] | None = None,
        default_name: str | None = None,
    ) -> list[str]:
        """
        Discover and register plugins via Python entry points.

        Parameters
        ----------
        group :
            Entry point group (e.g. ``"xyberos.providers"``).
        extra_groups :
            Additional groups for backward compatibility.
        default_name :
            If given, set this entry as the default.

        Returns
        -------
        list[str]
            Names of successfully registered providers.
        """
        return self._registry.discover(
            group,
            extra_groups=extra_groups,
            default_name=default_name,
        )

    # ── Phase 7: Capability-based selection ─────────────────────

    def best(
        self,
        input: Any,
        *,
        max_phase: int | None = None,
        prefer_fast: bool = False,
    ) -> T | None:
        """
        Select the best registered provider for *input*.

        Parameters
        ----------
        input :
            The input to check compatibility for.
        max_phase :
            Maximum capability phase to consider.
        prefer_fast :
            Prefer lower latency over higher priority.

        Returns
        -------
        T or None
        """
        return self._registry.best(
            input,
            max_phase=max_phase,
            prefer_fast=prefer_fast,
        )

    # ── Phase 7: Graceful degradation ───────────────────────────

    def fallback(
        self,
        input: Any,
        method_name: str,
        *args: Any,
        max_phase: int | None = None,
        default_result: Any = None,
        **kwargs: Any,
    ) -> Any:
        """
        Execute *method_name* with graceful degradation across providers.

        Parameters
        ----------
        input :
            Input to pass to ``can_handle()`` and the target method.
        method_name :
            Method to call on each provider (e.g. ``"detect"``).
        max_phase :
            Maximum capability phase to consider.
        default_result :
            Returned if all providers fail.
        args, kwargs :
            Additional arguments forwarded to the method.

        Returns
        -------
        Any
        """
        return self._registry.fallback(
            input,
            method_name,
            *args,
            max_phase=max_phase,
            default_result=default_result,
            **kwargs,
        )

registry property

Return the underlying provider registry.

best(input, *, max_phase=None, prefer_fast=False)

Select the best registered provider for input.

Parameters

input : The input to check compatibility for. max_phase : Maximum capability phase to consider. prefer_fast : Prefer lower latency over higher priority.

Returns

T or None

Source code in xyberos\common\service.py

def best(
    self,
    input: Any,
    *,
    max_phase: int | None = None,
    prefer_fast: bool = False,
) -> T | None:
    """
    Select the best registered provider for *input*.

    Parameters
    ----------
    input :
        The input to check compatibility for.
    max_phase :
        Maximum capability phase to consider.
    prefer_fast :
        Prefer lower latency over higher priority.

    Returns
    -------
    T or None
    """
    return self._registry.best(
        input,
        max_phase=max_phase,
        prefer_fast=prefer_fast,
    )

clear_providers()

Remove all providers.

Source code in xyberos\common\service.py

def clear_providers(self) -> None:
    """Remove all providers."""
    self._registry.clear()

default()

Return the default provider.

Source code in xyberos\common\service.py

def default(self) -> T:
    """Return the default provider."""
    return self._registry.default()

default_name()

Return the name of the default provider.

Source code in xyberos\common\service.py

def default_name(self) -> str:
    """Return the name of the default provider."""
    return self._registry.default_name()

discover(group, *, extra_groups=None, default_name=None)

Discover and register plugins via Python entry points.

Parameters

group : Entry point group (e.g. "xyberos.providers"). extra_groups : Additional groups for backward compatibility. default_name : If given, set this entry as the default.

Returns

list[str] Names of successfully registered providers.

Source code in xyberos\common\service.py

def discover(
    self,
    group: str,
    *,
    extra_groups: list[str] | None = None,
    default_name: str | None = None,
) -> list[str]:
    """
    Discover and register plugins via Python entry points.

    Parameters
    ----------
    group :
        Entry point group (e.g. ``"xyberos.providers"``).
    extra_groups :
        Additional groups for backward compatibility.
    default_name :
        If given, set this entry as the default.

    Returns
    -------
    list[str]
        Names of successfully registered providers.
    """
    return self._registry.discover(
        group,
        extra_groups=extra_groups,
        default_name=default_name,
    )

fallback(input, method_name, *args, max_phase=None, default_result=None, **kwargs)

Execute method_name with graceful degradation across providers.

Parameters

input : Input to pass to can_handle() and the target method. method_name : Method to call on each provider (e.g. "detect"). max_phase : Maximum capability phase to consider. default_result : Returned if all providers fail. args, kwargs : Additional arguments forwarded to the method.

Returns

Any

Source code in xyberos\common\service.py

def fallback(
    self,
    input: Any,
    method_name: str,
    *args: Any,
    max_phase: int | None = None,
    default_result: Any = None,
    **kwargs: Any,
) -> Any:
    """
    Execute *method_name* with graceful degradation across providers.

    Parameters
    ----------
    input :
        Input to pass to ``can_handle()`` and the target method.
    method_name :
        Method to call on each provider (e.g. ``"detect"``).
    max_phase :
        Maximum capability phase to consider.
    default_result :
        Returned if all providers fail.
    args, kwargs :
        Additional arguments forwarded to the method.

    Returns
    -------
    Any
    """
    return self._registry.fallback(
        input,
        method_name,
        *args,
        max_phase=max_phase,
        default_result=default_result,
        **kwargs,
    )

has_provider(name)

Check whether a provider is registered.

Source code in xyberos\common\service.py

def has_provider(self, name: str) -> bool:
    """Check whether a provider is registered."""
    return self._registry.exists(name)

provider(name)

Return a registered provider by name.

Source code in xyberos\common\service.py

def provider(self, name: str) -> T:
    """Return a registered provider by *name*."""
    return self._registry.get(name)

providers()

Return sorted names of all registered providers.

Source code in xyberos\common\service.py

def providers(self) -> tuple[str, ...]:
    """Return sorted names of all registered providers."""
    return self._registry.names()

register(name, provider, *, default=False)

Register a provider (delegates to self.registry).

Source code in xyberos\common\service.py

def register(
    self,
    name: str,
    provider: T,
    *,
    default: bool = False,
) -> None:
    """Register a provider (delegates to ``self.registry``)."""
    self._registry.register(name, provider, default=default)

remove_provider(name)

Unregister a provider.

Source code in xyberos\common\service.py

def remove_provider(self, name: str) -> None:
    """Unregister a provider."""
    self._registry.remove(name)

set_default(name)

Set the default provider.

Source code in xyberos\common\service.py

def set_default(self, name: str) -> None:
    """Set the default provider."""
    self._registry.set_default(name)

ProviderCapability dataclass

Self-declared capability of a provider.

Used by :meth:Provider.can_handle to determine whether a provider is suitable for a given input, and by managers to select the best matching provider.

Attributes

phase : Processing phase (1=deterministic, 2=NLP, 3=ML, 4=LLM). languages : ISO language codes this provider supports (empty = any). min_input_length : Minimum input length (characters) this provider requires. max_input_length : Maximum input length (characters) this provider can handle. 0 means no limit. latency_p95_ms : Expected p95 latency in milliseconds. requires_gpu : Whether this provider requires GPU hardware. requires_network : Whether this provider needs network access (e.g. API calls). description : Human-readable description of what this provider does. metadata : Arbitrary key-value pairs for extension.

Source code in xyberos\common\capabilities.py

@dataclass(slots=True, frozen=True)
class ProviderCapability:
    """
    Self-declared capability of a provider.

    Used by :meth:`Provider.can_handle` to determine whether a provider
    is suitable for a given input, and by managers to select the best
    matching provider.

    Attributes
    ----------
    phase :
        Processing phase (1=deterministic, 2=NLP, 3=ML, 4=LLM).
    languages :
        ISO language codes this provider supports (empty = any).
    min_input_length :
        Minimum input length (characters) this provider requires.
    max_input_length :
        Maximum input length (characters) this provider can handle.
        ``0`` means no limit.
    latency_p95_ms :
        Expected p95 latency in milliseconds.
    requires_gpu :
        Whether this provider requires GPU hardware.
    requires_network :
        Whether this provider needs network access (e.g. API calls).
    description :
        Human-readable description of what this provider does.
    metadata :
        Arbitrary key-value pairs for extension.
    """

    phase: int = 1
    languages: tuple[str, ...] = ()
    min_input_length: int = 0
    max_input_length: int = 0
    latency_p95_ms: float = 0.0
    requires_gpu: bool = False
    requires_network: bool = False
    description: str = ""
    metadata: dict[str, Any] = field(default_factory=lambda: {})

Pipeline

Bases: Generic[T]

Generic sequential processor chain.

Executes a list of :class:Stage instances in order. If a stage fails the error is wrapped in an :class:XyberosError with full context and re-raised.

When a monitor is provided, every stage execution emits duration and error metrics.

Usage::

pipeline: Pipeline[Observation] = Pipeline([
    LanguageProcessor(),
    TokenizerProcessor(),
])
result = pipeline.execute(observation)

Source code in xyberos\common\pipeline.py

class Pipeline(Generic[T]):
    """
    Generic sequential processor chain.

    Executes a list of :class:`Stage` instances in order.
    If a stage fails the error is wrapped in an :class:`XyberosError`
    with full context and re-raised.

    When a *monitor* is provided, every stage execution emits
    duration and error metrics.

    Usage::

        pipeline: Pipeline[Observation] = Pipeline([
            LanguageProcessor(),
            TokenizerProcessor(),
        ])
        result = pipeline.execute(observation)
    """

    def __init__(
        self,
        stages: list[Stage[T]] | None = None,
        monitor: CognitiveMonitor | None = None,
    ) -> None:
        self._stages: list[Stage[T]] = list(stages) if stages else []
        self._monitor = monitor or _get_null_monitor()

    # ── Registration ────────────────────────────────────────────

    def add(self, stage: Stage[T]) -> None:
        """Append a stage to the pipeline."""
        self._stages.append(stage)

    def insert(self, index: int, stage: Stage[T]) -> None:
        """Insert a stage at *index*."""
        self._stages.insert(index, stage)

    def remove(self, name: str) -> None:
        """Remove the first stage with the given *name*."""
        self._stages = [s for s in self._stages if s.name != name]

    @property
    def stages(self) -> list[Stage[T]]:
        """Return a copy of the registered stages."""
        return list(self._stages)

    # ── Execution ───────────────────────────────────────────────

    def execute(self, initial: T) -> T:
        """
        Run all stages sequentially, emitting metrics per stage.
        """
        value = initial
        for stage in self._stages:
            start = time.perf_counter()
            try:
                value = stage.process(value)
            except XyberosError:
                self._monitor.count(f"pipeline.{self._name()}.errors", 1)
                raise
            except Exception as exc:
                elapsed = (time.perf_counter() - start) * 1000
                self._monitor.count(f"pipeline.{self._name()}.errors", 1)
                self._monitor.timing(
                    f"pipeline.{self._name()}.duration",
                    elapsed,
                    stage=stage.name,
                    status="error",
                )
                msg = f"Pipeline stage '{stage.name}' failed: {exc}"
                logger.error(msg)
                ctx = ErrorContext(component=self.__class__.__name__, stage=stage.name, original=exc)
                raise XyberosError(message=msg, context=ctx) from exc
            else:
                elapsed = (time.perf_counter() - start) * 1000
                self._monitor.timing(
                    f"pipeline.{self._name()}.duration",
                    elapsed,
                    stage=stage.name,
                    status="ok",
                )
                self._monitor.count(f"pipeline.{self._name()}.throughput", 1)
        return value

    def _name(self) -> str:
        return self.__class__.__name__.lower().replace("pipeline", "")

    def __len__(self) -> int:
        return len(self._stages)

    def __bool__(self) -> bool:
        return len(self._stages) > 0

stages property

Return a copy of the registered stages.

add(stage)

Append a stage to the pipeline.

Source code in xyberos\common\pipeline.py

def add(self, stage: Stage[T]) -> None:
    """Append a stage to the pipeline."""
    self._stages.append(stage)

execute(initial)

Run all stages sequentially, emitting metrics per stage.

Source code in xyberos\common\pipeline.py

def execute(self, initial: T) -> T:
    """
    Run all stages sequentially, emitting metrics per stage.
    """
    value = initial
    for stage in self._stages:
        start = time.perf_counter()
        try:
            value = stage.process(value)
        except XyberosError:
            self._monitor.count(f"pipeline.{self._name()}.errors", 1)
            raise
        except Exception as exc:
            elapsed = (time.perf_counter() - start) * 1000
            self._monitor.count(f"pipeline.{self._name()}.errors", 1)
            self._monitor.timing(
                f"pipeline.{self._name()}.duration",
                elapsed,
                stage=stage.name,
                status="error",
            )
            msg = f"Pipeline stage '{stage.name}' failed: {exc}"
            logger.error(msg)
            ctx = ErrorContext(component=self.__class__.__name__, stage=stage.name, original=exc)
            raise XyberosError(message=msg, context=ctx) from exc
        else:
            elapsed = (time.perf_counter() - start) * 1000
            self._monitor.timing(
                f"pipeline.{self._name()}.duration",
                elapsed,
                stage=stage.name,
                status="ok",
            )
            self._monitor.count(f"pipeline.{self._name()}.throughput", 1)
    return value

insert(index, stage)

Insert a stage at index.

Source code in xyberos\common\pipeline.py

def insert(self, index: int, stage: Stage[T]) -> None:
    """Insert a stage at *index*."""
    self._stages.insert(index, stage)

remove(name)

Remove the first stage with the given name.

Source code in xyberos\common\pipeline.py

def remove(self, name: str) -> None:
    """Remove the first stage with the given *name*."""
    self._stages = [s for s in self._stages if s.name != name]

Stage

Bases: ABC, Generic[T]

A single stage in a processing pipeline.

Subclasses implement :meth:process and provide a name for logging and error reporting.

Source code in xyberos\common\pipeline.py

class Stage(ABC, Generic[T]):
    """
    A single stage in a processing pipeline.

    Subclasses implement :meth:`process` and provide a *name*
    for logging and error reporting.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """Human-readable stage name (e.g. ``"LanguageProcessor"``)."""
        ...

    @abstractmethod
    def process(self, value: T) -> T:
        """Transform *value* and return the result."""
        ...

name abstractmethod property

Human-readable stage name (e.g. "LanguageProcessor").

process(value) abstractmethod

Transform value and return the result.

Source code in xyberos\common\pipeline.py

@abstractmethod
def process(self, value: T) -> T:
    """Transform *value* and return the result."""
    ...