Utilities - core-ai

Overview

core-ai exports helpers for schema conversion, portable tool names, assistant message construction, stream creation, model middleware wrapping, reasoning effort clamping, and provider-specific metadata access.

toJsonSchema()

Return the JSON Schema that core-ai sends for a schema. It applies the same conversion core-ai uses for tool parameters and structured output schemas.

import { z } from 'zod';
import { toJsonSchema } from '@core-ai/core-ai';

const weatherSchema = z.object({
    city: z.string(),
    temperatureC: z.number(),
});

const jsonSchema = toJsonSchema(weatherSchema);
console.log(JSON.stringify(jsonSchema));

function toJsonSchema(schema: SchemaInput): JsonSchema;

A Standard Schema is converted to the JSON Schema of its input type (draft 2020-12).
Plain JSON Schema is returned unchanged.
A schema that cannot be converted throws a ValidationError.

Use it when you store or measure schemas, for example to persist tool definitions or estimate token counts. You get the same JSON Schema core-ai hands to provider adapters, which apply only semantics-preserving provider transforms on top, such as the normalization for strict tool schemas. Each call returns a copy, so changing it does not affect what core-ai sends.

toPortableToolName()

Return a tool name every provider accepts, for tool names you do not control, such as MCP tool names.

import { toPortableToolName } from '@core-ai/core-ai';

toPortableToolName('search'); // 'search'
toPortableToolName('github.create_issue'); // 'github_create_issue'

function toPortableToolName(name: string): string;

A name of letters, digits, underscores, and dashes that starts with a letter or underscore and has at most 128 characters is returned unchanged.
Any other name has each other character replaced with _, gets a leading _ unless it starts with a letter or underscore, and is truncated to 128 characters. Characters are replaced per UTF-16 code unit without Unicode normalization, so 🙂 becomes __.

The result depends only on the name you pass, so it stays the same across requests and releases, which keeps conversation histories and the prompt cache valid. Different names can convert to the same one, such as a.b and a:b to a_b. Check that the converted names in your tool catalog stay unique, and rename a tool yourself where they don’t. The model calls the tool by the converted name, so keep a map from the converted name to the original one and translate tool calls back. Discovered tools must have such a name; see Tool snapshots.

clampReasoningEffort()

Clamp a requested reasoning effort to the nearest value in a model’s supported effort list.

import { clampReasoningEffort } from '@core-ai/core-ai';

const effort = clampReasoningEffort(
    'medium',
    model.capabilities.reasoning.supportedEfforts
);

Returns the original effort when the supported list is empty or already includes it. Use this with ChatModel.capabilities or a provider get*ModelCapabilities helper before calling generate / stream.

resultToMessage()

Convert a GenerateResult into an AssistantMessage so you can continue a conversation with the assistant’s full response parts.

import { generate, resultToMessage } from '@core-ai/core-ai';

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Solve this step by step.' }],
    reasoning: { effort: 'high' },
});

const assistantTurn = resultToMessage(result);

Options

type ResultToMessageOptions = {
    includeReasoning?: boolean;
};

Set includeReasoning: false if you want to drop reasoning parts when reusing the message.

assistantMessage()

Create a simple assistant message from plain text.

import { assistantMessage } from '@core-ai/core-ai';

const greeting = assistantMessage('Hello, how can I help?');

This is equivalent to constructing an assistant message with a single text part.

getProviderMetadata()

Read provider-specific metadata from reasoning parts in a type-safe way.

import { generate, getProviderMetadata } from '@core-ai/core-ai';
import type { OpenAIReasoningMetadata } from '@core-ai/openai';

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Think carefully before answering.' }],
    reasoning: { effort: 'high' },
});

for (const part of result.parts) {
    if (part.type !== 'reasoning') continue;

    const metadata = getProviderMetadata<OpenAIReasoningMetadata>(
        part.providerMetadata,
        'openai'
    );

    console.log(metadata?.encryptedContent);
}

The top-level key matches the provider name, such as 'anthropic', 'google', or 'openai'.

createChatStream()

Create a ChatStream from an async iterable of StreamEvents. This is useful when building custom providers or testing.

