@celigo/api-specs 0.2.18 → 0.2.20

package/dist/guardrail.yml

@@ -584,14 +584,22 @@ components:
         AI Agent configuration used by both AiAgentImport and GuardrailImport (ai_agent type).
 
         Configures which AI provider and model to use, along with instructions, parameter
-        tuning, output format, and available tools. Three providers are supported:
+        tuning, output format, and available tools. Providers come in two families with
+        two configuration formats:
 
-        - **openai**: OpenAI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.). Configure via the `openai` object.
-        - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
-        - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
+        - **Built-in providers** — each has its own configuration block.
+          - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
+          - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
+          - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
+        - **Catalog providers** — `mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`. Added
+          as catalog data rather than platform code, they share one generic flat format:
+          `model`, `modelOptions`, `instructions`, `output`, and the `tools` / `prompts` /
+          `resources` arrays directly on this object.
 
-        A `_connectionId` is optional (BYOK). If not provided on the parent import,
-        platform-managed credentials are used.
+        A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
+        credentials. Without one, built-in providers run on platform-managed
+        credentials; catalog providers have no platform-managed credentials, so they
+        save without a connection but cannot run until one is attached.
       required:
         - provider
       properties:
@@ -601,18 +609,224 @@ components:
             - openai
             - gemini
             - anthropic
+            - mistral
+            - xai
+            - huggingface
+            - deepseek
+            - cohere
+            - groq
           x-enumDescriptions:
-            openai: Use OpenAI models via the OpenAI Responses API.
-            gemini: Use Google Gemini models via the LiteLLM proxy.
-            anthropic: Use Anthropic Claude models via the LiteLLM proxy.
+            openai: Use OpenAI models via the OpenAI Responses API (built-in; `openai` block).
+            gemini: Use Google Gemini models via the LiteLLM proxy (built-in; `litellm` block).
+            anthropic: Use Anthropic Claude models via the LiteLLM proxy (built-in; `litellm` block).
+            mistral: Use Mistral models (catalog provider; generic flat format, BYOK).
+            xai: Use xAI Grok models (catalog provider; generic flat format, BYOK).
+            huggingface: Use Hugging Face inference endpoint models (catalog provider; generic flat format, BYOK).
+            deepseek: Use DeepSeek models (catalog provider; generic flat format, BYOK).
+            cohere: Use Cohere models (catalog provider; generic flat format, BYOK).
+            groq: Use Groq-hosted models (catalog provider; generic flat format, BYOK).
           description: AI provider to use.
           x-celigo-ai-guidance:
             - |-
