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

easy_agentic_plugin/folder.py

@@ -0,0 +1,288 @@
+"""Parsing of folder agents: read an agent folder into a FolderSpec.
+
+Folder structure (open-item A):
+
+    agents/<agent_id>/
+      ├─ config.json   # name / description / config.configurable.llm_model_config.modelId
+      ├─ AGENTS.md     # system prompt (agent instructions); may carry YAML frontmatter (stripped)
+      ├─ tools.json    # { "tools": [str...], "interrupt_config": {} }
+      ├─ skills/       # optional: Agent Skills directory (each subdir holds a SKILL.md)
+      └─ subagents/    # optional: each subdir is a subagent (AGENTS.md + tools.json + skills/)
+
+Every file plus skills/ and subagents/ is optional; missing ones fall back to safe defaults.
+The tools entries are **tool-name strings**, resolved by the Application against the global
+registry at build time (see merge). If skills/ exists, its physical path is recorded in
+``skills_path`` and the Application turns it into one mount plus one skill source per ADR-0004
+(see build_folder_kwargs).
+
+Differences between a subagent and the main agent: a subagent's ``AGENTS.md`` carries its
+``description`` via **YAML frontmatter** (required by deepagents ``SubAgent``), and the body is
+the system_prompt; a subagent has no config.json (model is inherited from the main agent). See
+``SubAgentSpec`` / ``load_subagent_spec``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import EasyAgenticError
+
+CONFIG_FILE = "config.json"
+AGENT_FILE = "AGENTS.md"
+TOOLS_FILE = "tools.json"
+SKILLS_DIR = "skills"
+SUBAGENTS_DIR = "subagents"
+
+# The model placeholder exported by the LangChain platform: it cannot be resolved by
+# init_chat_model, so it is normalized to "unspecified" and left to the model priority
+# chain to fall back on (config.default_model = env EASY_AGENTIC_MODEL).
+PLATFORM_DEFAULT_MODEL = "langchain:default"
+
+# YAML frontmatter: ---\n ... \n---\n at the start of the file
+# (aligned with deepagents' skills parsing).
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+class FolderAgentError(EasyAgenticError):
+    """The folder agent's folder structure or content is invalid."""
+
+
+@dataclass
+class SubAgentSpec:
+    """Spec for one folder subagent (maps to deepagents' ``SubAgent``).
+
+    description / system_prompt are required (enforced by ``SubAgent``); an omitted model means
+    it is inherited from the main agent. tool_names here are just name strings; resolving them to
+    objects happens at Application build time (see build_folder_kwargs). skills_path is the
+    physical path of the subagent's own ``skills/`` directory (when present); the Application
+    mounts it into the CompositeBackend shared with the main agent and uses it as that subagent's
+    skill source.
+    """
+
+    name: str
+    description: str
+    system_prompt: str
+    tool_names: list[str] = field(default_factory=list)
+    interrupt_config: dict[str, Any] = field(default_factory=dict)
+    skills_path: Path | None = None
+
+
+@dataclass
+class FolderSpec:
+    """Baseline spec for one folder agent (the folder owns model / system_prompt / interrupt)."""
+
+    agent_id: str
+    model: str | None = None
+    system_prompt: str | None = None
+    tool_names: list[str] = field(default_factory=list)
+    interrupt_config: dict[str, Any] = field(default_factory=dict)
+    name: str | None = None
+    description: str | None = None
+    skills_path: Path | None = None  # physical path of skills/ (if present), else None
+    subagents: list[SubAgentSpec] = field(default_factory=list)
+
+    @classmethod
+    def from_path(cls, path: Path | str) -> FolderSpec:
+        return load_folder_spec(path)
+
+
+def load_folder_spec(path: Path | str) -> FolderSpec:
+    """Read an agent folder and return a FolderSpec. agent_id is taken from the folder name."""
+    folder = Path(path)
+    if not folder.is_dir():
+        raise FolderAgentError(f"folder agent path is not a directory: {folder}")
+
+    model: str | None = None
+    name: str | None = None
+    description: str | None = None
+    system_prompt: str | None = None
+    tool_names: list[str] = []
+    interrupt_config: dict[str, Any] = {}
+
+    config_path = folder / CONFIG_FILE
+    if config_path.is_file():
+        config = _read_json(config_path)
+        name = _opt_str(config.get("name"), "name", config_path)
+        description = _opt_str(config.get("description"), "description", config_path)
+        model = _extract_model_id(config, config_path)
+
+    agent_md = folder / AGENT_FILE
+    if agent_md.is_file():
+        # The main agent's description comes from config.json; if AGENTS.md has frontmatter,
+        # strip it and keep only the body.
+        _, body = _parse_frontmatter(agent_md.read_text(encoding="utf-8"))
+        system_prompt = body.strip() or None
+
+    tools_path = folder / TOOLS_FILE
+    if tools_path.is_file():
+        tools_data = _read_json(tools_path)
+        tool_names = _extract_tool_names(tools_data, tools_path)
+        interrupt_config = _extract_interrupt_config(tools_data, tools_path)
+
+    skills_dir = folder / SKILLS_DIR
+    skills_path = skills_dir if skills_dir.is_dir() else None
+
+    subagents = _load_subagents(folder / SUBAGENTS_DIR)
+
+    return FolderSpec(
+        agent_id=folder.name,
+        model=model,
+        system_prompt=system_prompt,
+        tool_names=tool_names,
+        interrupt_config=interrupt_config,
+        name=name,
+        description=description,
+        skills_path=skills_path,
+        subagents=subagents,
+    )
+
+
+def load_subagent_spec(path: Path | str) -> SubAgentSpec:
+    """Read a subagent subdirectory and return a SubAgentSpec. name is taken from the subdir name.
+
+    ``AGENTS.md``: ``description`` from the YAML frontmatter plus the body as system_prompt; both
+    are required.
+    ``tools.json``: optional, reuses the main agent's tools / interrupt_config parsing.
+    ``skills/``: optional, the subagent's own Agent Skills directory; if present it is recorded in
+    ``skills_path``.
+    """
+    folder = Path(path)
+    if not folder.is_dir():
+        raise FolderAgentError(f"subagent path is not a directory: {folder}")
+
+    agent_md = folder / AGENT_FILE
+    if not agent_md.is_file():
+        raise FolderAgentError(f"subagent {folder.name!r} is missing {AGENT_FILE}")
+
+    front, body = _parse_frontmatter(agent_md.read_text(encoding="utf-8"))
+    description = _opt_str(front.get("description"), "description", agent_md)
+    if not description:
+        raise FolderAgentError(
+            f"subagent {folder.name!r}'s {AGENT_FILE} frontmatter is missing description"
+        )
+    system_prompt = body.strip()
+    if not system_prompt:
+        raise FolderAgentError(f"subagent {folder.name!r}'s {AGENT_FILE} body is empty")
+
+    tool_names: list[str] = []
+    interrupt_config: dict[str, Any] = {}
+    tools_path = folder / TOOLS_FILE
+    if tools_path.is_file():
+        tools_data = _read_json(tools_path)
+        tool_names = _extract_tool_names(tools_data, tools_path)
+        interrupt_config = _extract_interrupt_config(tools_data, tools_path)
+
+    skills_dir = folder / SKILLS_DIR
+    skills_path = skills_dir if skills_dir.is_dir() else None
+
+    return SubAgentSpec(
+        name=folder.name,
+        description=description,
+        system_prompt=system_prompt,
+        tool_names=tool_names,
+        interrupt_config=interrupt_config,
+        skills_path=skills_path,
+    )
+
+
+def _load_subagents(subagents_dir: Path) -> list[SubAgentSpec]:
+    """Scan subagents/: each subdir with an AGENTS.md -> one SubAgentSpec (sorted by name)."""
+    if not subagents_dir.is_dir():
+        return []
+    specs: list[SubAgentSpec] = []
+    for sub in sorted(subagents_dir.iterdir()):
+        if not sub.is_dir() or sub.name.startswith((".", "__")):
+            continue
+        if not (sub / AGENT_FILE).is_file():
+            continue
+        specs.append(load_subagent_spec(sub))
+    return specs
+
+
+# ---- helpers ----
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise FolderAgentError(f"{path} is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise FolderAgentError(
+            f"{path} top level should be an object, but is {type(data).__name__}"
+        )
+    return data
+
+
+def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Split the leading YAML frontmatter from the body.
+
+    No frontmatter -> ``({}, text)``. If the frontmatter is invalid or not a mapping it is treated
+    as empty (returns ``{}``), and the body is whatever remains after the frontmatter.
+    """
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return {}, text
+    try:
+        data = yaml.safe_load(match.group(1))
+    except yaml.YAMLError:
+        data = None
+    front = data if isinstance(data, dict) else {}
+    body = text[match.end() :]
+    return front, body
+
+
+def _nested_get(data: dict[str, Any], *keys: str) -> Any:
+    cur: Any = data
+    for key in keys:
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(key)
+    return cur
+
+
+def _opt_str(value: Any, field_name: str, source: Path) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise FolderAgentError(
+            f"{source}'s {field_name} should be a string, but is {type(value).__name__}"
+        )
+    return value
+
+
+def _extract_model_id(config: dict[str, Any], source: Path) -> str | None:
+    model_id = _nested_get(config, "config", "configurable", "llm_model_config", "modelId")
+    model = _opt_str(model_id, "modelId", source)
+    if model == PLATFORM_DEFAULT_MODEL:
+        return None  # platform placeholder -> unspecified, defers to the model priority chain
+    return model
+
+
+def _extract_tool_names(data: dict[str, Any], source: Path) -> list[str]:
+    tools = data.get("tools", [])
+    if not isinstance(tools, list):
+        raise FolderAgentError(
+            f"{source}'s tools should be an array, but is {type(tools).__name__}"
+        )
+    for item in tools:
+        if not isinstance(item, str):
+            raise FolderAgentError(
+                f"{source}'s tools should all be strings (tool names), found {type(item).__name__}"
+            )
+    return list(tools)
+
+
+def _extract_interrupt_config(data: dict[str, Any], source: Path) -> dict[str, Any]:
+    interrupt = data.get("interrupt_config", {})
+    if not isinstance(interrupt, dict):
+        raise FolderAgentError(
+            f"{source}'s interrupt_config should be an object, but is {type(interrupt).__name__}"
+        )
+    return interrupt

easy_agentic_plugin/graph.py

@@ -0,0 +1,51 @@
+"""main graph -- easy-agentic-plugin's single graph entry point.
+
+Takes agent_id from the request (defaulting to "default"), uses thread_id as the session,
+and delegates to application.resolve to resolve the actual agent and run it.
+
+Consumers can reference `easy_agentic_plugin.graph:main` directly in their own langgraph.json,
+or compile it themselves via the `build_graph()` factory (e.g. to swap State / add nodes).
+"""
+
+from __future__ import annotations
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.graph.state import CompiledStateGraph
+
+
+class State(MessagesState):
+    agent_id: str
+
+
+def route(state: State, config: RunnableConfig) -> dict:
+    from easy_agentic_plugin import get_application
+
+    _application = get_application()
+    agent_id = state.get("agent_id", "default")
+    messages = state.get("messages", [])
+
+    thread_id = (config.get("configurable") or {}).get("thread_id", "default")
+    agent = _application.resolve(agent_id=agent_id, session_id=thread_id)
+
+    response = agent.invoke({"messages": messages}, config=config)
+    messages = response.get("messages", [])
+
+    return {"messages": messages}
+
+
+def _build() -> StateGraph:
+    builder = StateGraph(State)
+    builder.add_node("route", route)
+    builder.add_edge(START, "route")
+    builder.add_edge("route", END)
+    return builder
+
+
+def build_graph() -> CompiledStateGraph:
+    """Compile and return the global routing graph (usable by langgraph.json / consumers)."""
+    return _build().compile()
+
+
+# The entry-point object that langgraph.json points to.
+main = build_graph()

easy_agentic_plugin/merge.py

@@ -0,0 +1,137 @@
+"""Merge the AgentContributions of multiple plugins into kwargs for create_deep_agent.
+
+Merge rules (see ADR-0002 §3):
+- Additive fields (tools/subagents/skills/middleware): concatenated in plugin order.
+- String references: a str in tools/middleware is resolved by name to a globally registered
+  object; an unknown name raises.
+- Dedup vs conflict: the same object (same name and identity) appearing multiple times is
+  deduplicated; two different objects colliding on the same name raises.
+- Singular fields (model/backend): None means abstain; take the non-None one with the highest
+  order, raising on a tie; if none, use the default.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .contribution import AgentContribution
+from .errors import ConflictError, UnknownReferenceError
+from .registry import NamedRegistry
+
+# (order, contribution) -- passed in by application after sorting by (order, name).
+ContributionItem = tuple[int, "AgentContribution | None"]
+
+
+def _name_of(obj: Any) -> str:
+    """Try to derive a stable name, used for dedup / conflict detection of additive fields."""
+    if isinstance(obj, str):
+        return obj
+    if isinstance(obj, dict):
+        name = obj.get("name")
+        if isinstance(name, str) and name:
+            return name
+    name = getattr(obj, "name", None)
+    if isinstance(name, str) and name:
+        return name
+    fn_name = getattr(obj, "__name__", None)
+    if isinstance(fn_name, str) and fn_name:
+        return fn_name
+    return repr(obj)
+
+
+def resolve_named(
+    entries: Sequence[Any], registry: NamedRegistry[object] | None, kind: str
+) -> list[Any]:
+    """Resolve string references to registered objects; non-strings are kept as-is.
+
+    Used by merge to resolve top-level tools/middleware, and by application to resolve
+    tool names inside a subagent.
+    """
+    resolved: list[Any] = []
+    for entry in entries:
+        if isinstance(entry, str):
+            if registry is None:
+                raise UnknownReferenceError(f"no {kind} registry available to resolve {entry!r}")
+            obj = registry.get(entry)
+            if obj is None:
+                raise UnknownReferenceError(f"unknown {kind}: {entry!r}")
+            resolved.append(obj)
+        else:
+            resolved.append(entry)
+    return resolved
+
+
+def _dedup(entries: Sequence[Any], kind: str) -> list[Any]:
+    """Dedup entries with the same name and identity; raise if different objects share a name."""
+    seen: dict[str, Any] = {}
+    out: list[Any] = []
+    for obj in entries:
+        name = _name_of(obj)
+        if name in seen:
+            if seen[name] is obj:
+                continue  # same object referenced again -> deduplicate
+            raise ConflictError(f"two different {kind} objects collide on name {name!r}")
+        seen[name] = obj
+        out.append(obj)
+    return out
+
+
+def _arbitrate(candidates: Sequence[tuple[int, Any]], default: Any, field: str) -> Any:
+    """Arbitrate a singular field: take the highest order, raise on a tie; use default if none."""
+    if not candidates:
+        return default
+    max_order = max(order for order, _ in candidates)
+    top = [value for order, value in candidates if order == max_order]
+    if len(top) > 1:
+        raise ConflictError(f"multiple plugins contributed {field} at the same order {max_order}")
+    return top[0]
+
+
+def merge_contributions(
+    items: Sequence[ContributionItem],
+    *,
+    default_model: Any | None = None,
+    tool_registry: NamedRegistry[object] | None = None,
+    middleware_registry: NamedRegistry[object] | None = None,
+) -> dict[str, Any]:
+    """Merge contributions and return kwargs for create_deep_agent (all keys kept; caller picks).
+
+    backend is no longer arbitrated as a singular field; instead each contribution's ``mounts``
+    are aggregated additively (a collision on the same mount key raises), and the caller
+    assembles a CompositeBackend from them.
+    """
+    tools: list[Any] = []
+    subagents: list[Any] = []
+    skills: list[str] = []
+    middleware: list[Any] = []
+    model_candidates: list[tuple[int, Any]] = []
+    mounts: dict[str, Any] = {}
+
+    for _order, contrib in items:
+        if contrib is None:
+            continue
+        tools.extend(contrib.tools)
+        subagents.extend(contrib.subagents)
+        skills.extend(contrib.skills)
+        middleware.extend(contrib.middleware)
+        if contrib.model is not None:
+            model_candidates.append((_order, contrib.model))
+        for mount_path, target in contrib.mounts.items():
+            if mount_path in mounts:
+                raise ConflictError(f"mount point {mount_path!r} claimed by multiple contributors")
+            mounts[mount_path] = target
+
+    tools = _dedup(resolve_named(tools, tool_registry, "tool"), "tool")
+    middleware = _dedup(resolve_named(middleware, middleware_registry, "middleware"), "middleware")
+    subagents = _dedup(subagents, "subagent")
+    skills = list(dict.fromkeys(skills))  # dedup while preserving order
+
+    return {
+        "model": _arbitrate(model_candidates, default_model, "model"),
+        "tools": tools,
+        "subagents": subagents,
+        "skills": skills,
+        "middleware": middleware,
+        "mounts": mounts,
+    }

