@gitkraken/ai-provider-tools

AI text generation for GitKraken client SDKs: the GitKraken-hosted backend and BYOK providers (Anthropic, OpenAI, OpenRouter, Ollama) behind one model port.

Install

pnpm add @gitkraken/ai-provider-tools

Usage

import { createModel } from '@gitkraken/ai-provider-tools';
import { generateCommitMessage } from '@gitkraken/ai-provider-tools/generators';

const config = {
  provider: 'gitkraken' as const,
  getToken: async () => authStore.accessToken,
  organizationId: currentOrg.id,
};

const model = createModel(config);
const { text } = await model.generate({ messages: [{ role: 'user', content: 'hi' }] });

const { message, description } = await generateCommitMessage(config, diff);

runPromptCompletion(config, action, variables) (root export) runs any server-side prompt template by its task action name and returns { text, usage?, finishReason?, rawFinishReason?, model? }; the ./generators subpath wraps it for commit messages, pull requests, change explanations and changelogs, each result carrying the completion's usage when the provider reports it.

A BYOK provider looks the same, minus the GitKraken-only fields:

const model = createModel({ provider: 'anthropic', apiKey, model: 'claude-sonnet-4-5' });

Model port

createModel's result is a Model whose generate accepts either shared-tools' AiGenerateParams or a tool-aware superset of it (system/messages/tools/maxTokens/ temperature/signal), and is assignable to both @gitkraken/shared-tools' AiModelPort and @gitkraken/conflict-tools' ConflictModelPort — see ARCHITECTURE.md and src/model-port.type.test.ts.

generate resolves to { text, toolCalls?, usage?, finishReason?, rawFinishReason?, model? }. finishReason is provider-neutral (stop, length, tool-calls, content-filter, error, other), rawFinishReason is the provider's exact value, and model is the model id the response reports.

Errors

Every operation throws AiError on failure: { code, message, retryable, status?, providerErrorCode?, providerErrorType?, details? }. status is the HTTP status, and providerErrorCode/providerErrorType are the raw code/type of the provider's error body. code is one of credits_exhausted, not_logged_in, rate_limited, invalid_request, provider_error, truncated_output. User aborts are rethrown unchanged rather than wrapped. See ARCHITECTURE.md for the mapping.

What the host owns

getToken, fetch, request (an @gitkraken/api-tools ApiRequest), getCreditUsage, onCreditUsage, and telemetry are all injected. This package never reads process.env, writes through a StoragePort, or caches a model list — see ARCHITECTURE.md.