splox 0.2.4__tar.gz → 0.2.6__tar.gz

{splox-0.2.4 → splox-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splox
-Version: 0.2.4
+Version: 0.2.6
 Summary: Official Python SDK for the Splox API — run workflows, manage chats, and monitor execution
 Project-URL: Homepage, https://splox.io
 Project-URL: Documentation, https://docs.splox.io
@@ -220,6 +220,49 @@ connection errors, 429 and 5xx. POSTs are retried only when they carry an
 `Idempotency-Key` (always true for `runs.create` and `interactions.respond`),
 reusing the same key so replays are safe.
 
+## Discovery & building an agent
+
+`client.capabilities()` (`GET /v2/capabilities`) returns everything needed to
+assemble a runnable workflow graph: available LLM endpoints (one is marked
+`is_default` — the endpoint new agent nodes get automatically), the default
+model, and the MCP tool servers usable in tool nodes (system `system:*`
+servers include their tool list).
+
+```python
+caps = client.capabilities()
+
+default_ep = next(e for e in caps.llm_endpoints if e.is_default)
+compute = next(s for s in caps.tool_servers if s.id == "system:compute")
+print(caps.default_model, default_ep.client, [t.name for t in compute.tools])
+
+# Pick a model from the endpoint's light list, then fetch its parameter schema:
+model = default_ep.models[0]                       # LLMModelSummary(id, name)
+schema = next(m for m in client.models(default_ep.id) if m.id == model.id).input_schema
+# schema is the JSON Schema of the agent node's "additional_llm_config":
+#   {"text_llm_model": model.id, "additional_llm_config": {"temperature": 0.2, ...}}
+
+# Build a workflow: an agent wired to compute tools via a tool edge.
+wf = client.workflows.create("researcher")
+client.workflows.set_graph(
+    wf.id,
+    nodes=[
+        {"id": "agent", "type": "agent", "data": {
+            "system_prompt": "You are a research assistant.",
+            # optional — omitted fields fall back to the defaults above:
+            "text_llm_endpoint_id": default_ep.id,
+            "text_llm_model": caps.default_model,
+        }},
+        {"id": "tools", "type": "tool", "data": {
+            "mcp_server_id": compute.id,  # "system:compute"
+            "allowed_tools": ["compute_exec", "compute_read_file"],
+        }},
+    ],
+    edges=[{"source": "agent", "target": "tools"}],  # tool edge (inferred)
+)
+
+run = client.runs.create(wf.id, "How many CPUs does this sandbox have?").wait()
+```
+
 ## Workflow provisioning (v1, unchanged)
 
 Workflow CRUD reads remain available for provisioning:

{splox-0.2.4 → splox-0.2.6}/README.md

@@ -187,6 +187,49 @@ connection errors, 429 and 5xx. POSTs are retried only when they carry an
 `Idempotency-Key` (always true for `runs.create` and `interactions.respond`),
 reusing the same key so replays are safe.
 
+## Discovery & building an agent
+
+`client.capabilities()` (`GET /v2/capabilities`) returns everything needed to
+assemble a runnable workflow graph: available LLM endpoints (one is marked
+`is_default` — the endpoint new agent nodes get automatically), the default
+model, and the MCP tool servers usable in tool nodes (system `system:*`
+servers include their tool list).
+
+```python
+caps = client.capabilities()
+
+default_ep = next(e for e in caps.llm_endpoints if e.is_default)
+compute = next(s for s in caps.tool_servers if s.id == "system:compute")
+print(caps.default_model, default_ep.client, [t.name for t in compute.tools])
+
+# Pick a model from the endpoint's light list, then fetch its parameter schema:
+model = default_ep.models[0]                       # LLMModelSummary(id, name)
+schema = next(m for m in client.models(default_ep.id) if m.id == model.id).input_schema
+# schema is the JSON Schema of the agent node's "additional_llm_config":
+#   {"text_llm_model": model.id, "additional_llm_config": {"temperature": 0.2, ...}}
+
+# Build a workflow: an agent wired to compute tools via a tool edge.
+wf = client.workflows.create("researcher")
+client.workflows.set_graph(
+    wf.id,
+    nodes=[
+        {"id": "agent", "type": "agent", "data": {
+            "system_prompt": "You are a research assistant.",
+            # optional — omitted fields fall back to the defaults above:
+            "text_llm_endpoint_id": default_ep.id,
+            "text_llm_model": caps.default_model,
+        }},
+        {"id": "tools", "type": "tool", "data": {
+            "mcp_server_id": compute.id,  # "system:compute"
+            "allowed_tools": ["compute_exec", "compute_read_file"],
+        }},
+    ],
+    edges=[{"source": "agent", "target": "tools"}],  # tool edge (inferred)
+)
+
+run = client.runs.create(wf.id, "How many CPUs does this sandbox have?").wait()
+```
+
 ## Workflow provisioning (v1, unchanged)
 
 Workflow CRUD reads remain available for provisioning:

{splox-0.2.4 → splox-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "splox"
-version = "0.2.4"
+version = "0.2.6"
 description = "Official Python SDK for the Splox API — run workflows, manage chats, and monitor execution"
 readme = "README.md"
 license = "MIT"

{splox-0.2.4 → splox-0.2.6}/src/splox/__init__.py

@@ -3,6 +3,7 @@
 from splox._client import AsyncSploxClient, SploxClient
 from splox._ids import decode_id, encode_id
 from splox._models import (
+    Capabilities,
     ContentPart,
     GraphEdge,
     GraphEdgeInput,
@@ -12,6 +13,8 @@ from splox._models import (
     Interaction,
     InteractionPage,
     InteractionResponse,
+    LLMEndpointInfo,
+    LLMModelSummary,
     MCPCatalogItem,
     MCPCatalogListResponse,
     MCPConnection,
@@ -20,6 +23,7 @@ from splox._models import (
     MCPServerToolsResponse,
     Message,
     MessagePage,
+    ModelInfo,
     NodeExecution,
     Output,
     OutputPage,
@@ -32,6 +36,8 @@ from splox._models import (
     RunTreeNode,
     RunUsage,
     SSEEvent,
+    ToolInfo,
+    ToolServerInfo,
     Workflow,
     WorkflowGraph,
     WorkflowGraphUpdate,
@@ -79,6 +85,13 @@ __all__ = [
     "GraphEdge",
     "GraphNodeInput",
     "GraphEdgeInput",
+    # v2 capabilities (discovery)
+    "Capabilities",
+    "LLMEndpointInfo",
+    "LLMModelSummary",
+    "ModelInfo",
+    "ToolServerInfo",
+    "ToolInfo",
     # v1 resources (MCP, legacy stream events)
     "MCPCatalogItem",
     "MCPCatalogListResponse",
@@ -96,4 +109,4 @@ __all__ = [
     "async_notify",
 ]
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{splox-0.2.4 → splox-0.2.6}/src/splox/_client.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import os
-from typing import Optional, Any
+from typing import Optional, Any, List
 
 from splox._resources import async_notify, notify
 from splox._interactions import AsyncInteractions, Interactions
 from splox._mcp import AsyncMCP, MCP
+from splox._models import Capabilities, ModelInfo
 from splox._runs import AsyncRuns, Runs
 from splox._transport import DEFAULT_TIMEOUT, AsyncTransport, SyncTransport
 from splox._workflows import AsyncWorkflows, Workflows
@@ -52,6 +53,35 @@ class SploxClient:
         self.workflows = Workflows(self._transport)
         self.mcp = MCP(self._transport)
 
+    def capabilities(self) -> Capabilities:
+        """Discover the models, endpoints, and tools available to you.
+
+        Returns:
+            :class:`Capabilities` — ``llm_endpoints`` (for agent nodes'
+            ``text_llm_endpoint_id``; one carries ``is_default=True``),
+            ``default_model`` (assigned to new agent nodes), and
+            ``tool_servers`` (for tool nodes' ``mcp_server_id``; system
+            ``system:*`` servers include their tool list).
+        """
+        data = self._transport.request("GET", "/v2/capabilities")
+        return Capabilities.from_dict(data)
+
+    def models(self, endpoint_id: str) -> List[ModelInfo]:
+        """List the full model records of an LLM endpoint.
+
+        Args:
+            endpoint_id: LLM endpoint UUID (``llm_endpoints[].id`` from
+                :meth:`capabilities`).
+
+        Returns:
+            All models of the endpoint's provider (every operation), ordered
+            by display order. Each :class:`ModelInfo` carries the model's
+            ``input_schema`` — the JSON Schema of the parameters an agent
+            node accepts in ``additional_llm_config``.
+        """
+        data = self._transport.request("GET", f"/v2/llm-endpoints/{endpoint_id}/models")
+        return [ModelInfo.from_dict(m) for m in (data.get("data") or [])]
+
     @staticmethod
     def notify(webhook_url: str, data: Any) -> None:
         """POST data to a webhook URL as JSON."""
@@ -107,6 +137,18 @@ class AsyncSploxClient:
         self.workflows = AsyncWorkflows(self._transport)
         self.mcp = AsyncMCP(self._transport)
 
+    async def capabilities(self) -> Capabilities:
+        """Discover the models, endpoints, and tools available to you
+        (see :meth:`SploxClient.capabilities`)."""
+        data = await self._transport.request("GET", "/v2/capabilities")
+        return Capabilities.from_dict(data)
+
+    async def models(self, endpoint_id: str) -> List[ModelInfo]:
+        """List the full model records of an LLM endpoint
+        (see :meth:`SploxClient.models`)."""
+        data = await self._transport.request("GET", f"/v2/llm-endpoints/{endpoint_id}/models")
+        return [ModelInfo.from_dict(m) for m in (data.get("data") or [])]
+
     @staticmethod
     async def notify(webhook_url: str, data: Any) -> None:
         """Async POST data to a webhook URL as JSON."""

{splox-0.2.4 → splox-0.2.6}/src/splox/_models.py

@@ -975,3 +975,136 @@ class WorkflowGraphUpdate:
             workflow_version=data["workflow_version"],
             node_ids=data.get("node_ids") or {},
         )
+
+
+# ---------------------------------------------------------------------------
+# v2 capabilities (discovery)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ToolInfo:
+    """One tool exposed by an MCP tool server."""
+
+    name: str
+    description: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ToolInfo:
+        return cls(name=data["name"], description=data.get("description") or "")
+
+
+@dataclass
+class LLMModelSummary:
+    """Light model listing embedded in :class:`Capabilities`.
+
+    ``id`` is the value for an agent node's ``text_llm_model``.
+    """
+
+    id: str
+    name: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> LLMModelSummary:
+        return cls(id=data["id"], name=data.get("name") or "")
+
+
+@dataclass
+class ModelInfo:
+    """Full model record from ``client.models(endpoint_id)``.
+
+    ``id`` is the value an agent node takes in ``text_llm_model``;
+    ``input_schema`` is the JSON Schema (raw dict) of the parameters that
+    agent node accepts in ``additional_llm_config`` (temperature, top_p,
+    reasoning, ...). ``capabilities`` and ``input_schema`` are ``None`` when
+    the model has none.
+    """
+
+    id: str
+    name: str = ""
+    operation: str = ""
+    capabilities: Optional[Dict[str, Any]] = None
+    input_schema: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ModelInfo:
+        return cls(
+            id=data["id"],
+            name=data.get("name") or "",
+            operation=data.get("operation") or "",
+            capabilities=data.get("capabilities"),
+            input_schema=data.get("input_schema"),
+        )
+
+
+@dataclass
+class LLMEndpointInfo:
+    """An LLM endpoint usable in an agent node's ``text_llm_endpoint_id``.
+
+    ``id`` is a raw UUID (endpoint ids are referenced inside node data
+    documents, not addressable API resources). ``is_default`` marks the
+    endpoint the server stamps into agent nodes created without explicit
+    data. ``models`` is the light chat-model list; fetch full records (all
+    operations + parameter schemas) with ``client.models(endpoint.id)``.
+    """
+
+    id: str
+    name: str
+    client: str
+    is_platform: bool = False
+    is_default: bool = False
+    models: List[LLMModelSummary] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> LLMEndpointInfo:
+        return cls(
+            id=data["id"],
+            name=data.get("name", ""),
+            client=data.get("client", ""),
+            is_platform=bool(data.get("is_platform")),
+            is_default=bool(data.get("is_default")),
+            models=[LLMModelSummary.from_dict(m) for m in (data.get("models") or [])],
+        )
+
+
+@dataclass
+class ToolServerInfo:
+    """An MCP server usable in a tool node's ``mcp_server_id``.
+
+    System servers use stable ``system:*`` ids and include their tool list;
+    user servers use UUID ids and return ``tools`` empty (listing them
+    requires contacting the remote server).
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    tools: List[ToolInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ToolServerInfo:
+        return cls(
+            id=data["id"],
+            name=data.get("name", ""),
+            description=data.get("description") or "",
+            tools=[ToolInfo.from_dict(t) for t in (data.get("tools") or [])],
+        )
+
+
+@dataclass
+class Capabilities:
+    """Result of ``client.capabilities()``: everything needed to assemble a
+    runnable workflow graph — LLM endpoints for agent nodes, the server-side
+    default model, and MCP tool servers for tool nodes."""
+
+    llm_endpoints: List[LLMEndpointInfo] = field(default_factory=list)
+    default_model: str = ""
+    tool_servers: List[ToolServerInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Capabilities:
+        return cls(
+            llm_endpoints=[LLMEndpointInfo.from_dict(e) for e in (data.get("llm_endpoints") or [])],
+            default_model=data.get("default_model", ""),
+            tool_servers=[ToolServerInfo.from_dict(t) for t in (data.get("tool_servers") or [])],
+        )

splox-0.2.6/tests/test_capabilities.py

@@ -0,0 +1,196 @@
+"""Unit tests for client.capabilities() (transport stubbed)."""
+
+import pytest
+
+import splox._transport as transport_mod
+from splox import (
+    AsyncSploxClient,
+    Capabilities,
+    LLMEndpointInfo,
+    ModelInfo,
+    SploxClient,
+    ToolServerInfo,
+)
+from splox.exceptions import SploxAuthError, SploxNotFoundError
+
+V2 = "https://splox.io/api/v2"
+
+
+@pytest.fixture(autouse=True)
+def _no_backoff(monkeypatch):
+    """Keep retry/reconnect sleeps out of the unit test suite."""
+    monkeypatch.setattr(transport_mod, "_backoff_delay", lambda *a, **k: 0.0)
+    monkeypatch.setattr("time.sleep", lambda *_: None)
+
+
+def capabilities_json():
+    return {
+        "llm_endpoints": [
+            {
+                "id": "019e4f9a-a679-7512-86fe-ac78e9b6baf6",
+                "name": "Anthropic",
+                "client": "anthropic",
+                "is_platform": True,
+                "is_default": True,
+                "models": [
+                    {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
+                    {"id": "claude-opus-4-1", "name": "Claude Opus 4.1"},
+                ],
+            },
+            {
+                "id": "019e4f9a-a677-7a84-a7de-cdb4ffca85dc",
+                "name": "my key",
+                "client": "openai",
+                "is_platform": False,
+                "is_default": False,
+                "models": [],
+            },
+        ],
+        "default_model": "claude-sonnet-4-6",
+        "tool_servers": [
+            {
+                "id": "system:compute",
+                "name": "Compute",
+                "description": "Unified execution surface.",
+                "tools": [
+                    {"name": "compute_exec", "description": "Run a shell command."},
+                    {"name": "compute_read_file", "description": "Read a file."},
+                ],
+            },
+            {
+                "id": "22222222-2222-4222-8222-222222222222",
+                "name": "My Server",
+                "description": "",
+                "tools": [],
+            },
+        ],
+    }
+
+
+@pytest.fixture
+def client():
+    c = SploxClient(api_key="test-key")
+    yield c
+    c.close()
+
+
+class TestCapabilities:
+    def test_shape_and_types(self, httpx_mock, client) -> None:
+        httpx_mock.add_response(method="GET", url=f"{V2}/capabilities", json=capabilities_json())
+
+        caps = client.capabilities()
+
+        assert isinstance(caps, Capabilities)
+        assert caps.default_model == "claude-sonnet-4-6"
+
+        assert len(caps.llm_endpoints) == 2
+        default = caps.llm_endpoints[0]
+        assert isinstance(default, LLMEndpointInfo)
+        assert default.is_default and default.is_platform
+        assert default.client == "anthropic"
+        assert default.id == "019e4f9a-a679-7512-86fe-ac78e9b6baf6"
+        assert [m.id for m in default.models] == ["claude-sonnet-4-6", "claude-opus-4-1"]
+        assert default.models[0].name == "Claude Sonnet 4.6"
+        assert not caps.llm_endpoints[1].is_default
+        assert caps.llm_endpoints[1].models == []
+
+        assert len(caps.tool_servers) == 2
+        compute = caps.tool_servers[0]
+        assert isinstance(compute, ToolServerInfo)
+        assert compute.id == "system:compute"
+        assert [t.name for t in compute.tools] == ["compute_exec", "compute_read_file"]
+        assert compute.tools[0].description == "Run a shell command."
+        assert caps.tool_servers[1].tools == []
+
+        req = httpx_mock.get_request()
+        assert req.headers["Authorization"] == "Bearer test-key"
+
+    def test_auth_error(self, httpx_mock, client) -> None:
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{V2}/capabilities",
+            status_code=401,
+            json={"type": "about:blank", "title": "Unauthorized", "status": 401, "code": "unauthorized"},
+        )
+
+        with pytest.raises(SploxAuthError):
+            client.capabilities()
+
+    @pytest.mark.asyncio
+    async def test_async_capabilities(self, httpx_mock) -> None:
+        httpx_mock.add_response(method="GET", url=f"{V2}/capabilities", json=capabilities_json())
+
+        async with AsyncSploxClient(api_key="test-key") as client:
+            caps = await client.capabilities()
+
+        assert caps.default_model == "claude-sonnet-4-6"
+        assert caps.tool_servers[0].id == "system:compute"
+        assert len(caps.tool_servers[0].tools) == 2
+
+
+ENDPOINT_ID = "019e4f9a-a679-7512-86fe-ac78e9b6baf6"
+
+
+def models_json():
+    return {
+        "data": [
+            {
+                "id": "claude-sonnet-4-6",
+                "name": "Claude Sonnet 4.6",
+                "operation": "chat_completion",
+                "capabilities": {"supports_tools": True},
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"temperature": {"type": "number"}, "thinking_effort": {"type": "string"}},
+                },
+            },
+            {
+                "id": "claude-realtime",
+                "name": "Claude Realtime",
+                "operation": "realtime",
+                "capabilities": None,
+                "input_schema": None,
+            },
+        ]
+    }
+
+
+class TestModels:
+    def test_shape_and_raw_schema(self, httpx_mock, client) -> None:
+        httpx_mock.add_response(
+            method="GET", url=f"{V2}/llm-endpoints/{ENDPOINT_ID}/models", json=models_json()
+        )
+
+        models = client.models(ENDPOINT_ID)
+
+        assert len(models) == 2
+        m = models[0]
+        assert isinstance(m, ModelInfo)
+        assert m.id == "claude-sonnet-4-6"
+        assert m.operation == "chat_completion"
+        assert m.capabilities == {"supports_tools": True}
+        # input_schema stays a raw dict (JSON Schema of additional_llm_config).
+        assert set(m.input_schema["properties"]) == {"temperature", "thinking_effort"}
+        assert models[1].input_schema is None and models[1].capabilities is None
+
+    def test_not_found(self, httpx_mock, client) -> None:
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{V2}/llm-endpoints/{ENDPOINT_ID}/models",
+            status_code=404,
+            json={"type": "about:blank", "title": "Not Found", "status": 404, "code": "not_found"},
+        )
+
+        with pytest.raises(SploxNotFoundError):
+            client.models(ENDPOINT_ID)
+
+    @pytest.mark.asyncio
+    async def test_async_models(self, httpx_mock) -> None:
+        httpx_mock.add_response(
+            method="GET", url=f"{V2}/llm-endpoints/{ENDPOINT_ID}/models", json=models_json()
+        )
+
+        async with AsyncSploxClient(api_key="test-key") as client:
+            models = await client.models(ENDPOINT_ID)
+
+        assert [m.id for m in models] == ["claude-sonnet-4-6", "claude-realtime"]