@celigo/api-specs 0.2.19 → 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: