squidcloud-client 1.0.0__tar.gz

squidcloud_client-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: squidcloud-client
+Version: 1.0.0
+Summary: Squid Cloud Python client SDK
+Author-email: Squid Cloud <support@squid.cloud>
+License: MIT
+Project-URL: Homepage, https://squid.cloud
+Project-URL: Documentation, https://docs.squid.cloud
+Project-URL: Repository, https://github.com/squid-cloud/squid-cloud
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

squidcloud_client-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "squidcloud-client"
+version = "1.0.0"
+description = "Squid Cloud Python client SDK"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "Squid Cloud", email = "support@squid.cloud"}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://squid.cloud"
+Documentation = "https://docs.squid.cloud"
+Repository = "https://github.com/squid-cloud/squid-cloud"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[tool.setuptools.packages.find]
+include = ["squidcloud*"]

squidcloud_client-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

squidcloud_client-1.0.0/squidcloud/__init__.py

@@ -0,0 +1,110 @@
+"""Squid Cloud Python client SDK.
+
+Usage::
+
+    from squidcloud import Squid
+
+    squid = Squid(
+        app_id="my-app",
+        api_key="my-api-key",
+        region="us-east-1.aws",
+        environment_id="dev",
+    )
+
+    # AI agents
+    response = await squid.ai().agent("my-agent").ask("Hello!")
+
+    # Execute backend function
+    result = await squid.execute_function("MyService:greet", "World")
+
+    # Web utilities
+    content = await squid.web().get_url_content("https://example.com")
+"""
+
+from squidcloud.client import Squid
+from squidcloud.types import (
+    AiAgentExecutionPlanOptions,
+    AiAgentMemoryOptions,
+    AiAgentResponseFormat,
+    AiAudioCreateSpeechOptions,
+    AiChatModelSelection,
+    AiChatOptions,
+    AiChatPromptQuotas,
+    AiConnectedAgentMetadata,
+    AiConnectedIntegrationMetadata,
+    AiConnectedKnowledgeBaseMetadata,
+    AiContextFileOptions,
+    AiContextTextOptions,
+    AiFileUrl,
+    AiKnowledgeBaseMetadataField,
+    AiStructuredOutputFormat,
+    ContextRequest,
+    CreatePdfDimensionsOptions,
+    CreatePdfFormatOptions,
+    CreatePdfOutputOptions,
+    DallEOptions,
+    ExtractDataFromDocumentOptions,
+    FileContextRequest,
+    FluxOptions,
+    GuardrailsOptions,
+    ImageGenerateOptions,
+    IntegrationModelSpec,
+    KnowledgeBaseSearchOptions,
+    MmCategory,
+    MmEntity,
+    MmFindMatchesOptions,
+    MmListEntitiesOptions,
+    StableDiffusionOptions,
+    TextContextRequest,
+    UpsertAgentOptions,
+    WebAiSearchResponse,
+    WebShortUrlBulkResponse,
+    WebShortUrlResponse,
+)
+
+__all__ = [
+    "Squid",
+    # AI Chat
+    "AiChatOptions",
+    "AiChatModelSelection",
+    "AiAgentMemoryOptions",
+    "AiAgentResponseFormat",
+    "AiStructuredOutputFormat",
+    "AiConnectedAgentMetadata",
+    "AiConnectedIntegrationMetadata",
+    "AiConnectedKnowledgeBaseMetadata",
+    "AiFileUrl",
+    "AiChatPromptQuotas",
+    "AiAgentExecutionPlanOptions",
+    "AiAudioCreateSpeechOptions",
+    "GuardrailsOptions",
+    "IntegrationModelSpec",
+    "UpsertAgentOptions",
+    # Knowledge Base
+    "AiKnowledgeBaseMetadataField",
+    "KnowledgeBaseSearchOptions",
+    "TextContextRequest",
+    "FileContextRequest",
+    "ContextRequest",
+    "AiContextTextOptions",
+    "AiContextFileOptions",
+    # Image
+    "ImageGenerateOptions",
+    "DallEOptions",
+    "FluxOptions",
+    "StableDiffusionOptions",
+    # Matchmaking
+    "MmCategory",
+    "MmEntity",
+    "MmFindMatchesOptions",
+    "MmListEntitiesOptions",
+    # Extraction
+    "CreatePdfOutputOptions",
+    "CreatePdfFormatOptions",
+    "CreatePdfDimensionsOptions",
+    "ExtractDataFromDocumentOptions",
+    # Web
+    "WebAiSearchResponse",
+    "WebShortUrlResponse",
+    "WebShortUrlBulkResponse",
+]

