squidcloud

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

474class AiAgent(TypedDict, total=False):
475    """A definition of an AI agent with its properties and default chat options.
476
477    Returned by :meth:`AiClient.list_agents`.
478    """
479
480    id: str
481    """The unique identifier of the AI agent. Required."""
482    createdAt: str
483    """ISO 8601 timestamp of when the agent was created. Required."""
484    updatedAt: str
485    """ISO 8601 timestamp of when the agent was last updated. Required."""
486    description: str
487    """An optional description of the agent's purpose or capabilities."""
488    isPublic: bool
489    """Whether the agent is publicly accessible; defaults to False."""
490    auditLog: bool
491    """Whether audit logging is enabled for the agent's activities; defaults to False."""
492    auditLogFullContext: bool
493    """Whether the full agent context (system instructions and retrieved knowledge-base content) is recorded in the audit log; requires auditLog; defaults to False."""
494    options: AiChatOptions
495    """The agent's default chat options, overridable by the user during use. Required."""
496    apiKey: str
497    """Optional API key used specifically for operations on this agent."""
498    mcpServer: AiAgentMcpServerConfig
499    """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

440class AiAgentMcpServerConfig(TypedDict, total=False):
441    """Configuration for exposing an AI agent as an MCP server at ``/mcp/<agentId>``."""
442
443    enabled: bool
444    """Whether the agent is exposed as an MCP server. Required."""
445    description: str
446    """Description of the MCP server, served as the ``instructions`` field of the MCP initialize result."""
447    toolDescription: str
448    """Description of the MCP ``ask`` tool, exposed in the tools manifest."""
449    oauthIntegrationId: str
450    """ID of an auth integration used to OAuth-protect the MCP server."""
451    requireApiKey: bool
452    """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'."""

334class AiAskOptions(_AiChatOptionsBase, total=False):
335    """Options of :meth:`AgentClient.ask` and :meth:`AgentClient.ask_with_annotations`.
336
337    The same fields as :class:`AiChatOptions`, except that ``model`` may also be an
338    :class:`AiModelRoutingOptions` routing choice.
339    """
340
341    model: AiAskModelSelection
342    """LLM model to use: a name, an IntegrationModelSpec, or an AiModelRoutingOptions."""

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."""

323class AiChatOptions(_AiChatOptionsBase, total=False):
324    """Full chat options for AI agent chat operations and agent profiles.
325
326    Mirrors BaseAiChatOptions from the TypeScript SDK.
327    All fields are optional.
328    """
329
330    model: AiChatModelSelection
331    """LLM model to use. String name or IntegrationModelSpec."""

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

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

101class AiConnectedAgentMetadata(TypedDict):
102    """Metadata for a connected agent."""
103
104    agentId: str
105    description: str

108class AiConnectedIntegrationMetadata(TypedDict, total=False):
109    """Metadata for a connected integration.
110
111    ``integrationId`` and ``integrationType`` are required by the platform API;
112    the remaining fields are optional.
113    """
114
115    integrationId: str
116    """The ID of the connected integration. Required."""
117    integrationType: str
118    """The integration type, e.g. 'hubspot', 'slack', 'api'. Required."""
119    description: str
120    """Optional description used as the AI function description for the parent agent."""
121    instructions: str
122    """Optional instructions for the connected integration agent, overriding the default."""
123    functionsToUse: list[str]
124    """AI function IDs the agent may use. Omit for all functions; [] for none."""
125    options: dict[str, Any]
126    """Additional integration options interpreted by Squid Core or connector AI functions."""
127    connectedAsMcp: bool
128    """Treat this integration as an MCP server (API integrations with exposeAsMcpServer)."""

131class AiConnectedKnowledgeBaseMetadata(TypedDict, total=False):
132    """Metadata for a connected knowledge base."""
133
134    knowledgeBaseId: str
135    description: str
136    includeMetadata: bool