easy_agentic_plugin/plugin.py

@@ -0,0 +1,44 @@
+"""Plugin contract: class-based, with two optional hooks (setup / build). See ADR-0002."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .context import AgentBuildContext, AppContext
+    from .contribution import AgentContribution
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Structural type for a plugin. Implementers need name/order and may provide setup/build."""
+
+    name: str
+    order: int
+
+    def setup(self, app: AppContext) -> None:
+        """Startup hook: register agents / tools / middleware / shared services (one-time init)."""
+        ...
+
+    def build(self, ctx: AgentBuildContext) -> AgentContribution | None:
+        """Agent-creation hook: called each time a folder agent is built; returns its share."""
+        ...
+
+
+class PluginBase:
+    """Recommended plugin base class: both hooks are no-ops by default; override as needed.
+
+    Subclasses must set a unique ``name``; ``order`` controls apply order (lower first, default 0).
+    """
+
+    name: str = ""
+    order: int = 0
+
+    def __init__(self, config: dict | None = None):
+        self.config = config or {}
+
+    def setup(self, app: AppContext) -> None:
+        return None
+
+    def build(self, ctx: AgentBuildContext) -> AgentContribution | None:
+        return None

easy_agentic_plugin/plugins/folder_scan/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "builtin.folder-scan",
+  "order": -100,
+  "entry": "plugin:FolderScanPlugin",
+  "config": { "agents_dir": "agents" }
+}

