agentspec-ai 0.1.0__py3-none-any.whl

agentspec/__init__.py

@@ -0,0 +1,13 @@
+"""AgentSpec — The OpenAPI for Agentic AI.
+
+A universal specification standard for AI agent behavioral contracts.
+"""
+
+__version__ = "0.1.0"
+__spec_version__ = "0.1.0"
+
+from agentspec.core.models import AgentSpecDocument
+from agentspec.core.loader import SpecLoader
+from agentspec.core.validator import SpecValidator
+
+__all__ = ["AgentSpecDocument", "SpecLoader", "SpecValidator", "__version__", "__spec_version__"]

agentspec/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running agentspec as a module: python -m agentspec."""
+
+from agentspec.cli.app import app
+
+if __name__ == "__main__":
+    app()

agentspec/adapters/__init__.py

@@ -0,0 +1,45 @@
+"""Framework adapters for connecting AgentSpec to agent frameworks.
+
+Provides abstract base class and registry for adapter plugins.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class AgentAdapter(ABC):
+    """Abstract base class for all framework adapters."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to an agent instance."""
+
+    @abstractmethod
+    def extract_spec(self) -> dict[str, Any]:
+        """Extract a partial AgentSpec from the connected agent."""
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Disconnect from the agent."""
+
+
+class AdapterRegistry:
+    """Registry for discovering and loading adapters."""
+
+    _adapters: dict[str, type[AgentAdapter]] = {}
+
+    @classmethod
+    def register(cls, name: str, adapter_cls: type[AgentAdapter]) -> None:
+        cls._adapters[name] = adapter_cls
+
+    @classmethod
+    def get(cls, name: str) -> type[AgentAdapter] | None:
+        return cls._adapters.get(name)
+
+    @classmethod
+    def list_adapters(cls) -> list[str]:
+        return list(cls._adapters.keys())

agentspec/adapters/autogen.py

@@ -0,0 +1,116 @@
+"""AutoGen framework adapter.
+
+Connects to AutoGen ConversableAgent or AssistantAgent and extracts
+a partial AgentSpec.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentspec.adapters import AgentAdapter, AdapterRegistry
+
+
+class AutoGenAdapter(AgentAdapter):
+    """Adapter for Microsoft AutoGen agents.
+
+    Supports ConversableAgent, AssistantAgent, and UserProxyAgent.
+    Extracts system messages, registered functions, and model config.
+    """
+
+    name = "autogen"
+
+    def __init__(self) -> None:
+        self._agent: Any = None
+        self._system_message: str | None = None
+        self._functions: list[dict[str, Any]] = []
+        self._model: str | None = None
+
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to an AutoGen agent by importing its module.
+
+        Args:
+            source: Python module path to the agent.
+                    The module must expose an ``agent`` attribute.
+        """
+        import importlib
+
+        try:
+            module = importlib.import_module(source)
+            self._agent = getattr(module, "agent", None) or getattr(module, "assistant", None)
+        except ImportError as exc:
+            raise ConnectionError(f"Cannot import AutoGen agent from '{source}': {exc}") from exc
+
+        if self._agent is not None:
+            self._system_message = getattr(self._agent, "system_message", None)
+            self._extract_model()
+            self._extract_functions()
+
+    def disconnect(self) -> None:
+        self._agent = None
+
+    def extract_spec(self) -> dict[str, Any]:
+        """Extract a partial AgentSpec from the AutoGen agent."""
+        capabilities = [
+            {
+                "id": _to_kebab(fn.get("name", f"fn-{i}")),
+                "name": fn.get("name", f"Function {i}"),
+                "description": fn.get("description", ""),
+                "category": "tool-use",
+            }
+            for i, fn in enumerate(self._functions)
+        ]
+
+        # Add a default reasoning capability based on system message
+        if self._system_message and not capabilities:
+            capabilities.append({
+                "id": "agent-reasoning",
+                "name": "Agent Reasoning",
+                "description": self._system_message[:200],
+                "category": "reasoning",
+            })
+
+        spec: dict[str, Any] = {
+            "agentspec": "0.1.0",
+            "info": {"name": "autogen-agent", "version": "0.1.0"},
+            "agent": {
+                "type": "semi-autonomous",
+                "runtime": {
+                    "framework": "autogen",
+                    "model": self._model or "gpt-4o",
+                    "model_provider": "openai",
+                },
+            },
+            "capabilities": capabilities or [{"id": "default-task", "name": "Default Task", "category": "reasoning"}],
+            "boundaries": [],
+            "guardrails": {"behavioral_guardrails": {}},
+            "failure_modes": [],
+        }
+        return spec
+
+    def _extract_model(self) -> None:
+        if self._agent is None:
+            return
+        llm_config = getattr(self._agent, "llm_config", None) or {}
+        if isinstance(llm_config, dict):
+            configs = llm_config.get("config_list", [])
+            if configs and isinstance(configs[0], dict):
+                self._model = configs[0].get("model")
+
+    def _extract_functions(self) -> None:
+        if self._agent is None:
+            return
+        # AutoGen stores function_map as a dict
+        fn_map = getattr(self._agent, "function_map", {}) or {}
+        for name, fn in fn_map.items():
+            self._functions.append({
+                "name": name,
+                "description": getattr(fn, "__doc__", "") or "",
+            })
+
+
+def _to_kebab(name: str) -> str:
+    return name.replace("_", "-").replace(" ", "-").lower()
+
+
+AdapterRegistry.register("autogen", AutoGenAdapter)

agentspec/adapters/crewai.py

@@ -0,0 +1,102 @@
+"""CrewAI framework adapter.
+
+Maps CrewAI Agent/Crew/Task concepts to AgentSpec sections.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentspec.adapters import AgentAdapter, AdapterRegistry
+
+
+class CrewAIAdapter(AgentAdapter):
+    """Adapter for CrewAI Crew objects.
+
+    Maps Crew → multi-agent-orchestrator, Agent → agent,
+    Task → capability, Tool → tool.
+    """
+
+    name = "crewai"
+
+    def __init__(self) -> None:
+        self._crew: Any = None
+        self._agents: list[Any] = []
+        self._tasks: list[Any] = []
+        self._tools: list[Any] = []
+
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to a CrewAI Crew by importing its module.
+
+        Args:
+            source: Python module path to the crew (e.g., "my_crew.crew").
+                    The module must expose a ``crew`` attribute.
+        """
+        import importlib
+
+        try:
+            module = importlib.import_module(source)
+            self._crew = getattr(module, "crew", None)
+        except ImportError as exc:
+            raise ConnectionError(f"Cannot import CrewAI crew from '{source}': {exc}") from exc
+
+        if self._crew is not None:
+            self._agents = list(getattr(self._crew, "agents", []) or [])
+            self._tasks = list(getattr(self._crew, "tasks", []) or [])
+            # Collect tools from all agents
+            for agent in self._agents:
+                self._tools.extend(getattr(agent, "tools", []) or [])
+
+    def disconnect(self) -> None:
+        """Release references."""
+        self._crew = None
+        self._agents = []
+        self._tasks = []
+        self._tools = []
+
+    def extract_spec(self) -> dict[str, Any]:
+        """Extract a partial spec from the CrewAI crew."""
+        capabilities = [
+            {
+                "id": _to_kebab(getattr(task, "description", f"task-{i}")[:40]),
+                "name": getattr(task, "name", f"Task {i}") or f"Task {i}",
+                "description": getattr(task, "description", ""),
+                "category": "reasoning",
+            }
+            for i, task in enumerate(self._tasks)
+        ]
+
+        tools_spec = [
+            {
+                "id": _to_kebab(getattr(t, "name", f"tool-{i}")),
+                "name": getattr(t, "name", f"Tool {i}"),
+                "protocol": "custom",
+                "permissions": ["read"],
+            }
+            for i, t in enumerate(self._tools)
+        ]
+
+        agent_type = "multi-agent-orchestrator" if len(self._agents) > 1 else "autonomous"
+
+        spec: dict[str, Any] = {
+            "agentspec": "0.1.0",
+            "info": {"name": "crewai-crew", "version": "0.1.0"},
+            "agent": {
+                "type": agent_type,
+                "runtime": {"framework": "crewai"},
+            },
+            "capabilities": capabilities,
+            "boundaries": [],
+            "guardrails": {"behavioral_guardrails": {}},
+            "failure_modes": [],
+        }
+        if tools_spec:
+            spec["tools"] = tools_spec
+        return spec
+
+
+def _to_kebab(name: str) -> str:
+    return name.replace("_", "-").replace(" ", "-").lower().strip("-")[:40]
+
+
+AdapterRegistry.register("crewai", CrewAIAdapter)

agentspec/adapters/generic.py

@@ -0,0 +1,165 @@
+"""Generic HTTP/callable adapter.
+
+Provides a flexible adapter for any agent exposed as:
+- A Python callable (function or class with .invoke())
+- An HTTP endpoint
+- An MCP-compatible server (stdio or HTTP/SSE)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+from agentspec.adapters import AgentAdapter, AdapterRegistry
+
+
+class GenericAdapter(AgentAdapter):
+    """Generic adapter connecting to any callable, HTTP endpoint, or MCP server.
+
+    Args:
+        auth_header: Optional ``Authorization`` header value (e.g., "Bearer <token>").
+        response_path: JSONPath-style dot-notation to extract the response text
+                       (e.g., "choices.0.message.content"). Defaults to the raw body.
+    """
+
+    name = "generic"
+
+    def __init__(
+        self,
+        auth_header: str | None = None,
+        response_path: str | None = None,
+    ) -> None:
+        self._source: str | None = None
+        self._callable: Callable[[str], str] | None = None
+        self._endpoint: str | None = None
+        self._auth_header = auth_header
+        self._response_path = response_path
+        self._discovered_tools: list[dict[str, Any]] = []
+
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to a generic source.
+
+        Args:
+            source: Either a Python module path (e.g., ``mymodule.agent``),
+                    an HTTP URL (e.g., ``http://localhost:8080/invoke``), or
+                    an MCP server path (e.g., ``mcp://localhost:8081``).
+        """
+        self._source = source
+
+        if source.startswith(("http://", "https://")):
+            self._endpoint = source
+            self._probe_http()
+        elif source.startswith("mcp://"):
+            self._probe_mcp(source)
+        else:
+            # Assume Python module path
+            import importlib
+
+            try:
+                module = importlib.import_module(source)
+                agent = (
+                    getattr(module, "agent", None)
+                    or getattr(module, "app", None)
+                    or getattr(module, "invoke", None)
+                )
+                if callable(agent):
+                    self._callable = agent
+            except ImportError as exc:
+                raise ConnectionError(f"Cannot connect to '{source}': {exc}") from exc
+
+    def disconnect(self) -> None:
+        self._callable = None
+        self._endpoint = None
+        self._source = None
+
+    def extract_spec(self) -> dict[str, Any]:
+        """Generate a partial spec from discovered information."""
+        capabilities = [
+            {
+                "id": t["id"],
+                "name": t["name"],
+                "description": t.get("description", ""),
+                "category": "tool-use",
+            }
+            for t in self._discovered_tools
+        ] or [{"id": "default-capability", "name": "Default Capability", "category": "reasoning"}]
+
+        agent_type = "tool-agent" if self._discovered_tools else "reactive"
+
+        spec: dict[str, Any] = {
+            "agentspec": "0.1.0",
+            "info": {"name": _source_to_name(self._source or "generic-agent"), "version": "0.1.0"},
+            "agent": {
+                "type": agent_type,
+                "runtime": {"framework": "custom"},
+            },
+            "capabilities": capabilities,
+            "boundaries": [],
+            "guardrails": {"behavioral_guardrails": {}},
+            "failure_modes": [],
+        }
+
+        if self._endpoint:
+            spec["agent"]["protocol"] = "http"
+
+        return spec
+
+    def _probe_http(self) -> None:
+        """Attempt to probe the HTTP endpoint for OpenAPI or tool definitions."""
+        if not self._endpoint:
+            return
+        try:
+            import httpx
+
+            headers: dict[str, str] = {}
+            if self._auth_header:
+                headers["Authorization"] = self._auth_header
+
+            # Try /.well-known/agent.json (A2A-style)
+            for probe_path in ["/tools", "/capabilities", "/.well-known/agent.json"]:
+                try:
+                    url = self._endpoint.rstrip("/") + probe_path
+                    resp = httpx.get(url, headers=headers, timeout=5.0)
+                    if resp.status_code == 200:
+                        data = resp.json()
+                        self._parse_tool_list(data)
+                        break
+                except Exception:
+                    continue
+        except ImportError:
+            pass  # httpx not available
+
+    def _probe_mcp(self, source: str) -> None:
+        """Attempt to probe an MCP server for tool definitions."""
+        # MCP probing would require an MCP client library; stub with no-op
+        self._discovered_tools = []
+
+    def _parse_tool_list(self, data: Any) -> None:
+        """Parse a JSON tool list into discovered_tools."""
+        if isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    self._discovered_tools.append({
+                        "id": _to_kebab(item.get("name", "tool")),
+                        "name": item.get("name", "Tool"),
+                        "description": item.get("description", ""),
+                    })
+        elif isinstance(data, dict):
+            tools = data.get("tools") or data.get("capabilities") or []
+            self._parse_tool_list(tools)
+
+
+def _to_kebab(name: str) -> str:
+    return name.replace("_", "-").replace(" ", "-").lower()
+
+
+def _source_to_name(source: str) -> str:
+    """Derive a short agent name from the source string."""
+    if "/" in source or "\\" in source:
+        return Path(source).stem.replace("_", "-")
+    return source.split(".")[-1].replace("_", "-")
+
+
+AdapterRegistry.register("generic", GenericAdapter)

agentspec/adapters/langchain.py

@@ -0,0 +1,131 @@
+"""LangChain framework adapter.
+
+Connects to a LangChain agent (AgentExecutor or LangGraph) and extracts
+a partial AgentSpec, including detected tools and system prompts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentspec.adapters import AgentAdapter, AdapterRegistry
+
+
+class LangChainAdapter(AgentAdapter):
+    """Adapter for LangChain agents (AgentExecutor, LangGraph chains).
+
+    Supports direct Python import connection. Extracts tools from the
+    agent's tool list and system prompt from the model's messages.
+    """
+
+    name = "langchain"
+
+    def __init__(self) -> None:
+        self._agent: Any = None
+        self._tools: list[dict[str, Any]] = []
+        self._system_prompt: str | None = None
+        self._model: str | None = None
+
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to a LangChain agent by importing its module.
+
+        Args:
+            source: Python module path to the agent (e.g., "my_agent.agent").
+                    The module must expose an ``agent`` attribute.
+        """
+        import importlib
+
+        try:
+            module = importlib.import_module(source)
+            self._agent = getattr(module, "agent", None) or getattr(module, "executor", None)
+        except ImportError as exc:
+            raise ConnectionError(f"Cannot import LangChain agent from '{source}': {exc}") from exc
+
+        if self._agent is not None:
+            self._extract_tools()
+            self._extract_model()
+
+    def disconnect(self) -> None:
+        """Release the reference to the connected agent."""
+        self._agent = None
+
+    def extract_spec(self) -> dict[str, Any]:
+        """Extract a partial AgentSpec from the connected agent.
+
+        Returns:
+            Partial spec dict with detected tools, capabilities, and agent type.
+        """
+        capabilities = [
+            {
+                "id": t["id"],
+                "name": t["name"],
+                "description": t.get("description", ""),
+                "category": "tool-use",
+            }
+            for t in self._tools
+        ]
+        tools = [
+            {
+                "id": t["id"],
+                "name": t["name"],
+                "protocol": "custom",
+                "permissions": ["read"],
+            }
+            for t in self._tools
+        ]
+
+        spec: dict[str, Any] = {
+            "agentspec": "0.1.0",
+            "info": {"name": "langchain-agent", "version": "0.1.0"},
+            "agent": {
+                "type": "autonomous",
+                "runtime": {
+                    "framework": "langchain",
+                    "model": self._model or "unknown",
+                },
+            },
+            "capabilities": capabilities,
+            "boundaries": [],
+            "guardrails": {"behavioral_guardrails": {}},
+            "failure_modes": [],
+        }
+        if tools:
+            spec["tools"] = tools
+        return spec
+
+    def _extract_tools(self) -> None:
+        """Pull tool definitions from the agent."""
+        if self._agent is None:
+            return
+
+        raw_tools = getattr(self._agent, "tools", None)
+        if not raw_tools:
+            return
+
+        for tool in raw_tools:
+            self._tools.append({
+                "id": _to_kebab(getattr(tool, "name", "unknown-tool")),
+                "name": getattr(tool, "name", "Unknown"),
+                "description": getattr(tool, "description", ""),
+            })
+
+    def _extract_model(self) -> None:
+        """Try to detect the underlying model name."""
+        if self._agent is None:
+            return
+        llm = getattr(self._agent, "llm", None) or getattr(self._agent, "llm_chain", None)
+        if llm:
+            model_name = (
+                getattr(llm, "model_name", None)
+                or getattr(llm, "model", None)
+            )
+            if model_name:
+                self._model = str(model_name)
+
+
+def _to_kebab(name: str) -> str:
+    """Convert a snake_case or space name to kebab-case."""
+    return name.replace("_", "-").replace(" ", "-").lower()
+
+
+AdapterRegistry.register("langchain", LangChainAdapter)

agentspec/adapters/openai_agents.py

@@ -0,0 +1,111 @@
+"""OpenAI Agents (Responses API) adapter.
+
+Maps OpenAI function definitions and instructions to AgentSpec sections.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentspec.adapters import AgentAdapter, AdapterRegistry
+
+
+class OpenAIAgentsAdapter(AgentAdapter):
+    """Adapter for OpenAI Agents SDK / Responses API.
+
+    Extracts function tools and system instructions to generate a partial spec.
+    """
+
+    name = "openai"
+
+    def __init__(self) -> None:
+        self._agent: Any = None
+        self._functions: list[dict[str, Any]] = []
+        self._instructions: str | None = None
+        self._model: str | None = None
+
+    def connect(self, source: str, **kwargs: Any) -> None:
+        """Connect to an OpenAI agent by importing its module.
+
+        Args:
+            source: Python module path to the agent.
+                    The module must expose an ``agent`` attribute.
+        """
+        import importlib
+
+        try:
+            module = importlib.import_module(source)
+            self._agent = getattr(module, "agent", None) or getattr(module, "assistant", None)
+        except ImportError as exc:
+            raise ConnectionError(f"Cannot import OpenAI agent from '{source}': {exc}") from exc
+
+        if self._agent is not None:
+            self._extract_functions()
+            self._instructions = getattr(self._agent, "instructions", None)
+            self._model = getattr(self._agent, "model", None)
+
+    def disconnect(self) -> None:
+        self._agent = None
+
+    def extract_spec(self) -> dict[str, Any]:
+        """Extract a partial AgentSpec from the OpenAI agent."""
+        capabilities = [
+            {
+                "id": _to_kebab(fn.get("name", f"fn-{i}")),
+                "name": fn.get("name", f"Function {i}"),
+                "description": fn.get("description", ""),
+                "category": "tool-use",
+            }
+            for i, fn in enumerate(self._functions)
+        ]
+        tools = [
+            {
+                "id": _to_kebab(fn.get("name", f"fn-{i}")),
+                "name": fn.get("name", f"Function {i}"),
+                "protocol": "custom",
+                "permissions": ["execute"],
+            }
+            for i, fn in enumerate(self._functions)
+        ]
+
+        spec: dict[str, Any] = {
+            "agentspec": "0.1.0",
+            "info": {"name": "openai-agent", "version": "0.1.0"},
+            "agent": {
+                "type": "tool-agent",
+                "runtime": {
+                    "framework": "openai",
+                    "model": self._model or "gpt-4o",
+                    "model_provider": "openai",
+                },
+            },
+            "capabilities": capabilities,
+            "boundaries": [],
+            "guardrails": {"behavioral_guardrails": {}},
+            "failure_modes": [],
+        }
+        if tools:
+            spec["tools"] = tools
+        return spec
+
+    def _extract_functions(self) -> None:
+        if self._agent is None:
+            return
+        # OpenAI SDK stores tools as list of dicts with "type"/"function" or direct callables
+        raw = getattr(self._agent, "tools", None) or getattr(self._agent, "functions", None) or []
+        for item in raw:
+            if isinstance(item, dict):
+                fn = item.get("function") or item
+                self._functions.append(fn)
+            elif callable(item):
+                self._functions.append({
+                    "name": getattr(item, "__name__", "unknown"),
+                    "description": getattr(item, "__doc__", "") or "",
+                })
+
+
+def _to_kebab(name: str) -> str:
+    return name.replace("_", "-").replace(" ", "-").lower()
+
+
+AdapterRegistry.register("openai", OpenAIAgentsAdapter)