splox 0.2.7__tar.gz → 0.2.8__tar.gz

{splox-0.2.7 → splox-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splox
-Version: 0.2.7
+Version: 0.2.8
 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

{splox-0.2.7 → splox-0.2.8}/pyproject.toml

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

{splox-0.2.7 → splox-0.2.8}/src/splox/__init__.py

@@ -105,4 +105,4 @@ __all__ = [
     "async_notify",
 ]
 
-__version__ = "0.2.7"
+__version__ = "0.2.8"

splox-0.2.8/src/splox/builder/__init__.py

@@ -0,0 +1,314 @@
+"""Splox workflow *builder* — declare an agent graph in Python, push it once.
+
+A thin, mostly-pure convenience layer over ``client.workflows`` (the v2 graph
+API in :mod:`splox._workflows`). You describe a workflow as nested
+:func:`agent` / :func:`tool` dictionaries; :func:`upsert` flattens that tree
+into the ``nodes``/``edges`` payload the ``PUT /v2/workflows/{id}/graph``
+endpoint expects, creating the workflow first when it does not yet exist.
+
+WORKED EXAMPLE
+--------------
+::
+
+    from splox import SploxClient
+    from splox.builder import agent, tool, upsert, pull
+
+    client = SploxClient(api_key="sk-...")
+
+    research = agent(
+        "researcher",
+        "You research topics and cite your sources.",
+        model="gpt-4o",
+        tools=[tool("system:web_search", allow=["search"])],
+    )
+    root = agent(
+        "assistant",
+        "You answer the user with help from the researcher sub-agent.",
+        subagents=[research],
+    )
+
+    result = upsert(client, "Docs Assistant", root)
+    print(result)
+    # UpsertResult(workflow_id='wf_01J...', version='wfv_01J...', created=True,
+    #              node_ids={'assistant': '2f8c...-uuid',
+    #                        'researcher': 'a1b2...-uuid',
+    #                        'web_search': 'c7d9...-uuid'})
+
+    graph = pull(client, result.workflow_id)
+    print(graph["nodes"][0])
+    # {'id': '2f8c...-uuid', 'type': 'agent', 'label': 'assistant',
+    #  'position': {'x': 0.0, 'y': 0.0},
+    #  'data': {'system_prompt': 'You answer ...',
+    #           'as_tool_code_only': False, 'background': False}}
+
+IDEMPOTENCY
+-----------
+:func:`upsert` is keyed on the workflow **name**. It pages through
+``client.workflows.list()`` and, on an exact name match, replaces that
+workflow's graph via ``set_graph`` (``created=False``); with no match it calls
+``workflows.create`` first (``created=True``). Re-running ``upsert`` with the
+same name therefore updates the existing workflow in place instead of
+spawning duplicates. Every ``set_graph`` publishes a brand-new, immutable
+workflow *version* (surfaced as ``UpsertResult.version``); ``publish=False``
+stages that version without making it active. ``workflows.create`` itself
+sends an ``Idempotency-Key`` header, so a retried create never double-inserts.
+Client node keys are de-duplicated deterministically — a ``-2`` / ``-3``
+suffix is appended on collision — so identical inputs yield a stable graph.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from splox import SploxClient
+
+__all__ = ["agent", "tool", "upsert", "pull", "UpsertResult"]
+
+_SYSTEM_PREFIX = "system:"
+
+
+@dataclass
+class UpsertResult:
+    """Outcome of :func:`upsert`.
+
+    Attributes:
+        workflow_id: ``str`` — the workflow public id (``wf_...``). Sourced from
+            the matched ``workflows.list`` entry or a fresh ``workflows.create``
+            (both ``/v2/workflows``).
+        version: ``str`` — the new active workflow version id (``wfv_...``)
+            returned by ``workflows.set_graph`` (``PUT /v2/workflows/{id}/graph``).
+        created: ``bool`` — ``True`` when the workflow was created during this
+            call, ``False`` when an existing same-named workflow was updated.
+        node_ids: ``dict[str, str]`` — client node key -> server node UUID map,
+            copied verbatim from the ``set_graph`` response ``node_ids``.
+    """
+
+    workflow_id: str
+    version: str
+    created: bool
+    node_ids: Dict[str, str] = field(default_factory=dict)
+
+
+def agent(
+    key: str,
+    system_prompt: str,
+    *,
+    label: Optional[str] = None,
+    model: Optional[str] = None,
+    endpoint_id: Optional[str] = None,
+    llm_config: Optional[Dict[str, Any]] = None,
+    tools: "Tuple[Dict[str, Any], ...]" = (),
+    subagents: "Tuple[Dict[str, Any], ...]" = (),
+    as_tool: Optional[str] = None,
+    as_tool_description: Optional[str] = None,
+    code_only: bool = False,
+    background: bool = False,
+    data_extra: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Describe an ``agent`` node (pure — performs no I/O).
+
+    The returned dict is a builder spec, not a server node: :func:`upsert`
+    turns it into an ``agent`` graph node whose ``data`` document is assembled
+    from the arguments below and mirrors the v2 agent-node schema.
+
+    Args:
+        key: Client node key; used as the node ``id`` in ``set_graph`` and as
+            the ``node_ids`` map key in :class:`UpsertResult`.
+        system_prompt: Stored as ``data.system_prompt``.
+        label: Optional human-facing node label (``None`` omits it).
+        model: Stored as ``data.text_llm_model`` when set.
+        endpoint_id: Stored as ``data.text_llm_endpoint_id`` when set.
+        llm_config: Stored as ``data.additional_llm_config`` when set.
+        tools: :func:`tool` specs to attach via ``tool`` edges.
+        subagents: nested :func:`agent` specs to attach via ``tool`` edges.
+        as_tool: When this agent is exposed as a callable tool, its tool name
+            (``data.as_tool_name``).
+        as_tool_description: Description shown to callers (``data.as_tool_description``).
+        code_only: Stored as ``data.as_tool_code_only``.
+        background: Stored as ``data.background``.
+        data_extra: Extra raw ``data`` keys merged last (``dict.update``), so it
+            can override any of the above.
+
+    Returns:
+        ``{"key", "type": "agent", "label", "data", "tools", "subagents"}``.
+    """
+    data: Dict[str, Any] = {"system_prompt": system_prompt}
+    if model is not None:
+        data["text_llm_model"] = model
+    if endpoint_id is not None:
+        data["text_llm_endpoint_id"] = endpoint_id
+    if llm_config is not None:
+        data["additional_llm_config"] = llm_config
+    if as_tool is not None:
+        data["as_tool_name"] = as_tool
+    if as_tool_description is not None:
+        data["as_tool_description"] = as_tool_description
+    data["as_tool_code_only"] = code_only
+    data["background"] = background
+    data.update(data_extra or {})
+    return {
+        "key": key,
+        "type": "agent",
+        "label": label,
+        "data": data,
+        "tools": list(tools),
+        "subagents": list(subagents),
+    }
+
+
+def tool(
+    server_id: str,
+    *,
+    allow: Optional["List[str]"] = None,
+    label: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Describe a ``tool`` node bound to an MCP server (pure — performs no I/O).
+
+    Args:
+        server_id: MCP server id (e.g. ``"system:web_search"``). Stored as
+            ``data.mcp_server_id``; the ``system:`` prefix is stripped to form
+            the node ``key``.
+        allow: Optional allow-list of tool names; when given it is stored as
+            ``data.allowed_tools`` (``None`` leaves the server fully enabled).
+        label: Optional human-facing node label (``None`` omits it).
+
+    Returns:
+        ``{"key", "type": "tool", "label", "data"}`` where ``data`` carries
+        ``mcp_server_id`` and an empty ``tool_approval`` map (plus
+        ``allowed_tools`` when ``allow`` is set).
+    """
+    key = server_id[len(_SYSTEM_PREFIX):] if server_id.startswith(_SYSTEM_PREFIX) else server_id
+    data: Dict[str, Any] = {"mcp_server_id": server_id, "tool_approval": {}}
+    if allow is not None:
+        data["allowed_tools"] = list(allow)
+    return {
+        "key": key,
+        "type": "tool",
+        "label": label,
+        "data": data,
+    }
+
+
+def _node(spec: Dict[str, Any], node_id: str) -> Dict[str, Any]:
+    node: Dict[str, Any] = {
+        "id": node_id,
+        "type": spec.get("type", "agent"),
+        "data": spec.get("data") or {},
+    }
+    if spec.get("label") is not None:
+        node["label"] = spec["label"]
+    return node
+
+
+def _build_graph(
+    agents: "Tuple[Dict[str, Any], ...]",
+) -> "Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]":
+    """Flatten builder specs into ``(nodes, edges)`` with unique node ids."""
+    nodes: List[Dict[str, Any]] = []
+    edges: List[Dict[str, Any]] = []
+    counts: Dict[str, int] = {}
+
+    def unique(key: str) -> str:
+        if key not in counts:
+            counts[key] = 1
+            return key
+        candidate = key
+        while candidate in counts:
+            counts[key] += 1
+            candidate = f"{key}-{counts[key]}"
+        counts[candidate] = 1
+        return candidate
+
+    def add_agent(spec: Dict[str, Any]) -> str:
+        node_id = unique(spec["key"])
+        nodes.append(_node(spec, node_id))
+        for tool_spec in spec.get("tools") or ():
+            tool_id = unique(tool_spec["key"])
+            nodes.append(_node(tool_spec, tool_id))
+            edges.append({"source": node_id, "target": tool_id, "edge_type": "tool"})
+        for sub_spec in spec.get("subagents") or ():
+            sub_id = add_agent(sub_spec)
+            edges.append({"source": node_id, "target": sub_id, "edge_type": "tool"})
+        return node_id
+
+    for spec in agents:
+        add_agent(spec)
+    return nodes, edges
+
+
+def _find_workflow_id(client: "SploxClient", name: str) -> Optional[str]:
+    cursor: Optional[str] = None
+    while True:
+        page = client.workflows.list(cursor=cursor)
+        for workflow in page.data:
+            if workflow.name == name:
+                return workflow.id
+        if not page.page.has_more or not page.page.next_cursor:
+            return None
+        cursor = page.page.next_cursor
+
+
+def upsert(
+    client: "SploxClient",
+    name: str,
+    *agents: Dict[str, Any],
+    graph: Optional[Any] = None,
+    publish: bool = True,
+    description: str = "",
+) -> UpsertResult:
+    """Create-or-update a workflow named ``name`` and set its graph.
+
+    This is the only function here that touches the network. When ``graph`` is
+    given its ``nodes``/``edges`` (the shape returned by :func:`pull` /
+    ``get_graph``) are used verbatim; otherwise the graph is assembled by
+    walking ``*agents`` — each :func:`agent` becomes a node, its tools and
+    sub-agents become nodes joined by ``tool`` edges (see :func:`_build_graph`).
+
+    Args:
+        client: A :class:`splox.SploxClient`.
+        name: Workflow name; the idempotency key for the lookup (see the module
+            IDEMPOTENCY section).
+        *agents: Root :func:`agent` specs (ignored when ``graph`` is supplied).
+        graph: Optional pre-built graph dict/``WorkflowGraph`` to publish as-is.
+        publish: Passed through to ``set_graph`` (make the new version active).
+        description: Description used only when a new workflow is created.
+
+    Returns:
+        :class:`UpsertResult`.
+    """
+    if graph is not None:
+        source = graph if isinstance(graph, dict) else dataclasses.asdict(graph)
+        nodes = list(source.get("nodes") or [])
+        edges = list(source.get("edges") or [])
+    else:
+        nodes, edges = _build_graph(agents)
+
+    workflow_id = _find_workflow_id(client, name)
+    if workflow_id is None:
+        workflow = client.workflows.create(name, description)
+        workflow_id = workflow.id
+        created = True
+    else:
+        created = False
+
+    update = client.workflows.set_graph(workflow_id, nodes, edges, publish=publish)
+    return UpsertResult(
+        workflow_id=workflow_id,
+        version=update.workflow_version,
+        created=created,
+        node_ids=update.node_ids,
+    )
+
+
+def pull(client: "SploxClient", workflow_id: str) -> Dict[str, Any]:
+    """Fetch a workflow's active graph as a plain dict.
+
+    Reads ``client.workflows.get_graph`` (``GET /v2/workflows/{id}/graph``) and
+    returns the :class:`splox.WorkflowGraph` as ``{"workflow_version", "nodes",
+    "edges"}`` (dataclass -> dict, node/edge ``data`` preserved as-is). The
+    result is directly consumable as :func:`upsert`'s ``graph`` argument.
+    """
+    return dataclasses.asdict(client.workflows.get_graph(workflow_id))