dagent-ai 0.2.1__py3-none-any.whl

dagent/__init__.py

@@ -0,0 +1,90 @@
+"""Reviewable DAG agent runtime SDK."""
+
+from dagent.agent import AutoAgent, DagAgent, ToolAgent
+from dagent.capabilities import (
+    SkillAmbiguousError,
+    SkillEntry,
+    SkillNotFoundError,
+    SkillPermissionError,
+    SkillStore,
+    SkillStoreError,
+    SkillView,
+    default_managed_skill_root,
+    default_skill_roots,
+)
+from dagent.capabilities.decorator import CapabilityBinding, tool
+from dagent.dag_builder import ArtifactRef, ArtifactValueRef, Dag, FormatRef, InputRef, Node, NodeOutputRef
+from dagent.harness_runtime import ArtifactUpload, CapabilityScope, validate_dag_spec
+from dagent.profiles import AgentProfile, ProfileStore, list_builtin_profiles, load_builtin_profile
+from dagent.providers import Provider
+from dagent.result import RunResult, RunStreamChunk, RunStreamEvent
+from dagent.review import ReviewDecision, ReviewHandle, ReviewLevel
+from dagent.runner import Runner
+from dagent.schemas import (
+    Boundary,
+    CapabilityDefinition,
+    CapabilityInvocation,
+    CapabilityPolicy,
+    CapabilityResult,
+    DAG,
+    DAGRun,
+    DAGSpec,
+    PendingReview,
+    RiskLevel,
+    RunTrace,
+    RuntimeResponse,
+)
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "__version__",
+    "AgentProfile",
+    "ArtifactRef",
+    "ArtifactUpload",
+    "ArtifactValueRef",
+    "AutoAgent",
+    "Boundary",
+    "CapabilityBinding",
+    "CapabilityDefinition",
+    "CapabilityInvocation",
+    "CapabilityPolicy",
+    "CapabilityResult",
+    "CapabilityScope",
+    "DAG",
+    "DAGRun",
+    "DAGSpec",
+    "DagAgent",
+    "Dag",
+    "FormatRef",
+    "InputRef",
+    "list_builtin_profiles",
+    "load_builtin_profile",
+    "Node",
+    "NodeOutputRef",
+    "PendingReview",
+    "ProfileStore",
+    "Provider",
+    "ReviewLevel",
+    "ReviewDecision",
+    "ReviewHandle",
+    "RiskLevel",
+    "RunResult",
+    "RunStreamChunk",
+    "RunStreamEvent",
+    "RunTrace",
+    "RuntimeResponse",
+    "Runner",
+    "SkillAmbiguousError",
+    "SkillEntry",
+    "SkillNotFoundError",
+    "SkillPermissionError",
+    "SkillStore",
+    "SkillStoreError",
+    "SkillView",
+    "ToolAgent",
+    "default_managed_skill_root",
+    "default_skill_roots",
+    "tool",
+    "validate_dag_spec",
+]

dagent/agent.py

