Open Kortyx on GitHub

Mistral Provider

Updated 19 days ago • May 3, 2026

@kortyx/mistral is the Mistral provider package for Kortyx.

It gives you two entry points:

  • mistral: a batteries-included default provider selector
  • createMistral(...): an explicit factory for custom setup

1. Install the package

pnpm add @kortyx/mistral

2. What the package exports

import { MODELS, PROVIDER_ID, createMistral, mistral, } from "@kortyx/mistral";

What each export is for:

  • mistral: default provider selector for the fastest start
  • createMistral(...): custom provider instance with explicit settings
  • MODELS: built-in Mistral model ids exposed by the package
  • PROVIDER_ID: the provider id string, currently "mistral"

3. Basic usage in the same file

import { mistral } from "@kortyx/mistral"; const model = mistral("mistral-large-latest");

mistral is a provider selector, which means:

  • it is callable: mistral("mistral-large-latest")
  • it also exposes provider metadata: mistral.id, mistral.models
mistral.id; // "mistral" mistral.models; // readonly list of built-in model ids

Good to know: The built-in model list gives autocomplete, but arbitrary Mistral model ids are accepted as strings.

4. Shared app bootstrap usage

If you want one shared import path across your app, re-export mistral from a bootstrap file such as src/lib/providers.ts.

src/lib/providers.ts
export { mistral } from "@kortyx/mistral";

Then import it from that file where you actually use it:

src/nodes/chat.node.ts
import { mistral } from "@/lib/providers";

5. Advanced usage with explicit settings

Use createMistral(...) when you want app-owned configuration instead of the default environment-based setup.

import { createMistral } from "@kortyx/mistral"; export const mistral = createMistral({ apiKey: process.env.MISTRAL_API_KEY, });

Use the factory when you need to:

  • pass apiKey explicitly
  • use a custom baseUrl
  • provide a custom fetch

6. Credentials and first-use behavior

The default mistral export resolves credentials on first use, not at import time.

Supported environment variables:

  • MISTRAL_API_KEY
  • KORTYX_MISTRAL_API_KEY

If neither variable is set and you did not pass apiKey to createMistral(...), the provider throws a configuration error the first time a Mistral model is actually used.

7. Create model refs for workflow and node params

params: { model: mistral("mistral-large-latest"), temperature: 0.3, }

You can also attach default model options to the ref itself:

const model = mistral("mistral-small-latest", { providerOptions: { mistral: { safePrompt: true, reasoningEffort: "high", }, }, });

Those become default options for later useReason(...) calls unless you override them at call time.

8. Use the model with useReason(...)

import { useReason } from "kortyx"; import { mistral } from "@/lib/providers"; const result = await useReason({ model: mistral("mistral-large-latest"), input: "Write a concise answer for a support engineer.", temperature: 0.3, emit: true, stream: true, }); result.text; result.usage; result.finishReason; result.providerMetadata; result.warnings;

Good to know: Provider setup is not done on createAgent(...). Model selection happens where you call useReason(...) by passing a model ref.

9. Supported normalized call options

Mistral currently maps these generic Kortyx options:

  • temperature
  • streaming
  • maxOutputTokens
  • abortSignal
  • reasoning.effort
  • reasoning.maxTokens
  • reasoning.includeThoughts
  • responseFormat.type
  • responseFormat.schema

Current Mistral provider options:

  • providerOptions.mistral.safePrompt
  • providerOptions.mistral.structuredOutputs
  • providerOptions.mistral.strictJsonSchema
  • providerOptions.mistral.reasoningEffort
  • providerOptions.mistral.topP
  • providerOptions.mistral.randomSeed

Current mapping details:

  • responseFormat.type: "json" maps to Mistral JSON mode
  • responseFormat.schema maps to Mistral JSON schema output unless structuredOutputs is false
  • safePrompt maps to Mistral safe_prompt
  • reasoningEffort maps only for mistral-small-latest and mistral-small-2603

Current warning-backed gaps:

  • stopSequences is currently reported as unsupported and not sent
  • reasoning options on unsupported models are reported in result.warnings
  • unknown providerOptions keys are ignored and reported in result.warnings

10. Normalized metadata you get back

Mistral returns the normalized Kortyx result fields when the API provides them:

  • usage
  • finishReason
  • providerMetadata
  • warnings
  • raw

Mistral-specific metadata currently includes fields such as:

  • providerId
  • modelId
  • responseId
  • responseModel
  • created
  • usage

Use providerMetadata when you need debugging or observability details without coupling your app code to the raw provider payload shape.

Supported scope

@kortyx/mistral currently supports text generation through Mistral chat completions via useReason(...), including streaming and non-streaming invocation.

It does not currently expose Mistral embeddings, OCR/document APIs, file APIs, or provider-hosted tools. Check result.warnings when you rely on advanced generic options and want to verify how Mistral handled them.

Available built-in Mistral model ids

  • ministral-3b-latest
  • ministral-8b-latest
  • ministral-14b-latest
  • mistral-large-latest
  • mistral-medium-latest
  • mistral-large-2512
  • mistral-medium-2508
  • mistral-medium-2505
  • mistral-small-2506
  • mistral-small-latest
  • mistral-small-2603
  • magistral-medium-latest
  • magistral-small-latest
  • magistral-medium-2509
  • magistral-small-2509
  • pixtral-large-latest

Next steps

  • See Hooks for useReason(...) behavior and structured output
  • See Provider API for the shared normalized provider contract