sofias-sdk-lite 0.2.1__tar.gz → 0.4.0__tar.gz

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sofias-sdk-lite
-Version: 0.2.1
+Version: 0.4.0
 Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
 Keywords: agents,ai,llm,rabbitmq,sofias
 Author: Sofias Tech, S.L.
@@ -56,6 +56,11 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
   from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
   builds the client when you need it explicitly; `LLMCallable` stays a protocol
   for anything the bundled clients do not cover.
+- **The user's connectors** — `McpToolProvider` turns the connectors the platform
+  sends with each turn (mail, documents, CRM, the company's own MCP servers…)
+  into tools for your LLM nodes. They go through the platform's intermediary:
+  your agent never sees a credential. See
+  [Using the user's connectors](https://docs.sofias.ai/guides/connectors/).
 
 Nothing here depends on a private backend or an internal config service.
 Where the model lives is deployment configuration, not agent code.
@@ -209,11 +214,11 @@ if __name__ == "__main__":
 
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
-Sofias gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
-tool discovery are intentionally out of scope for v1 — the SDK ships the
-relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
-your own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, LLM clients for the Sofias
+gateway / any OpenAI-compatible endpoint and, since 0.3.0, the user's
+connectors (MCP) ship today. Memory is intentionally out of scope for v1 — the
+SDK ships the `MemoryProvider` protocol so you can plug in your own, and it
+becomes an optional extra in a later release.
 
 ## Source and contributions
 

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/README.md

@@ -20,6 +20,11 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
   from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
   builds the client when you need it explicitly; `LLMCallable` stays a protocol
   for anything the bundled clients do not cover.
+- **The user's connectors** — `McpToolProvider` turns the connectors the platform
+  sends with each turn (mail, documents, CRM, the company's own MCP servers…)
+  into tools for your LLM nodes. They go through the platform's intermediary:
+  your agent never sees a credential. See
+  [Using the user's connectors](https://docs.sofias.ai/guides/connectors/).
 
 Nothing here depends on a private backend or an internal config service.
 Where the model lives is deployment configuration, not agent code.
@@ -173,11 +178,11 @@ if __name__ == "__main__":
 
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
-Sofias gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
-tool discovery are intentionally out of scope for v1 — the SDK ships the
-relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
-your own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, LLM clients for the Sofias
+gateway / any OpenAI-compatible endpoint and, since 0.3.0, the user's
+connectors (MCP) ship today. Memory is intentionally out of scope for v1 — the
+SDK ships the `MemoryProvider` protocol so you can plug in your own, and it
+becomes an optional extra in a later release.
 
 ## Source and contributions
 

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.2.1"
+version = "0.4.0"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.2.1"
+version = "0.4.0"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/src/sofias_sdk_lite/__init__.py

@@ -103,6 +103,12 @@ from sofias_sdk_lite.llm import (
     ToolCall,
     ToolSpec,
 )
+from sofias_sdk_lite.files import (
+    Attachment,
+    FileAccess,
+    FileAccessError,
+    ReturnedFile,
+)
 from sofias_sdk_lite.messaging import (
     AgentTaskMessage,
     ApiTaskMessage,
@@ -171,6 +177,11 @@ except PackageNotFoundError:  # pragma: no cover - source checkout without insta
 
 __all__ = [
     "__version__",
+    # Files (0.4.0)
+    "Attachment",
+    "FileAccess",
+    "FileAccessError",
+    "ReturnedFile",
     # Agent
     "Agent",
     "AgentBuilder",

sofias_sdk_lite-0.4.0/src/sofias_sdk_lite/files.py

@@ -0,0 +1,195 @@
+"""Files for third-party agents: the turn's attachments and the files you return.
+
+Everything goes through the platform's intermediary with the turn's short-lived
+grant (the same one your connectors use). Your agent never sees storage keys or
+permanent links, and the grant expires when the turn does.
+
+The task message carries what you need::
+
+    def prepare_input(self, task, history, role):
+        for attachment in task.attachment_details:      # what the user attached
+            data = task.files.download(attachment)        # bytes
+        saved = task.files.upload("report.csv", csv_bytes, "text/csv")
+        answer = f"Here is the report.\\n\\n{saved.artifact()}"
+
+``task.files`` is ``None`` when the platform has no intermediary for your agent
+(for instance, a local run): check it before using it.
+
+Images for a vision model::
+
+    part = task.files.image_part(attachment)   # OpenAI-compatible content part
+    messages = [{"role": "user", "content": [{"type": "text", "text": "What is it?"}, part]}]
+
+Limits: 25 MB per file and 10 returned files per turn.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, ClassVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "MAX_FILE_BYTES",
+    "Attachment",
+    "FileAccess",
+    "FileAccessError",
+    "ReturnedFile",
+]
+
+#: The intermediary rejects bigger files; checked here too, before sending.
+MAX_FILE_BYTES = 25 * 1024 * 1024
+
+
+class FileAccessError(RuntimeError):
+    """A download or upload the intermediary refused (status in ``status_code``)."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class Attachment(BaseModel):
+    """A file the user attached, as listed in ``task.attachment_details``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str | None = None
+    filename: str
+    content_type: str | None = None
+    byte_size: int | None = None
+    url: str
+
+
+class ReturnedFile(BaseModel):
+    """A file you uploaded with ``FileAccess.upload``: return it with ``artifact()``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    filename: str
+    content_type: str | None = None
+    byte_size: int | None = None
+    url: str | None = None
+
+    def artifact(self) -> str:
+        """The tag that hands this file to the user. Put it in your answer."""
+        return "[ARTIFACT]\n" + json.dumps({"file_id": self.id}) + "\n[/ARTIFACT]"
+
+
+class FileAccess(BaseModel):
+    """Download the turn's attachments and upload the files you return.
+
+    Built by the SDK from the ``files`` entry of the task message; the token is
+    the turn's grant and never appears in ``repr`` or logs.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    url: str
+    token: str = Field(repr=False)
+    timeout: float = 60.0
+
+    #: Tests swap the HTTP transport here (``httpx.MockTransport``).
+    _transport: ClassVar[httpx.BaseTransport | None] = None
+    _async_transport: ClassVar[httpx.AsyncBaseTransport | None] = None
+
+    # -- download -----------------------------------------------------------
+
+    def download(self, attachment: Attachment | str) -> bytes:
+        """The bytes of an attachment (or of an intermediary file URL)."""
+        with httpx.Client(timeout=self.timeout, transport=self._transport) as client:
+            response = client.get(_url_of(attachment), headers=self._headers())
+        return _content(response, "download")
+
+    async def adownload(self, attachment: Attachment | str) -> bytes:
+        """Async ``download``."""
+        async with httpx.AsyncClient(
+            timeout=self.timeout, transport=self._async_transport
+        ) as client:
+            response = await client.get(_url_of(attachment), headers=self._headers())
+        return _content(response, "download")
+
+    def image_part(self, attachment: Attachment) -> dict[str, Any]:
+        """An OpenAI-compatible ``image_url`` content part for a vision model."""
+        return _image_part(attachment, self.download(attachment))
+
+    async def aimage_part(self, attachment: Attachment) -> dict[str, Any]:
+        """Async ``image_part``."""
+        return _image_part(attachment, await self.adownload(attachment))
+
+    # -- upload -------------------------------------------------------------
+
+    def upload(
+        self, filename: str, data: bytes, content_type: str = "application/octet-stream"
+    ) -> ReturnedFile:
+        """Store a file for this turn; return it to the user with ``.artifact()``."""
+        _check_size(data)
+        with httpx.Client(timeout=self.timeout, transport=self._transport) as client:
+            response = client.post(
+                self._upload_url(filename), content=data, headers=self._headers(content_type)
+            )
+        return _returned(response)
+
+    async def aupload(
+        self, filename: str, data: bytes, content_type: str = "application/octet-stream"
+    ) -> ReturnedFile:
+        """Async ``upload``."""
+        _check_size(data)
+        async with httpx.AsyncClient(
+            timeout=self.timeout, transport=self._async_transport
+        ) as client:
+            response = await client.post(
+                self._upload_url(filename), content=data, headers=self._headers(content_type)
+            )
+        return _returned(response)
+
+    # -- internals ----------------------------------------------------------
+
+    def _headers(self, content_type: str | None = None) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        return headers
+
+    def _upload_url(self, filename: str) -> str:
+        return f"{self.url.rstrip('/')}?filename={quote(filename)}"
+
+
+def _url_of(attachment: Attachment | str) -> str:
+    return attachment if isinstance(attachment, str) else attachment.url
+
+
+def _check_size(data: bytes) -> None:
+    if not data:
+        raise ValueError("cannot upload an empty file")
+    if len(data) > MAX_FILE_BYTES:
+        raise ValueError(f"file too large: {len(data)} bytes (limit {MAX_FILE_BYTES})")
+
+
+def _content(response: httpx.Response, action: str) -> bytes:
+    if response.status_code != 200:
+        raise FileAccessError(
+            f"file {action} failed (HTTP {response.status_code})", response.status_code
+        )
+    return response.content
+
+
+def _returned(response: httpx.Response) -> ReturnedFile:
+    if response.status_code != 201:
+        raise FileAccessError(
+            f"file upload failed (HTTP {response.status_code})", response.status_code
+        )
+    return ReturnedFile.model_validate(response.json())
+
+
+def _image_part(attachment: Attachment, data: bytes) -> dict[str, Any]:
+    content_type = attachment.content_type or "image/png"
+    if not content_type.startswith("image/"):
+        raise ValueError(f"{attachment.filename} is not an image ({content_type})")
+    encoded = base64.b64encode(data).decode("ascii")
+    return {"type": "image_url", "image_url": {"url": f"data:{content_type};base64,{encoded}"}}

sofias_sdk_lite-0.4.0/src/sofias_sdk_lite/mcp.py

@@ -0,0 +1,240 @@
+"""MCP connectors delivered by the Sofias platform.
+
+The platform sends each turn's connectors in ``AgentTaskMessage.mcp_servers``.
+Inside ``configuration`` it puts the transport details under ``__mcp_*`` keys:
+
+- ``__mcp_url``: the endpoint to call. For marketplace agents it is always the
+  platform's MCP intermediary, which adds the user's real credentials itself.
+- ``__mcp_headers``: headers for every request (a short-lived grant). Never put
+  them in a prompt or a log.
+- ``__mcp_tools``: the allow list approved for that connector.
+- ``__mcp_namespace``: offer the tools as ``connector__tool`` so two connectors
+  with a tool of the same name do not clash.
+
+``McpToolProvider`` implements the ``ToolProvider`` protocol on top of those
+entries with a minimal Streamable HTTP client (JSON-RPC over ``httpx``, JSON or
+event-stream answers, ``Mcp-Session-Id``), so it needs no extra dependency::
+
+    from sofias_sdk_lite.mcp import McpToolProvider
+    from sofias_sdk_lite.tools import ToolRegistry
+
+    provider = McpToolProvider(task.mcp_servers)
+    builder.with_tool_registry(ToolRegistry(provider))
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from sofias_sdk_lite.llm.tools import ToolSpec
+from sofias_sdk_lite.observability._log import get_logger
+
+logger = get_logger("mcp")
+
+__all__ = ["McpError", "McpServer", "McpToolProvider", "mcp_servers_from_message"]
+
+PROTOCOL_VERSION = "2025-06-18"
+_UNSUPPORTED = re.compile(r"[^A-Za-z0-9_-]")
+
+
+class McpError(Exception):
+    """An MCP server answered with an error or could not be reached."""
+
+
+@dataclass(frozen=True)
+class McpServer:
+    """One connector of the turn, ready to call."""
+
+    name: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    tools: tuple[str, ...] | None = None
+    namespace: bool = False
+
+
+def _field(raw: Any, name: str) -> Any:
+    return raw.get(name) if isinstance(raw, dict) else getattr(raw, name, None)
+
+
+def mcp_servers_from_message(raw_servers: list[Any]) -> list[McpServer]:
+    """Read the ``mcp_servers`` of a task message (models or plain dicts)."""
+    servers: list[McpServer] = []
+    for raw in raw_servers:
+        conf = dict(_field(raw, "conf") or _field(raw, "configuration") or {})
+        tools = conf.get("__mcp_tools")
+        servers.append(
+            McpServer(
+                name=str(_field(raw, "name")),
+                url=conf.get("__mcp_url") or f"http://{_field(raw, 'address')}:{_field(raw, 'port')}/mcp",
+                headers=dict(conf.get("__mcp_headers") or {}),
+                tools=tuple(tools) if tools else None,
+                namespace=bool(conf.get("__mcp_namespace") or conf.get("__mcp_headers")),
+            )
+        )
+    return servers
+
+
+def _offered_name(server: McpServer, tool: str) -> str:
+    if not server.namespace:
+        return tool
+    return _UNSUPPORTED.sub("_", f"{server.name}__{tool}")[:64]
+
+
+class _Session:
+    """A minimal Streamable HTTP MCP session against one server."""
+
+    def __init__(self, server: McpServer, client: httpx.AsyncClient) -> None:
+        self._server = server
+        self._client = client
+        self._session_id: str | None = None
+        self._next_id = 0
+        self._initialized = False
+
+    async def _post(self, payload: dict[str, Any]) -> dict[str, Any] | None:
+        headers = {
+            **self._server.headers,
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "MCP-Protocol-Version": PROTOCOL_VERSION,
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        try:
+            response = await self._client.post(self._server.url, json=payload, headers=headers)
+        except httpx.HTTPError as exc:
+            raise McpError(f"{self._server.name}: unreachable ({type(exc).__name__})") from exc
+        self._session_id = response.headers.get("Mcp-Session-Id") or self._session_id
+        if response.status_code == 202 or "id" not in payload:
+            return None
+        if response.status_code >= 400:
+            raise McpError(f"{self._server.name}: HTTP {response.status_code}")
+        message = self._message(response, payload["id"])
+        if message.get("error"):
+            raise McpError(f"{self._server.name}: {message['error'].get('message', message['error'])}")
+        return message.get("result") or {}
+
+    @staticmethod
+    def _message(response: httpx.Response, id_: int) -> dict[str, Any]:
+        if "text/event-stream" not in response.headers.get("Content-Type", ""):
+            return response.json()
+        messages = []
+        for event in re.split(r"\r?\n\r?\n", response.text):
+            data = "\n".join(line[5:].strip() for line in event.splitlines() if line.startswith("data:"))
+            if data:
+                try:
+                    messages.append(json.loads(data))
+                except json.JSONDecodeError:
+                    continue
+        for message in messages:
+            if message.get("id") == id_:
+                return message
+        raise McpError("event stream without an answer")
+
+    async def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        if not self._initialized:
+            await self._initialize()
+        return await self._call(method, params) or {}
+
+    async def _call(self, method: str, params: dict[str, Any] | None) -> dict[str, Any] | None:
+        self._next_id += 1
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "id": self._next_id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        return await self._post(payload)
+
+    async def _initialize(self) -> None:
+        await self._call(
+            "initialize",
+            {"protocolVersion": PROTOCOL_VERSION, "capabilities": {},
+             "clientInfo": {"name": "sofias-sdk-lite", "version": "1"}},
+        )
+        await self._post({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        self._initialized = True
+
+
+class McpToolProvider:
+    """``ToolProvider`` over the connectors the platform sent for this turn.
+
+    Connects lazily on the first ``get_tools``. A connector that cannot be
+    reached is skipped (and logged) so the others keep working.
+    """
+
+    def __init__(self, raw_servers: list[Any], *, transport: httpx.AsyncBaseTransport | None = None,
+                 timeout: float = 60.0) -> None:
+        self._servers = mcp_servers_from_message(raw_servers)
+        self._client = httpx.AsyncClient(transport=transport, timeout=timeout)
+        self._sessions = {server.name: _Session(server, self._client) for server in self._servers}
+        self._routes: dict[str, tuple[str, str]] = {}
+        self._specs: list[ToolSpec] | None = None
+
+    async def get_tools(self, node_name: str) -> list[ToolSpec]:
+        if self._specs is None:
+            self._specs = []
+            for server in self._servers:
+                try:
+                    listed = await self._list(server)
+                except McpError as exc:
+                    logger.warning("mcp_server_unavailable", server=server.name, error=str(exc))
+                    continue
+                self._specs.extend(listed)
+        return list(self._specs)
+
+    async def _list(self, server: McpServer) -> list[ToolSpec]:
+        specs: list[ToolSpec] = []
+        cursor: str | None = None
+        while True:
+            result = await self._sessions[server.name].request("tools/list", {"cursor": cursor} if cursor else None)
+            for tool in result.get("tools", []):
+                name = tool.get("name")
+                if not name or (server.tools is not None and name not in server.tools):
+                    continue
+                offered = _offered_name(server, name)
+                self._routes[offered] = (server.name, name)
+                specs.append(ToolSpec(name=offered, description=tool.get("description") or name,
+                                      parameters_schema=tool.get("inputSchema") or {"type": "object"}))
+            cursor = result.get("nextCursor")
+            if not cursor:
+                return specs
+
+    async def execute_tool(self, tool_name: str, tool_input: dict[str, Any]) -> Any:
+        if self._specs is None:
+            await self.get_tools("")
+        route = self._routes.get(tool_name)
+        if route is None:
+            raise McpError(f"unknown MCP tool '{tool_name}'")
+        server_name, real_name = route
+        result = await self._sessions[server_name].request(
+            "tools/call", {"name": real_name, "arguments": tool_input or {}}
+        )
+        if result.get("isError"):
+            raise McpError(_text(result) or f"{tool_name} failed")
+        return _with_structured(result)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+def _text(result: dict[str, Any]) -> str:
+    return "\n".join(block.get("text", "") for block in result.get("content", []) if block.get("type") == "text")
+
+
+def _with_structured(result: dict[str, Any]) -> str:
+    """The text of a tool result plus its ``structuredContent``, unless the text
+    already is that same JSON. Some servers only put a summary in the text."""
+    text = _text(result)
+    structured = result.get("structuredContent")
+    if not structured:
+        return text if result.get("content") else json.dumps(result)
+    for block in result.get("content", []):
+        try:
+            if json.loads(block.get("text", "")) == structured:
+                return text
+        except (TypeError, ValueError):
+            continue
+    serialized = json.dumps(structured)
+    return f"{text}\n{serialized}" if text else serialized

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/src/sofias_sdk_lite/messaging/models.py

@@ -37,6 +37,7 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 import nh3
 
 from sofias_sdk_lite.contracts.strict_contract import StrictContract
+from sofias_sdk_lite.files import Attachment, FileAccess
 from sofias_sdk_lite.observability._log import get_logger
 
 logger = get_logger("messaging.models")
@@ -105,6 +106,15 @@ class _BaseTaskMessage(BaseModel):
     available_agents: dict[str, Any] | list[str] = {}
     agent_internal_capabilities: str | None = None
 
+    # --- Files (0.4.0) ---
+    # What the user attached: download URLs, and their details. For third-party
+    # agents both point at the platform's intermediary, with the turn's grant.
+    attachments: list[str] = []
+    attachment_details: list[Attachment] = []
+    # Where to download from and upload to with the turn's grant (``None`` when
+    # the platform sends no intermediary, e.g. a local run). See ``sofias_sdk_lite.files``.
+    files: FileAccess | None = None
+
     # --- Delegation (optional) ---
     reply_to: str | None = None
     correlation_id: str | None = None

{sofias_sdk_lite-0.2.1 → sofias_sdk_lite-0.4.0}/src/sofias_sdk_lite/nodes/llm_node.py

@@ -48,6 +48,7 @@ from sofias_sdk_lite.llm import (
 )
 from sofias_sdk_lite.nodes.base_node import BaseNode, NodeType
 from sofias_sdk_lite.nodes.prompt_assembler import PromptAssembler
+from sofias_sdk_lite.observability.tool_events import emit_tool_call
 from sofias_sdk_lite.observability._log import get_logger
 
 if TYPE_CHECKING:
@@ -727,7 +728,11 @@ class LLMNode(BaseNode):
         )
 
     async def _execute_tool(self, tool_call: ToolCall) -> ToolResult:
-        """Execute a single tool call.
+        """Execute a single tool call and leave its event line (``emit_tool_call``).
+
+        Both paths -- streaming and not -- and both kinds of tool -- your own
+        and the connectors' -- come through here, so this is the one place the
+        sandbox logs learn which tools ran.
 
         Args:
             tool_call: The tool call to execute.
@@ -735,6 +740,20 @@ class LLMNode(BaseNode):
         Returns:
             ToolResult with success/failure and output/error.
         """
+        started = time.perf_counter()
+        result = await self._run_tool(tool_call)
+        known = tool_call.name in self._tools_by_name or self._tool_registry is not None
+        emit_tool_call(
+            tool_call.name,
+            ok=result.success,
+            duration_ms=(time.perf_counter() - started) * 1000,
+            node_name=self.name,
+            error_type=None if result.success else ("failed" if known else "not_found"),
+        )
+        return result
+
+    async def _run_tool(self, tool_call: ToolCall) -> ToolResult:
+        """Execute a single tool call (see ``_execute_tool``)."""
         tool_start = time.perf_counter()
         tool = self._tools_by_name.get(tool_call.name)
         if tool is None:

sofias_sdk_lite-0.4.0/src/sofias_sdk_lite/observability/tool_events.py

@@ -0,0 +1,80 @@
+"""One line per tool call, for the developer portal's sandbox logs.
+
+Every tool the model calls -- your own or a connector's -- leaves one line on
+standard output, whatever your logging configuration::
+
+    SOFIAS_EVENT {"type":"tool_call","tool":"search","server":"notion","ok":true,"duration_ms":412,...}
+
+The portal reads these lines to show which tools your agent called. They carry
+names, timings and outcome only: never the arguments or the results, which may
+hold your users' data. Set ``SOFIAS_EVENTS=off`` to silence them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+from typing import Any
+
+__all__ = ["EVENT_PREFIX", "emit_tool_call"]
+
+#: Marks the lines the portal parses; everything else in the log is shown raw.
+EVENT_PREFIX = "SOFIAS_EVENT"
+
+_logger = logging.getLogger("sofias_sdk_lite.events")
+
+
+class _StdoutHandler(logging.StreamHandler):  # type: ignore[type-arg]
+    """Writes to whatever ``sys.stdout`` is at emit time (it may be swapped later)."""
+
+    @property  # type: ignore[override]
+    def stream(self) -> Any:
+        return sys.stdout
+
+    @stream.setter
+    def stream(self, _value: Any) -> None:
+        pass
+
+
+def _ensure_handler() -> None:
+    """Own stdout handler, so the line appears even without logging configured."""
+    if _logger.handlers:
+        return
+    handler = _StdoutHandler()
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _logger.addHandler(handler)
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+
+
+def emit_tool_call(
+    tool_name: str,
+    *,
+    ok: bool,
+    duration_ms: float,
+    node_name: str | None = None,
+    error_type: str | None = None,
+) -> None:
+    """Write the event line for one tool call (no arguments, no results)."""
+    if os.environ.get("SOFIAS_EVENTS", "").lower() in {"off", "0", "false"}:
+        return
+    server, separator, tool = tool_name.partition("__")
+    if not separator:
+        server, tool = "", tool_name
+    event: dict[str, Any] = {
+        "type": "tool_call",
+        "tool": tool,
+        "server": server or None,
+        "ok": ok,
+        "duration_ms": round(duration_ms),
+        "node": node_name,
+        "error_type": error_type,
+        "ts": round(time.time(), 3),
+    }
+    _ensure_handler()
+    _logger.info(
+        "%s %s", EVENT_PREFIX, json.dumps(event, separators=(",", ":"), ensure_ascii=False)
+    )