easy-agentic-plugin 0.1.0__py3-none-any.whl

easy_agentic_plugin/__init__.py

@@ -0,0 +1,47 @@
+"""easy-agentic-plugin -- an Agent-oriented plugin framework (core package)."""
+
+from __future__ import annotations
+
+from .application import (
+    Application,
+    build_folder_kwargs,
+    compose_backend,
+    discover_plugins,
+    get_application,
+)
+from .config import Config
+from .context import AgentBuildContext, AppContext
+from .contribution import AgentContribution
+from .errors import ConflictError, EasyAgenticError, UnknownReferenceError
+from .folder import FolderAgentError, FolderSpec, load_folder_spec
+from .graph import build_graph
+from .merge import merge_contributions
+from .plugin import Plugin, PluginBase
+from .registry import NamedRegistry
+from .sources import AgentSource, FolderAgent, GraphFactory
+
+__all__ = [
+    "AgentBuildContext",
+    "AgentContribution",
+    "AgentSource",
+    "AppContext",
+    "Application",
+    "Config",
+    "ConflictError",
+    "EasyAgenticError",
+    "FolderAgent",
+    "FolderAgentError",
+    "FolderSpec",
+    "GraphFactory",
+    "NamedRegistry",
+    "Plugin",
+    "PluginBase",
+    "UnknownReferenceError",
+    "build_folder_kwargs",
+    "build_graph",
+    "compose_backend",
+    "discover_plugins",
+    "get_application",
+    "load_folder_spec",
+    "merge_contributions",
+]

easy_agentic_plugin/application.py

