squidcloud

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

426class AiAgent(TypedDict, total=False):
427    """A definition of an AI agent with its properties and default chat options.
428
429    Returned by :meth:`AiClient.list_agents`.
430    """
431
432    id: str
433    """The unique identifier of the AI agent. Required."""
434    createdAt: str
435    """ISO 8601 timestamp of when the agent was created. Required."""
436    updatedAt: str
437    """ISO 8601 timestamp of when the agent was last updated. Required."""
438    description: str
439    """An optional description of the agent's purpose or capabilities."""
440    isPublic: bool
441    """Whether the agent is publicly accessible; defaults to False."""
442    auditLog: bool
443    """Whether audit logging is enabled for the agent's activities; defaults to False."""
444    auditLogFullContext: bool
445    """Whether the full agent context (system instructions and retrieved knowledge-base content) is recorded in the audit log; requires auditLog; defaults to False."""
446    options: AiChatOptions
447    """The agent's default chat options, overridable by the user during use. Required."""
448    apiKey: str
449    """Optional API key used specifically for operations on this agent."""
450    mcpServer: AiAgentMcpServerConfig
451    """Optional configuration for exposing the agent as an MCP server."""

166class AiAgentExecutionPlanOptions(TypedDict, total=False):
167    """Options for AI agent execution plan."""
168
169    enabled: bool

392class AiAgentMcpServerConfig(TypedDict, total=False):
393    """Configuration for exposing an AI agent as an MCP server at ``/mcp/<agentId>``."""
394
395    enabled: bool
396    """Whether the agent is exposed as an MCP server. Required."""
397    description: str
398    """Description of the MCP server, served as the ``instructions`` field of the MCP initialize result."""
399    toolDescription: str
400    """Description of the MCP ``ask`` tool, exposed in the tools manifest."""
401    oauthIntegrationId: str
402    """ID of an auth integration used to OAuth-protect the MCP server."""
403    requireApiKey: bool
404    """Require the agent's API key as a bearer token; combinable with OAuth (either is accepted)."""

92class AiAgentMemoryOptions(TypedDict, total=False):
93    """Memory/session configuration for agent chat."""
94
95    memoryId: str
96    """Unique memory ID. Reuse to continue a conversation."""
97    memoryMode: AiMemoryMode
98    """How memory is used: 'read-write', 'read-only', 'write-only', 'disabled'."""

206class AiAudioCreateSpeechOptions(TypedDict, total=False):
207    """Options for text-to-speech."""
208
209    modelName: str
210    """'tts-1' or 'tts-1-hd'."""
211    voice: str
212    """'alloy'|'ash'|'ballad'|'coral'|'echo'|'fable'|'onyx'|'nova'|'sage'|'shimmer'|'verse'."""
213    responseFormat: str
214    """Audio output format."""
215    instructions: str
216    """Extra instructions for speech generation."""
217    speed: float
218    """Speech speed."""

221class AiChatOptions(TypedDict, total=False):
222    """Full chat options for AI agent ask/chat operations.
223
224    Mirrors BaseAiChatOptions from the TypeScript SDK.
225    All fields are optional.
226    """
227
228    model: AiChatModelSelection
229    """LLM model to use. String name or IntegrationModelSpec."""
230    maxTokens: int
231    """Max input tokens for the AI model."""
232    maxOutputTokens: int
233    """Max output tokens from the AI model."""
234    temperature: float
235    """Sampling temperature (default 0.5)."""
236    instructions: str
237    """Extra instructions to include with the prompt."""
238    functions: list[str]
239    """AI function IDs to expose to the agent."""
240    memoryOptions: AiAgentMemoryOptions
241    """Memory/session configuration."""
242    responseFormat: AiAgentResponseFormat
243    """Response format: 'text', 'json_object', or structured output."""
244    includeReference: bool
245    """Include source references from context."""
246    citation: bool
247    """Cite the sources behind the agent's statements."""
248    allowSourceDownloads: bool
249    """Allow citation links to the original files. Read from the stored agent only; ignored when passed with a request."""
250    smoothTyping: bool
251    """Smooth typing effect for UI display (default true)."""
252    disableContext: bool
253    """Disable the whole context for this request."""
254    enablePromptRewriteForRag: bool
255    """Rewrite prompt for RAG (default false)."""
256    agentContext: dict[str, Any]
257    """Global context passed to agent and all AI functions."""
258    connectedAgents: list[AiConnectedAgentMetadata]
259    """Connected agents that can be called."""
260    connectedIntegrations: list[AiConnectedIntegrationMetadata]
261    """Connected integrations."""
262    connectedKnowledgeBases: list[AiConnectedKnowledgeBaseMetadata]
263    """Connected knowledge bases."""
264    guardrails: GuardrailsOptions
265    """Guardrail options."""
266    pii: AiPiiOptions
267    """PII screening. Read from the stored agent only; ignored when passed with a request."""
268    contextMetadataFilterForKnowledgeBase: dict[str, Any]
269    """Metadata filters per knowledge base ID."""
270    voiceOptions: AiAudioCreateSpeechOptions
271    """Options for voice response."""
272    quotas: AiChatPromptQuotas
273    """Budget for nested AI calls."""
274    executionPlanOptions: AiAgentExecutionPlanOptions
275    """Execution plan options."""
276    fileUrls: list[AiFileUrl]
277    """File URLs to include in context."""
278    fileIds: list[str]
279    """File IDs from AI provider's Files API."""
280    reasoningEffort: AiReasoningEffort
281    """Reasoning effort level."""
282    verbosity: AiVerbosityLevel
283    """Response verbosity level."""
284    useCodeInterpreter: Literal["none", "llm"]
285    """Enable LLM's built-in code interpreter."""
286    rerankProvider: AiRerankProvider
287    """Reranker provider for context (default 'cohere')."""
288    rerankScoreThreshold: float
289    """Minimum reranker relevance score a chunk must reach to stay once at least 10 chunks are
290    already kept (default 0.2). Score ranges differ per reranker."""
291    includeMetadata: bool
292    """Include metadata in context (deprecated)."""
293    timeoutMs: int
294    """Request timeout in milliseconds (default 240000)."""

160class AiChatPromptQuotas(TypedDict, total=False):
161    """Budget for nested/recursive AI chat calls."""
162
163    maxNestedCalls: int

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