-              - **openai**: Uses OpenAI Responses API. Configure via the `openai` object.
-              - **gemini**: Uses Google Gemini via LiteLLM. Configure via `litellm` with
-                Gemini-specific overrides in `litellm._overrides.gemini`.
-              - **anthropic**: Uses Anthropic Claude via LiteLLM. Configure via `litellm` with
-                Claude-specific overrides in `litellm._overrides.anthropic`.
+              The provider decides the configuration format, and the server rejects a
+              mismatch with 422 `invalid_provider_config_format`: `openai` needs the
+              `openai` block, `gemini` and `anthropic` need the `litellm` block (Gemini- or
+              Claude-specific settings under `litellm._overrides`), and the catalog
+              providers (`mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`) need the
+              generic flat format — `model` and `modelOptions` directly on this object,
+              never an `openai` or `litellm` block.
+            - |-
+              Catalog providers are BYOK-only at run time: the agent saves without a
+              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
+              key configured for provider …"). Always attach an HTTP connection to the
+              vendor's API (token auth) when the provider is a catalog provider.
+        model:
+          type: string
+          description: |-
+            Model identifier for a catalog provider (generic flat format) — for example
+            `grok-4.6`. Built-in providers set the model inside their own block
+            (`openai.model`, `litellm.model`) instead.
+          x-celigo-ai-guidance:
+            - |-
+              Required for every catalog provider — omitting it or sending an empty string
+              fails the save with 422 `missing_required_field`.
+            - |-
+              Without a `_connectionId` on the parent import the model must be one the
+              catalog lists for the provider: an unknown id fails the save with 422
+              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
+              `_connectionId` (BYOK) any model string saves — the server does not check it
+              against the catalog or the vendor.
+        modelOptions:
+          type: object
+          description: |-
+            Model tuning for a catalog provider (generic flat format). Which keys, values, and
+            ranges are accepted is defined per catalog model and validated on save when the
+            model is a catalog entry.
+          properties:
+            maxOutputTokens:
+              type: number
+              description: Maximum number of tokens the model may generate.
+            temperature:
+              type: number
+              description: Sampling temperature.
+            topP:
+              type: number
+              description: Nucleus sampling threshold.
+            reasoning_effort:
+              type: string
+              enum:
+                - low
+                - medium
+                - high
+                - xhigh
+              x-enumDescriptions:
+                low: Minimal reasoning before answering.
+                medium: Moderate reasoning.
+                high: Extensive reasoning.
+                xhigh: Maximum reasoning.
+              description: Reasoning depth for models that expose it.
+          x-celigo-ai-guidance:
+            - |-
+              When the model is a catalog entry, the server validates this object against
+              that model's schema and fails the save with 422 `invalid_model_options`
+              naming the key: unknown keys are rejected, `reasoning_effort` must be one of
+              the enum values where the model accepts it at all (xAI's `grok-4.6` does;
+              DeepSeek's `deepseek-chat` rejects the key), and numeric bounds apply —
+              on `grok-4.6`, `temperature` ≤ 2, `topP` ≤ 1, `maxOutputTokens` ≥ 100.
+            - |-
+              With a `_connectionId` and a model the catalog does not list, the object is
+              passed through unvalidated — send only options the vendor's API accepts.
+        instructions:
+          type: string
+          description: |-
+            System prompt for a catalog provider (generic flat format). Built-in providers
+            set it inside their own block (`openai.instructions`,
+            `litellm._overrides.anthropic.systemInstruction`).
+        output:
+          type: object
+          description: |-
+            Output format for a catalog provider (generic flat format). Built-in providers
+            configure it inside their own block (`openai.output`, `litellm.responseFormat`).
+          properties:
+            format:
+              type: object
+              description: Controls the structure of the model's output.
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - text
+                    - json_schema
+                  x-enumDescriptions:
+                    text: Free-form text.
+                    json_schema: Structured JSON conforming to `jsonSchema`.
+                  description: Output type.
+                  x-celigo-ai-guidance:
+                    - |-
+                      `blob` is not accepted here — the save fails with 422
+                      `unsupported_output_format` naming the model (verified on `grok-4.6`).
+                name:
+                  type: string
+                  description: Name of the JSON schema, for `json_schema` output.
+                strict:
+                  type: boolean
+                  description: When true, the model must conform exactly to `jsonSchema`.
+                jsonSchema:
+                  type: object
+                  additionalProperties: true
+                  description: JSON Schema the structured output must conform to, for `json_schema` output.
+            verbose:
+              type: string
+              description: Level of detail in the model's response, for models that expose it.
+        tools:
+          type: array
+          description: |-
+            Tools available to a catalog-provider agent (generic flat format). Entries mirror
+            the built-in providers' tool entries: a Celigo Tool by `_toolId`, an MCP server by
+            `_mcpConnectionId`, or a vendor web-search tool.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - tool
+                  - mcp
+                  - web_search
+                x-enumDescriptions:
+                  tool: Reference a reusable Celigo Tool resource.
+                  mcp: Connect to an MCP server for additional external tools.
+                  web_search: Search the web for real-time information, where the vendor's model supports it.
+                description: Type of tool entry.
+              tool:
+                type: object
+                description: Reference to a Celigo Tool resource, used when type is "tool".
+                properties:
+                  _toolId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: tools
+                    description: The Celigo Tool to call.
+              mcp:
+                type: object
+                description: MCP server connection, used when type is "mcp".
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server.
+                  allowedTools:
+                    type: array
+                    description: |-
+                      Specific tools to allow from the MCP server (all if omitted). Each entry
+                      is either a plain tool name or an object carrying display metadata.
+                    items:
+                      type:
+                        - string
+                        - object
+              config:
+                type: object
+                additionalProperties: true
+                description: Tool-specific options for vendor-native tools (for example web-search settings).
+          x-celigo-ai-guidance:
+            - |-
+              References are checked on save: an unknown `_toolId` or `_mcpConnectionId`
+              fails with 422 `invalid_ref` naming the array index.
+        prompts:
+          type: array
+          description: |-
+            MCP prompt entries available to a catalog-provider agent (generic flat format).
+            Each entry references one MCP connection and the prompt names allowed from it.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - mcp
+                x-enumDescriptions:
+                  mcp: Reference prompts exposed by an MCP server.
+                description: Type of prompt entry. Always "mcp".
+              mcp:
+                type: object
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server that exposes the prompts.
+                  allowedPrompts:
+                    type: array
+                    description: Prompt names the agent may fetch from the server.
+                    items:
+                      type: string
+          x-celigo-ai-guidance:
+            - |-
+              An unknown `_mcpConnectionId` fails the save with 422 `invalid_ref` naming
+              the array index.
+        resources:
+          $ref: '#/components/schemas/McpResources'
         openai:
           type: object
           description: |
@@ -643,10 +857,11 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   With platform-managed credentials (no `_connectionId` on the parent
-                  import), the model must be on the platform's allowlist — an
-                  unlisted model fails the save with 422. A BYOK connection bypasses
-                  the allowlist and the model string is passed through to the
-                  provider as-is.
+                  import), the model must be one the platform hosts. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models. A
+                  BYOK connection bypasses the hosted list and the model string is
+                  passed through to the provider as-is.
             reasoning:
               type: object
               description: Controls depth of reasoning for complex tasks.
