babelagent 0.1.0__py3-none-any.whl

babelagent/__init__.py

@@ -0,0 +1,87 @@
+"""Babelagent — the Babel that lets AI agents understand each other.
+
+A neutral layer that gives heterogeneous agents (plain callables, HTTP/OpenAPI
+endpoints, MCP tools, framework agents, or LLMs) one shared tongue, so they can
+exchange messages and collaborate on a task, agent-to-agent, and be graded at
+each hop.
+
+    from babelagent import Graph, adapt
+
+    graph = Graph().node("shout", str.upper)
+    result = await graph.run("hello")   # result.output == "HELLO"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .core import (
+    Agent,
+    BarrierKind,
+    BarrierPolicy,
+    CompiledGraph,
+    Context,
+    GateMode,
+    Grade,
+    Graph,
+    IdentityAgent,
+    Message,
+    Node,
+    Result,
+    Topology,
+    Verdict,
+    is_agent,
+)
+from .core.errors import (
+    AdapterError,
+    BabelagentError,
+    CycleError,
+    MissingDependencyError,
+    TopologyError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Graph",
+    "CompiledGraph",
+    "Message",
+    "Result",
+    "Context",
+    "Agent",
+    "IdentityAgent",
+    "is_agent",
+    "Node",
+    "Topology",
+    "BarrierKind",
+    "BarrierPolicy",
+    "GateMode",
+    "Grade",
+    "Verdict",
+    "adapt",
+    "register_adapter",
+    "A2ARef",
+    "McpRef",
+    "BabelagentError",
+    "AdapterError",
+    "CycleError",
+    "TopologyError",
+    "MissingDependencyError",
+]
+
+# adapt() and the adapter refs live in the adapters package; expose lazily so
+# importing babelagent never eagerly pulls optional adapter dependencies.
+_LAZY = {"adapt", "register_adapter", "A2ARef", "McpRef"}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        from . import adapters
+
+        return getattr(adapters, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

babelagent/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m babelagent`` entry point."""
+
+from .io.cli import main
+
+if __name__ == "__main__":
+    main()

babelagent/adapters/__init__.py

@@ -0,0 +1,22 @@
+"""Babelagent adapters: normalize anything a user brings into a uniform Agent."""
+
+from __future__ import annotations
+
+from .a2a_agent import A2AAgent, A2ARef
+from .auto import adapt, register_adapter
+from .callable_agent import CallableAgent
+from .http_agent import HttpAgent
+from .llm_agent import LLM
+from .mcp_agent import McpAgent, McpRef
+
+__all__ = [
+    "adapt",
+    "register_adapter",
+    "A2AAgent",
+    "A2ARef",
+    "CallableAgent",
+    "HttpAgent",
+    "LLM",
+    "McpAgent",
+    "McpRef",
+]

babelagent/adapters/a2a_agent.py

