squidcloud

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

354class AiAgent(TypedDict, total=False):
355    """A definition of an AI agent with its properties and default chat options.
356
357    Returned by :meth:`AiClient.list_agents`.
358    """
359
360    id: str
361    """The unique identifier of the AI agent. Required."""
362    createdAt: str
363    """ISO 8601 timestamp of when the agent was created. Required."""
364    updatedAt: str
365    """ISO 8601 timestamp of when the agent was last updated. Required."""
366    description: str
367    """An optional description of the agent's purpose or capabilities."""
368    isPublic: bool
369    """Whether the agent is publicly accessible; defaults to False."""
370    auditLog: bool
371    """Whether audit logging is enabled for the agent's activities; defaults to False."""
372    options: AiChatOptions
373    """The agent's default chat options, overridable by the user during use. Required."""
374    apiKey: str
375    """Optional API key used specifically for operations on this agent."""

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

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

162class AiAudioCreateSpeechOptions(TypedDict, total=False):
163    """Options for text-to-speech."""
164
165    modelName: str
166    """'tts-1' or 'tts-1-hd'."""
167    voice: str
168    """'alloy'|'ash'|'ballad'|'coral'|'echo'|'fable'|'onyx'|'nova'|'sage'|'shimmer'|'verse'."""
169    responseFormat: str
170    """Audio output format."""
171    instructions: str
172    """Extra instructions for speech generation."""
173    speed: float
174    """Speech speed."""

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

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

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

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

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

106class AiConnectedKnowledgeBaseMetadata(TypedDict, total=False):
107    """Metadata for a connected knowledge base."""
108
109    knowledgeBaseId: str
110    description: str
111    includeMetadata: bool

450class AiContextFileOptions(TypedDict, total=False):
451    """Options for file context processing."""
452
453    chunkOverlap: int
454    ragType: str

430class AiContextTextOptions(TypedDict, total=False):
431    """Options for text context processing."""
432
433    chunkOverlap: int
434    """Amount of chunk overlap in characters."""
435    ragType: str
436    """The type of RAG to use."""

114class AiFileUrl(TypedDict, total=False):
115    """File URL to include in chat context."""
116
117    id: str
118    type: str
119    purpose: str
120    url: str
121    description: str
122    fileName: str

515class AiFunctionAttributes(TypedDict, total=False):
516    """Additional optional readonly metadata for an AI function."""
517
518    integrationType: list[str]
519    """Types of integration this function is used for. Functions with a defined
520    'integrationType' require 'integrationId' to be passed as part of the function context."""

523class AiFunctionMetadata(TypedDict, total=False):
524    """Metadata describing an AI function available in the application.
525
526    Returned by :meth:`AiClient.list_functions`.
527    """
528
529    serviceFunction: str
530    """The fully qualified name of the function ('ServiceName:functionName'). Required."""
531    description: str
532    """Description of what the function does."""
533    promptId: str
534    """Opaque ID of a registered prompt that supplies this function's description;
535    resolved server-side."""
536    params: list[AiFunctionParam]
537    """Parameters that the function accepts. Required."""
538    attributes: AiFunctionAttributes
539    """Additional attributes for the function."""
540    categories: list[str]
541    """Categories this function belongs to."""
542    internal: bool
543    """Whether this function is internal and not meant for direct use."""

500class AiFunctionParam(TypedDict, total=False):
501    """Defines the structure of a parameter for an AI function."""
502
503    name: str
504    """Name of the parameter. Required."""
505    description: str
506    """Description of the parameter's purpose. Required."""
507    type: AiFunctionParamType
508    """Data type of the parameter. Required."""
509    required: bool
510    """Indicates if the parameter is mandatory. Required."""
511    enum: list[str]
512    """List of possible values for the parameter, if applicable."""

405class AiKnowledgeBase(TypedDict, total=False):
406    """An AI knowledge base that can be attached to an AI agent.
407
408    Returned by :meth:`AiClient.list_knowledge_bases`.
409    """
410
411    id: str
412    """The unique identifier of the knowledge base. Required."""
413    appId: str
414    """The app ID that the knowledge base belongs to. Required."""
415    description: str
416    """The user's description of the knowledge base. Required."""
417    metadataFields: list[AiKnowledgeBaseMetadataField]
418    """Predefined metadata fields that can be used for filtering. Required."""
419    embeddingModel: AiEmbeddingsModelSelection
420    """The embedding model used by this knowledge base. Required."""
421    chatModel: AiChatModelSelection
422    """The model used when asking questions of this knowledge base. Required."""
423    vectorDbType: Literal["postgres", "mongoAtlas"]
424    """The vector store backend the knowledge base reads/writes from. Set at creation
425    and immutable thereafter. Absent on older records."""
426    updatedAt: str
427    """ISO 8601 timestamp of when the knowledge base was last updated. Required."""