@@ -0,0 +1,89 @@
+"""Declarative public agent SDK configurations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from dagent.capabilities.decorator import CapabilityBinding
+from dagent.profiles import AgentProfile
+from dagent.review import ReviewLevel
+
+
+CapabilityRef = CapabilityBinding | str
+
+
+@dataclass(frozen=True)
+class AutoAgent:
+    """Agent configuration that lets the runtime choose tool-loop or DAG execution."""
+
+    profile: str | AgentProfile = "conversation"
+    planner_profile: str | AgentProfile = "dag_agent"
+    name: str | None = None
+    max_steps: int = 8
+    max_cycles: int = 6
+    capabilities: Iterable[CapabilityRef] | None = None
+    skills: Iterable[str] | None = None
+    review: ReviewLevel = "fast"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", self.name or _default_profile_name(self.profile))
+        if self.max_steps < 1:
+            raise ValueError("max_steps must be at least 1.")
+        if self.max_cycles < 1:
+            raise ValueError("max_cycles must be at least 1.")
+        if self.capabilities is not None:
+            object.__setattr__(self, "capabilities", tuple(self.capabilities))
+        if self.skills is not None:
+            object.__setattr__(self, "skills", tuple(str(skill) for skill in self.skills))
+
+
+@dataclass(frozen=True)
+class ToolAgent:
+    """Profile-backed tool-loop agent configuration."""
+
+    profile: str | AgentProfile
+    name: str | None = None
+    max_steps: int = 8
+    capabilities: Iterable[CapabilityRef] | None = None
+    skills: Iterable[str] | None = None
+    review: ReviewLevel = "fast"
+    description: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", self.name or _default_profile_name(self.profile))
+        if self.max_steps < 1:
+            raise ValueError("max_steps must be at least 1.")
+        if self.capabilities is not None:
+            object.__setattr__(self, "capabilities", tuple(self.capabilities))
+        if self.skills is not None:
+            object.__setattr__(self, "skills", tuple(str(skill) for skill in self.skills))
+
+
+@dataclass(frozen=True)
+class DagAgent:
+    """Dynamic DAG planner configuration."""
+
+    planner_profile: str | AgentProfile = "dag_agent"
+    name: str | None = None
+    max_cycles: int = 6
+    capabilities: Iterable[CapabilityRef] | None = None
+    skills: Iterable[str] | None = None
+    review: ReviewLevel = "fast"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", self.name or _default_profile_name(self.planner_profile))
+        if self.max_cycles < 1:
+            raise ValueError("max_cycles must be at least 1.")
+        if self.capabilities is not None:
+            object.__setattr__(self, "capabilities", tuple(self.capabilities))
+        if self.skills is not None:
+            object.__setattr__(self, "skills", tuple(str(skill) for skill in self.skills))
+
+
+def _default_profile_name(profile: str | AgentProfile) -> str:
+    if isinstance(profile, AgentProfile):
+        return profile.name
+    path = Path(profile)
+    return path.stem if path.suffix == ".md" else path.name

dagent/capabilities/__init__.py

@@ -0,0 +1,42 @@
+"""Capability registration and providers."""
+
+from dagent.capabilities.bootstrap import create_default_capability_catalog
+from dagent.capabilities.catalog import CapabilityCatalog
+from dagent.capabilities.decorator import CapabilityBinding, tool
+from dagent.capabilities.mcp import MCPCapabilityProvider
+from dagent.capabilities.providers import AgentCapabilityProvider, AgentNodeSessionStore
+from dagent.capabilities.skills import (
+    SkillAmbiguousError,
+    SkillEntry,
+    SkillNotFoundError,
+    SkillPermissionError,
+    SkillStore,
+    SkillStoreError,
+    SkillView,
+    SkillsCapabilityProvider,
+    default_managed_skill_root,
+    default_skill_roots,
+)
+from dagent.capabilities.toolsets import CapabilityToolAdapter, CapabilityToolset
+
+__all__ = [
+    "AgentCapabilityProvider",
+    "AgentNodeSessionStore",
+    "CapabilityBinding",
+    "CapabilityCatalog",
+    "CapabilityToolAdapter",
+    "CapabilityToolset",
+    "MCPCapabilityProvider",
+    "SkillAmbiguousError",
+    "SkillEntry",
+    "SkillNotFoundError",
+    "SkillPermissionError",
+    "SkillStore",
+    "SkillStoreError",
+    "SkillView",
+    "SkillsCapabilityProvider",
+    "create_default_capability_catalog",
+    "default_managed_skill_root",
+    "default_skill_roots",
+    "tool",
+]

dagent/capabilities/bootstrap.py

@@ -0,0 +1,28 @@
+"""Default capability catalog assembly."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dagent.capabilities.catalog import CapabilityCatalog
+from dagent.capabilities.providers import (
+    MemoryCapabilityProvider,
+    ToolCapabilityProvider,
+)
+from dagent.capabilities.skills import SkillsCapabilityProvider
+from dagent.capabilities.tools.file_tools import create_file_tool_registry
+
+
+def create_default_capability_catalog(
+    *,
+    workspace_root: str | Path = ".",
+    skill_roots: list[str | Path] | None = None,
+    skills_provider: SkillsCapabilityProvider | None = None,
+) -> CapabilityCatalog:
+    if skills_provider is not None and skill_roots is not None:
+        raise ValueError("Pass either skill_roots or skills_provider, not both.")
+    catalog = CapabilityCatalog(workspace_root=workspace_root)
+    ToolCapabilityProvider(create_file_tool_registry()).register_into(catalog)
+    MemoryCapabilityProvider().register_into(catalog)
+    (skills_provider or SkillsCapabilityProvider(skill_roots)).register_into(catalog)
+    return catalog