@@ -0,0 +1,143 @@
+"""Adapt a remote Agent2Agent (A2A) agent as a node in the graph.
+
+A2A is a wire protocol for (usually remote) agents to talk over JSON-RPC/HTTP.
+Babelagent treats such an agent as *just another Agent*: point at its base URL
+and it becomes a node that other agents can hand messages to. Implemented on
+httpx (a base dependency), so no extra is required; the same SSRF guard as the
+HTTP adapter applies.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ..core.agent import Context
+from ..core.errors import AdapterError
+from ..core.message import Message
+from .http_agent import MAX_RESPONSE_BYTES, _guarded_client, _read_capped, guard_url
+
+# Agent Card discovery paths, newest first (the A2A spec renamed the file).
+_CARD_PATHS = ("/.well-known/agent-card.json", "/.well-known/agent.json")
+
+
+@dataclass
+class A2ARef:
+    """A reference to a remote A2A agent by base URL (recognized by ``adapt()``)."""
+
+    url: str
+    name: str | None = None
+    allow_private: bool = False
+
+
+class A2AAgent:
+    """Calls a remote A2A agent via the ``message/send`` JSON-RPC method."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        name: str | None = None,
+        timeout: float = 60.0,
+        allow_private: bool = False,
+    ) -> None:
+        self.url = guard_url(url, allow_private=allow_private)
+        self.name = name or f"a2a:{httpx.URL(url).host}"
+        self.timeout = timeout
+        self.allow_private = allow_private
+
+    async def run(self, message: Message, ctx: Context) -> Message:
+        text = message.payload if isinstance(message.payload, str) else str(message.payload)
+        request = {
+            "jsonrpc": "2.0",
+            "id": uuid.uuid4().hex,
+            "method": "message/send",
+            "params": {
+                "message": {
+                    "role": "user",
+                    "parts": [{"kind": "text", "text": text}],
+                    "messageId": uuid.uuid4().hex,
+                }
+            },
+        }
+        guard_url(self.url, allow_private=self.allow_private)  # re-validate (TOCTOU)
+        async with _guarded_client(allow_private=self.allow_private, timeout=self.timeout) as client:
+            async with client.stream("POST", self.url, json=request) as resp:
+                resp.raise_for_status()
+                raw = await _read_capped(resp)
+        try:
+            import json
+
+            body = json.loads(raw)
+        except ValueError as exc:
+            raise AdapterError("A2A response was not valid JSON") from exc
+        if not isinstance(body, dict):
+            raise AdapterError("A2A response was not a JSON object")
+        if body.get("error"):
+            raise AdapterError(f"A2A agent returned error: {body['error']}")
+        out = _extract_text(body.get("result", body))
+        return message.with_payload(out, node=self.name)
+
+    @classmethod
+    async def from_card(
+        cls, base_url: str, *, allow_private: bool = False, **kwargs: Any
+    ) -> A2AAgent:
+        """Discover an agent's card to resolve its service URL and name."""
+        card = await _fetch_agent_card(base_url, allow_private=allow_private)
+        service_url = card.get("url") or base_url
+        name = kwargs.pop("name", None) or card.get("name")
+        return cls(service_url, name=name, allow_private=allow_private, **kwargs)
+
+
+def _extract_text(result: Any) -> Any:
+    """Pull text out of an A2A Message or Task result, tolerant of shape drift."""
+    if not isinstance(result, dict):
+        return result
+    # A direct Message: {"parts": [...]}
+    if "parts" in result:
+        return _join_parts(result["parts"])
+    # A Task: prefer artifacts, then the status message.
+    texts: list[str] = []
+    for artifact in result.get("artifacts") or []:
+        if isinstance(artifact, dict):
+            texts.append(_join_parts(artifact.get("parts") or []))
+    status = result.get("status") or {}
+    status_msg = status.get("message") if isinstance(status, dict) else None
+    if isinstance(status_msg, dict):
+        texts.append(_join_parts(status_msg.get("parts") or []))
+    joined = "\n".join(t for t in texts if t)
+    return joined or result
+
+
+def _join_parts(parts: Any) -> str:
+    if not isinstance(parts, list):
+        return ""
+    out: list[str] = []
+    for part in parts:
+        if isinstance(part, dict) and "text" in part:
+            out.append(str(part["text"]))
+    return "".join(out)
+
+
+async def _fetch_agent_card(base_url: str, *, allow_private: bool) -> dict[str, Any]:
+    base = base_url.rstrip("/")
+    async with _guarded_client(allow_private=allow_private, timeout=15.0) as client:
+        for path in _CARD_PATHS:
+            url = guard_url(base + path, allow_private=allow_private)
+            try:
+                async with client.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        continue
+                    raw = await _read_capped(resp, cap=MAX_RESPONSE_BYTES)
+            except httpx.HTTPError:
+                continue
+            try:
+                import json
+
+                return json.loads(raw)
+            except ValueError:
+                continue
+    raise AdapterError(f"no A2A agent card found under {base_url!r}")

babelagent/adapters/auto.py

