snowflake-cortex-agent-sdk 0.0.2__tar.gz → 0.0.3__tar.gz

snowflake_cortex_agent_sdk-0.0.3/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: snowflake-cortex-agent-sdk
+Version: 0.0.3
+Summary: Python SDK for the Snowflake Cortex Agent REST API (agent:run streaming, threads, feedback)
+Author-email: "Snowflake, Inc." <support@snowflake.com>
+License: See LICENSE
+License-File: LICENSE
+Keywords: cortex,cortex-agent,openapi,sdk,snowflake
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: snowflake-connector-python[secure-local-storage]<5,>=4.7.1
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.28; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Snowflake Cortex Agent SDK for Python
+
+Python SDK for the Snowflake Cortex Agent REST API. Covers the current public surface:
+
+- Durable lite, data-agent, and coding-agent conversations
+- Named + versioned data agents through the direct API client
+- Coding-agent runs with sandbox, bash, skills, and workspace mounts
+- Threads, background runs, streaming, and feedback through `cortex_agent_sdk.api`
+- High-level `Conversation.send()` -> `Turn` abstraction
+- Route-test helpers in `cortex_agent_sdk.testing` (see `docs/13-testing.md`)
+- Curated `AgentResponse` content and usage view
+- Synchronous and asyncio clients
+- Claude-shaped local Cortex Code sessions via `cortex_agent_sdk.cortexcode`
+
+## Install
+
+[View `snowflake-cortex-agent-sdk` on PyPI](https://pypi.org/project/snowflake-cortex-agent-sdk/).
+
+```bash
+pip install snowflake-cortex-agent-sdk
+```
+
+Requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+import os
+from cortex_agent_sdk import (
+    AgentResponse,
+    Conversation,
+    ConversationMessage,
+    CortexAgentClient,
+    Turn,
+)
+
+client: CortexAgentClient = CortexAgentClient(
+    account="my_account",
+    auth=os.environ["SNOWFLAKE_PAT"],
+)
+
+conversation: Conversation = client.conversations.create(
+    origin_application="cortex_agent_sdk",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "claude-sonnet-4-5"}}},
+)
+
+turn: Turn = conversation.send("What is Snowflake Arctic?")
+print(f"run: {turn.id}")
+
+answer: AgentResponse = turn.result()
+print(answer.text)
+
+history: list[ConversationMessage] = conversation.history()
+```
+
+Set a default agent when creating a conversation. A send can override it for one
+turn when needed:
+
+```python
+inline_turn: Turn = conversation.send(
+    "Summarize the context.",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+)
+
+data_turn: Turn = conversation.send(
+    "Which products grew fastest?",
+    agent={
+        "type": "data",
+        "spec": {"database": "ANALYTICS", "schema": "PUBLIC", "name": "SALES_AGENT"},
+    },
+)
+
+coding_turn: Turn = conversation.send(
+    "Fix the failing test.",
+    agent={
+        "type": "coding",
+        "spec": {
+            "models": {"orchestration": "claude-sonnet-4-5"},
+            "permission_policy": "always_allow",
+            "workspace_mounts": [{"name": "USER$MY_USER.PUBLIC.DEFAULT$"}],
+        },
+    },
+)
+```
+
+Use `turn.events()` for event-level progress and `turn.cancel()` to stop a run.
+
+## Async
+
+The asynchronous API mirrors the sync API:
+
+```python
+from cortex_agent_sdk import AgentResponse, AsyncConversation, AsyncCortexAgentClient, AsyncTurn
+
+async with AsyncCortexAgentClient(account="my_account", auth="<token>") as client:
+    conversation: AsyncConversation = await client.conversations.create(
+        origin_application="cortex_agent_sdk",
+        agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+    )
+    turn: AsyncTurn = await conversation.send("Analyze this data.")
+    answer: AgentResponse = await turn.result()
+```
+
+## Cortex Code sessions (`cortex_agent_sdk.cortexcode`)
+
+`cortex_agent_sdk.cortexcode` is the Cortex Code SDK for driving the local
+`cortex` binary from Python. It exposes one-shot `query()` calls and long-lived
+`CortexCodeSDKClient` sessions with permissions, hooks, MCP, plugins, structured
+output, and session controls.
+
+```python
+import asyncio
+from cortex_agent_sdk.cortexcode import AssistantMessage, ResultMessage, query
+
+async def main() -> None:
+    async for message in query(prompt="Summarize this repository"):
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if hasattr(block, "text"):
+                    print(block.text, end="")
+        elif isinstance(message, ResultMessage):
+            print(f"\nDone: {message.subtype}")
+
+asyncio.run(main())
+```
+
+This entry point runs the local Cortex Code CLI. For server-side integrations,
+use the package-root `CortexAgentClient` with a coding-agent conversation
+instead.
+
+## Resources at a glance
+
+| Resource | Purpose |
+| --- | --- |
+| `client.conversations` | Create, attach, list, and search conversations |
+| `client.feedback` | Send feedback for a data-agent turn |
+
+`Conversation` binds a thread to an inline, data, or coding agent and hides
+message and run plumbing. `send()` returns a `Turn` with `id`, `result()`,
+`events()`, and `cancel()`.
+
+For direct REST request shapes, streaming modes, raw response wrappers, or SSE
+parsing, import `CortexAgentClient` and related types from
+`cortex_agent_sdk.api`.
+
+Separate entry point, not a `client.*` resource:
+
+| Entry point | Purpose |
+| --- | --- |
+| `cortex_agent_sdk.cortexcode` | Python SDK for the local Cortex Code CLI: permissions, hooks, MCP, plugins, and session controls |
+
+## Auth at a glance
+
+Authentication headers are rebuilt for every attempt. `refresh_auth` runs only
+for recognized token/session expiry responses, including legacy `200` JSON error
+envelopes; by default the SDK refreshes once
+and replays the request once. SDK-generated errors do not include credential
+values.
+
+| Class | For | Header shape |
+| --- | --- | --- |
+| `PatAuth` (or string shorthand) | Programmatic Access Token | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN` |
+| `OAuthAuth` | External OAuth / Snowflake OAuth access tokens | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: OAUTH` |
+| `KeyPairJwtAuth` | Key-pair JWT auth | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT` |
+| `SnowflakeSessionTokenAuth` | `snowflake-connector-python` session tokens | `Authorization: Snowflake Token="<token>"` |
+| `CallableAuth` | Lazy token minting | Bearer + configurable token-type header |
+| Custom `Authenticator` | Anything else | You return the header map |
+
+## Status
+
+Preview. Expect breaking changes as the underlying API stabilizes.
+
+## License
+
+See `LICENSE`. Use is governed by your Snowflake customer agreement.

