claritty-sdk 2.2.0__tar.gz → 2.4.0__tar.gz

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claritty-sdk
-Version: 2.2.0
+Version: 2.4.0
 Summary: Official SDK for building apps on the Claritty Platform
 Author: Claritty Platform
 License: MIT

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk/__init__.py

@@ -39,7 +39,7 @@ decorator/registry runtime (``@workflow``/``@uses_agent``/``@trigger_template``,
 ``WorkflowExecutor``) has been removed — there is one canonical (v2) runtime.
 """
 
-from . import llm
+from . import files, llm
 from .context import AgentContext, AgentResult, BaseAgent, ToolCtx, WorkflowContext
 from .decorators import (
     agent,
@@ -65,6 +65,8 @@ __all__ = [
     "list_registered_tool_ids",
     # llm
     "llm",
+    # per-(user, app) file storage
+    "files",
     # canvas graph (manifest-driven)
     "build_graph",
     # per-request user context
@@ -72,4 +74,4 @@ __all__ = [
     "use_user_context",
 ]
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk/context.py

@@ -145,6 +145,21 @@ class ToolCtx:
             )
         return self._integration_resolver(integration_id)
 
+    @property
+    def files(self) -> Any:
+        """Per-(user, app) file storage bound to this context's ``user_id``.
+
+        Returns a :class:`claritty_sdk.files.BoundFiles` exposing
+        ``upload_bytes`` / ``create_upload_url`` / ``list`` / ``download_url`` /
+        ``confirm`` / ``delete`` for the current user. The platform brokers all
+        access; the app never holds S3 credentials.
+        """
+        # Imported lazily so context.py stays import-light and httpx is only
+        # required when a tool actually touches files.
+        from .files import BoundFiles
+
+        return BoundFiles(self.user_id)
+
     def log(self, level: str, message: str) -> None:
         _log("tool", level, message)
 

claritty_sdk-2.4.0/claritty_sdk/files.py

@@ -0,0 +1,229 @@
+"""Per-(user, app) file storage for deployed apps.
+
+End users can upload files THROUGH an app; each file is bound to the app
+instance (``CLARITY_APP_ID``) and private to the uploading user. The app never
+holds S3 credentials — it brokers every operation through the platform over
+``${CLARITTY_PLATFORM_URL}/internal/files/*`` with the ``CLARITY_INTERNAL_SECRET``
+shared secret (the same trust model as integration credentials,
+:mod:`claritty_sdk.integrations.platform_creds`). The platform validates that
+``user_id`` may access the app, then mints short-lived presigned S3 URLs.
+
+Typical use inside a ``@tool`` handler::
+
+    from claritty_sdk import files
+
+    @tool(id="docs.save")
+    def save(input: dict, ctx: ToolCtx) -> dict:
+        info = files.upload_bytes(
+            filename=input["name"],
+            content_type=input["type"],
+            data=base64.b64decode(input["b64"]),
+            user_id=ctx.user_id,
+        )
+        return {"file_id": info["fileId"]}
+
+Or via the bound accessor (``user_id`` taken from the context)::
+
+    info = ctx.files.upload_bytes(name, content_type, data)
+    items = ctx.files.list()
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+# Files can be large; allow a longer ceiling than the creds fetch.
+_TIMEOUT_S = float(os.environ.get("CLARITTY_FILES_TIMEOUT_S", "60"))
+
+
+class FileBrokerError(RuntimeError):
+    """A file broker call failed (misconfig, denied access, or platform error)."""
+
+
+def _config() -> tuple[str, str, Optional[str]]:
+    base = (os.environ.get("CLARITTY_PLATFORM_URL") or "").rstrip("/")
+    secret = (
+        os.environ.get("CLARITY_INTERNAL_SECRET")
+        or os.environ.get("CLARITTY_INTERNAL_SECRET")
+        or ""
+    )
+    if not base or not secret:
+        raise FileBrokerError(
+            "File broker not configured (CLARITTY_PLATFORM_URL / "
+            "CLARITY_INTERNAL_SECRET missing). In a deployed app these are "
+            "injected by the platform."
+        )
+    app_id = os.environ.get("CLARITY_APP_ID") or os.environ.get("CLARITTY_APP_ID")
+    return base, secret, app_id
+
+
+def _post(path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+    base, secret, app_id = _config()
+    if not app_id:
+        raise FileBrokerError(
+            "CLARITY_APP_ID is not set — files are scoped per app and cannot "
+            "be brokered without it."
+        )
+    body = {"appId": app_id, **payload}
+    url = f"{base}/internal/files/{path}"
+    try:
+        resp = httpx.post(
+            url,
+            json=body,
+            headers={
+                "X-Claritty-Internal": secret,
+                "Content-Type": "application/json",
+            },
+            timeout=_TIMEOUT_S,
+        )
+    except httpx.HTTPError as exc:
+        raise FileBrokerError(f"file broker call {path!r} failed: {exc}") from exc
+    if resp.status_code == 401:
+        raise FileBrokerError(
+            "file broker returned 401 — check CLARITY_INTERNAL_SECRET."
+        )
+    if resp.status_code == 403:
+        raise FileBrokerError("user does not have access to this app's files.")
+    if resp.status_code >= 400:
+        raise FileBrokerError(
+            f"file broker {path!r} failed: HTTP {resp.status_code} {resp.text[:200]}"
+        )
+    try:
+        return resp.json() or {}
+    except ValueError as exc:
+        raise FileBrokerError(
+            f"file broker {path!r} returned a non-JSON response"
+        ) from exc
+
+
+def create_upload_url(
+    filename: str,
+    content_type: str,
+    user_id: str,
+    *,
+    size_bytes: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Reserve a file and get a presigned PUT URL.
+
+    Returns ``{"fileId", "uploadUrl", "contentType"}``. PUT the bytes to
+    ``uploadUrl`` with ``Content-Type: contentType``, then call :func:`confirm`.
+    Prefer :func:`upload_bytes` which does all three steps.
+    """
+    payload: Dict[str, Any] = {
+        "userId": user_id,
+        "filename": filename,
+        "contentType": content_type,
+    }
+    if size_bytes is not None:
+        payload["sizeBytes"] = int(size_bytes)
+    return _post("upload-url", payload)
+
+
+def confirm(file_id: str, user_id: str) -> Dict[str, Any]:
+    """Mark an uploaded object READY (records its real size). Returns the file."""
+    return _post("confirm", {"userId": user_id, "fileId": file_id})
+
+
+def list_files(user_id: str) -> List[Dict[str, Any]]:
+    """List the user's READY files for this app (newest first)."""
+    return _post("list", {"userId": user_id}).get("files", [])
+
+
+def download_url(file_id: str, user_id: str) -> Dict[str, Any]:
+    """Get a short-lived presigned GET URL: ``{"url", "filename", "contentType"}``."""
+    return _post("download-url", {"userId": user_id, "fileId": file_id})
+
+
+def delete(file_id: str, user_id: str) -> Dict[str, Any]:
+    """Delete one of the user's own files (object + metadata)."""
+    return _post("delete", {"userId": user_id, "fileId": file_id})
+
+
+def upload_bytes(
+    filename: str,
+    content_type: str,
+    data: bytes,
+    user_id: str,
+) -> Dict[str, Any]:
+    """One-shot server-side upload: reserve → PUT to S3 → confirm.
+
+    Returns the confirmed file (``{"fileId", "filename", "sizeBytes", ...}``).
+    Note Lambda's ~6MB sync payload cap — for large browser uploads, hand the
+    presigned ``uploadUrl`` from :func:`create_upload_url` to the client and PUT
+    directly from the browser instead of streaming bytes through the app.
+    """
+    reserved = create_upload_url(
+        filename, content_type, user_id, size_bytes=len(data)
+    )
+    try:
+        put = httpx.put(
+            reserved["uploadUrl"],
+            content=data,
+            headers={"Content-Type": reserved.get("contentType", content_type)},
+            timeout=_TIMEOUT_S,
+        )
+    except httpx.HTTPError as exc:
+        raise FileBrokerError(f"upload PUT failed: {exc}") from exc
+    if put.status_code >= 400:
+        raise FileBrokerError(
+            f"upload PUT failed: HTTP {put.status_code} {put.text[:200]}"
+        )
+    return confirm(reserved["fileId"], user_id)
+
+
+class BoundFiles:
+    """:mod:`claritty_sdk.files` with ``user_id`` pre-bound (see ``ToolCtx.files``)."""
+
+    def __init__(self, user_id: Optional[str]) -> None:
+        self._user_id = user_id
+
+    def _uid(self) -> str:
+        if not self._user_id:
+            raise FileBrokerError(
+                "no user_id on this context — files are per-user and cannot be "
+                "accessed without an authenticated user."
+            )
+        return self._user_id
+
+    def create_upload_url(
+        self,
+        filename: str,
+        content_type: str,
+        *,
+        size_bytes: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        return create_upload_url(
+            filename, content_type, self._uid(), size_bytes=size_bytes
+        )
+
+    def upload_bytes(
+        self, filename: str, content_type: str, data: bytes
+    ) -> Dict[str, Any]:
+        return upload_bytes(filename, content_type, data, self._uid())
+
+    def confirm(self, file_id: str) -> Dict[str, Any]:
+        return confirm(file_id, self._uid())
+
+    def list(self) -> List[Dict[str, Any]]:
+        return list_files(self._uid())
+
+    def download_url(self, file_id: str) -> Dict[str, Any]:
+        return download_url(file_id, self._uid())
+
+    def delete(self, file_id: str) -> Dict[str, Any]:
+        return delete(file_id, self._uid())
+
+
+__all__ = [
+    "FileBrokerError",
+    "create_upload_url",
+    "confirm",
+    "list_files",
+    "download_url",
+    "delete",
+    "upload_bytes",
+    "BoundFiles",
+]

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk/integrations/catalog.py

@@ -91,8 +91,8 @@ def _wire_native_integration(
     """Register a PLATFORM-DELEGATING handler for each tool a native integration
     advertises. The real provider REST + the user's credentials live on the
     platform (the seed is a public repo), so the app never executes the call
-    itself — it forwards to /internal/integrations/<id>/<tool>/execute via the
-    SDK PlatformClient. Skips any tool already registered (a vendored handler,
+    itself — it forwards to /internal/integrations/tools/<id>/<tool>/execute via
+    the SDK PlatformClient. Skips any tool already registered (a vendored handler,
     if present, wins)."""
     for t in manifest.get("providedTools") or []:
         tool_id = (t or {}).get("id")

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk/integrations/platform_creds.py

@@ -154,4 +154,97 @@ def fetch_for_user(integration_id: str, user_id: str) -> Credentials:
     )
 
 
-__all__ = ["Credentials", "CredentialsNotAvailable", "fetch_for_user"]
+def is_connected(integration_id: str, user_id: str) -> bool:
+    """Whether ``integration_id`` is connected for ``user_id`` in THIS app.
+
+    A CREDENTIAL-FREE probe: it asks the platform's state endpoint whether a
+    connection exists WITHOUT ever fetching the raw token — so it works even for
+    brokered / gate-only integrations (where ``fetch_for_user`` is refused). Use
+    this for connect prompts / setup checklists; act on an integration only via
+    its registered tool handlers (which reach the platform broker).
+
+    Fail-closed: returns ``False`` on not-connected / misconfig / any transient
+    error, so a checklist degrades to "connect" rather than crashing. Scoped to
+    THIS app via ``CLARITY_APP_ID`` (same as ``fetch_for_user``).
+    """
+    # Local dev override mirrors fetch_for_user: a fake cred means "connected".
+    if os.environ.get(f"CLARITTY_FAKE_CREDS_{integration_id.upper()}"):
+        return True
+
+    base = (os.environ.get("CLARITTY_PLATFORM_URL") or "").rstrip("/")
+    secret = os.environ.get("CLARITY_INTERNAL_SECRET") or ""
+    if not base or not secret:
+        return False
+
+    import httpx
+
+    payload = {"userId": user_id, "integrationCatalogId": integration_id}
+    app_id = os.environ.get("CLARITY_APP_ID")
+    if app_id:
+        payload["appId"] = app_id
+    try:
+        with httpx.Client(timeout=_FETCH_TIMEOUT_S) as client:
+            res = client.post(
+                f"{base}/internal/integrations/state",
+                json=payload,
+                headers={
+                    "X-Claritty-Internal": secret,
+                    "Content-Type": "application/json",
+                },
+            )
+        if res.status_code >= 400:
+            return False
+        return bool((res.json() or {}).get("connected"))
+    except Exception as exc:  # noqa: BLE001 — a probe must never crash a checklist
+        logger.warning(
+            "connection state for integration=%s failed: %s", integration_id, exc
+        )
+        return False
+
+
+def _platform_app_url() -> str:
+    """Public URL of the Claritty platform app (where the connect popup runs), as
+    distinct from CLARITTY_PLATFORM_URL (the internal API base the broker calls).
+    Read at call time so a late-set env var is honored."""
+    return (
+        os.environ.get("CLARITTY_PLATFORM_APP_URL") or "https://app.claritty.ai"
+    ).rstrip("/")
+
+
+def connect_url(integration_id: str) -> Optional[str]:
+    """Deep link to the platform-hosted, per-(user,app) connect surface for
+    ``integration_id`` — the URL a deployed app opens (popup) so the user can
+    connect WITHOUT the app ever handling a credential. The popup runs at
+    ``app.claritty.ai`` and identifies the user by their platform session.
+
+    Returns ``None`` when ``CLARITY_APP_ID`` isn't set (can't scope the connect
+    to an app — e.g. local runs without the platform), so callers can omit the
+    CTA gracefully.
+    """
+    app_id = os.environ.get("CLARITY_APP_ID")
+    if not app_id:
+        return None
+    return f"{_platform_app_url()}/connect/{app_id}/{integration_id}"
+
+
+def not_connected_error(integration_id: str) -> Dict[str, Any]:
+    """The STANDARD not-connected result every tool/adapter should return when an
+    integration isn't connected, so the app UI can render a "Connect X" CTA with
+    zero extra round-trips. Shape:
+    ``{"error": "<id>_not_connected", "service": <id>, "connect_url": <url|None>}``.
+    """
+    return {
+        "error": f"{integration_id}_not_connected",
+        "service": integration_id,
+        "connect_url": connect_url(integration_id),
+    }
+
+
+__all__ = [
+    "Credentials",
+    "CredentialsNotAvailable",
+    "fetch_for_user",
+    "is_connected",
+    "connect_url",
+    "not_connected_error",
+]

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk/runtime/platform_client.py

@@ -134,8 +134,11 @@ class PlatformClient:
         # tool_id may arrive dotted (linkedin.create_post); the endpoint wants
         # the bare tool segment.
         bare = tool_id.split(".", 1)[1] if "." in tool_id else tool_id
+        # Canonical broker route is `/internal/integrations/tools/{id}/{tool}/execute`
+        # (see clarity-api InternalIntegrationsController). Earlier builds omitted
+        # the `tools/` segment and every brokered call 404'd — keep the segment.
         url = (
-            f"{self.base_url}/internal/integrations/"
+            f"{self.base_url}/internal/integrations/tools/"
             f"{integration_id}/{bare}/execute"
         )
         # Per-app scoping: platform serves the connection bound to THIS app.
@@ -159,6 +162,13 @@ class PlatformClient:
             ) from exc
         if res.status_code == 409:
             return {"error": f"{integration_id}_not_connected"}
+        if res.status_code == 404:
+            # The tool/route/executor isn't brokered for this app (unbrokered
+            # catalog integration, or a stale route). DEGRADE rather than raise —
+            # a brokered call is optional from the app's view, so a hard crash here
+            # would break an otherwise-working flow (this 500'd onboarding when
+            # brave-search had no executor). Callers see the not-connected signal.
+            return {"error": f"{integration_id}_not_connected"}
         if res.status_code == 401:
             raise RuntimeError(
                 f"integration execute 401 from {url} — check CLARITY_INTERNAL_SECRET."

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claritty-sdk
-Version: 2.2.0
+Version: 2.4.0
 Summary: Official SDK for building apps on the Claritty Platform
 Author: Claritty Platform
 License: MIT

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/claritty_sdk.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ claritty_sdk/cli_verify.py
 claritty_sdk/context.py
 claritty_sdk/decorators.py
 claritty_sdk/eval.py
+claritty_sdk/files.py
 claritty_sdk/graph.py
 claritty_sdk/llm.py
 claritty_sdk/manifest.py

{claritty_sdk-2.2.0 → claritty_sdk-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claritty-sdk"
-version = "2.2.0"
+version = "2.4.0"
 description = "Official SDK for building apps on the Claritty Platform"
 readme = "README.md"
 requires-python = ">=3.9"

claritty_sdk-2.4.0/tests/test_integration_broker_dispatch.py

@@ -0,0 +1,140 @@
+"""Phase 3: the agent tool-loop must BROKER integration-provided tools through
+the platform executor — the credential never reaches the app. A catalog-source
+tool with no locally-registered handler is dispatched via the platform delegate
+(PlatformClient.execute_integration_tool), and only its result is returned.
+"""
+import asyncio
+
+from claritty_sdk.runtime import tool_loop
+from claritty_sdk.runtime import platform_client
+from claritty_sdk.manifest import ToolDecl
+from claritty_sdk.context import AgentContext
+
+
+def _ctx():
+    return AgentContext(user_id="u1")
+
+
+def test_integration_tool_is_brokered(monkeypatch):
+    seen = {}
+
+    def fake_exec(self, integration_id, tool_id, user_id, arguments):
+        seen.update(
+            integration_id=integration_id,
+            tool_id=tool_id,
+            user_id=user_id,
+            arguments=arguments,
+        )
+        return {"message_id": "m1"}
+
+    monkeypatch.setattr(
+        platform_client.PlatformClient, "execute_integration_tool", fake_exec
+    )
+
+    toolset = {
+        "gmail.send": ToolDecl(
+            id="gmail.send", source="catalog", handler="", input={}, output={}
+        )
+    }
+    out = asyncio.run(
+        tool_loop._dispatch_tool(
+            "gmail.send", {"to": "x@y.com"}, toolset, _ctx(), None
+        )
+    )
+    # Only the result comes back — no credential.
+    assert out == {"message_id": "m1"}
+    assert seen["integration_id"] == "gmail"
+    assert seen["user_id"] == "u1"
+    assert seen["arguments"] == {"to": "x@y.com"}
+
+
+def test_execute_posts_to_canonical_tools_route(monkeypatch):
+    """The broker POST must target the canonical
+    `/internal/integrations/tools/{id}/{tool}/execute` route the platform
+    serves. Omitting the `tools/` segment 404s every brokered call — this
+    guards that regression."""
+    captured = {}
+
+    class _Resp:
+        status_code = 200
+        content = b"{}"
+
+        def json(self):
+            return {"result": {"ok": True}}
+
+    class _FakeClient:
+        def __init__(self, *a, **k):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def post(self, url, **kwargs):
+            captured["url"] = url
+            captured["json"] = kwargs.get("json")
+            return _Resp()
+
+    monkeypatch.setenv("CLARITTY_PLATFORM_URL", "https://api.claritty.ai")
+    monkeypatch.setenv("CLARITY_INTERNAL_SECRET", "sec")
+    monkeypatch.setattr(platform_client.httpx, "Client", _FakeClient)
+
+    out = platform_client.PlatformClient().execute_integration_tool(
+        "hubspot", "hubspot.search_contacts", "u1", {"query": "acme"}
+    )
+
+    assert out == {"ok": True}
+    assert (
+        captured["url"]
+        == "https://api.claritty.ai/internal/integrations/tools/hubspot/search_contacts/execute"
+    )
+    assert captured["json"]["userId"] == "u1"
+
+
+def test_404_degrades_to_not_connected(monkeypatch):
+    """An unbrokered integration / stale route (404) must DEGRADE to a
+    not-connected signal, not raise — a raise here 500'd onboarding when
+    `brave-search.search` had no executor."""
+    class _Resp:
+        status_code = 404
+        content = b'{"message":"Cannot POST ..."}'
+        text = '{"message":"Cannot POST ..."}'
+
+        def json(self):
+            return {}
+
+    class _FakeClient:
+        def __init__(self, *a, **k):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def post(self, url, **kwargs):
+            return _Resp()
+
+    monkeypatch.setenv("CLARITTY_PLATFORM_URL", "https://api.claritty.ai")
+    monkeypatch.setenv("CLARITY_INTERNAL_SECRET", "sec")
+    monkeypatch.setattr(platform_client.httpx, "Client", _FakeClient)
+
+    out = platform_client.PlatformClient().execute_integration_tool(
+        "brave-search", "brave-search.search", "u1", {"query": "x"}
+    )
+    assert out == {"error": "brave-search_not_connected"}
+
+
+def test_unknown_custom_tool_still_errors():
+    toolset = {
+        "foo.bar": ToolDecl(
+            id="foo.bar", source="custom", handler="", input={}, output={}
+        )
+    }
+    out = asyncio.run(
+        tool_loop._dispatch_tool("foo.bar", {}, toolset, _ctx(), None)
+    )
+    assert "no registered handler" in out.get("error", "")

claritty_sdk-2.2.0/tests/test_integration_broker_dispatch.py

@@ -1,60 +0,0 @@
-"""Phase 3: the agent tool-loop must BROKER integration-provided tools through
-the platform executor — the credential never reaches the app. A catalog-source
-tool with no locally-registered handler is dispatched via the platform delegate
-(PlatformClient.execute_integration_tool), and only its result is returned.
-"""
-import asyncio
-
-from claritty_sdk.runtime import tool_loop
-from claritty_sdk.runtime import platform_client
-from claritty_sdk.manifest import ToolDecl
-from claritty_sdk.context import AgentContext
-
-
-def _ctx():
-    return AgentContext(user_id="u1")
-
-
-def test_integration_tool_is_brokered(monkeypatch):
-    seen = {}
-
-    def fake_exec(self, integration_id, tool_id, user_id, arguments):
-        seen.update(
-            integration_id=integration_id,
-            tool_id=tool_id,
-            user_id=user_id,
-            arguments=arguments,
-        )
-        return {"message_id": "m1"}
-
-    monkeypatch.setattr(
-        platform_client.PlatformClient, "execute_integration_tool", fake_exec
-    )
-
-    toolset = {
-        "gmail.send": ToolDecl(
-            id="gmail.send", source="catalog", handler="", input={}, output={}
-        )
-    }
-    out = asyncio.run(
-        tool_loop._dispatch_tool(
-            "gmail.send", {"to": "x@y.com"}, toolset, _ctx(), None
-        )
-    )
-    # Only the result comes back — no credential.
-    assert out == {"message_id": "m1"}
-    assert seen["integration_id"] == "gmail"
-    assert seen["user_id"] == "u1"
-    assert seen["arguments"] == {"to": "x@y.com"}
-
-
-def test_unknown_custom_tool_still_errors():
-    toolset = {
-        "foo.bar": ToolDecl(
-            id="foo.bar", source="custom", handler="", input={}, output={}
-        )
-    }
-    out = asyncio.run(
-        tool_loop._dispatch_tool("foo.bar", {}, toolset, _ctx(), None)
-    )
-    assert "no registered handler" in out.get("error", "")