@@ -1049,6 +1264,13 @@ components:
                 - claude-sonnet-4-6
                 - claude-opus-4-7
               x-celigo-ui-override: Required by the AI agent configuration form. Encoded here to mirror the form so builders produce connectable configurations.
+              x-celigo-ai-guidance:
+                - |-
+                  With platform-managed credentials (no `_connectionId` on the parent
+                  import), the model must be one the platform hosts for the provider —
+                  Gemini and Anthropic Claude both have a hosted list. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models.
             temperature:
               type: number
               minimum: 0
@@ -1703,6 +1925,22 @@ components:
             litellm:
               required:
                 - model
+        else:
+          if:
+            properties:
+              provider:
+                enum:
+                  - mistral
+                  - xai
+                  - huggingface
+                  - deepseek
+                  - cohere
+                  - groq
+            required:
+              - provider
+          then:
+            required:
+              - model
     GuardrailConfig:
       type: object
       description: |-
@@ -2355,7 +2593,7 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: BYOK connection backing an `ai_agent` guardrail. Absent when platform-managed credentials are used.
+              description: BYOK connection backing an `ai_agent` guardrail. Absent when a built-in provider runs on platform-managed credentials.
               examples:
                 - 68ae48d6b5f755d2dd38c294
             _sourceId:
@@ -2489,7 +2727,12 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: connections
-          description: Connection for BYOK (bring your own key). Only needed for `ai_agent` type guardrails. Optional — platform-managed credentials are used when omitted.
+          description: |-
+            Connection for BYOK (bring your own key) — only meaningful for `ai_agent` type
+            guardrails. Optional for the built-in providers (`openai`, `gemini`, `anthropic`),
+            which run on platform-managed credentials when it is omitted; catalog providers
+            (`mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`) have no platform-managed
+            credentials and need it to run.
           examples:
             - 68ae48d6b5f755d2dd38c294
         adaptorType:

package/dist/iclient.yml

@@ -1744,73 +1744,36 @@ components:
               items:
                 type: string
               description: |-
-                Domain names used to validate OAuth URLs. Provide each
-                unique domain once (no scheme, no path).
+                Registrable domains (`domain.com`, `domain.co.uk` — the host with its
+                subdomains removed) of the OAuth URLs this client's credentials are
+                sent to: the access token, authorization, and revoke URLs. Before an
+                OAuth request leaves integrator.io, the target URL's registrable
+                domain must appear here; a full hostname never matches.
               examples:
                 - - domain.com
                 - - domain.com
                   - domain1.com
                   - domain2.com