dagent/capabilities/boundaries.py

@@ -0,0 +1,32 @@
+"""Boundary inference for capability invocations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dagent.schemas import Boundary, CapabilityDefinition
+
+
+def infer_capability_boundary(
+    definition: CapabilityDefinition | None,
+    args: dict[str, Any],
+) -> Boundary:
+    if definition is None:
+        return Boundary(mode="read_only")
+    config = definition.config
+    checked_args = {**(config.get("default_args") or {}), **args}
+    path_args = tuple(config.get("path_args") or ())
+    paths = [_boundary_path_value(checked_args.get(path_arg)) for path_arg in path_args] or ["."]
+    action = str(config.get("action") or "read")
+
+    if action in {"write", "command"}:
+        return Boundary(mode="write_limited", allowed_paths=paths)
+    return Boundary(mode="read_only", allowed_paths=paths)
+
+
+def _boundary_path_value(value: Any) -> Any:
+    if value is None or value == "":
+        return "."
+    if isinstance(value, dict):
+        return value
+    return str(value)

dagent/capabilities/catalog.py

@@ -0,0 +1,131 @@
+"""Catalog for executable capabilities."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from dagent.schemas import (
+    CapabilityDefinition,
+    CapabilityInvocation,
+    CapabilityKind,
+    CapabilityResult,
+)
+
+
+CapabilityHandlerResult = CapabilityResult | Awaitable[CapabilityResult]
+CapabilityHandler = Callable[..., CapabilityHandlerResult]
+ShutdownHook = Callable[[], None]
+
+
+@dataclass(frozen=True)
+class CapabilityEntry:
+    definition: CapabilityDefinition
+    handler: CapabilityHandler
+    supports_context: bool = False
+
+
+class CapabilityCatalog:
+    """Owns capability definitions and their executable handlers."""
+
+    def __init__(self, *, workspace_root: str | Path = ".") -> None:
+        self.workspace_root = Path(workspace_root).resolve()
+        self._entries: dict[str, CapabilityEntry] = {}
+        self._shutdown_hooks: list[ShutdownHook] = []
+        self._shutdown_complete = False
+
+    def register(
+        self,
+        definition: CapabilityDefinition,
+        handler: CapabilityHandler,
+        *,
+        supports_context: bool = False,
+    ) -> None:
+        if definition.id in self._entries:
+            raise ValueError(f"Capability '{definition.id}' is already registered.")
+        self._entries[definition.id] = CapabilityEntry(
+            definition=definition.model_copy(deep=True),
+            handler=handler,
+            supports_context=supports_context,
+        )
+
+    def replace(
+        self,
+        definition: CapabilityDefinition,
+        handler: CapabilityHandler,
+        *,
+        supports_context: bool = False,
+    ) -> None:
+        if definition.id not in self._entries:
+            raise KeyError(f"Capability '{definition.id}' is not registered.")
+        self._entries[definition.id] = CapabilityEntry(
+            definition=definition.model_copy(deep=True),
+            handler=handler,
+            supports_context=supports_context,
+        )
+
+    def set_enabled(self, capability_id: str, enabled: bool) -> CapabilityDefinition:
+        entry = self._entries.get(capability_id)
+        if entry is None:
+            raise KeyError(f"Capability '{capability_id}' is not registered.")
+        updated = entry.definition.model_copy(update={"enabled": enabled}, deep=True)
+        self._entries[capability_id] = CapabilityEntry(
+            definition=updated,
+            handler=entry.handler,
+            supports_context=entry.supports_context,
+        )
+        return updated
+
+    def delete(self, capability_id: str) -> None:
+        self._entries.pop(capability_id, None)
+
+    def get(self, capability_id: str) -> CapabilityDefinition | None:
+        entry = self._entries.get(capability_id)
+        return entry.definition.model_copy(deep=True) if entry is not None else None
+
+    def get_entry(self, capability_id: str) -> CapabilityEntry | None:
+        return self._entries.get(capability_id)
+
+    def get_by_name(self, name: str, *, kind: CapabilityKind | None = None) -> CapabilityDefinition | None:
+        for entry in self._entries.values():
+            definition = entry.definition
+            if definition.name == name and (kind is None or definition.kind == kind):
+                return definition.model_copy(deep=True)
+        return None
+
+    def list(self, *, kind: CapabilityKind | None = None, enabled_only: bool = False) -> list[CapabilityDefinition]:
+        definitions = [entry.definition for entry in self._entries.values()]
+        if kind is not None:
+            definitions = [definition for definition in definitions if definition.kind == kind]
+        if enabled_only:
+            definitions = [definition for definition in definitions if definition.enabled]
+        return sorted(
+            [definition.model_copy(deep=True) for definition in definitions],
+            key=lambda definition: definition.id,
+        )
+
+    def names(self, *, kind: CapabilityKind | None = None) -> set[str]:
+        return {definition.name for definition in self.list(kind=kind)}
+
+    def ids(self) -> set[str]:
+        return set(self._entries)
+
+    def add_shutdown_hook(self, hook: ShutdownHook) -> None:
+        if hook not in self._shutdown_hooks:
+            self._shutdown_hooks.append(hook)
+
+    def remove_shutdown_hook(self, hook: ShutdownHook) -> None:
+        try:
+            self._shutdown_hooks.remove(hook)
+        except ValueError:
+            pass
+
+    def shutdown(self) -> None:
+        if self._shutdown_complete:
+            return
+        self._shutdown_complete = True
+        hooks = list(self._shutdown_hooks)
+        self._shutdown_hooks.clear()
+        for hook in hooks:
+            hook()

