unique-sdk 2026.24.0.dev0__tar.gz → 2026.24.0.dev1__tar.gz

{unique_sdk-2026.24.0.dev0 → unique_sdk-2026.24.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.24.0.dev0
+Version: 2026.24.0.dev1
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.24.0.dev0 → unique_sdk-2026.24.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.24.0.dev0"
+version = "2026.24.0.dev1"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.24.0.dev0 → unique_sdk-2026.24.0.dev1}/unique_sdk/cli/cli.py

@@ -27,6 +27,10 @@ from unique_sdk.cli.commands.scheduled_tasks import (
     cmd_schedule_update,
 )
 from unique_sdk.cli.commands.search import cmd_search
+from unique_sdk.cli.commands.subagent import cmd_subagent
+from unique_sdk.cli.commands.subagent import (
+    is_error_output as _is_subagent_error_output,
+)
 from unique_sdk.cli.commands.web_search import (
     cmd_web_crawl,
     cmd_web_search,
@@ -82,6 +86,7 @@ Examples:
   unique-cli upload ./file.pdf      Upload to current folder
   unique-cli download cont_abc123   Download by content ID
   unique-cli elicit ask "Which?"    Ask the user a question synchronously
+  unique-cli subagent Legal "Review" Invoke a connected space/subagent
   unique-cli web-search search "x"  Search the web via the public API
   unique-cli web-search crawl URL   Crawl a URL via the public API
 """
@@ -465,6 +470,87 @@ def mcp(
     )
 
 
+@main.command()
+@click.argument("tool_name")
+@click.argument("message")
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to .unique-subagents.json. Defaults to $UNIQUE_SUBAGENTS_CONFIG or cwd.",
+)
+@click.option(
+    "--chat-id",
+    "parent_chat_id",
+    default=None,
+    envvar="UNIQUE_CHAT_ID",
+    help="Parent chat ID for message correlation.",
+)
+@click.option(
+    "--message-id",
+    "parent_message_id",
+    default=None,
+    envvar="UNIQUE_MESSAGE_ID",
+    help="Parent message ID for message correlation.",
+)
+@click.option(
+    "--assistant-id",
+    "parent_assistant_id",
+    default=None,
+    envvar="UNIQUE_ASSISTANT_ID",
+    help="Parent assistant ID for message correlation.",
+)
+@click.option(
+    "--reset-chat",
+    is_flag=True,
+    help="Ignore any saved reusable chat for this subagent call.",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Print the raw response JSON instead of a human-readable response.",
+)
+@click.pass_context
+def subagent(
+    ctx: click.Context,
+    tool_name: str,
+    message: str,
+    config_path: str | None,
+    parent_chat_id: str | None,
+    parent_message_id: str | None,
+    parent_assistant_id: str | None,
+    reset_chat: bool,
+    output_json: bool,
+) -> None:
+    """Invoke a configured connected-space subagent.
+
+    \b
+    TOOL_NAME must match an entry in .unique-subagents.json. The command sends
+    MESSAGE to that connected assistant and waits for the assistant response.
+
+    \b
+    Examples:
+      unique-cli subagent LegalReview "Review this contract clause"
+      unique-cli subagent Finance "Summarize Q4 revenue" --reset-chat
+    """
+    output = cmd_subagent(
+        LazyState.get(ctx),
+        tool_name=tool_name,
+        message=message,
+        config_path=config_path,
+        parent_chat_id=parent_chat_id,
+        parent_message_id=parent_message_id,
+        parent_assistant_id=parent_assistant_id,
+        reset_chat=reset_chat,
+        output_json=output_json,
+    )
+    click.echo(output)
+    if _is_subagent_error_output(output):
+        ctx.exit(1)
+
+
 # -- Scheduled Tasks -------------------------------------------------------
 
 

unique_sdk-2026.24.0.dev1/unique_sdk/cli/commands/subagent.py

@@ -0,0 +1,298 @@
+"""Subagent command: invoke configured connected spaces via the Unique platform."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any, Literal, TypedDict, cast
+
+from unique_sdk._error import APIError
+from unique_sdk.api_resources._space import Space
+from unique_sdk.cli.state import ShellState
+from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion
+
+CONFIG_FILENAME = ".unique-subagents.json"
+STATE_FILENAME = ".unique-subagent-chats.json"
+ENV_CONFIG_PATH = "UNIQUE_SUBAGENTS_CONFIG"
+SUBAGENT_ERROR_PREFIX = "subagent:"
+
+
+class SubagentDefinition(TypedDict, total=False):
+    name: str
+    displayName: str
+    configuration: dict[str, Any]
+    assistantId: str
+    chatId: str | None
+    reuseChat: bool
+    forcedTools: list[str]
+    pollInterval: float
+    maxWait: float
+    stopCondition: Literal["stoppedStreamingAt", "completedAt"]
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when ``output`` is a CLI error message."""
+    return output.startswith(SUBAGENT_ERROR_PREFIX)
+
+
+def resolve_config_path(config_path: str | None = None) -> Path:
+    """Resolve the subagent config file path."""
+    if config_path:
+        return Path(config_path).expanduser()
+    env_path = os.environ.get(ENV_CONFIG_PATH)
+    if env_path:
+        return Path(env_path).expanduser()
+    return Path.cwd() / CONFIG_FILENAME
+
+
+def _load_config(config_path: Path) -> list[SubagentDefinition]:
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ValueError(f"config file not found: {config_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"config file is not valid JSON: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise ValueError("config root must be a JSON object")
+
+    subagents = raw.get("subagents")
+    if not isinstance(subagents, list):
+        raise ValueError('config must contain a "subagents" array')
+
+    validated: list[SubagentDefinition] = []
+    for item in subagents:
+        if isinstance(item, dict):
+            validated.append(cast(SubagentDefinition, cast(object, item)))
+    return validated
+
+
+def _find_subagent(
+    subagents: list[SubagentDefinition],
+    tool_name: str,
+) -> SubagentDefinition:
+    for subagent in subagents:
+        if subagent.get("name") == tool_name:
+            return subagent
+    available = sorted(name for subagent in subagents if (name := subagent.get("name")))
+    suffix = f" Available: {', '.join(available)}." if available else ""
+    raise ValueError(f"unknown subagent tool {tool_name!r}.{suffix}")
+
+
+def _get_str(
+    subagent: SubagentDefinition,
+    *keys: str,
+    required: bool = False,
+) -> str | None:
+    value = _get_value(subagent, *keys)
+    if isinstance(value, str) and value.strip():
+        return value
+    if required:
+        key_list = " / ".join(keys)
+        raise ValueError(f"subagent {subagent.get('name')!r} is missing {key_list}")
+    return None
+
+
+def _get_value(subagent: SubagentDefinition, *keys: str) -> Any:
+    subagent_data = cast(dict[str, Any], cast(object, subagent))
+    for key in keys:
+        if key in subagent_data:
+            return subagent_data[key]
+    configuration = subagent.get("configuration")
+    if isinstance(configuration, dict):
+        for key in keys:
+            if key in configuration:
+                return configuration[key]
+    return None
+
+
+def _get_bool(
+    subagent: SubagentDefinition,
+    *keys: str,
+    default: bool,
+) -> bool:
+    value = _get_value(subagent, *keys)
+    return value if isinstance(value, bool) else default
+
+
+def _get_float(
+    subagent: SubagentDefinition,
+    *keys: str,
+    default: float,
+) -> float:
+    value = _get_value(subagent, *keys)
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        return float(value)
+    return default
+
+
+def _get_forced_tools(subagent: SubagentDefinition) -> list[str] | None:
+    value = _get_value(subagent, "forcedTools", "forced_tools")
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value or None
+    return None
+
+
+def _get_stop_condition(
+    subagent: SubagentDefinition,
+) -> Literal["stoppedStreamingAt", "completedAt"]:
+    value = _get_value(subagent, "stopCondition", "stop_condition")
+    if value in ("stoppedStreamingAt", "completedAt"):
+        return value
+    return "completedAt"
+
+
+def _load_chat_state(state_path: Path) -> dict[str, str]:
+    if not state_path.is_file():
+        return {}
+    try:
+        raw = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        key: value
+        for key, value in raw.items()
+        if isinstance(key, str) and isinstance(value, str)
+    }
+
+
+def _save_chat_state(state_path: Path, state: dict[str, str]) -> None:
+    state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def _format_response(
+    *,
+    tool_name: str,
+    display_name: str,
+    response: Space.Message,
+    output_json: bool,
+) -> str:
+    if output_json:
+        return json.dumps(response, indent=2, default=str)
+
+    text = response.get("text")
+    if text is None:
+        raise ValueError(f"subagent {tool_name!r} returned no text")
+
+    lines = [f"Subagent: {display_name} ({tool_name})"]
+    chat_id = response.get("chatId")
+    if chat_id:
+        lines.append(f"Chat: {chat_id}")
+    lines.append("")
+    lines.append(text)
+    return "\n".join(lines)
+
+
+async def _send_to_subagent(
+    *,
+    state: ShellState,
+    subagent: SubagentDefinition,
+    message: str,
+    chat_id: str | None,
+    parent_chat_id: str | None,
+    parent_message_id: str | None,
+    parent_assistant_id: str | None,
+) -> Space.Message:
+    assistant_id = _get_str(
+        subagent,
+        "assistantId",
+        "assistant_id",
+        required=True,
+    )
+    assert assistant_id is not None
+
+    correlation: Space.Correlation | None = None
+    if parent_chat_id and parent_message_id and parent_assistant_id:
+        correlation = {
+            "parentMessageId": parent_message_id,
+            "parentChatId": parent_chat_id,
+            "parentAssistantId": parent_assistant_id,
+        }
+
+    return await send_message_and_wait_for_completion(
+        user_id=state.config.user_id,
+        company_id=state.config.company_id,
+        assistant_id=assistant_id,
+        text=message,
+        tool_choices=_get_forced_tools(subagent),
+        chat_id=chat_id,
+        poll_interval=_get_float(
+            subagent,
+            "pollInterval",
+            "poll_interval",
+            default=1.0,
+        ),
+        max_wait=_get_float(
+            subagent,
+            "maxWait",
+            "max_wait",
+            default=120.0,
+        ),
+        stop_condition=_get_stop_condition(subagent),
+        correlation=correlation,
+    )
+
+
+def cmd_subagent(
+    state: ShellState,
+    tool_name: str,
+    message: str,
+    *,
+    config_path: str | None = None,
+    parent_chat_id: str | None = None,
+    parent_message_id: str | None = None,
+    parent_assistant_id: str | None = None,
+    reset_chat: bool = False,
+    output_json: bool = False,
+) -> str:
+    """Invoke one configured connected-space subagent."""
+    try:
+        resolved_config_path = resolve_config_path(config_path)
+        subagent = _find_subagent(
+            _load_config(resolved_config_path),
+            tool_name=tool_name,
+        )
+        display_name = _get_str(subagent, "displayName") or tool_name
+        configured_chat_id = _get_str(subagent, "chatId", "chat_id")
+        reuse_chat = _get_bool(subagent, "reuseChat", "reuse_chat", default=True)
+
+        state_path = resolved_config_path.parent / STATE_FILENAME
+        chat_id = configured_chat_id
+        chat_state: dict[str, str] = {}
+        if chat_id is None and reuse_chat and not reset_chat:
+            chat_state = _load_chat_state(state_path)
+            chat_id = chat_state.get(tool_name)
+
+        response = asyncio.run(
+            _send_to_subagent(
+                state=state,
+                subagent=subagent,
+                message=message,
+                chat_id=chat_id,
+                parent_chat_id=parent_chat_id,
+                parent_message_id=parent_message_id,
+                parent_assistant_id=parent_assistant_id,
+            )
+        )
+
+        response_chat_id = response.get("chatId")
+        if configured_chat_id is None and reuse_chat and response_chat_id:
+            chat_state = chat_state or _load_chat_state(state_path)
+            chat_state[tool_name] = response_chat_id
+            try:
+                _save_chat_state(state_path, chat_state)
+            except OSError:
+                pass
+
+        return _format_response(
+            tool_name=tool_name,
+            display_name=display_name,
+            response=response,
+            output_json=output_json,
+        )
+    except (ValueError, OSError, TimeoutError, APIError) as exc:
+        return f"{SUBAGENT_ERROR_PREFIX} {exc}"

unique_sdk-2026.24.0.dev1/unique_sdk/cli/skills/unique-cli-subagent/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: unique-cli-subagent
+description: >-
+  Invoke connected Unique spaces/subagents through the unique-cli subagent
+  command. Use when the workspace exposes connected-space tools and you need
+  to delegate a question or task to one of those configured assistants.
+---
+
+# Unique CLI -- Connected Spaces / Subagents
+
+Use this skill to call a connected Unique space as a tool. Each connected
+space is configured by the platform in `.unique-subagents.json`; call it by
+the tool name shown in the generated connected-space skill.
+
+## Usage
+
+```bash
+unique-cli subagent "<tool_name>" "<message>" \
+  --chat-id "$UNIQUE_CHAT_ID" \
+  --message-id "$UNIQUE_MESSAGE_ID" \
+  --assistant-id "$UNIQUE_ASSISTANT_ID"
+```
+
+## Rules
+
+1. Use the exact tool name from the connected-space skill or from
+   `.unique-subagents.json`.
+2. Send a focused message that contains the subagent-specific task and the
+   relevant context.
+3. Treat the returned text as the connected space's answer. Do not invent
+   details that are not in the response.
+4. If the connected space has references in its text, preserve them exactly.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `<tool_name>` | required | Name of the configured connected-space tool. |
+| `<message>` | required | Prompt sent to the connected space. |
+| `--reset-chat` | off | Start from a fresh subagent chat instead of reusing the saved chat. |
+| `--json` | off | Print the raw response JSON. |
+| `--config` | `.unique-subagents.json` | Override the config path. |
+
+## Prerequisites
+
+The platform sets these environment variables automatically:
+
+```bash
+UNIQUE_USER_ID
+UNIQUE_COMPANY_ID
+UNIQUE_CHAT_ID
+UNIQUE_MESSAGE_ID
+UNIQUE_ASSISTANT_ID
+UNIQUE_API_KEY
+UNIQUE_APP_ID
+```