@celigo/api-specs 0.2.18 → 0.2.20

package/dist/tool.yml

@@ -4887,11 +4887,13 @@ components:
                 When true, rate-limit errors from the target system trigger automatic recovery: concurrency
                 drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes,
                 after which the flag switches itself off), and concurrency climbs back toward
-                `targetConcurrencyLevel`. While true, `concurrencyLevel` is platform-managed and writes to
-                it are ignored — `targetConcurrencyLevel` is the lever.
+                `targetConcurrencyLevel`. While true, `targetConcurrencyLevel` is the throughput lever: a
+                `concurrencyLevel` sent in a PUT is ignored, and one sent in a PATCH is stored but the
+                recovery machinery moves it back toward the target.
               x-celigo-ai-guidance:
-                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` write returns 200 and changes nothing.
-                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off copies the target back into `concurrencyLevel` and unsets the target.
+                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
+                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -6168,7 +6170,7 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
-            Platform-managed while `autoRecoverRateLimitErrors` is true — writes are ignored; set `targetConcurrencyLevel` instead.
+            Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
@@ -16602,7 +16604,7 @@ components:
         For most file imports, you need at minimum:
         - `fileName`: The output file name (supports Handlebars like `{{timestamp}}`)
         - `type`: The file format (json, csv, xml, xlsx)
-        - `skipAggregation`: Usually `false` for standard imports
+        - `aggregation.type`: How the run's records are batched into files (`all` for one file per run)
 
         **Example (S3 Import)**
 
@@ -16610,7 +16612,7 @@ components:
         {
           "file": {
             "fileName": "customers-{{timestamp}}.json",
-            "skipAggregation": false,
+            "aggregation": { "type": "all" },
             "type": "json"
           },
           "s3": {
@@ -16652,18 +16654,22 @@ components:
         skipAggregation:
           type: boolean
           description: |-
-            Controls whether records are aggregated into a single file or processed individually.
-
-            **Values**
-            - `false` (DEFAULT): Records are aggregated into a single output file
-            - `true`: Each record is written as a separate file
-
-            **When to use**
-            - **`false`**: Standard batch imports where all records go into one file
-            - **`true`**: When each record needs its own file (e.g., individual documents)
-
-            **Default:** `false`
+            Legacy companion of `aggregation.type`: `true` when the run's records are written one
+            file per page, `false` when they are combined across the run or grouped by key.
+            Validation reads the value sent — an EDI file definition needs `true` unless
+            `aggregation.type` is `key`, and `batchSize` needs `true` — then the save rewrites it
+            from `aggregation.type`, so send the two as a consistent pair.
           default: false
+          x-celigo-ai-guidance:
+            - |-
+              Send `skipAggregation` and `aggregation.type` as a consistent pair, exactly as the UI
+              does: `page` with `true`; `all` or `key` with `false`. Validation reads the SENT flag —
+              a `file.type: filedefinition` import saved with `page` and no `skipAggregation: true`
+              fails with 422 `not_supported` ("Aggregation is not supported for EDI files, please set
+              skipAggregation to true in Imports"), and `batchSize` fails with 422 `not_supported`
+              ("File imports do not support batching with aggregation") unless the sent flag is
+              `true`. The SAVED flag is then derived from `aggregation.type`, so this flag alone never
+              says which mode is active — read `aggregation.type`. It does not mean one file per record.
         type:
           type: string
           enum:
@@ -16769,7 +16775,15 @@ components:
             - When target system has file size limitations
 
             **Note**
-            - Only applicable when `skipAggregation` is `true`
+            - Offered when records are written one file per page (`aggregation.type: page` with
+              `skipAggregation: true`)
+          x-celigo-ai-guidance:
+            - |-
+              Probed for `all` and `page`: the save rejects `batchSize` with 422 `not_supported`
+              ("File imports do not support batching with aggregation") when the sent
+              `skipAggregation` is not `true`, and accepts it with `page` + `skipAggregation: true`.
+              The `key` + `batchSize` combination has not been probed (it needs a B2B Manager
+              account) — treat it as unverified, neither allowed nor forbidden.
         encrypt:
           type: boolean
           description: |-
@@ -16875,21 +16889,45 @@ components:
         aggregation:
           type: object
           description: |-
-            Controls how records are batched into output files. Newer imports use this object; the
-            legacy skipAggregation flag is the older equivalent.
+            Controls how a flow run's records are batched into output files — the transfer form's
+            "How many files would you like to generate?" setting. The legacy `skipAggregation` flag
+            mirrors `type` and is maintained by the platform.
           properties:
             type:
               type: string
               enum:
                 - all
                 - page
+                - key
               x-enumDescriptions:
-                all: Aggregate every record from the flow run into a single output file.
-                page: Write one output file per page of records.
-              description: Whether all records across the flow run go to one file, or one file is written per page.
+                all: One file per flow run — every record from the run (per export, or per request on real-time flows) in a single file
+                page: One file per page of records
+                key: One file per aggregation key — EDI file definitions only; records sharing the key derived from the file definition's document type are combined into one document
+              description: |-
+                Which batches of a run's records become separate output files. EDI file definitions
+                (`file.type: filedefinition`) are written per page or per key, never per run; `key`
+                is accepted only for them and only when the account has B2B Manager. The grouping
+                key and the line-item loop it merges come from the EDI file definition's document
+                type, so there is no separate key field to configure.
               examples:
                 - all
                 - page
+                - key
+              x-celigo-ai-guidance:
+                - |-
+                  Validated on save: an unknown value fails with 422 `enum`; `key` fails with 422
+                  `not_supported` unless `file.type` is `filedefinition` ("Aggregation type key is
+                  only supported for file type filedefinition") and the account has B2B Manager
+                  ("Aggregation type key is only supported for B2B Manager").
+                - |-
+                  For `file.type: filedefinition` send `page` (with `skipAggregation: true`) or `key`
+                  (with `false`); `all` is not an EDI option — the validator enforces this through the
+                  `skipAggregation` rule (see that field). For every other file type the choices are
+                  `all` and `page`. The UI offers exactly these splits.
+                - |-
+                  A user asking where the "aggregation key" is configured is asking about this
+                  field: the key itself is derived from the file definition's document type, never
+                  entered.
         lookups:
           type: array
           description: |-
@@ -17140,14 +17178,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:
-
-        - **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`.
-
-        A `_connectionId` is optional (BYOK). If not provided on the parent import,
-        platform-managed credentials are used.
+        tuning, output format, and available tools. Providers come in two families with
+        two configuration formats:
+
+        - **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` 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:
@@ -17157,18 +17203,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: |
@@ -17199,10 +17451,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.
@@ -17605,6 +17858,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
@@ -18259,6 +18519,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: |-
@@ -20028,7 +20304,7 @@ components:
             MongodbImport: MongoDB database import for document-based operations.
             DynamodbImport: Amazon DynamoDB import for NoSQL table operations.
             WrapperImport: Custom adaptor import built outside of Celigo (rarely used).
-            AiAgentImport: AI agent import using OpenAI, Gemini, or Anthropic Claude models for data processing.
+            AiAgentImport: AI agent import using OpenAI, Gemini, Anthropic Claude, or a BYOK catalog provider (Mistral, xAI, Hugging Face, DeepSeek, Cohere, Groq) for data processing.
             GuardrailImport: Safety and compliance check import for PII detection, moderation, or AI evaluation.
             FileSystemImport: Local or network file system import.
             ToolImport: Import that executes a reusable Celigo Tool resource.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [