squidcloud

146class AgentClient:
147    """Operations on a single AI agent.
148
149    Provides methods for chatting with an agent, managing its configuration,
150    updating guardrails, and working with revisions.
151
152    Obtained via :meth:`AiClient.agent`.
153
154    Example::
155
156        agent = squid.ai().agent("my-agent")
157        response = await agent.ask("What is the weather?", options={"temperature": 0.7})
158        await agent.update_instructions("Always respond in haiku format.")
159    """
160
161    def __init__(self, http: HttpTransport, agent_id: str) -> None:
162        self._http = http
163        self._agent_id = agent_id
164
165    # --- Chat ---
166
167    async def ask(
168        self,
169        prompt: str,
170        options: AiChatOptions | None = None,
171    ) -> str:
172        """Ask the agent a question and get a text response.
173
174        Args:
175            prompt: The user's question or instruction.
176            options: Chat options controlling model, temperature, memory,
177                functions, guardrails, and more. See :class:`AiChatOptions`.
178
179        Returns:
180            The agent's response as a string.
181
182        Raises:
183            SquidHttpError: If the agent is not found or the request fails.
184
185        Example::
186
187            response = await agent.ask(
188                "Summarize this document",
189                options={
190                    "model": "gemini-3-flash",
191                    "temperature": 0.3,
192                    "memoryOptions": {"memoryId": "session-1", "memoryMode": "read-write"},
193                },
194            )
195        """
196        result = await self._http.post(
197            "squid-api/v1/ai/agent/ask",
198            {"agentId": self._agent_id, "prompt": prompt, "options": options or {}},
199        )
200        return result.get("responseString", "") if result else ""
201
202    async def ask_with_annotations(
203        self,
204        prompt: str,
205        options: AiChatOptions | None = None,
206    ) -> dict:
207        """Ask the agent and get a response with annotations.
208
209        Annotations include file references, citations, and other metadata
210        the agent may attach to its response.
211
212        Args:
213            prompt: The user's question or instruction.
214            options: Chat options. See :class:`AiChatOptions`.
215
216        Returns:
217            A dict with:
218                - ``responseString`` (str): The text response.
219                - ``annotations`` (dict): Annotation metadata keyed by ID.
220
221        Example::
222
223            result = await agent.ask_with_annotations("Find relevant docs")
224            print(result["responseString"])
225            for ann_id, ann in result.get("annotations", {}).items():
226                print(f"  Annotation: {ann}")
227        """
228        return await self._http.post(
229            "squid-api/v1/ai/agent/askWithAnnotations",
230            {"agentId": self._agent_id, "prompt": prompt, "options": options or {}},
231        )
232
233    # --- Management ---
234
235    async def get(self) -> dict | None:
236        """Get the agent's configuration.
237
238        Returns:
239            An ``AiAgent`` dict with keys: ``id``, ``createdAt``, ``updatedAt``,
240            ``description``, ``isPublic``, ``auditLog``, ``auditLogFullContext``,
241            ``options``, ``apiKey``.
242            Returns ``None`` if the agent does not exist.
243        """
244        return await self._http.get(f"squid-api/v1/ai/agent/get/{self._agent_id}")
245
246    async def upsert(
247        self,
248        *,
249        description: str | None = None,
250        is_public: bool | None = None,
251        audit_log: bool | None = None,
252        audit_log_full_context: bool | None = None,
253        api_key: str | None = None,
254        mcp_server: AiAgentMcpServerConfig | None = None,
255        options: AiChatOptions | None = None,
256    ) -> None:
257        """Create or update the agent.
258
259        If the agent does not exist, it is created. If it exists, the provided
260        fields are updated (fields set to ``None`` are left unchanged).
261
262        Args:
263            description: A description of the agent's purpose or capabilities.
264            is_public: Whether the agent is publicly accessible (default ``False``).
265            audit_log: Enable audit logging for the agent's activities.
266            audit_log_full_context: Record the full agent context (system
267                instructions and retrieved knowledge-base content) in the audit
268                log; requires ``audit_log``.
269            api_key: Optional API key used specifically for this agent.
270            mcp_server: Configuration for exposing the agent as an MCP server
271                at ``/mcp/<agentId>``. See :class:`AiAgentMcpServerConfig`.
272            options: Default chat options applied to every request unless
273                overridden per-call. See :class:`AiChatOptions`.
274
275        Example::
276
277            await agent.upsert(
278                description="Customer support agent",
279                options={"model": "gemini-3-flash", "temperature": 0.5},
280            )
281        """
282        body: dict[str, Any] = {"id": self._agent_id}
283        if description is not None:
284            body["description"] = description
285        if is_public is not None:
286            body["isPublic"] = is_public
287        if audit_log is not None:
288            body["auditLog"] = audit_log
289        if audit_log_full_context is not None:
290            body["auditLogFullContext"] = audit_log_full_context
291        if api_key is not None:
292            body["apiKey"] = api_key
293        if mcp_server is not None:
294            body["mcpServer"] = mcp_server
295        if options is not None:
296            body["options"] = options
297        await self._http.post("squid-api/v1/ai/agent/upsert", body)
298
299    async def delete(self) -> None:
300        """Delete the agent permanently."""
301        await self._http.post("squid-api/v1/ai/agent/delete", {"agentId": self._agent_id})
302
303    async def update_instructions(self, instructions: str) -> None:
304        """Update the agent's system instructions.
305
306        Args:
307            instructions: The new system prompt / instructions text.
308        """
309        await self._http.post(
310            "squid-api/v1/ai/agent/updateInstructions",
311            {"agentId": self._agent_id, "instructions": instructions},
312        )
313
314    async def update_model(self, model: AiChatModelSelection) -> None:
315        """Update the agent's default LLM model.
316
317        Args:
318            model: A model name string (e.g., ``'gemini-3-flash'``) or an
319                ``IntegrationModelSpec`` dict (``{'integrationId': str, 'model': str}``).
320        """
321        await self._http.post(
322            "squid-api/v1/ai/agent/updateModel",
323            {"agentId": self._agent_id, "model": model},
324        )
325
326    async def update_connected_agents(
327        self, connected_agents: list[AiConnectedAgentMetadata]
328    ) -> None:
329        """Update the list of connected agents.
330
331        Connected agents can be called by this agent during conversations.
332
333        Args:
334            connected_agents: List of ``{'agentId': str, 'description': str}`` dicts.
335        """
336        await self._http.post(
337            "squid-api/v1/ai/agent/updateConnectedAgents",
338            {"agentId": self._agent_id, "connectedAgents": connected_agents},
339        )
340
341    async def update_guardrails(self, guardrails: GuardrailsOptions) -> None:
342        """Update the agent's guardrail settings.
343
344        Args:
345            guardrails: A :class:`GuardrailsOptions` dict with optional keys:
346                ``custom``, ``disablePii``, ``professionalTone``,
347                ``offTopicAnswers``, ``disableProfanity``.
348
349        Example::
350
351            await agent.update_guardrails(
352                {
353                    "professionalTone": True,
354                    "disableProfanity": True,
355                }
356            )
357        """
358        await self._http.post(
359            "squid-api/v1/ai/agent/updateGuardrails",
360            {"agentId": self._agent_id, "guardrails": guardrails},
361        )
362
363    async def update_custom_guardrails(self, custom_guardrail: str) -> None:
364        """Update the custom guardrail instruction text.
365
366        Args:
367            custom_guardrail: Free-form guardrail instruction string.
368        """
369        await self._http.post(
370            "squid-api/v1/ai/agent/updateCustomGuardrails",
371            {"agentId": self._agent_id, "customGuardrail": custom_guardrail},
372        )
373
374    async def delete_custom_guardrails(self) -> None:
375        """Delete the custom guardrail, reverting to defaults."""
376        await self._http.post(
377            "squid-api/v1/ai/agent/deleteCustomGuardrails",
378            {"agentId": self._agent_id},
379        )
380
381    async def update_pii(self, pii: AiPiiOptions) -> None:
382        """Update the agent's PII screening, merging with its existing settings.
383
384        With ``onDetect`` set to ``"reject"`` the agent refuses any prompt carrying
385        PII before it reaches the model, so the prompt is never answered and never
386        stored. This is the inverse of ``GuardrailsOptions.disablePii``, which asks
387        the agent's own model not to emit PII in its answer.
388
389        Args:
390            pii: An :class:`AiPiiOptions` dict with optional keys: ``onDetect``,
391                ``entities``, ``customRules``, ``classifierModel``, ``allowList``.
392
393        Example::
394
395            await agent.update_pii(
396                {
397                    "onDetect": "reject",
398                    "customRules": ["internal case numbers like CASE-12345"],
399                }
400            )
401        """
402        agent = await self.get()
403        existing = (agent or {}).get("options", {}).get("pii", {})
404        merged = {"onDetect": "off", **existing, **pii}
405        await self._http.post(
406            "squid-api/v1/ai/agent/setAgentOptionInPath",
407            {"agentId": self._agent_id, "path": "pii", "value": merged},
408        )
409
410    # --- Revisions ---
411
412    async def list_revisions(self) -> list[dict]:
413        """List all revisions of this agent.
414
415        Returns:
416            A list of ``AiAgentRevision`` dicts, each containing:
417            ``agentId``, ``revisionNumber``, ``action``, ``createdAt``,
418            ``agentSnapshot``.
419        """
420        result = await self._http.get(f"squid-api/v1/ai/agent/revisions/{self._agent_id}")
421        return result.get("revisions", []) if result else []
422
423    async def restore_revision(self, revision_number: int) -> None:
424        """Restore the agent to a previous revision.
425
426        Args:
427            revision_number: The revision number to restore.
428        """
429        await self._http.post(
430            "squid-api/v1/ai/agent/restoreRevision",
431            {"agentId": self._agent_id, "revisionNumber": revision_number},
432        )
433
434    async def delete_revision(self, revision_number: int) -> None:
435        """Delete a specific revision.
436
437        Args:
438            revision_number: The revision number to delete.
439        """
440        await self._http.post(
441            "squid-api/v1/ai/agent/deleteRevision",
442            {"agentId": self._agent_id, "revisionNumber": revision_number},
443        )

