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

snowflake_cortex_agent_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: snowflake-cortex-agent-sdk
+Version: 0.0.2
+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
+
+The SDK centers on conversations, durable turns, and completed responses. It
+uses background runs internally while hiding run and thread bookkeeping.
+
+```python
+from cortex_agent_sdk import (
+    AgentResponse,
+    Conversation,
+    ConversationMessage,
+    CortexAgentClient,
+    Turn,
+)
+
+client: CortexAgentClient = CortexAgentClient(account="my_account", auth="<token>")
+conversation: Conversation = client.conversations.create(
+    origin_application="cortex_agent_sdk",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+)
+turn: Turn = conversation.send("What is Snowflake Arctic?")
+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.
+
+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": {}}
+    )
+    turn: AsyncTurn = await conversation.send("Analyze this data.")
+    answer: AgentResponse = await turn.result()
+```
+
+The root client exposes `conversations` and `feedback`. Advanced streaming and
+explicit run/thread management live under
+`cortex_agent_sdk.api`:
+
+```python
+from cortex_agent_sdk.api import CortexAgentClient
+
+api_client: CortexAgentClient = CortexAgentClient(
+    account="my_account",
+    auth="<token>",
+)
+```
+
+Authentication headers are rebuilt for every attempt. `refresh_auth` runs only
+for recognized token/session expiry responses; by default the SDK refreshes once
+and replays the request once. SDK-generated errors do not include credential
+values.
+
+Requires Python 3.10 or newer.

snowflake_cortex_agent_sdk-0.0.2/README.md

@@ -0,0 +1,90 @@
+# Snowflake Cortex Agent SDK for Python
+
+The SDK centers on conversations, durable turns, and completed responses. It
+uses background runs internally while hiding run and thread bookkeeping.
+
+```python
+from cortex_agent_sdk import (
+    AgentResponse,
+    Conversation,
+    ConversationMessage,
+    CortexAgentClient,
+    Turn,
+)
+
+client: CortexAgentClient = CortexAgentClient(account="my_account", auth="<token>")
+conversation: Conversation = client.conversations.create(
+    origin_application="cortex_agent_sdk",
+    agent={"type": "inline", "spec": {"models": {"orchestration": "auto"}}},
+)
+turn: Turn = conversation.send("What is Snowflake Arctic?")
+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.
+
+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": {}}
+    )
+    turn: AsyncTurn = await conversation.send("Analyze this data.")
+    answer: AgentResponse = await turn.result()
+```
+
+The root client exposes `conversations` and `feedback`. Advanced streaming and
+explicit run/thread management live under
+`cortex_agent_sdk.api`:
+
+```python
+from cortex_agent_sdk.api import CortexAgentClient
+
+api_client: CortexAgentClient = CortexAgentClient(
+    account="my_account",
+    auth="<token>",
+)
+```
+
+Authentication headers are rebuilt for every attempt. `refresh_auth` runs only
+for recognized token/session expiry responses; by default the SDK refreshes once
+and replays the request once. SDK-generated errors do not include credential
+values.
+
+Requires Python 3.10 or newer.

snowflake_cortex_agent_sdk-0.0.2/cortex_agent_sdk/__init__.py

@@ -0,0 +1,126 @@
+"""Snowflake Cortex Agent SDK (Python).
+
+Sync::
+
+    from cortex_agent_sdk import AgentResponse, Conversation, CortexAgentClient, Turn
+
+    client = CortexAgentClient(account="myacct", auth="<pat>")
+    conversation: Conversation = client.conversations.create(
+        origin_application="cortex_agent_sdk", agent={"type": "inline", "spec": {}}
+    )
+    turn: Turn = conversation.send("What is Snowflake Arctic?")
+    answer: AgentResponse = turn.result()
+    print(answer.text)
+
+Async::
+
+    import asyncio
+    from cortex_agent_sdk import AsyncConversation, AsyncCortexAgentClient
+
+    async def main():
+        async with AsyncCortexAgentClient(account="myacct", auth="<pat>") as client:
+            conversation: AsyncConversation = await client.conversations.create(
+                origin_application="cortex_agent_sdk", agent={"type": "inline", "spec": {}}
+            )
+            turn: AsyncTurn = await conversation.send("What is Snowflake Arctic?")
+            answer: AgentResponse = await turn.result()
+            print(answer.text)
+
+    asyncio.run(main())
+
+Start with ``docs/01-getting-started.md``.
+"""
+
+from __future__ import annotations
+
+from ._request_options import RequestOptions
+from ._transport import AuthRefreshContext, RetryPolicy
+from ._version import __title__, __version__
+from .auth import (
+    Authenticator,
+    CallableAuth,
+    KeyPairJwtAuth,
+    OAuthAuth,
+    PatAuth,
+    SnowflakeSessionTokenAuth,
+    SnowflakeTokenAuth,
+    SnowflakeTokenType,
+)
+from .conversation import (
+    AgentSpec,
+    AsyncConversation,
+    CodingAgentSpec,
+    Conversation,
+    ConversationInput,
+    ConversationMessage,
+    DataAgentSpec,
+    InlineAgentSpec,
+)
+from .errors import (
+    APIConnectionAbortedError,
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    AuthRefreshFailureContext,
+    BadRequestError,
+    ConflictError,
+    CortexAgentAPIError,
+    CortexAgentError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+from .public_client import AsyncCortexAgentClient, CortexAgentClient
+from .turn import AsyncTurn, Turn
+from .views.agent_response import AgentResponseView as AgentResponse
+
+__all__ = [
+    # Core clients + config
+    "AgentSpec",
+    "AgentResponse",
+    "AuthRefreshContext",
+    "AsyncConversation",
+    "AsyncCortexAgentClient",
+    "AsyncTurn",
+    "Conversation",
+    "ConversationInput",
+    "ConversationMessage",
+    "CodingAgentSpec",
+    "DataAgentSpec",
+    "InlineAgentSpec",
+    "CortexAgentClient",
+    "RequestOptions",
+    "RetryPolicy",
+    "Turn",
+    # Auth
+    "Authenticator",
+    "CallableAuth",
+    "KeyPairJwtAuth",
+    "OAuthAuth",
+    "PatAuth",
+    "SnowflakeSessionTokenAuth",
+    "SnowflakeTokenAuth",
+    "SnowflakeTokenType",
+    # Errors
+    "APIConnectionAbortedError",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthRefreshFailureContext",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "CortexAgentAPIError",
+    "CortexAgentError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnprocessableEntityError",
+    # Metadata
+    "__title__",
+    "__version__",
+]

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

@@ -55,7 +55,9 @@ from .errors import (
     APIConnectionAbortedError,
     APIConnectionError,
     APITimeoutError,
+    AuthRefreshFailureContext,
     CortexAgentError,
+    attach_auth_refresh_failure_context,
     create_api_error,
 )
 
@@ -84,8 +86,11 @@ class BaseClient:
     ) -> None:
         if base_url is None and account is None:
             raise CortexAgentError("Either `account` or `base_url` is required.")