easy_agentic_plugin/plugins/folder_scan/plugin.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from easy_agentic_plugin import AppContext, FolderAgent, PluginBase
+
+
+class FolderScanPlugin(PluginBase):
+    def setup(self, app: AppContext) -> None:
+        base = Path(self.config.get("agents_dir", "agents"))
+        if not base.is_dir():
+            return
+        for sub in sorted(base.iterdir()):
+            if sub.is_dir() and not sub.name.startswith((".", "__")):
+                agent_file = sub / "AGENTS.md"
+                if agent_file.exists():
+                    app.register_agent(sub.name, FolderAgent(sub))

easy_agentic_plugin/registry.py

@@ -0,0 +1,44 @@
+"""Generic "name -> object" registry that fails fast on duplicate names by default.
+
+Reused by all three registries: agent / tool / middleware.
+"""
+
+from __future__ import annotations
+
+from .errors import ConflictError, UnknownReferenceError
+
+
+class NamedRegistry[T]:
+    def __init__(self, label: str) -> None:
+        self._label = label
+        self._items: dict[str, T] = {}
+
+    def register(self, name: str, item: T, *, override: bool = False) -> None:
+        """Register an object. Raises ConflictError on a duplicate name unless ``override``."""
+        if not name:
+            raise ValueError(f"{self._label} name must not be empty")
+        if name in self._items and not override:
+            raise ConflictError(
+                f"{self._label} {name!r} already registered (pass override=True to replace)"
+            )
+        self._items[name] = item
+
+    def get(self, name: str) -> T | None:
+        """Get an object, returning None if it does not exist."""
+        return self._items.get(name)
+
+    def require(self, name: str) -> T:
+        """Get an object, raising UnknownReferenceError if it does not exist."""
+        try:
+            return self._items[name]
+        except KeyError:
+            raise UnknownReferenceError(f"unknown {self._label}: {name!r}") from None
+
+    def names(self) -> list[str]:
+        return list(self._items)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._items
+
+    def __len__(self) -> int:
+        return len(self._items)

easy_agentic_plugin/sources.py

@@ -0,0 +1,38 @@
+"""The three forms of an Agent (AgentSource).
+
+- folder (default): defined by a directory; content is injected via the plugin build phase.
+- graph: an already-compiled graph, used as-is.
+- graph factory: a function returning a graph; called to obtain the graph, used as-is.
+
+Note: the graph / factory forms do not go through plugin injection (see the scope of ADR-0002).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from langgraph.graph.state import CompiledStateGraph
+
+    from .context import AgentBuildContext
+
+
+@dataclass
+class FolderAgent:
+    """Folder form: the agent is defined by a directory.
+
+    The baseline spec format inside the folder is still undecided (architecture open-item A);
+    for now it only holds the path.
+    """
+
+    path: Path
+
+
+# Factory function returning a graph (receives the build context).
+GraphFactory = Callable[["AgentBuildContext"], "CompiledStateGraph"]
+
+# The agent source registered with the application: one of the three forms.
+AgentSource = Union["FolderAgent", "CompiledStateGraph", "GraphFactory"]