+                - - microsoftonline.com
+                  - microsoft.com
               x-celigo-ai-guidance:
                 - |-
-                  Set this to the list of unique domain names used to validate the OAuth URLs (Authorization,
-                  Access Token, Revoke Token).
-                  In the UI, enter each unique domain name as comma-separated values;
-                  if the same domain is used for each URL, provide it only once.
-                  For multiple domains, set this to `["domain.com", "domain1.com",
-                  "domain2.com"]`; if all URLs share the same domain (e.g.
-                  `domain.com`), set this to `["domain.com"]`.
-                - |-
-                  Example: if your URLs are:
-                  - `https://<AccessTokenURL>.domain.com`
-                  - `https://<RevokeTokenURL>.domain1.com`
-                  - `https://<AuthorizationURL>.domain2.com`
-
-                  then set `validDomainNames` to: `["domain.com", "domain1.com", "domain2.com"]`.
-                - |-
-                  ## TECHNICAL DETAILS:
-                  - Stored as an array of strings.
-                - |-
-                  ## FIELD BEHAVIOR:
-                  - Array of domain names (no scheme, no path).
-                  - Used to validate the OAuth URL domains (authorization/token/revoke).
-                  - Provide each unique domain once.
-                - |-
-                  ## DEPENDENCY CHAIN:
-                  - Used alongside `oauth2.auth.uri`, `oauth2.token.uri`, and `oauth2.revoke.uri`.
-                - |-
-                  ## IMPLEMENTATION GUIDANCE:
-                  - Extract the domain portion from each OAuth URL and include it here.
-                  - Do not include `https://` or any URL path/query—only the domain.
-                  - Keep this list in sync if any OAuth URLs change.
-                - |-
-                  ## EXAMPLES:
-                  - ["domain.com"]
-                  - ["domain.com", "domain1.com", "domain2.com"]
-                - |-
-                  ## IMPORTANT NOTES:
-                  - This is about **domains** for OAuth URLs, not full URLs.
-                - |-
-                  Example: if your URLs are:
-                  - `https://<AccessTokenURL>.domain.com`
-                  - `https://<RevokeTokenURL>.domain1.com`
-                  - `https://<AuthorizationURL>.domain2.com`
-                - |-
-                  Set this to the list of unique domain names used to validate the OAuth URLs (Authorization,
-                  Access Token, Revoke Token).
-                  In the UI, enter each unique domain name as comma-separated values;
-                  if the same domain is used for each URL, provide it only once.
-                  For multiple domains, set this to `["domain.com", "domain1.com",
-                  "domain2.com"]`; if all URLs share the same domain (e.g.
-                  `domain.com`), set this to `["domain.com"]`.
-                - |-
-                  Set this to the list of unique domain names used to validate the OAuth URLs (Authorization,
-                  Access Token, Revoke Token).
-                  In the UI, enter each unique domain name as comma-separated values;
-                  if the same domain is used for each URL, provide it only once.
-                  For multiple domains, set this to `["domain.com", "domain1.com",
-                  "domain2.com"]`; if all URLs share the same domain (e.g.
-                  `domain.com`), set this to `["domain.com"]`.
+                  Store the registrable domain, never the hostname. For the token URL
+                  `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` the entry is
+                  `microsoftonline.com`; `login.microsoftonline.com` fails the connection test with
+                  `[invalid_domain] The domain of request url should be present in
+                  iClient.oauth2.validDomainNames` and no request is sent. Public suffixes are
+                  honoured: `auth.example.co.uk` → `example.co.uk`, not `co.uk`.
+                - |-
+                  List the registrable domain of every OAuth URL on the client (token, authorization,
+                  revoke) once each — a missing token-URL domain is what blocks the connection.
+                  Celigo's connector setup guides also list the API host's registrable domain next to
+                  them (Microsoft: `microsoftonline.com`, `microsoft.com`); include it to match the
+                  guides — an extra entry is harmless.
+                - |-
+                  When a connection using this client reports `[invalid_domain]`, the fix is this
+                  field — replace hostnames with registrable domains. The connection's base URI and
+                  ping path are where the request goes, not where the allow-list lives.
             failPath:
               type: string
               description: |-