@@ -0,0 +1,471 @@
+"""Application -- plugin manager + agent registry.
+
+Responsibilities: load plugins -> run setup to populate the registry -> resolve and cache agents
+by agent_id (at session level). See ADR-0002 / architecture.md for the public interface.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+import threading
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from langgraph.graph.state import CompiledStateGraph
+
+from .config import Config
+from .context import AgentBuildContext, AppContext
+from .contribution import AgentContribution
+from .errors import ConflictError, EasyAgenticError
+from .folder import FolderSpec, SubAgentSpec, load_folder_spec
+from .merge import merge_contributions, resolve_named
+from .plugin import Plugin
+from .registry import NamedRegistry
+from .sources import AgentSource, FolderAgent
+
+logger = logging.getLogger(__name__)
+
+# Built-in plugins directory (shipped with the framework) /
+# user drop-in directory (relative to CWD).
+_BUILTIN_PLUGINS_DIR = Path(__file__).parent / "plugins"
+_USER_PLUGINS_DIR = Path("plugins")
+
+# order for the folder baseline contribution: ahead of all plugins
+# (folder tools first, plugin tools after).
+_FOLDER_BASE_ORDER = -1_000_000
+
+
+def discover_plugins(
+    *, builtin_dir: Path | None = None, user_dir: Path | None = None
+) -> list[Plugin]:
+    """Scan the built-in and user plugin dirs; load and return the Plugin list (see ADR-0003).
+
+    - Each subdirectory containing a ``plugin.json`` is treated as a plugin.
+    - Error in the built-in directory -> fail-fast; error in the user directory -> log + skip;
+      duplicate plugin name -> fail-fast.
+    """
+    builtin = _BUILTIN_PLUGINS_DIR if builtin_dir is None else Path(builtin_dir)
+    user = _USER_PLUGINS_DIR if user_dir is None else Path(user_dir)
+
+    plugins: list[Plugin] = []
+    seen: set[str] = set()
+    for base, is_builtin in ((builtin, True), (user, False)):
+        if not base.is_dir():
+            continue
+        for sub in sorted(base.iterdir()):
+            if not sub.is_dir() or sub.name.startswith((".", "__")):
+                continue
+            manifest_path = sub / "plugin.json"
+            if not manifest_path.is_file():
+                continue
+            try:
+                plugin = _load_plugin(sub, manifest_path)
+            except Exception as exc:
+                if is_builtin:
+                    raise  # built-in: fail-fast
+                logger.warning("skipping user plugin %s: %s", sub.name, exc)
+                continue
+            if plugin.name in seen:
+                raise ConflictError(f"duplicate plugin name {plugin.name!r}")
+            seen.add(plugin.name)
+            plugins.append(plugin)
+    return plugins
+
+
+def _load_plugin(folder: Path, manifest_path: Path) -> Plugin:
+    """Read plugin.json -> parse entry -> instantiate -> inject name/order/config."""
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise EasyAgenticError(f"{manifest_path} is not valid JSON: {exc}") from exc
+    if not isinstance(manifest, dict):
+        raise EasyAgenticError(f"{manifest_path} top level should be an object")
+
+    name = manifest.get("name")
+    if not isinstance(name, str) or not name:
+        raise EasyAgenticError(f"{manifest_path} is missing a valid name")
+    entry = manifest.get("entry")
+    if not isinstance(entry, str) or ":" not in entry:
+        raise EasyAgenticError(
+            f"{manifest_path} is missing a valid entry (should be 'module:attr')"
+        )
+
+    module_name, _, attr = entry.partition(":")
+    target = _resolve_entry(folder, module_name.strip(), attr.strip())
+    # entry is a class -> construct with no args; is an instance -> use directly (see ADR-0003).
+    # Dynamically loaded, so its type is Any.
+    instance: Any = target() if isinstance(target, type) else target
+    if not (
+        callable(getattr(instance, "setup", None)) and callable(getattr(instance, "build", None))
+    ):
+        raise EasyAgenticError(
+            f"{manifest_path}'s entry {entry!r} is not a Plugin (missing setup/build)"
+        )
+
+    # The manifest is the source of truth: inject name/order/config into the instance.
+    instance.name = name
+    instance.order = manifest.get("order", getattr(instance, "order", 0))
+    instance.config = manifest.get("config", {})
+    return instance
+
+
+def _resolve_entry(folder: Path, module_name: str, attr: str) -> object:
+    """Load the plugin's single-file module by path and return the attribute the entry points to."""
+    module_file = folder / f"{module_name}.py"
+    if not module_file.is_file():
+        raise EasyAgenticError(f"entry module {module_file} not found")
+    unique = f"easy_agentic_plugin_plugin_{folder.name}_{module_name}"
+    spec = importlib.util.spec_from_file_location(unique, module_file)
+    if spec is None or spec.loader is None:
+        raise EasyAgenticError(f"cannot load {module_file}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    try:
+        return getattr(module, attr)
+    except AttributeError:
+        raise EasyAgenticError(f"{module_file} has no attribute {attr!r}") from None
+
+
+@dataclass
+class _CacheEntry:
+    graph: CompiledStateGraph
+    last_access: float
+
+
+def _skill_mount_key(agent_id: str) -> str:
+    """Mount point for folder skills/ = the skill source path.
+
+    Namespaced by agent_id to avoid clashing with plugins.
+    """
+    return f"/skills/{agent_id}/"
+
+
+def _subagent_skill_mount_key(sub_name: str) -> str:
+    """Mount point for subagent skills/ (option A).
+
+    Mirrors the physical structure and is kept separate from the main agent's /skills/.
+    A subagent name is unique within its agent, so there is no need to also carry agent_id. The
+    mount value goes into the CompositeBackend shared with the main agent, and the subagent's
+    SkillsMiddleware reads from the same backend at this path.
+    """
+    return f"/subagents/{sub_name}/skills/"
+
+
+def _subagent_dict(
+    spec: SubAgentSpec,
+    tool_registry: NamedRegistry[object] | None,
+    *,
+    skill_sources: list[str] | None = None,
+) -> dict[str, Any]:
+    """Convert a SubAgentSpec into a deepagents SubAgent dict.
+
+    - tool names are resolved to objects via the registry; **if empty, omit the tools key ->
+      inherit the main agent's tools**.
+    - if interrupt_config is empty it is omitted; an omitted model -> inherit from the main agent.
+    - skill_sources are provided by the caller (corresponding to mount keys already mounted into
+      the backend); if empty, the skills key is omitted.
+    """
+    d: dict[str, Any] = {
+        "name": spec.name,
+        "description": spec.description,
+        "system_prompt": spec.system_prompt,
+    }
+    if spec.tool_names:
+        d["tools"] = resolve_named(spec.tool_names, tool_registry, "tool")
+    if spec.interrupt_config:
+        d["interrupt_on"] = spec.interrupt_config
+    if skill_sources:
+        d["skills"] = list(skill_sources)
+    return d
+
+
+def _folder_base_contribution(
+    spec: FolderSpec, *, tool_registry: NamedRegistry[object] | None = None
+) -> AgentContribution:
+    """The folder's own baseline contribution: tools, skills/ (-> mount + source), and subagents/.
+
+    Subagents include their own skills/.
+    """
+    skills: list[str] = []
+    mounts: dict[str, Any] = {}
+    if spec.skills_path is not None:
+        key = _skill_mount_key(spec.agent_id)
+        skills.append(key)
+        mounts[key] = str(spec.skills_path)
+
+    subagents: list[dict[str, Any]] = []
+    for s in spec.subagents:
+        sub_sources: list[str] = []
+        if s.skills_path is not None:
+            sub_key = _subagent_skill_mount_key(s.name)
+            mounts[sub_key] = str(s.skills_path)
+            sub_sources.append(sub_key)
+        subagents.append(_subagent_dict(s, tool_registry, skill_sources=sub_sources))
+
+    return AgentContribution(
+        tools=list(spec.tool_names), skills=skills, mounts=mounts, subagents=subagents
+    )
+
+
+def build_folder_kwargs(
+    spec: FolderSpec,
+    items: Sequence[tuple[int, AgentContribution | None]],
+    *,
+    default_model: Any | None = None,
+    tool_registry: NamedRegistry[object] | None = None,
+    middleware_registry: NamedRegistry[object] | None = None,
+) -> dict[str, Any]:
+    """Assemble the folder baseline spec and plugin contributions into create_deep_agent kwargs.
+
+    A pure function, easy to test.
+
+    - The folder's tool names act as a "baseline contribution" ordered ahead of all plugins, and
+      go through merge together (resolve + dedupe).
+    - The folder's skills/ (if any) is also a baseline contribution: one mount (``/skills/<id>/``
+      -> physical path) plus one skill source ``/skills/<id>/`` (see ADR-0004); merged additively
+      with the plugins' skills/mounts.
+    - The folder's subagents/ (if any) are converted into deepagents SubAgent dicts as baseline
+      contributions; a subagent's tool names are resolved against the registry here, and merged
+      additively with the plugin contributions' subagents (name collisions fail-fast).
+    - Model priority chain: folder.model -> plugin contribution -> system default; error if all
+      are empty.
+    - The folder's exclusive system_prompt / interrupt_on are applied directly; empty values are
+      always omitted.
+    - If the return value contains a ``mounts`` key, the caller must assemble it into
+      ``backend=CompositeBackend(...)`` (this function stays deepagents-free for easy unit testing).
+    """
+    base = (_FOLDER_BASE_ORDER, _folder_base_contribution(spec, tool_registry=tool_registry))
+    merged = merge_contributions(
+        [base, *items],
+        default_model=default_model,
+        tool_registry=tool_registry,
+        middleware_registry=middleware_registry,
+    )
+
+    model = spec.model or merged["model"]
+    if model is None:
+        raise EasyAgenticError(
+            f"agent {spec.agent_id!r} has no model specified: "
+            f"folder / plugin / system default are all empty"
+        )
+
+    kwargs: dict[str, Any] = {"model": model}
+    if spec.system_prompt:
+        kwargs["system_prompt"] = spec.system_prompt
+    if merged["tools"]:
+        kwargs["tools"] = merged["tools"]
+    if merged["subagents"]:
+        kwargs["subagents"] = merged["subagents"]
+    if merged["skills"]:
+        kwargs["skills"] = merged["skills"]
+    if merged["middleware"]:
+        kwargs["middleware"] = merged["middleware"]
+    if spec.interrupt_config:
+        kwargs["interrupt_on"] = spec.interrupt_config
+    if merged["mounts"]:
+        kwargs["mounts"] = merged["mounts"]
+    name = spec.name or spec.agent_id
+    if name:
+        kwargs["name"] = name
+    return kwargs
+
+
+def compose_backend(mounts: dict[str, Any]) -> Any:
+    """Assemble the mount mapping into a single CompositeBackend.
+
+    A mount value that is a physical path (str) -> wrapped as FilesystemBackend(root_dir=...);
+    a Backend instance -> used directly. Unmatched paths go to the default StateBackend.
+    """
+    from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend
+
+    routes = {
+        mount_path: (
+            FilesystemBackend(root_dir=target, virtual_mode=True)
+            if isinstance(target, str)
+            else target
+        )
+        for mount_path, target in mounts.items()
+    }
+    return CompositeBackend(default=StateBackend(), routes=routes)
+
+
+class Application:
+    def __init__(
+        self, plugins: list[Plugin] | None = None, *, config: Config | None = None
+    ) -> None:
+        # plugins=None means leave it to discover_plugins();
+        # an explicit list is used as-is (for testing).
+        self._given_plugins = list(plugins) if plugins is not None else None
+        self.config = config or Config()
+        self._agents: NamedRegistry[AgentSource] = NamedRegistry("agent")
+        self._tools: NamedRegistry[object] = NamedRegistry("tool")
+        self._middleware: NamedRegistry[object] = NamedRegistry("middleware")
+        self._services: dict[str, object] = {}
+        self._active_plugins: list[Plugin] = []
+        self._cache: dict[tuple[str, str], _CacheEntry] = {}
+        # Concurrency: the langgraph server runs sync nodes on a thread pool; this guards
+        # _cache reads/writes and the evict traversal.
+        self._lock = threading.RLock()
+        self._last_sweep: float = 0.0  # timestamp of the last lazy eviction sweep (monotonic)
+        self._loaded = False
+
+    # ---- startup ----
+
+    def load(self) -> Application:
+        """Discover plugins -> sort -> run setup in turn to populate the registry. Idempotent."""
+        if self._loaded:
+            return self
+        plugins = self._given_plugins if self._given_plugins is not None else discover_plugins()
+        for p in plugins:
+            if not getattr(p, "name", ""):
+                raise EasyAgenticError(f"plugin {p!r} is missing name")
+        # Deterministic order: order ascending, ties broken by name. Affects the middleware chain,
+        # list concatenation, and single-field arbitration.
+        self._active_plugins = sorted(plugins, key=lambda p: (getattr(p, "order", 0), p.name))
+        ctx = AppContext(
+            config=self.config,
+            agents=self._agents,
+            tools=self._tools,
+            middleware=self._middleware,
+            services=self._services,
+        )
+        for p in self._active_plugins:
+            setup = getattr(p, "setup", None)
+            if callable(setup):
+                setup(ctx)
+        self._loaded = True
+        return self
+
+    def list_agents(self) -> list[str]:
+        if not self._loaded:
+            self.load()
+        return self._agents.names()
+
+    # ---- request time ----
+
+    def resolve(self, agent_id: str, session_id: str) -> CompiledStateGraph:
+        """Get/build the agent graph for (agent_id, session_id), reusing the cache on a hit.
+
+        Concurrency-safe: _cache reads/writes are inside the RLock; materialize is slow, so it runs
+        outside the lock, with double-checking to avoid duplicate concurrent builds.
+        Eviction: lazily triggered -- each resolve opportunistically sweeps idle cache entries once,
+        throttled by eviction_sweep_seconds.
+        """
+        if not self._loaded:
+            self.load()
+        key = (agent_id, session_id)
+        now = time.monotonic()
+
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is not None:
+                entry.last_access = now
+                self._maybe_sweep(now)
+                return entry.graph
+            source = self._agents.require(agent_id)
+
+        # Miss: materialize outside the lock to avoid holding it and blocking other requests.
+        graph = self._materialize(agent_id, session_id, source)
+
+        with self._lock:
+            existing = self._cache.get(key)  # double-check: another thread may have built it
+            if existing is not None:
+                existing.last_access = now
+                self._maybe_sweep(now)
+                return existing.graph
+            self._cache[key] = _CacheEntry(graph=graph, last_access=now)
+            self._maybe_sweep(now)
+            return graph
+
+    def _materialize(
+        self, agent_id: str, session_id: str, source: AgentSource
+    ) -> CompiledStateGraph:
+        if isinstance(source, CompiledStateGraph):
+            return source
+        if isinstance(source, FolderAgent):
+            return self._build_folder_agent(agent_id, session_id, source)
+        if callable(source):
+            return source(self._build_context(agent_id, session_id))
+        raise TypeError(f"unsupported agent source: {source!r}")
+
+    def _build_context(self, agent_id: str, session_id: str) -> AgentBuildContext:
+        return AgentBuildContext(
+            agent_id=agent_id,
+            session_id=session_id,
+            config=self.config,
+            services=self._services,
+        )
+
+    def _build_folder_agent(
+        self, agent_id: str, session_id: str, source: FolderAgent
+    ) -> CompiledStateGraph:
+        spec = load_folder_spec(source.path)
+        ctx = self._build_context(agent_id, session_id)
+        items = [
+            (getattr(p, "order", 0), p.build(ctx))
+            for p in self._active_plugins
+            if callable(getattr(p, "build", None))
+        ]
+        kwargs = build_folder_kwargs(
+            spec,
+            items,
+            default_model=self.config.default_model,
+            tool_registry=self._tools,
+            middleware_registry=self._middleware,
+        )
+
+        mounts = kwargs.pop("mounts", None)
+        if mounts:
+            kwargs["backend"] = compose_backend(mounts)
+
+        from deepagents import create_deep_agent
+
+        return create_deep_agent(**kwargs)
+
+    # ---- eviction ----
+
+    def _maybe_sweep(self, now: float) -> None:
+        """Throttled lazy eviction: only sweeps once >= eviction_sweep_seconds since the last sweep.
+
+        Caller must hold self._lock.
+        """
+        if now - self._last_sweep >= self.config.eviction_sweep_seconds:
+            self._last_sweep = now
+            self.evict_idle(now=now)
+
+    def evict_idle(self, *, ttl_seconds: int | None = None, now: float | None = None) -> int:
+        """Evict session agents that have been idle past the timeout; return the number cleaned up.
+
+        ``now`` can be injected for testing; defaults to time.monotonic(). This is called both by
+        resolve's lazy sweep (while holding the lock -> RLock is reentrant) and can also be safely
+        called on its own by external/test code.
+        """
+        ttl = self.config.idle_ttl_seconds if ttl_seconds is None else ttl_seconds
+        current = time.monotonic() if now is None else now
+        cutoff = current - ttl
+        with self._lock:
+            stale = [key for key, entry in self._cache.items() if entry.last_access < cutoff]
+            for key in stale:
+                del self._cache[key]
+        return len(stale)
+
+    def cached_count(self) -> int:
+        with self._lock:
+            return len(self._cache)
+
+
+# ---- module-level singleton: load once on import (system startup semantics) ----
+
+_application: Application | None = None
+
+
+def get_application() -> Application:
+    global _application
+    if _application is None:
+        _application = Application().load()
+    return _application

easy_agentic_plugin/config.py

@@ -0,0 +1,26 @@
+"""Runtime configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Config:
+    """Runtime configuration for the application (fields extended as needed).
+
+    - default_model: fallback default model used when no plugin contributes a model;
+      read from the ``EASY_AGENTIC_MODEL`` environment variable. A folder's
+      ``langchain:default`` placeholder, once normalized to "unspecified", also lands
+      here (see folder._extract_model_id).
+    - idle_ttl_seconds: how long a session agent may stay idle before it can be
+      reclaimed (default 1 hour).
+    - eviction_sweep_seconds: throttle interval for lazy reclamation -- resolve sweeps
+      the idle cache at most once per this interval (default 5 minutes) to avoid a full
+      scan on every request.
+    """
+
+    default_model: str | None = field(default_factory=lambda: os.getenv("EASY_AGENTIC_MODEL"))
+    idle_ttl_seconds: int = 3600
+    eviction_sweep_seconds: int = 300

easy_agentic_plugin/context.py

@@ -0,0 +1,79 @@
+"""The two contexts passed to plugins: AppContext (setup phase) / AgentBuildContext (build phase).
+
+AppContext is a registration facade: it narrows operations on the application's internal
+registries down to a stable interface. AgentBuildContext is a read-only build context.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import ConflictError
+
+if TYPE_CHECKING:
+    from .config import Config
+    from .registry import NamedRegistry
+    from .sources import AgentSource
+
+
+class AppContext:
+    """Passed to plugins in the setup phase. Provides registration for agents / tools /
+    middleware / shared services."""
+
+    def __init__(
+        self,
+        *,
+        config: Config,
+        agents: NamedRegistry[AgentSource],
+        tools: NamedRegistry[object],
+        middleware: NamedRegistry[object],
+        services: dict[str, object],
+    ) -> None:
+        self.config = config
+        self._agents = agents
+        self._tools = tools
+        self._middleware = middleware
+        self._services = services
+
+    def register_agent(self, agent_id: str, source: AgentSource, *, override: bool = False) -> None:
+        self._agents.register(agent_id, source, override=override)
+
+    def register_tool(self, name: str, tool: object, *, override: bool = False) -> None:
+        """Register a global tool; plugins can later reference it by name in a contribution."""
+        self._tools.register(name, tool, override=override)
+
+    def register_middleware(self, name: str, mw: object, *, override: bool = False) -> None:
+        """Register global middleware; plugins can later reference it by name in a contribution."""
+        self._middleware.register(name, mw, override=override)
+
+    def provide(self, key: str, service: object, *, override: bool = False) -> None:
+        """Register a shared service (a decoupling channel between plugins). Fail-fast on dupes."""
+        if key in self._services and not override:
+            raise ConflictError(
+                f"shared service {key!r} already registered (pass override=True to replace)"
+            )
+        self._services[key] = service
+
+    def get(self, key: str) -> object | None:
+        return self._services.get(key)
+
+
+class AgentBuildContext:
+    """Passed to plugins in the build phase (read-only)."""
+
+    def __init__(
+        self,
+        *,
+        agent_id: str,
+        session_id: str,
+        config: Config,
+        services: dict[str, object],
+    ) -> None:
+        self.agent_id = agent_id
+        self.session_id = session_id
+        self.config = config
+        self._services = services
+
+    def get(self, key: str) -> object | None:
+        """Get a shared service registered during the setup phase."""
+        return self._services.get(key)

easy_agentic_plugin/contribution.py

@@ -0,0 +1,36 @@
+"""AgentContribution -- the declarative contribution a plugin returns during the build phase.
+
+Fields mirror deepagents' ``create_deep_agent`` parameters. See ADR-0002 for details.
+``tools`` / ``middleware`` may hold either actual objects or strings (references to names
+registered in the global registry during the setup phase).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from deepagents.backends.protocol import BackendProtocol
+    from langchain.agents.middleware.types import AgentMiddleware
+    from langchain_core.language_models.chat_models import BaseChatModel
+    from langchain_core.tools import BaseTool
+
+    ToolItem = BaseTool | Callable[..., Any] | dict[str, Any] | str
+    MiddlewareItem = AgentMiddleware | str
+    # Mount value: a physical path (str, wrapped into a FilesystemBackend at build time)
+    # or a Backend instance (used directly).
+    MountTarget = str | BackendProtocol
+
+
+@dataclass
+class AgentContribution:
+    tools: list[ToolItem] = field(default_factory=list)
+    subagents: list[Any] = field(default_factory=list)  # = agent injection (SubAgent, etc.)
+    skills: list[str] = field(default_factory=list)
+    middleware: list[MiddlewareItem] = field(default_factory=list)
+    model: str | BaseChatModel | None = None  # single value, None = abstain
+    # Filesystem mounts: {virtual path: physical path | Backend}. Additive; once aggregated
+    # they are assembled into a single CompositeBackend.
+    mounts: dict[str, MountTarget] = field(default_factory=dict)

easy_agentic_plugin/errors.py

@@ -0,0 +1,16 @@
+"""Exception types for easy-agentic-plugin."""
+
+from __future__ import annotations
+
+
+class EasyAgenticError(Exception):
+    """Base class for all easy-agentic-plugin custom exceptions."""
+
+
+class ConflictError(EasyAgenticError):
+    """Conflicts such as duplicate names or equal priority; following "explicit >
+    silent", we raise by default rather than silently overwrite."""
+
+
+class UnknownReferenceError(EasyAgenticError):
+    """Referencing an unregistered object by name (agent / tool / middleware)."""