395class AiAgent(TypedDict, total=False):
396    """A definition of an AI agent with its properties and default chat options.
397
398    Returned by :meth:`AiClient.list_agents`.
399    """
400
401    id: str
402    """The unique identifier of the AI agent. Required."""
403    createdAt: str
404    """ISO 8601 timestamp of when the agent was created. Required."""
405    updatedAt: str
406    """ISO 8601 timestamp of when the agent was last updated. Required."""
407    description: str
408    """An optional description of the agent's purpose or capabilities."""
409    isPublic: bool
410    """Whether the agent is publicly accessible; defaults to False."""
411    auditLog: bool
412    """Whether audit logging is enabled for the agent's activities; defaults to False."""
413    auditLogFullContext: bool
414    """Whether the full agent context (system instructions and retrieved knowledge-base content) is recorded in the audit log; requires auditLog; defaults to False."""
415    options: AiChatOptions
416    """The agent's default chat options, overridable by the user during use. Required."""
417    apiKey: str
418    """Optional API key used specifically for operations on this agent."""
419    mcpServer: AiAgentMcpServerConfig
420    """Optional configuration for exposing the agent as an MCP server."""

142class AiAgentExecutionPlanOptions(TypedDict, total=False):
143    """Options for AI agent execution plan."""
144
145    enabled: bool

361class AiAgentMcpServerConfig(TypedDict, total=False):
362    """Configuration for exposing an AI agent as an MCP server at ``/mcp/<agentId>``."""
363
364    enabled: bool
365    """Whether the agent is exposed as an MCP server. Required."""
366    description: str
367    """Description of the MCP server, served as the ``instructions`` field of the MCP initialize result."""
368    toolDescription: str
369    """Description of the MCP ``ask`` tool, exposed in the tools manifest."""
370    oauthIntegrationId: str
371    """ID of an auth integration used to OAuth-protect the MCP server."""
372    requireApiKey: bool
373    """Require the agent's API key as a bearer token; combinable with OAuth (either is accepted)."""

68class AiAgentMemoryOptions(TypedDict, total=False):
69    """Memory/session configuration for agent chat."""
70
71    memoryId: str
72    """Unique memory ID. Reuse to continue a conversation."""
73    memoryMode: AiMemoryMode
74    """How memory is used: 'read-write', 'read-only', 'write-only', 'disabled'."""

182class AiAudioCreateSpeechOptions(TypedDict, total=False):
183    """Options for text-to-speech."""
184
185    modelName: str
186    """'tts-1' or 'tts-1-hd'."""
187    voice: str
188    """'alloy'|'ash'|'ballad'|'coral'|'echo'|'fable'|'onyx'|'nova'|'sage'|'shimmer'|'verse'."""
189    responseFormat: str
190    """Audio output format."""
191    instructions: str
192    """Extra instructions for speech generation."""
193    speed: float
194    """Speech speed."""