snowflake_cortex_agent_sdk-0.0.3/README.md

@@ -0,0 +1,175 @@
+# Snowflake Cortex Agent SDK for Python
+
+Python SDK for the Snowflake Cortex Agent REST API. Covers the current public surface:
+
+- Durable lite, data-agent, and coding-agent conversations
+- Named + versioned data agents through the direct API client
+- Coding-agent runs with sandbox, bash, skills, and workspace mounts
+- Threads, background runs, streaming, and feedback through `cortex_agent_sdk.api`
+- High-level `Conversation.send()` -> `Turn` abstraction
+- Route-test helpers in `cortex_agent_sdk.testing` (see `docs/13-testing.md`)
+- Curated `AgentResponse` content and usage view
+- Synchronous and asyncio clients
+- Claude-shaped local Cortex Code sessions via `cortex_agent_sdk.cortexcode`
+
+## Install
+
+[View `snowflake-cortex-agent-sdk` on PyPI](https://pypi.org/project/snowflake-cortex-agent-sdk/).
+
+```bash
+pip install snowflake-cortex-agent-sdk
+```
+
+Requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+import os
+from cortex_agent_sdk import (
+    AgentResponse,
+    Conversation,
+    ConversationMessage,
+    CortexAgentClient,
+    Turn,
+)
+
+client: CortexAgentClient = CortexAgentClient(
+    account="my_account",
+    auth=os.environ["SNOWFLAKE_PAT"],
+)
+
+conversation: Conversation = client.conversations.create(
+    origin_application="cortex_agent_sdk",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "claude-sonnet-4-5"}}},
+)
+
+turn: Turn = conversation.send("What is Snowflake Arctic?")
+print(f"run: {turn.id}")
+
+answer: AgentResponse = turn.result()
+print(answer.text)
+
+history: list[ConversationMessage] = conversation.history()
+```
+
+Set a default agent when creating a conversation. A send can override it for one
+turn when needed:
+
+```python
+inline_turn: Turn = conversation.send(
+    "Summarize the context.",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+)
+
+data_turn: Turn = conversation.send(
+    "Which products grew fastest?",
+    agent={
+        "type": "data",
+        "spec": {"database": "ANALYTICS", "schema": "PUBLIC", "name": "SALES_AGENT"},
+    },
+)
+
+coding_turn: Turn = conversation.send(
+    "Fix the failing test.",
+    agent={
+        "type": "coding",
+        "spec": {
+            "models": {"orchestration": "claude-sonnet-4-5"},
+            "permission_policy": "always_allow",
+            "workspace_mounts": [{"name": "USER$MY_USER.PUBLIC.DEFAULT$"}],
+        },
+    },
+)
+```
+
+Use `turn.events()` for event-level progress and `turn.cancel()` to stop a run.
+
+## Async
+
+The asynchronous API mirrors the sync API:
+
+```python
+from cortex_agent_sdk import AgentResponse, AsyncConversation, AsyncCortexAgentClient, AsyncTurn
+
+async with AsyncCortexAgentClient(account="my_account", auth="<token>") as client:
+    conversation: AsyncConversation = await client.conversations.create(
+        origin_application="cortex_agent_sdk",
+        agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+    )
+    turn: AsyncTurn = await conversation.send("Analyze this data.")
+    answer: AgentResponse = await turn.result()
+```
+
+## Cortex Code sessions (`cortex_agent_sdk.cortexcode`)
+
+`cortex_agent_sdk.cortexcode` is the Cortex Code SDK for driving the local
+`cortex` binary from Python. It exposes one-shot `query()` calls and long-lived
+`CortexCodeSDKClient` sessions with permissions, hooks, MCP, plugins, structured
+output, and session controls.
+
+```python
+import asyncio
+from cortex_agent_sdk.cortexcode import AssistantMessage, ResultMessage, query
+
+async def main() -> None:
+    async for message in query(prompt="Summarize this repository"):
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if hasattr(block, "text"):
+                    print(block.text, end="")
+        elif isinstance(message, ResultMessage):
+            print(f"\nDone: {message.subtype}")
+
+asyncio.run(main())
+```
+
+This entry point runs the local Cortex Code CLI. For server-side integrations,
+use the package-root `CortexAgentClient` with a coding-agent conversation
+instead.
+
+## Resources at a glance
+
+| Resource | Purpose |
+| --- | --- |
+| `client.conversations` | Create, attach, list, and search conversations |
+| `client.feedback` | Send feedback for a data-agent turn |
+
+`Conversation` binds a thread to an inline, data, or coding agent and hides
+message and run plumbing. `send()` returns a `Turn` with `id`, `result()`,
+`events()`, and `cancel()`.
+
+For direct REST request shapes, streaming modes, raw response wrappers, or SSE
+parsing, import `CortexAgentClient` and related types from
+`cortex_agent_sdk.api`.
+
+Separate entry point, not a `client.*` resource:
+
+| Entry point | Purpose |
+| --- | --- |
+| `cortex_agent_sdk.cortexcode` | Python SDK for the local Cortex Code CLI: permissions, hooks, MCP, plugins, and session controls |
+
+## Auth at a glance
+
+Authentication headers are rebuilt for every attempt. `refresh_auth` runs only
+for recognized token/session expiry responses, including legacy `200` JSON error
+envelopes; by default the SDK refreshes once
+and replays the request once. SDK-generated errors do not include credential
+values.
+
+| Class | For | Header shape |
+| --- | --- | --- |
+| `PatAuth` (or string shorthand) | Programmatic Access Token | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN` |
+| `OAuthAuth` | External OAuth / Snowflake OAuth access tokens | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: OAUTH` |
+| `KeyPairJwtAuth` | Key-pair JWT auth | `Authorization: Bearer <token>` + `X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT` |
+| `SnowflakeSessionTokenAuth` | `snowflake-connector-python` session tokens | `Authorization: Snowflake Token="<token>"` |
+| `CallableAuth` | Lazy token minting | Bearer + configurable token-type header |
+| Custom `Authenticator` | Anything else | You return the header map |
+
+## Status
+
+Preview. Expect breaking changes as the underlying API stabilizes.
+
+## License
+
+See `LICENSE`. Use is governed by your Snowflake customer agreement.

{snowflake_cortex_agent_sdk-0.0.2 → snowflake_cortex_agent_sdk-0.0.3}/cortex_agent_sdk/__init__.py

@@ -55,6 +55,7 @@ from .conversation import (
     ConversationMessage,
     DataAgentSpec,
     InlineAgentSpec,
+    PermissionDecision,
 )
 from .errors import (
     APIConnectionAbortedError,
@@ -74,7 +75,7 @@ from .errors import (
     UnprocessableEntityError,
 )
 from .public_client import AsyncCortexAgentClient, CortexAgentClient
-from .turn import AsyncTurn, Turn
+from .turn import AsyncTurn, ClientToolUse, PermissionRequest, Turn
 from .views.agent_response import AgentResponseView as AgentResponse
 
 __all__ = [
@@ -89,6 +90,7 @@ __all__ = [
     "ConversationInput",
     "ConversationMessage",
     "CodingAgentSpec",
+    "ClientToolUse",
     "DataAgentSpec",
     "InlineAgentSpec",
     "CortexAgentClient",
@@ -101,6 +103,8 @@ __all__ = [
     "KeyPairJwtAuth",
     "OAuthAuth",
     "PatAuth",
+    "PermissionRequest",
+    "PermissionDecision",
     "SnowflakeSessionTokenAuth",
     "SnowflakeTokenAuth",
     "SnowflakeTokenType",

{snowflake_cortex_agent_sdk-0.0.2 → snowflake_cortex_agent_sdk-0.0.3}/cortex_agent_sdk/_base_client.py

@@ -24,6 +24,7 @@ import platform
 import random
 import time
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any
 from urllib.parse import urlparse
 
@@ -31,6 +32,7 @@ import httpx
 
 from ._constants import (
     DEFAULT_MAX_RETRIES,
+    DEFAULT_STREAM_READ_TIMEOUT,
     DEFAULT_TIMEOUT,
     INITIAL_RETRY_DELAY,
     MAX_RETRY_AFTER_DELAY,
@@ -39,7 +41,9 @@ from ._constants import (
     RETRY_STATUSES,
     SHOULD_RETRY_HEADER,
 )
+from ._partner_attribution import validate_partner_application
 from ._request_options import RequestOptions, RequestOptionsLike, normalize_options
+from ._telemetry import SDK_OPERATION_HEADER, identity_headers
 from ._transport import (
     AuthRefreshContext,
     RetryPolicy,
@@ -47,7 +51,7 @@ from ._transport import (
     is_transport_retry_safe_by_default,
     merge_retry_policies,
 )
-from ._types import NotGiven, Omit, given_or
+from ._types import NotGiven, Omit, given_or, is_given, not_given
 from ._version import __version__
 from .api_response import APIResponse
 from .auth import Authenticator, coerce_authenticator
@@ -78,11 +82,14 @@ class BaseClient:
         base_url: str | None,
         auth: str | Authenticator | Any,
         timeout: float | httpx.Timeout | None | NotGiven,
+        stream_read_timeout: float | None | NotGiven = not_given,
         retry_policy: RetryPolicy | None,
         refresh_auth: Any,
         auth_refresh_max_retries: int,
         default_headers: Mapping[str, str] | None,
         default_query: Mapping[str, Any] | None,
+        partner_application: str | None = None,
+        sdk_surface: str = "agent",
     ) -> None:
         if base_url is None and account is None:
             raise CortexAgentError("Either `account` or `base_url` is required.")
@@ -102,7 +109,37 @@ class BaseClient:
         self.refresh_auth = refresh_auth
         self.auth_refresh_max_retries = auth_refresh_max_retries
         self.timeout: float | httpx.Timeout | None = given_or(timeout, DEFAULT_TIMEOUT)
-        self.default_headers: dict[str, str] = dict(default_headers or {})
+        # ``None`` disables the gap timeout. Omitted uses the 10-minute default.
+        self.stream_read_timeout: float | None = given_or(
+            stream_read_timeout, DEFAULT_STREAM_READ_TIMEOUT
+        )
+        identity = identity_headers(surface=sdk_surface)
+        application = validate_partner_application(partner_application)
+        configured_user_agent = next(
+            (
+                value
+                for name, value in (default_headers or {}).items()
+                if name.lower() == "user-agent"
+            ),
+            None,
+        )
+        if (
+            application is not None
+            and configured_user_agent is not None
+            and configured_user_agent != application
+        ):
+            raise CortexAgentError(
+                "Configure partner attribution with `partner_application`, not a "
+                "conflicting `default_headers['User-Agent']`."
+            )
+        attribution_headers = {"User-Agent": application} if application else {}
+        self.partner_application = application
+        self.sdk_surface = sdk_surface
+        self.default_headers: dict[str, str] = {
+            **identity,
+            **attribution_headers,
+            **dict(default_headers or {}),
+        }
         self.default_query: dict[str, Any] = dict(default_query or {})
         # Kept for copy()/with_options(), which must reproduce the original args.
         self._account = account
@@ -146,6 +183,8 @@ class BaseClient:
             headers.update(opts.headers)
         if opts.extra_headers:
             headers.update(opts.extra_headers)
+        if is_given(opts.sdk_operation):
+            headers[SDK_OPERATION_HEADER] = str(opts.sdk_operation)
         if has_body:
             headers.setdefault("Content-Type", "application/json")
         # `omit` removes a header the SDK would otherwise send.
@@ -178,13 +217,14 @@ class BaseClient:
         base = given_or(opts.timeout, self.timeout)
         if not stream:
             return base
-        # A long-running SSE response legitimately has long gaps between chunks,
-        # so `read` is unbounded unless the caller asks for a cap.
+        # A long-running SSE response legitimately has long gaps between chunks.
+        # `read` uses the client default (10 minutes) unless this request sets
+        # `stream_read_timeout`. Explicit ``None`` waits indefinitely.
         connect = base.connect if isinstance(base, httpx.Timeout) else base
         return httpx.Timeout(
             None,
             connect=connect,
-            read=given_or(opts.stream_read_timeout, None),
+            read=given_or(opts.stream_read_timeout, self.stream_read_timeout),
             write=connect,
         )
 
@@ -287,7 +327,11 @@ class BaseClient:
     ) -> AuthRefreshContext | None:
         if self.refresh_auth is None or attempt > self.auth_refresh_max_retries:
             return None
-        if response.status_code not in {401, 403}:
+        # A successful SSE response is a live stream; only a non-SSE 200 can
+        # be the legacy JSON expired-session envelope.
+        if stream and response.status_code == 200 and _is_sse_response(response):
+            return None
+        if response.status_code not in {200, 401, 403}:
             return None
         response_body = self._read_response_body(response)
         if not is_auth_expired_response(response.status_code, response_body):
@@ -313,7 +357,11 @@ class BaseClient:
     ) -> AuthRefreshContext | None:
         if self.refresh_auth is None or attempt > self.auth_refresh_max_retries:
             return None
-        if response.status_code not in {401, 403}:
+        # A successful SSE response is a live stream; only a non-SSE 200 can
+        # be the legacy JSON expired-session envelope.
+        if stream and response.status_code == 200 and _is_sse_response(response):
+            return None
+        if response.status_code not in {200, 401, 403}:
             return None
         response_body = await self._aread_response_body(response)
         if not is_auth_expired_response(response.status_code, response_body):
@@ -362,6 +410,8 @@ class BaseClient:
     ) -> tuple[RequestOptions, dict[str, Any], _ResolvedRetryPolicy, Any, Any]:
         """Resolve options once, before the retry loop."""
         opts = normalize_options(options)
+        if not is_given(opts.sdk_operation):
+            opts = replace(opts, sdk_operation="client.request")
         return (
             opts,
             self._build_query(params, opts),
@@ -400,11 +450,14 @@ class BaseClient:
             "base_url": self.base_url,
             "auth": self.auth,
             "timeout": self.timeout,
+            "stream_read_timeout": self.stream_read_timeout,
             "retry_policy": self.retry_policy,
             "refresh_auth": self.refresh_auth,
             "auth_refresh_max_retries": self.auth_refresh_max_retries,
             "default_headers": self.default_headers,
             "default_query": self.default_query,
+            "partner_application": self.partner_application,
+            "sdk_surface": self.sdk_surface,
         }
 
 
@@ -742,6 +795,10 @@ def _is_local_host(hostname: str | None) -> bool:
     return hostname in _LOCAL_HOSTS or (hostname is not None and hostname.endswith(".local"))
 
 
+def _is_sse_response(response: httpx.Response) -> bool:
+    return "text/event-stream" in response.headers.get("content-type", "").lower()
+
+
 def _validate_base_url(base_url: str) -> str:
     """Reject a base URL that would put the credential on the wire in clear text.
 

{snowflake_cortex_agent_sdk-0.0.2 → snowflake_cortex_agent_sdk-0.0.3}/cortex_agent_sdk/_constants.py

@@ -16,6 +16,11 @@ import httpx
 #: ``APITimeoutError``s; a short *connect* timeout still fails fast on a bad host.
 DEFAULT_TIMEOUT: Final = httpx.Timeout(600.0, connect=5.0)
 
+#: Max gap between SSE chunks before a stream fails. Matches the 10-minute
+#: total timeout: long enough for a quiet tool call, short enough that a dead
+#: socket does not wait forever. Pass ``stream_read_timeout=None`` to disable.
+DEFAULT_STREAM_READ_TIMEOUT: Final = 600.0
+
 DEFAULT_MAX_RETRIES: Final = 2
 
 #: First retry delay, doubled per attempt up to :data:`MAX_RETRY_DELAY`.

snowflake_cortex_agent_sdk-0.0.3/cortex_agent_sdk/_partner_attribution.py

@@ -0,0 +1,18 @@
+"""Partner attribution helpers for REST requests."""
+
+from __future__ import annotations
+
+from .errors import CortexAgentError
+
+
+def validate_partner_application(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not value:
+        raise CortexAgentError("`partner_application` must not be empty.")
+    if "\r" in value or "\n" in value:
+        raise CortexAgentError("`partner_application` must not contain CR or LF characters.")
+    return value
+
+
+__all__ = ["validate_partner_application"]

{snowflake_cortex_agent_sdk-0.0.2 → snowflake_cortex_agent_sdk-0.0.3}/cortex_agent_sdk/_request_options.py

@@ -72,6 +72,9 @@ class RequestOptions:
     #: next event boundary. The async client uses task cancellation instead.
     cancel: threading.Event | None | NotGiven = field(default=not_given, repr=False)
 
+    #: Internal stable, low-cardinality public SDK operation name.
+    sdk_operation: str | NotGiven = field(default=not_given, repr=False)
+
     def merge(self, other: RequestOptions | None) -> RequestOptions:
         """A copy with every *given* field of ``other`` layered on top."""
         if other is None:
@@ -155,4 +158,16 @@ def with_overrides(
     return replace(base, **overrides) if overrides else base
 
 
-__all__ = ["RequestOptions", "RequestOptionsLike", "normalize_options", "with_overrides"]
+def with_sdk_operation(options: RequestOptionsLike, operation: str) -> RequestOptions:
+    """Set the semantic operation unless an outer SDK wrapper already set it."""
+    base = normalize_options(options)
+    return base if is_given(base.sdk_operation) else replace(base, sdk_operation=operation)
+
+
+__all__ = [
+    "RequestOptions",
+    "RequestOptionsLike",
+    "normalize_options",
+    "with_overrides",
+    "with_sdk_operation",
+]

snowflake_cortex_agent_sdk-0.0.3/cortex_agent_sdk/_telemetry.py

@@ -0,0 +1,24 @@
+"""Bounded request metadata used for SDK telemetry."""
+
+from __future__ import annotations
+
+from ._version import __version__
+
+SDK_OPERATION_HEADER = "x-cortex-agent-sdk-operation"
+SDK_SURFACE_HEADER = "x-cortex-agent-sdk-surface"
+
+
+def identity_headers(*, surface: str = "agent") -> dict[str, str]:
+    return {
+        "User-Agent": f"cortex-agent-sdk-python/{__version__}",
+        "x-cortex-agent-sdk-lang": "python",
+        "x-cortex-agent-sdk-version": __version__,
+        SDK_SURFACE_HEADER: surface,
+    }
+
+
+__all__ = [
+    "SDK_OPERATION_HEADER",
+    "SDK_SURFACE_HEADER",
+    "identity_headers",
+]