+        # Account identifiers may contain underscores, but DNS host labels use
+        # Snowflake's canonical hyphenated form.
+        account_host = account.replace("_", "-") if account is not None else None
         self.base_url = _validate_base_url(
-            (base_url or f"https://{account}.snowflakecomputing.com").rstrip("/")
+            (base_url or f"https://{account_host}.snowflakecomputing.com").rstrip("/")
         )
         self.auth: Authenticator = coerce_authenticator(auth)
         self.retry_policy = merge_retry_policies(None, retry_policy)
@@ -540,10 +545,18 @@ class SyncAPIClient(BaseClient):
                     try:
                         self.refresh_auth(refresh_context)
                     except Exception as exc:
-                        raise create_api_error(
+                        api_error = create_api_error(
                             response.status_code,
                             refresh_context.request_id,
                             refresh_context.response_body,
+                        )
+                        raise attach_auth_refresh_failure_context(
+                            api_error,
+                            AuthRefreshFailureContext(
+                                attempt=refresh_context.attempt,
+                                provider=_auth_provider_name(self.auth),
+                                request_id=refresh_context.request_id,
+                            ),
                         ) from exc
                     auth_refresh_attempt += 1
                     continue
@@ -693,10 +706,18 @@ class AsyncAPIClient(BaseClient):
                     try:
                         await self._call_refresh_auth(refresh_context)
                     except Exception as exc:
-                        raise create_api_error(
+                        api_error = create_api_error(
                             response.status_code,
                             refresh_context.request_id,
                             refresh_context.response_body,
+                        )
+                        raise attach_auth_refresh_failure_context(
+                            api_error,
+                            AuthRefreshFailureContext(
+                                attempt=refresh_context.attempt,
+                                provider=_auth_provider_name(self.auth),
+                                request_id=refresh_context.request_id,
+                            ),
                         ) from exc
                     auth_refresh_attempt += 1
                     continue
@@ -711,11 +732,16 @@ class AsyncAPIClient(BaseClient):
             await asyncio.sleep(delay)
 
 
-#: Hosts where plaintext HTTP is acceptable, because the credential never leaves
-#: the machine. Anything else must be TLS.
+#: Hosts where plaintext HTTP is acceptable in local development. Local GS uses
+#: account-qualified ``*.local`` names (for example ``snowflake.reg.local``),
+#: while public endpoints must remain TLS-only.
 _LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
 
 
+def _is_local_host(hostname: str | None) -> bool:
+    return hostname in _LOCAL_HOSTS or (hostname is not None and hostname.endswith(".local"))
+
+
 def _validate_base_url(base_url: str) -> str:
     """Reject a base URL that would put the credential on the wire in clear text.
 
@@ -728,7 +754,7 @@ def _validate_base_url(base_url: str) -> str:
     parsed = urlparse(base_url)
     if parsed.scheme == "https":
         return base_url
-    if parsed.scheme == "http" and parsed.hostname in _LOCAL_HOSTS:
+    if parsed.scheme == "http" and _is_local_host(parsed.hostname):
         return base_url
     if not parsed.scheme:
         raise CortexAgentError(
@@ -738,11 +764,16 @@ def _validate_base_url(base_url: str) -> str:
         f"base_url must use https — got {parsed.scheme!r} in {base_url!r}. Every "
         f"request sends a credential in an Authorization header, so a plaintext "
         f"endpoint would expose it to anyone on the network path. "
-        f"(http:// is allowed for loopback hosts only: "
-        f"{', '.join(sorted(_LOCAL_HOSTS))}.)"
+        "(http:// is allowed for local hosts only: localhost, loopback addresses, "
+        "or a *.local development endpoint.)"
     )
 
 
+def _auth_provider_name(auth: Authenticator) -> str:
+    name = type(auth).__name__
+    return name if name != "object" else "Authenticator"
+
+
 def _parse_retry_after(headers: httpx.Headers) -> float | None:
     """Seconds from ``retry-after-ms`` (preferred), ``retry-after``, or an HTTP date."""
     ms = headers.get("retry-after-ms")