import { createChatStream } from '@core-ai/core-ai';
import type { StreamEvent } from '@core-ai/core-ai';

const events: StreamEvent[] = [
    { type: 'text-delta', text: 'Hello' },
    {
        type: 'finish',
        finishReason: 'stop',
        usage: {
            inputTokens: 5,
            outputTokens: 1,
            inputTokenDetails: { cacheReadTokens: 0, cacheWriteTokens: 0 },
            outputTokenDetails: {},
        },
    },
];

async function* generate() {
    for (const event of events) yield event;
}

const chatStream = createChatStream(generate());

The source parameter accepts an AsyncIterable<StreamEvent> or a () => Promise<AsyncIterable<StreamEvent>> factory function.

Options

type CreateChatStreamOptions = {
    signal?: AbortSignal;
    mapError?: (error: unknown) => CoreAIError;
    request?: Pick<GenerateOptions, 'toolDiscovery'>;
};

Pass signal to abort the stream. Pass mapError so in-band source failures become the same typed errors as a failed initial request. Already-typed core-ai errors pass through unchanged. Pass the request the stream answers so that, with toolDiscovery, calls to the discovery tool arrive as one tool-discovery-call event. A custom ChatModel that builds its GenerateResult itself passes it through finalizeGenerateResult(result, options) for the same treatment.

createObjectStream()

Create an ObjectStream from an async iterable of ObjectStreamEvents.

import { createObjectStream } from '@core-ai/core-ai';

const objectStream = createObjectStream(asyncIterable);

Like createChatStream, this accepts an optional { signal: AbortSignal } options object.

wrapChatModel()

Wrap a ChatModel with middleware to add cross-cutting behavior like logging, validation, or tracing.

import { wrapChatModel } from '@core-ai/core-ai';
import type { ChatModelMiddleware } from '@core-ai/core-ai';

const wrappedModel = wrapChatModel({
    model,
    middleware: myMiddleware, // single middleware or array
});

Returns a new ChatModel with the same interface. See the Middleware concept page for details on writing and composing middleware.

wrapEmbeddingModel()

Wrap an EmbeddingModel with middleware.

import { wrapEmbeddingModel } from '@core-ai/core-ai';

const wrappedModel = wrapEmbeddingModel({
    model: embeddingModel,
    middleware: myMiddleware,
});

wrapImageModel()

Wrap an ImageModel with middleware.

import { wrapImageModel } from '@core-ai/core-ai';

const wrappedModel = wrapImageModel({
    model: imageModel,
    middleware: myMiddleware,
});

stripModelDateSuffix()

Remove a trailing -YYYYMMDD date suffix from a model ID. This is used internally for model capability lookups.

import { stripModelDateSuffix } from '@core-ai/core-ai';

stripModelDateSuffix('gpt-5-mini-20250101'); // 'gpt-5-mini'
stripModelDateSuffix('gpt-5-mini'); // 'gpt-5-mini'

asObject()

Safely cast an unknown value to Record<string, unknown>. Returns an empty object if the input is not an object.

import { asObject } from '@core-ai/core-ai';

const obj = asObject(someValue);

safeParseJsonObject()

Safely parse a JSON string into an object. Returns undefined if parsing fails or the result is not an object.

import { safeParseJsonObject } from '@core-ai/core-ai';

const result = safeParseJsonObject('{"key": "value"}');
// { key: 'value' }

const invalid = safeParseJsonObject('not json');
// undefined

​Overview

​toJsonSchema()

​toPortableToolName()

​clampReasoningEffort()

​resultToMessage()

​Options

​assistantMessage()

​getProviderMetadata()

​createChatStream()

​Options

​createObjectStream()

​wrapChatModel()

​wrapEmbeddingModel()

​wrapImageModel()

​stripModelDateSuffix()

​asObject()

​safeParseJsonObject()

Overview

toJsonSchema()

toPortableToolName()

clampReasoningEffort()

resultToMessage()

Options

assistantMessage()

getProviderMetadata()

createChatStream()

Options

createObjectStream()

wrapChatModel()

wrapEmbeddingModel()

wrapImageModel()

stripModelDateSuffix()

asObject()

safeParseJsonObject()