squidcloud_client-1.0.0/squidcloud/ai.py

@@ -0,0 +1,411 @@
+"""AI client — agents, knowledge base, audio, image.
+
+Covers all /squid-api/v1/ai/* endpoints from the OpenAPI spec.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from squidcloud.types import (
+    AiAudioCreateSpeechOptions,
+    AiChatModelSelection,
+    AiChatOptions,
+    AiConnectedAgentMetadata,
+    AiKnowledgeBaseMetadataField,
+    ContextRequest,
+    GuardrailsOptions,
+    ImageGenerateOptions,
+    KnowledgeBaseSearchOptions,
+)
+
+if TYPE_CHECKING:
+    from squidcloud.http import HttpTransport
+
+
+class AiClient:
+    """Entry point for AI operations: agents, knowledge base, audio, image."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def agent(self, agent_id: str) -> AgentClient:
+        return AgentClient(self._http, agent_id)
+
+    def knowledge_base(self, knowledge_base_id: str) -> KnowledgeBaseClient:
+        return KnowledgeBaseClient(self._http, knowledge_base_id)
+
+    def image(self) -> ImageClient:
+        return ImageClient(self._http)
+
+    def audio(self) -> AudioClient:
+        return AudioClient(self._http)
+
+
+# ---------------------------------------------------------------------------
+# Agent
+# ---------------------------------------------------------------------------
+
+
+class AgentClient:
+    """Operations on a single AI agent."""
+
+    def __init__(self, http: HttpTransport, agent_id: str) -> None:
+        self._http = http
+        self._agent_id = agent_id
+
+    # --- Chat ---
+
+    async def ask(
+        self,
+        prompt: str,
+        options: Optional[AiChatOptions] = None,
+    ) -> str:
+        """Ask the agent a question. Returns the response string."""
+        result = await self._http.post(
+            "squid-api/v1/ai/agent/ask",
+            {"agentId": self._agent_id, "prompt": prompt, "options": options or {}},
+        )
+        return result.get("responseString", "") if result else ""
+
+    async def ask_with_annotations(
+        self,
+        prompt: str,
+        options: Optional[AiChatOptions] = None,
+    ) -> dict:
+        """Ask the agent and get response with annotations.
+
+        Returns dict with 'responseString' and 'annotations'.
+        """
+        return await self._http.post(
+            "squid-api/v1/ai/agent/askWithAnnotations",
+            {"agentId": self._agent_id, "prompt": prompt, "options": options or {}},
+        )
+
+    # --- Management ---
+
+    async def get(self) -> Optional[dict]:
+        """Get agent configuration.
+
+        Returns AiAgent dict with: id, createdAt, updatedAt, description,
+        isPublic, auditLog, options, apiKey. Returns None if not found.
+        """
+        return await self._http.get(f"squid-api/v1/ai/agent/get/{self._agent_id}")
+
+    async def upsert(
+        self,
+        *,
+        description: Optional[str] = None,
+        is_public: Optional[bool] = None,
+        audit_log: Optional[bool] = None,
+        api_key: Optional[str] = None,
+        options: Optional[AiChatOptions] = None,
+    ) -> None:
+        """Create or update the agent."""
+        body: dict[str, Any] = {"id": self._agent_id}
+        if description is not None:
+            body["description"] = description
+        if is_public is not None:
+            body["isPublic"] = is_public
+        if audit_log is not None:
+            body["auditLog"] = audit_log
+        if api_key is not None:
+            body["apiKey"] = api_key
+        if options is not None:
+            body["options"] = options
+        await self._http.post("squid-api/v1/ai/agent/upsert", body)
+
+    async def delete(self) -> None:
+        """Delete the agent."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/delete", {"agentId": self._agent_id}
+        )
+
+    async def update_instructions(self, instructions: str) -> None:
+        """Update the agent's system instructions."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/updateInstructions",
+            {"agentId": self._agent_id, "instructions": instructions},
+        )
+
+    async def update_model(self, model: AiChatModelSelection) -> None:
+        """Update the agent's default model."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/updateModel",
+            {"agentId": self._agent_id, "model": model},
+        )
+
+    async def update_connected_agents(
+        self, connected_agents: list[AiConnectedAgentMetadata]
+    ) -> None:
+        """Update connected agents."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/updateConnectedAgents",
+            {"agentId": self._agent_id, "connectedAgents": connected_agents},
+        )
+
+    async def update_guardrails(self, guardrails: GuardrailsOptions) -> None:
+        """Update agent guardrails."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/updateGuardrails",
+            {"agentId": self._agent_id, "guardrails": guardrails},
+        )
+
+    async def update_custom_guardrails(self, custom_guardrail: str) -> None:
+        """Update custom guardrail instruction text."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/updateCustomGuardrails",
+            {"agentId": self._agent_id, "customGuardrail": custom_guardrail},
+        )
+
+    async def delete_custom_guardrails(self) -> None:
+        """Delete the custom guardrail."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/deleteCustomGuardrails",
+            {"agentId": self._agent_id},
+        )
+
+    # --- Revisions ---
+
+    async def list_revisions(self) -> list[dict]:
+        """List agent revisions."""
+        result = await self._http.get(
+            f"squid-api/v1/ai/agent/revisions/{self._agent_id}"
+        )
+        return result.get("revisions", []) if result else []
+
+    async def restore_revision(self, revision_number: int) -> None:
+        """Restore the agent to a specific revision."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/restoreRevision",
+            {"agentId": self._agent_id, "revisionNumber": revision_number},
+        )
+
+    async def delete_revision(self, revision_number: int) -> None:
+        """Delete a specific revision."""
+        await self._http.post(
+            "squid-api/v1/ai/agent/deleteRevision",
+            {"agentId": self._agent_id, "revisionNumber": revision_number},
+        )
+
+
+# ---------------------------------------------------------------------------
+# Knowledge Base
+# ---------------------------------------------------------------------------
+
+
+class KnowledgeBaseClient:
+    """Operations on a single knowledge base."""
+
+    def __init__(self, http: HttpTransport, kb_id: str) -> None:
+        self._http = http
+        self._kb_id = kb_id
+
+    async def get(self) -> Optional[dict]:
+        """Get knowledge base details."""
+        return await self._http.get(
+            f"squid-api/v1/ai/knowledge-base/get/{self._kb_id}"
+        )
+
+    async def upsert(
+        self,
+        *,
+        description: Optional[str] = None,
+        metadata_fields: Optional[list[AiKnowledgeBaseMetadataField]] = None,
+        embedding_model: Optional[str] = None,
+        chat_model: Optional[AiChatModelSelection] = None,
+        name: Optional[str] = None,
+    ) -> None:
+        """Create or update the knowledge base."""
+        kb: dict[str, Any] = {"id": self._kb_id}
+        if description is not None:
+            kb["description"] = description
+        if metadata_fields is not None:
+            kb["metadataFields"] = metadata_fields
+        if embedding_model is not None:
+            kb["embeddingModel"] = embedding_model
+        if chat_model is not None:
+            kb["chatModel"] = chat_model
+        if name is not None:
+            kb["name"] = name
+        await self._http.post(
+            "squid-api/v1/ai/knowledge-base/upsert", {"knowledgeBase": kb}
+        )
+
+    async def delete(self) -> None:
+        """Delete the knowledge base."""
+        await self._http.post(
+            "squid-api/v1/ai/knowledge-base/delete", {"id": self._kb_id}
+        )
+
+    # --- Contexts ---
+
+    async def get_context(self, context_id: str) -> Optional[dict]:
+        """Get a specific context."""
+        return await self._http.get(
+            f"squid-api/v1/ai/knowledge-base/getContext/{self._kb_id}/{context_id}"
+        )
+
+    async def list_contexts(self) -> list[dict]:
+        """List all contexts in the knowledge base."""
+        result = await self._http.get(
+            f"squid-api/v1/ai/knowledge-base/listContexts/{self._kb_id}"
+        )
+        return result.get("contexts", []) if result else []
+
+    async def upsert_contexts(
+        self,
+        contexts: list[ContextRequest],
+        files: Optional[list[tuple[str, bytes, str]]] = None,
+    ) -> dict:
+        """Add or update contexts.
+
+        Args:
+            contexts: List of TextContextRequest or FileContextRequest.
+            files: Optional list of (filename, data, content_type) tuples.
+
+        Returns:
+            dict with 'failures' list.
+        """
+        form_data = {
+            "knowledgeBaseId": self._kb_id,
+            "contexts": json.dumps(contexts),
+        }
+        file_tuples = []
+        if files:
+            for fname, fdata, ftype in files:
+                file_tuples.append(("files", (fname, fdata, ftype)))
+        return await self._http.post_form(
+            "squid-api/v1/ai/knowledge-base/upsertContexts",
+            data=form_data,
+            files=file_tuples,
+        )
+
+    async def delete_contexts(self, context_ids: list[str]) -> None:
+        """Delete contexts by IDs."""
+        await self._http.post(
+            "squid-api/v1/ai/knowledge-base/deleteContexts",
+            {"knowledgeBaseId": self._kb_id, "contextIds": context_ids},
+        )
+
+    # --- Search ---
+
+    async def search(
+        self,
+        prompt: str,
+        options: Optional[KnowledgeBaseSearchOptions] = None,
+    ) -> list[dict]:
+        """Search the knowledge base. Returns list of result chunks."""
+        search_options: dict[str, Any] = {"prompt": prompt, **(options or {})}
+        result = await self._http.post(
+            "squid-api/v1/ai/knowledge-base/search",
+            {
+                "knowledgeBaseId": self._kb_id,
+                "prompt": prompt,
+                "options": search_options,
+            },
+        )
+        return result.get("chunks", []) if result else []
+
+
+# ---------------------------------------------------------------------------
+# Image
+# ---------------------------------------------------------------------------
+
+
+class ImageClient:
+    """Image generation and processing."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    async def generate(
+        self,
+        prompt: str,
+        options: Optional[ImageGenerateOptions] = None,
+    ) -> str:
+        """Generate an image from a text prompt. Returns image URL."""
+        result = await self._http.post(
+            "squid-api/v1/ai/image/generate",
+            {"prompt": prompt, "options": options or {}},
+        )
+        return result if isinstance(result, str) else str(result)
+
+    async def remove_background(
+        self,
+        image_data: bytes,
+        filename: str = "image.png",
+        content_type: str = "image/png",
+    ) -> str:
+        """Remove background from an image. Returns result image URL."""
+        result = await self._http.post_form(
+            "squid-api/v1/ai/image/removeBackground",
+            data={},
+            files=[("file", (filename, image_data, content_type))],
+        )
+        return result if isinstance(result, str) else str(result)
+
+
+# ---------------------------------------------------------------------------
+# Audio
+# ---------------------------------------------------------------------------
+
+
+class AudioClient:
+    """Audio transcription and speech synthesis."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    async def transcribe(
+        self,
+        audio_data: bytes,
+        filename: str = "audio.wav",
+        content_type: str = "audio/wav",
+        *,
+        options: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """Transcribe audio to text."""
+        form_data: dict[str, str] = {}
+        if options:
+            form_data["optionsJson"] = json.dumps(options)
+        result = await self._http.post_form(
+            "squid-api/v1/ai/audio/transcribe",
+            data=form_data,
+            files=[("file", (filename, audio_data, content_type))],
+        )
+        return result if isinstance(result, str) else str(result)
+
+    async def create_speech(
+        self,
+        text: str,
+        options: AiAudioCreateSpeechOptions,
+    ) -> dict:
+        """Generate speech from text. Returns SquidFile dict with audio data."""
+        return await self._http.post(
+            "squid-api/v1/ai/audio/createSpeech",
+            {"input": text, "options": options},
+        )
+
+
+# ---------------------------------------------------------------------------
+# AI Query
+# ---------------------------------------------------------------------------
+
+
+async def execute_ai_query(
+    http: HttpTransport,
+    integration_id: str,
+    prompt: str,
+    *,
+    response_format: Optional[dict[str, Any]] = None,
+) -> dict:
+    """Execute an AI-powered database query. Returns AiQueryResponse."""
+    body: dict[str, Any] = {
+        "integrationId": integration_id,
+        "prompt": prompt,
+    }
+    if response_format is not None:
+        body["responseFormat"] = response_format
+    return await http.post("squid-api/v1/db/executeAiQuery", body)