@celigo/api-specs 0.2.19 → 0.2.21

package/dist/import.yml

@@ -8260,7 +8260,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)**
 
@@ -8268,7 +8268,7 @@ components:
         {
           "file": {
             "fileName": "customers-{{timestamp}}.json",
-            "skipAggregation": false,
+            "aggregation": { "type": "all" },
             "type": "json"
           },
           "s3": {
@@ -8310,18 +8310,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:
@@ -8427,7 +8431,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: |-
@@ -8533,21 +8545,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: |-
@@ -8798,14 +8834,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:
@@ -8815,18 +8859,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: |
@@ -8857,10 +9107,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.
@@ -9263,6 +9514,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
@@ -9917,6 +10175,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: |-
@@ -13765,7 +14039,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.