197class AiChatOptions(TypedDict, total=False):
198    """Full chat options for AI agent ask/chat operations.
199
200    Mirrors BaseAiChatOptions from the TypeScript SDK.
201    All fields are optional.
202    """
203
204    model: AiChatModelSelection
205    """LLM model to use. String name or IntegrationModelSpec."""
206    maxTokens: int
207    """Max input tokens for the AI model."""
208    maxOutputTokens: int
209    """Max output tokens from the AI model."""
210    temperature: float
211    """Sampling temperature (default 0.5)."""
212    instructions: str
213    """Extra instructions to include with the prompt."""
214    functions: list[str]
215    """AI function IDs to expose to the agent."""
216    memoryOptions: AiAgentMemoryOptions
217    """Memory/session configuration."""
218    responseFormat: AiAgentResponseFormat
219    """Response format: 'text', 'json_object', or structured output."""
220    includeReference: bool
221    """Include source references from context."""
222    smoothTyping: bool
223    """Smooth typing effect for UI display (default true)."""
224    disableContext: bool
225    """Disable the whole context for this request."""
226    enablePromptRewriteForRag: bool
227    """Rewrite prompt for RAG (default false)."""
228    agentContext: dict[str, Any]
229    """Global context passed to agent and all AI functions."""
230    connectedAgents: list[AiConnectedAgentMetadata]
231    """Connected agents that can be called."""
232    connectedIntegrations: list[AiConnectedIntegrationMetadata]
233    """Connected integrations."""
234    connectedKnowledgeBases: list[AiConnectedKnowledgeBaseMetadata]
235    """Connected knowledge bases."""
236    guardrails: GuardrailsOptions
237    """Guardrail options."""
238    pii: AiPiiOptions
239    """PII screening. Read from the stored agent only; ignored when passed with a request."""
240    contextMetadataFilterForKnowledgeBase: dict[str, Any]
241    """Metadata filters per knowledge base ID."""
242    voiceOptions: AiAudioCreateSpeechOptions
243    """Options for voice response."""
244    quotas: AiChatPromptQuotas
245    """Budget for nested AI calls."""
246    executionPlanOptions: AiAgentExecutionPlanOptions
247    """Execution plan options."""
248    fileUrls: list[AiFileUrl]
249    """File URLs to include in context."""
250    fileIds: list[str]
251    """File IDs from AI provider's Files API."""
252    reasoningEffort: AiReasoningEffort
253    """Reasoning effort level."""
254    verbosity: AiVerbosityLevel
255    """Response verbosity level."""
256    useCodeInterpreter: Literal["none", "llm"]
257    """Enable LLM's built-in code interpreter."""
258    rerankProvider: AiRerankProvider
259    """Reranker provider for context (default 'cohere')."""
260    includeMetadata: bool
261    """Include metadata in context (deprecated)."""
262    timeoutMs: int
263    """Request timeout in milliseconds (default 240000)."""

136class AiChatPromptQuotas(TypedDict, total=False):
137    """Budget for nested/recursive AI chat calls."""
138
139    maxNestedCalls: int

 37class AiClient:
 38    """Entry point for AI operations: agents, knowledge base, audio, image.
 39
 40    Obtained via :meth:`Squid.ai()`.
 41
 42    Example::
 43
 44        ai = squid.ai()
 45        agent = ai.agent("my-agent")
 46        kb = ai.knowledge_base("my-kb")
 47        image_url = await ai.image().generate("a cat in space")
 48    """
 49
 50    def __init__(self, http: HttpTransport) -> None:
 51        self._http = http
 52
 53    def agent(self, agent_id: str) -> AgentClient:
 54        """Get a client for a specific AI agent.
 55
 56        Args:
 57            agent_id: The unique agent identifier.
 58
 59        Returns:
 60            An :class:`AgentClient` bound to the given agent ID.
 61        """
 62        return AgentClient(self._http, agent_id)
 63
 64    def knowledge_base(self, knowledge_base_id: str) -> KnowledgeBaseClient:
 65        """Get a client for a specific knowledge base.
 66
 67        Args:
 68            knowledge_base_id: The unique knowledge base identifier.
 69
 70        Returns:
 71            A :class:`KnowledgeBaseClient` bound to the given knowledge base ID.
 72        """
 73        return KnowledgeBaseClient(self._http, knowledge_base_id)
 74
 75    def image(self) -> ImageClient:
 76        """Get a client for image generation and processing.
 77
 78        Returns:
 79            An :class:`ImageClient` instance.
 80        """
 81        return ImageClient(self._http)
 82
 83    def audio(self) -> AudioClient:
 84        """Get a client for audio transcription and speech synthesis.
 85
 86        Returns:
 87            An :class:`AudioClient` instance.
 88        """
 89        return AudioClient(self._http)
 90
 91    async def list_agents(self) -> list[AiAgent]:
 92        """List all AI agents defined for the application.
 93
 94        Returns:
 95            A list of ``AiAgent`` dicts. Empty list if no agents are defined.
 96        """
 97        result = await self._http.get("squid-api/v1/ai/agent/listAgents")
 98        return result.get("agents", []) if result else []
 99
100    async def list_knowledge_bases(self) -> list[AiKnowledgeBase]:
101        """List all AI knowledge bases defined for the application.
102
103        Returns:
104            A list of ``AiKnowledgeBase`` dicts. Empty list if no knowledge
105            bases are defined.
106        """
107        result = await self._http.get("squid-api/v1/ai/knowledge-base/listKnowledgeBases")
108        return result.get("knowledgeBases", []) if result else []
109
110    async def list_chat_models(self, include_deprecated: bool = False) -> list[ModelIdSpec]:
111        """List all AI chat models available to the application.
112
113        Includes both Squid-provided vendor models and any custom integration
114        models configured for the app.
115
116        Args:
117            include_deprecated: When True, deprecated vendor models are
118                included and marked with ``replacedBy``. Defaults to False.
119
120        Returns:
121            A list of ``ModelIdSpec`` dicts, each with ``modelId``, an optional
122            ``integrationId``, and a human-readable ``displayName``. Vendor
123            models also carry a ``description``, and deprecated vendor models a
124            ``replacedBy`` with the active model their calls are routed to.
125        """
126        params = {"includeDeprecated": "true"} if include_deprecated else None
127        result = await self._http.get("squid-api/v1/ai/settings/listChatModels", params=params)
128        return result.get("models", []) if result else []
129
130    async def list_functions(self) -> list[AiFunctionMetadata]:
131        """List all AI functions registered for the application's deployed bundle.
132
133        Returns:
134            A list of ``AiFunctionMetadata`` dicts. Empty list if no functions
135            are registered.
136        """
137        result = await self._http.get("squid-api/v1/ai/function/listFunctions")
138        return result.get("functions", []) if result else []

77class AiConnectedAgentMetadata(TypedDict):
78    """Metadata for a connected agent."""
79
80    agentId: str
81    description: str

 84class AiConnectedIntegrationMetadata(TypedDict, total=False):
 85    """Metadata for a connected integration.
 86
 87    ``integrationId`` and ``integrationType`` are required by the platform API;
 88    the remaining fields are optional.
 89    """
 90
 91    integrationId: str
 92    """The ID of the connected integration. Required."""
 93    integrationType: str
 94    """The integration type, e.g. 'hubspot', 'slack', 'api'. Required."""
 95    description: str
 96    """Optional description used as the AI function description for the parent agent."""
 97    instructions: str
 98    """Optional instructions for the connected integration agent, overriding the default."""
 99    functionsToUse: list[str]
100    """AI function IDs the agent may use. Omit for all functions; [] for none."""
101    options: dict[str, Any]
102    """Additional integration options interpreted by Squid Core or connector AI functions."""
103    connectedAsMcp: bool
104    """Treat this integration as an MCP server (API integrations with exposeAsMcpServer)."""