dagent/capabilities/decorator.py

@@ -0,0 +1,207 @@
+"""Public capability decorator for the dagent SDK."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel
+
+from dagent.capabilities.catalog import CapabilityHandler
+from dagent.schemas import (
+    CapabilityDefinition,
+    CapabilityInvocation,
+    CapabilityPolicy,
+    CapabilityResult,
+    RiskLevel,
+)
+from dagent.schemas.common import json_schema_for_type
+
+
+@dataclass(frozen=True)
+class CapabilityBinding:
+    """A public SDK binding of a capability definition and executable handler."""
+
+    definition: CapabilityDefinition
+    handler: CapabilityHandler
+    supports_context: bool = False
+
+
+def tool(
+    fn: Callable[..., Any] | None = None,
+    *,
+    id: str | None = None,
+    name: str | None = None,
+    description: str = "",
+    risk: RiskLevel = "low",
+    requires_review: bool = False,
+    sandbox_required: bool = False,
+    network: bool = False,
+    secrets: list[str] | None = None,
+    parameters: dict[str, Any] | None = None,
+    config: dict[str, Any] | None = None,
+    enabled: bool = True,
+    supports_context: bool = False,
+) -> CapabilityBinding | Callable[[Callable[..., Any]], CapabilityBinding]:
+    """Decorate a Python function as a dagent tool capability.
+
+    This is the public way to expose a Python function as an LLM-callable
+    tool. MCP and skill capabilities are registered through
+    ``Runner.add_mcp_server`` and ``Runner.add_skill_root``.
+    """
+
+    def decorate(func: Callable[..., Any]) -> CapabilityBinding:
+        type_hints = _type_hints_for(func)
+        capability_name = name or func.__name__
+        capability_id = id or f"tool.{capability_name}"
+        definition = CapabilityDefinition(
+            id=capability_id,
+            name=capability_name,
+            kind="tool",
+            description=description or inspect.getdoc(func) or "",
+            parameters=parameters or _schema_from_signature(func, type_hints),
+            output_schema=_output_schema_from_signature(func, type_hints),
+            policy=CapabilityPolicy(
+                risk=risk,
+                requires_review=requires_review,
+                sandbox_required=sandbox_required,
+                network=network,
+                secrets=secrets or [],
+            ),
+            config=config or {},
+            enabled=enabled,
+        )
+
+        async def handler(
+            invocation: CapabilityInvocation,
+            *,
+            context: Any = None,
+            callbacks: Any = None,
+        ) -> CapabilityResult:
+            try:
+                result = _invoke_function(
+                    func,
+                    invocation.arguments,
+                    context=context,
+                    callbacks=callbacks,
+                    supports_context=supports_context,
+                )
+                if inspect.isawaitable(result):
+                    result = await result
+                if isinstance(result, CapabilityResult):
+                    return _normalize_capability_result(result)
+                content, value = _content_and_value_from_result(result)
+                return CapabilityResult(
+                    invocation_id=invocation.invocation_id,
+                    capability_id=invocation.capability_id,
+                    kind=invocation.kind,
+                    status="completed",
+                    content=content,
+                    value=value,
+                )
+            except Exception as exc:
+                return CapabilityResult(
+                    invocation_id=invocation.invocation_id,
+                    capability_id=invocation.capability_id,
+                    kind=invocation.kind,
+                    status="failed",
+                    error=str(exc),
+                    stop_reason=type(exc).__name__,
+                )
+
+        return CapabilityBinding(
+            definition=definition,
+            handler=handler,
+            supports_context=supports_context,
+        )
+
+    if fn is not None:
+        return decorate(fn)
+    return decorate
+
+
+def _invoke_function(
+    func: Callable[..., Any],
+    arguments: dict[str, Any],
+    *,
+    context: Any,
+    callbacks: Any,
+    supports_context: bool,
+) -> Any:
+    if supports_context:
+        return func(**arguments, context=context, callbacks=callbacks)
+    return func(**arguments)
+
+
+def _content_and_value_from_result(result: Any) -> tuple[str, Any]:
+    if result is None:
+        return "", None
+    if isinstance(result, BaseModel):
+        value = result.model_dump(mode="json")
+        return result.model_dump_json(), value
+    if isinstance(result, str):
+        return result, result
+    if isinstance(result, bytes):
+        value = result.decode("utf-8", errors="replace")
+        return value, value
+    if isinstance(result, tuple):
+        value = list(result)
+        return json.dumps(value, ensure_ascii=False), value
+    if isinstance(result, (dict, list, bool, int, float)):
+        return json.dumps(result, ensure_ascii=False), result
+    value = str(result)
+    return value, value
+
+
+def _normalize_capability_result(result: CapabilityResult) -> CapabilityResult:
+    if result.status == "completed" and result.value is None:
+        return result.model_copy(update={"value": result.content})
+    return result
+
+
+def _schema_from_signature(func: Callable[..., Any], type_hints: dict[str, Any]) -> dict[str, Any]:
+    signature = inspect.signature(func)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for parameter in signature.parameters.values():
+        if parameter.kind in {
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        }:
+            raise ValueError(f"Cannot infer schema for variadic parameter '{parameter.name}'.")
+        if parameter.name in {"context", "callbacks"}:
+            continue
+        schema = _schema_for_annotation(type_hints.get(parameter.name, parameter.annotation))
+        if parameter.default is inspect.Parameter.empty:
+            required.append(parameter.name)
+        else:
+            schema["default"] = parameter.default
+        properties[parameter.name] = schema
+    output: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        output["required"] = required
+    return output
+
+
+def _output_schema_from_signature(func: Callable[..., Any], type_hints: dict[str, Any]) -> dict[str, Any]:
+    annotation = type_hints.get("return", inspect.signature(func).return_annotation)
+    return json_schema_for_type(annotation)
+
+
+def _type_hints_for(func: Callable[..., Any]) -> dict[str, Any]:
+    try:
+        return get_type_hints(func, include_extras=True)
+    except (NameError, TypeError, AttributeError):
+        return {}
+
+
+def _schema_for_annotation(annotation: Any) -> dict[str, Any]:
+    if annotation is inspect.Parameter.empty:
+        return {"type": "string"}
+    return json_schema_for_type(annotation) or {"type": "string"}