@@ -0,0 +1,137 @@
+"""``adapt()`` — the on-the-fly adapter creator.
+
+Hand it anything a user brought (a callable, an HTTP/OpenAPI URL, an MCP ref, a
+framework agent, or an already-conforming Agent) and it returns a uniform
+:class:`~babelagent.core.agent.Agent`. Extensible: third parties register their
+own matchers via :func:`register_adapter` or the ``babelagent.adapters``
+entry-point group.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ..core.agent import Agent, is_agent
+from ..core.errors import AdapterError
+
+# A matcher decides whether it can handle *obj*; a builder turns it into an Agent.
+Matcher = Callable[[Any], bool]
+Builder = Callable[..., Agent]
+
+
+@dataclass
+class _Registration:
+    name: str
+    matches: Matcher
+    build: Builder
+
+
+_REGISTRY: list[_Registration] = []
+_ENTRYPOINTS_LOADED = False
+
+
+def register_adapter(name: str, matches: Matcher, build: Builder) -> None:
+    """Register a custom adapter. Later registrations take precedence."""
+    _REGISTRY.insert(0, _Registration(name=name, matches=matches, build=build))
+
+
+def _load_entrypoint_adapters() -> None:
+    global _ENTRYPOINTS_LOADED
+    if _ENTRYPOINTS_LOADED:
+        return
+    _ENTRYPOINTS_LOADED = True
+    # Discovery imports (runs) code from any installed `babelagent.adapters`
+    # plugin. Locked-down deployments can disable it. Trust your dependency set.
+    if os.environ.get("BABELAGENT_NO_PLUGINS"):
+        return
+    try:
+        from importlib.metadata import entry_points
+
+        eps = entry_points(group="babelagent.adapters")
+    except Exception:  # noqa: BLE001 — discovery is best-effort
+        return
+    for ep in eps:
+        try:
+            obj = ep.load()
+        except Exception:  # noqa: BLE001 — a broken plugin must not break adapt()
+            continue
+        if hasattr(obj, "matches") and hasattr(obj, "build"):
+            register_adapter(ep.name, obj.matches, obj.build)
+
+
+def _string_looks_http(value: str) -> bool:
+    return value.startswith(("http://", "https://"))
+
+
+def _string_looks_openapi(value: str) -> bool:
+    low = value.lower()
+    return low.endswith(".json") or "openapi" in low or "swagger" in low
+
+
+def adapt(obj: Any, *, name: str | None = None, **hints: Any) -> Agent:
+    """Return an :class:`Agent` for *obj*, inferring the right adapter.
+
+    Resolution order: already-an-Agent → custom/entry-point registrations →
+    MCP ref → framework agent → HTTP/OpenAPI → plain callable.
+    """
+    _load_entrypoint_adapters()
+
+    if is_agent(obj):
+        return obj  # type: ignore[return-value]
+
+    # Custom + entry-point adapters get first crack (most specific wins).
+    for reg in _REGISTRY:
+        try:
+            if reg.matches(obj):
+                return reg.build(obj, name=name, **hints)
+        except Exception as exc:  # noqa: BLE001
+            raise AdapterError(f"adapter {reg.name!r} failed on object: {exc}") from exc
+
+    # MCP reference.
+    from .mcp_agent import McpAgent, McpRef
+
+    if isinstance(obj, McpRef):
+        return McpAgent(obj)
+
+    # Remote A2A (Agent2Agent) reference.
+    from .a2a_agent import A2AAgent, A2ARef
+
+    if isinstance(obj, A2ARef):
+        return A2AAgent(
+            obj.url, name=name or obj.name, allow_private=obj.allow_private, **hints
+        )
+
+    # Framework agents (detected without importing the frameworks).
+    from . import frameworks as fw
+
+    if fw.looks_like_langchain(obj):
+        return fw.LangChainAgent(obj, name=name)
+    if fw.looks_like_crewai(obj):
+        return fw.CrewAgent(obj, name=name)
+    if fw.looks_like_autogen(obj):
+        return fw.AutoGenAgent(obj, name=name)
+
+    # HTTP / OpenAPI endpoints.
+    from .http_agent import HttpAgent
+
+    if isinstance(obj, str) and _string_looks_http(obj):
+        if _string_looks_openapi(obj):
+            return HttpAgent.from_openapi(obj, name=name, **hints)
+        return HttpAgent(obj, name=name, **hints)
+    if isinstance(obj, dict) and ("openapi" in obj or "swagger" in obj):
+        return HttpAgent.from_openapi(obj, name=name, **hints)
+
+    # Plain callable — the universal fallback.
+    if callable(obj):
+        from .callable_agent import CallableAgent
+
+        return CallableAgent(obj, name=name)
+
+    raise AdapterError(
+        f"don't know how to adapt {type(obj).__name__}; bring an Agent, a callable, "
+        f"an http(s) URL, an McpRef, a framework agent, or register a custom adapter "
+        f"with babelagent.register_adapter(...)."
+    )

babelagent/adapters/base.py

@@ -0,0 +1,104 @@
+"""Shared helpers for adapters: signature binding and I/O schema inference."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def bind_payload(payload: Any, sig: inspect.Signature | None) -> tuple[tuple, dict]:
+    """Decide how to pass a message's *payload* into a callable.
+
+    Deterministic rules:
+
+    * 0 or 1 parameter  → ``fn(payload)``
+    * dict payload whose keys EXACTLY match the callable's *required* params
+      → ``fn(**payload)``
+    * list/tuple payload with a multi-arg callable  → ``fn(*payload)``
+    * otherwise                                     → ``fn(payload)``
+
+    Security note: a payload can come from an untrusted upstream node (e.g. a
+    remote A2A/HTTP agent's output). To prevent that output from injecting
+    keyword arguments into optional / keyword-only "flag" parameters
+    (``admin=True``, ``dry_run=False``, ...) or wholesale into ``**kwargs``, the
+    dict-spread fires ONLY when the payload keys are exactly the callable's
+    required parameters. Anything else falls back to a single positional arg.
+    """
+    if sig is None:
+        return (payload,), {}
+
+    params = [
+        p
+        for p in sig.parameters.values()
+        if p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        )
+    ]
+
+    if len(params) <= 1:
+        return (payload,), {}
+
+    if isinstance(payload, dict):
+        required = {
+            p.name
+            for p in params
+            if p.default is inspect.Parameter.empty
+            and p.kind is not inspect.Parameter.POSITIONAL_ONLY
+        }
+        if required and set(payload) == required:
+            return (), dict(payload)
+
+    if isinstance(payload, (list, tuple)):
+        # Same discipline for positional splat: only when the item count exactly
+        # fills the required positional params (and there is no ``*args`` to soak
+        # up extras), so an untrusted list cannot positionally set a flag arg.
+        req_positional = [
+            p
+            for p in params
+            if p.default is inspect.Parameter.empty
+            and p.kind
+            in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+        has_var_positional = any(
+            p.kind is inspect.Parameter.VAR_POSITIONAL for p in sig.parameters.values()
+        )
+        if not has_var_positional and len(payload) == len(req_positional):
+            return tuple(payload), {}
+
+    return (payload,), {}
+
+
+def infer_io_schema(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Best-effort JSON-schema hints for a callable's inputs and output.
+
+    Never raises; returns ``{}`` for anything it cannot introspect. Used purely
+    for ``babelagent inspect`` / documentation, never for execution.
+    """
+    schema: dict[str, Any] = {"inputs": {}, "output": None}
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return {}
+
+    try:
+        from pydantic import TypeAdapter
+
+        for pname, p in sig.parameters.items():
+            if p.annotation is inspect.Parameter.empty:
+                continue
+            try:
+                schema["inputs"][pname] = TypeAdapter(p.annotation).json_schema()
+            except Exception:  # noqa: BLE001 — schema hints are best-effort only
+                schema["inputs"][pname] = {"type": "unknown"}
+        if sig.return_annotation is not inspect.Signature.empty:
+            try:
+                schema["output"] = TypeAdapter(sig.return_annotation).json_schema()
+            except Exception:  # noqa: BLE001
+                schema["output"] = {"type": "unknown"}
+    except Exception:  # noqa: BLE001 — pydantic missing or annotation unresolvable
+        return schema
+    return schema

babelagent/adapters/callable_agent.py

@@ -0,0 +1,52 @@
+"""Wrap any Python callable as an :class:`~babelagent.core.agent.Agent`."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from ..core.agent import Context
+from ..core.message import Message
+from .base import bind_payload, infer_io_schema
+
+
+class CallableAgent:
+    """Adapts a plain callable into a graph agent.
+
+    Sync callables run in a worker thread so they never block the event loop.
+    The callable's return value becomes the next message's payload (unless it
+    already returns a :class:`Message`).
+
+    Timeout caveat (residual): a node ``timeout_s`` / run ``deadline_s`` cancels
+    the awaiting coroutine, but Python cannot force-kill the worker thread, so a
+    *blocked* sync callable keeps running until it returns on its own (the run
+    still reports the timeout). For untrusted or possibly-blocking work, prefer
+    an async agent or an out-of-process agent, which can be interrupted.
+    """
+
+    def __init__(self, fn: Callable[..., Any], *, name: str | None = None) -> None:
+        if not callable(fn):
+            raise TypeError(f"CallableAgent needs a callable, got {type(fn).__name__}")
+        self.fn = fn
+        self.name = name or getattr(fn, "__name__", None) or type(fn).__name__
+        dunder_call = getattr(type(fn), "__call__", None)  # noqa: B004 — async detection, not a callability test
+        self._is_async = inspect.iscoroutinefunction(fn) or inspect.iscoroutinefunction(
+            dunder_call
+        )
+        try:
+            self._sig: inspect.Signature | None = inspect.signature(fn)
+        except (TypeError, ValueError):
+            self._sig = None
+        self.io_schema = infer_io_schema(fn)
+
+    async def run(self, message: Message, ctx: Context) -> Message:
+        args, kwargs = bind_payload(message.payload, self._sig)
+        if self._is_async:
+            out = await self.fn(*args, **kwargs)
+        else:
+            out = await asyncio.to_thread(self.fn, *args, **kwargs)
+        if isinstance(out, Message):
+            return out
+        return message.with_payload(out, node=self.name)

babelagent/adapters/frameworks/__init__.py

@@ -0,0 +1,81 @@
+"""Adapters for third-party agent frameworks (LangChain, CrewAI, AutoGen).
+
+Detection is by the wrapped object's module/attributes, so importing this
+package never imports the frameworks themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...core.agent import Context
+from ...core.message import Message
+
+
+def looks_like_langchain(obj: Any) -> bool:
+    mod = type(obj).__module__ or ""
+    return mod.startswith(("langchain", "langgraph")) and hasattr(obj, "invoke")
+
+
+def looks_like_crewai(obj: Any) -> bool:
+    mod = type(obj).__module__ or ""
+    return mod.startswith("crewai") and hasattr(obj, "kickoff")
+
+
+def looks_like_autogen(obj: Any) -> bool:
+    mod = type(obj).__module__ or ""
+    return mod.startswith(("autogen", "pyautogen")) and (
+        hasattr(obj, "generate_reply") or hasattr(obj, "run")
+    )
+
+
+class LangChainAgent:
+    """Wraps a LangChain / LangGraph Runnable (anything with ``.invoke``)."""
+
+    def __init__(self, runnable: Any, *, name: str | None = None) -> None:
+        self.runnable = runnable
+        self.name = name or type(runnable).__name__
+
+    async def run(self, message: Message, ctx: Context) -> Message:
+        if hasattr(self.runnable, "ainvoke"):
+            out = await self.runnable.ainvoke(message.payload)
+        else:
+            import asyncio
+
+            out = await asyncio.to_thread(self.runnable.invoke, message.payload)
+        out = getattr(out, "content", out)
+        return message.with_payload(out, node=self.name)
+
+
+class CrewAgent:
+    """Wraps a CrewAI Crew (anything with ``.kickoff``)."""
+
+    def __init__(self, crew: Any, *, name: str | None = None) -> None:
+        self.crew = crew
+        self.name = name or type(crew).__name__
+
+    async def run(self, message: Message, ctx: Context) -> Message:
+        import asyncio
+
+        inputs = message.payload if isinstance(message.payload, dict) else {"input": message.payload}
+        out = await asyncio.to_thread(self.crew.kickoff, inputs)
+        out = getattr(out, "raw", out)
+        return message.with_payload(out, node=self.name)
+
+
+class AutoGenAgent:
+    """Wraps an AutoGen agent (``.generate_reply`` / ``.run``)."""
+
+    def __init__(self, agent: Any, *, name: str | None = None) -> None:
+        self.agent = agent
+        self.name = name or type(agent).__name__
+
+    async def run(self, message: Message, ctx: Context) -> Message:
+        import asyncio
+
+        if hasattr(self.agent, "generate_reply"):
+            msg = [{"role": "user", "content": str(message.payload)}]
+            out = await asyncio.to_thread(self.agent.generate_reply, msg)
+        else:
+            out = await asyncio.to_thread(self.agent.run, message.payload)
+        return message.with_payload(out, node=self.name)