@clinebot/core 0.0.35 → 0.0.37

package/src/llms/provider-settings.ts

@@ -0,0 +1,310 @@
+import * as Llms from "@clinebot/llms";
+import { z } from "zod";
+import {
+	DEFAULT_EXTERNAL_OCA_BASE_URL,
+	DEFAULT_INTERNAL_OCA_BASE_URL,
+} from "../auth/oca";
+import {
+	OPENAI_COMPATIBLE_PROVIDERS,
+	type ProviderDefaults,
+} from "./provider-defaults";
+
+export type ModelInfo = Llms.ModelInfo;
+export type ProviderClient = Llms.ProviderClient;
+export type ProviderProtocol = Llms.ProviderProtocol;
+export type ProviderId = Llms.ProviderId;
+export type ProviderCapability = Llms.ProviderCapability;
+export type ProviderConfig = Llms.ProviderConfig;
+export type BuiltInProviderId = Llms.BuiltInProviderId;
+
+export const BUILT_IN_PROVIDER = Llms.BUILT_IN_PROVIDER;
+export const BUILT_IN_PROVIDER_IDS = Llms.BUILT_IN_PROVIDER_IDS;
+export const isBuiltInProviderId = Llms.isBuiltInProviderId;
+export const normalizeProviderId = Llms.normalizeProviderId;
+
+export type ProviderDefaultsConfig = ProviderDefaults;
+
+export const ProviderIdSchema = z
+	.string()
+	.min(1)
+	.regex(/^[a-z0-9][a-z0-9-]*$/i);
+
+export const ProviderProtocolSchema = z.enum([
+	"anthropic",
+	"gemini",
+	"openai-chat",
+	"openai-responses",
+	"openai-r1",
+	"ai-sdk",
+]);
+
+export const ProviderClientSchema = z.enum([
+	"anthropic",
+	"ai-sdk",
+	"ai-sdk-community",
+	"openai",
+	"openai-compatible",
+	"openai-r1",
+	"gemini",
+	"bedrock",
+	"custom",
+	"fetch",
+	"vertex",
+]);
+
+export const AuthSettingsSchema = z.object({
+	apiKey: z.string().optional(),
+	accessToken: z.string().optional(),
+	refreshToken: z.string().optional(),
+	expiresAt: z.number().int().positive().optional(),
+	accountId: z.string().optional(),
+});
+
+export type AuthSettings = z.infer<typeof AuthSettingsSchema>;
+
+const ReasoningLevelSchema = z.enum(["none", "low", "medium", "high", "xhigh"]);
+
+export const ReasoningSettingsSchema = z.object({
+	enabled: z.boolean().optional(),
+	effort: ReasoningLevelSchema.optional(),
+	budgetTokens: z.number().int().positive().optional(),
+});
+
+export type ReasoningSettings = z.infer<typeof ReasoningSettingsSchema>;
+
+export const AwsSettingsSchema = z.object({
+	accessKey: z.string().optional(),
+	secretKey: z.string().optional(),
+	sessionToken: z.string().optional(),
+	region: z.string().optional(),
+	profile: z.string().optional(),
+	authentication: z.enum(["iam", "api-key", "profile"]).optional(),
+	usePromptCache: z.boolean().optional(),
+	useCrossRegionInference: z.boolean().optional(),
+	useGlobalInference: z.boolean().optional(),
+	endpoint: z.string().url().optional(),
+	customModelBaseId: z.string().optional(),
+});
+
+export type AwsSettings = z.infer<typeof AwsSettingsSchema>;
+
+export const GcpSettingsSchema = z.object({
+	projectId: z.string().optional(),
+	region: z.string().optional(),
+});
+
+export type GcpSettings = z.infer<typeof GcpSettingsSchema>;
+
+export const AzureSettingsSchema = z.object({
+	apiVersion: z.string().optional(),
+	useIdentity: z.boolean().optional(),
+});
+
+export type AzureSettings = z.infer<typeof AzureSettingsSchema>;
+
+export const SapSettingsSchema = z.object({
+	clientId: z.string().optional(),
+	clientSecret: z.string().optional(),
+	tokenUrl: z.string().url().optional(),
+	resourceGroup: z.string().optional(),
+	deploymentId: z.string().optional(),
+	useOrchestrationMode: z.boolean().optional(),
+	api: z.enum(["orchestration", "foundation-models"]).optional(),
+	defaultSettings: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type SapSettings = z.infer<typeof SapSettingsSchema>;
+
+export const OcaSettingsSchema = z.object({
+	mode: z.enum(["internal", "external"]).optional(),
+	usePromptCache: z.boolean().optional(),
+});
+
+export type OcaSettings = z.infer<typeof OcaSettingsSchema>;
+
+export const ModelCatalogSettingsSchema = z.object({
+	loadLatestOnInit: z.boolean().optional(),
+	loadPrivateOnAuth: z.boolean().optional(),
+	url: z.string().url().optional(),
+	cacheTtlMs: z.number().int().positive().optional(),
+	failOnError: z.boolean().optional(),
+});
+
+export type ModelCatalogSettings = z.infer<typeof ModelCatalogSettingsSchema>;
+export type ModelCatalogConfig = ModelCatalogSettings;
+
+export const ProviderSettingsSchema = z.object({
+	provider: ProviderIdSchema,
+	apiKey: z.string().optional(),
+	auth: AuthSettingsSchema.optional(),
+	model: z.string().optional(),
+	protocol: ProviderProtocolSchema.optional(),
+	client: ProviderClientSchema.optional(),
+	routingProviderId: ProviderIdSchema.optional(),
+	maxTokens: z.number().int().positive().optional(),
+	contextWindow: z.number().int().positive().optional(),
+	baseUrl: z.string().url().optional(),
+	headers: z.record(z.string(), z.string()).optional(),
+	timeout: z.number().int().positive().optional(),
+	reasoning: ReasoningSettingsSchema.optional(),
+	aws: AwsSettingsSchema.optional(),
+	gcp: GcpSettingsSchema.optional(),
+	azure: AzureSettingsSchema.optional(),
+	sap: SapSettingsSchema.optional(),
+	oca: OcaSettingsSchema.optional(),
+	region: z.string().optional(),
+	apiLine: z.enum(["china", "international"]).optional(),
+	capabilities: z
+		.array(
+			z.enum([
+				"reasoning",
+				"prompt-cache",
+				"streaming",
+				"tools",
+				"vision",
+				"computer-use",
+				"oauth",
+			]),
+		)
+		.optional(),
+	modelCatalog: ModelCatalogSettingsSchema.optional(),
+});
+
+export type ProviderSettings = z.infer<typeof ProviderSettingsSchema>;
+
+export function parseSettings(input: unknown): ProviderSettings {
+	return ProviderSettingsSchema.parse(input);
+}
+
+export function safeParseSettings(
+	input: unknown,
+): ReturnType<typeof ProviderSettingsSchema.safeParse> {
+	return ProviderSettingsSchema.safeParse(input);
+}
+
+function shouldRouteThroughOpenAIResponses(
+	settings: ProviderSettings,
+): boolean {
+	return (
+		settings.protocol === "openai-responses" || settings.client === "openai"
+	);
+}
+
+export function toProviderConfig(settings: ProviderSettings): ProviderConfig {
+	const providerId = settings.provider as ProviderId;
+	const normalizedProviderId = normalizeProviderId(providerId);
+	const unifiedReasoningLevel = settings.reasoning?.effort || "none";
+	const reasoningEffort =
+		unifiedReasoningLevel === "none" ? undefined : unifiedReasoningLevel;
+
+	const providerDefaults = OPENAI_COMPATIBLE_PROVIDERS[normalizedProviderId];
+	const generatedKnownModels = Object.assign(
+		{},
+		...Llms.resolveProviderModelCatalogKeys(normalizedProviderId).map(
+			(catalogKey) => Llms.getGeneratedModelsForProvider(catalogKey),
+		),
+	);
+	const generatedDefaultModelId = Object.keys(generatedKnownModels)[0];
+
+	const apiKey =
+		settings.auth?.accessToken ?? settings.apiKey ?? settings.auth?.apiKey;
+	const resolvedBaseUrl =
+		settings.baseUrl ??
+		(normalizedProviderId === "oca"
+			? settings.oca?.mode === "internal"
+				? DEFAULT_INTERNAL_OCA_BASE_URL
+				: DEFAULT_EXTERNAL_OCA_BASE_URL
+			: providerDefaults?.baseUrl);
+	const routingProviderId =
+		settings.routingProviderId ??
+		(shouldRouteThroughOpenAIResponses(settings) &&
+		normalizedProviderId !== BUILT_IN_PROVIDER.OPENAI_NATIVE
+			? BUILT_IN_PROVIDER.OPENAI_NATIVE
+			: undefined);
+
+	const config: ProviderConfig = {
+		providerId,
+		clientType: settings.client,
+		routingProviderId,
+		modelId:
+			settings.model ??
+			providerDefaults?.modelId ??
+			generatedDefaultModelId ??
+			"default",
+		knownModels:
+			providerDefaults?.knownModels ??
+			(Object.keys(generatedKnownModels).length > 0
+				? generatedKnownModels
+				: undefined),
+		apiKey,
+		accessToken: settings.auth?.accessToken,
+		refreshToken: settings.auth?.refreshToken,
+		accountId: settings.auth?.accountId,
+		baseUrl: resolvedBaseUrl,
+		headers: settings.headers,
+		timeoutMs: settings.timeout,
+		maxOutputTokens: settings.maxTokens,
+		maxContextTokens: settings.contextWindow,
+		thinking: settings.reasoning?.enabled,
+		reasoningEffort,
+		thinkingBudgetTokens: settings.reasoning?.budgetTokens,
+		region: settings.region ?? settings.aws?.region ?? settings.gcp?.region,
+		apiLine: settings.apiLine,
+		useCrossRegionInference: settings.aws?.useCrossRegionInference,
+		useGlobalInference: settings.aws?.useGlobalInference,
+		aws: settings.aws
+			? {
+					accessKey: settings.aws.accessKey,
+					secretKey: settings.aws.secretKey,
+					sessionToken: settings.aws.sessionToken,
+					authentication: settings.aws.authentication,
+					profile: settings.aws.profile,
+					usePromptCache: settings.aws.usePromptCache,
+					endpoint: settings.aws.endpoint,
+					customModelBaseId: settings.aws.customModelBaseId,
+				}
+			: undefined,
+		gcp: settings.gcp
+			? {
+					projectId: settings.gcp.projectId,
+					region: settings.gcp.region,
+				}
+			: undefined,
+		azure: settings.azure,
+		sap: settings.sap,
+		oca: settings.oca,
+		capabilities: (settings.capabilities ?? providerDefaults?.capabilities) as
+			| ProviderCapability[]
+			| undefined,
+		modelCatalog: settings.modelCatalog
+			? {
+					loadLatestOnInit: settings.modelCatalog.loadLatestOnInit,
+					loadPrivateOnAuth: settings.modelCatalog.loadPrivateOnAuth,
+					url: settings.modelCatalog.url,
+					cacheTtlMs: settings.modelCatalog.cacheTtlMs,
+					failOnError: settings.modelCatalog.failOnError,
+				}
+			: undefined,
+	};
+
+	return Object.fromEntries(
+		Object.entries(config).filter(([_, value]) => value !== undefined),
+	) as ProviderConfig;
+}
+
+export function createProviderConfig(input: unknown): ProviderConfig {
+	const settings = parseSettings(input);
+	return toProviderConfig(settings);
+}
+
+export function safeCreateProviderConfig(
+	input: unknown,
+):
+	| { success: true; config: ProviderConfig }
+	| { success: false; error: z.ZodError } {
+	const result = safeParseSettings(input);
+	if (result.success) {
+		return { success: true, config: toProviderConfig(result.data) };
+	}
+	return { success: false, error: result.error };
+}

package/src/llms/runtime-config.ts

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { LlmsConfig } from "./runtime-types";
+
+export function defineLlmsConfig(config: LlmsConfig): LlmsConfig {
+	return config;
+}
+
+export async function loadLlmsConfigFromFile(
+	configPath: string,
+): Promise<LlmsConfig> {
+	const resolvedPath = path.resolve(configPath);
+	const raw = await readFile(resolvedPath, "utf8");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const details = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`Failed to parse JSON config at "${resolvedPath}": ${details}`,
+		);
+	}
+	return assertLlmsConfig(parsed, resolvedPath);
+}
+
+function assertLlmsConfig(value: unknown, source: string): LlmsConfig {
+	if (!value || typeof value !== "object") {
+		throw new Error(`Invalid llms config in "${source}": expected an object.`);
+	}
+	const config = value as Record<string, unknown>;
+	const providers = config.providers;
+	if (!Array.isArray(providers)) {
+		throw new Error(
+			`Invalid llms config in "${source}": "providers" must be an array.`,
+		);
+	}
+	if (!providers.length) {
+		throw new Error(
+			`Invalid llms config in "${source}": "providers" cannot be empty.`,
+		);
+	}
+	return value as LlmsConfig;
+}

package/src/llms/runtime-registry.ts

@@ -0,0 +1,172 @@
+import type { ApiHandler } from "@clinebot/llms";
+import {
+	BUILT_IN_PROVIDER_IDS,
+	createHandler as createProviderHandler,
+	createHandlerAsync as createProviderHandlerAsync,
+	getProviderCollection,
+	hasProvider,
+	registerAsyncHandler,
+	registerHandler,
+	registerModel as registerModelInCatalog,
+	registerProvider as registerProviderInCatalog,
+} from "@clinebot/llms";
+import {
+	ConfiguredProviderRegistry,
+	toBuiltInProviderSummary,
+} from "./configured-provider-registry";
+import type {
+	BuiltInProviderSummary,
+	CreateHandlerInput,
+	LlmsConfig,
+	LlmsSdk,
+	RegisterBuiltinProviderInput,
+	RegisteredProviderSummary,
+	RegisterModelInput,
+	RegisterProviderInput,
+} from "./runtime-types";
+
+export class DefaultLlmsSdk implements LlmsSdk {
+	private readonly configuredProviders = new ConfiguredProviderRegistry();
+
+	constructor(config: LlmsConfig) {
+		this.applyConfig(config);
+	}
+
+	createHandler(input: CreateHandlerInput): ApiHandler {
+		return createProviderHandler(
+			this.configuredProviders.createHandlerConfig(input),
+		);
+	}
+
+	async createHandlerAsync(input: CreateHandlerInput): Promise<ApiHandler> {
+		return createProviderHandlerAsync(
+			this.configuredProviders.createHandlerConfig(input),
+		);
+	}
+
+	registerProvider(input: RegisterProviderInput): void {
+		registerProviderInCatalog(input.collection);
+		if (input.handlerFactory && input.asyncHandlerFactory) {
+			throw new Error(
+				`Provider "${input.collection.provider.id}" cannot register both sync and async handlers.`,
+			);
+		}
+		if (input.handlerFactory) {
+			registerHandler(input.collection.provider.id, input.handlerFactory);
+		}
+		if (input.asyncHandlerFactory) {
+			registerAsyncHandler(
+				input.collection.provider.id,
+				input.asyncHandlerFactory,
+			);
+		}
+		this.configuredProviders.register({
+			id: input.collection.provider.id,
+			models: input.exposeModels ?? Object.keys(input.collection.models),
+			defaultModel:
+				input.defaultModel ?? input.collection.provider.defaultModelId,
+			defaults: input.defaults,
+		});
+	}
+
+	registerBuiltinProvider(input: RegisterBuiltinProviderInput): void {
+		const exposedModels = input.exposeModels ?? Object.keys(input.models);
+		const defaultModel = input.defaultModel ?? exposedModels[0];
+		if (!defaultModel) {
+			throw new Error(`Provider "${input.id}" must define a default model.`);
+		}
+		registerProviderInCatalog({
+			provider: {
+				id: input.id,
+				name: input.name ?? input.id,
+				description: input.description,
+				protocol: input.protocol,
+				baseUrl: input.baseUrl,
+				defaultModelId: defaultModel,
+				client: input.client ?? "openai-compatible",
+				capabilities: input.capabilities,
+				env: input.env,
+				source: "system",
+			},
+			models: input.models,
+		});
+		this.configuredProviders.register({
+			id: input.id,
+			models: exposedModels,
+			defaultModel,
+			defaults: {
+				routingProviderId: input.builtinProviderId,
+				...(input.defaults ?? {}),
+			},
+		});
+	}
+
+	registerModel(input: RegisterModelInput): void {
+		registerModelInCatalog(input.providerId, input.modelId, input.info);
+		this.configuredProviders.registerModel(input.providerId, input.modelId);
+	}
+
+	getProviders(): RegisteredProviderSummary[] {
+		return this.configuredProviders.list();
+	}
+
+	getBuiltInProviderIds() {
+		return [...BUILT_IN_PROVIDER_IDS];
+	}
+
+	async getBuiltInProviders(): Promise<BuiltInProviderSummary[]> {
+		const collections = await Promise.all(
+			BUILT_IN_PROVIDER_IDS.map((providerId: string) =>
+				getProviderCollection(providerId),
+			),
+		);
+		return collections
+			.filter(
+				(collection): collection is NonNullable<typeof collection> =>
+					collection !== undefined,
+			)
+			.map((collection) => toBuiltInProviderSummary({ collection }));
+	}
+
+	getModels(providerId: string): string[] {
+		return this.configuredProviders.getModels(providerId);
+	}
+
+	isProviderConfigured(providerId: string): boolean {
+		return this.configuredProviders.hasProvider(providerId);
+	}
+
+	isModelConfigured(providerId: string, modelId: string): boolean {
+		return this.configuredProviders.hasModel(providerId, modelId);
+	}
+
+	private applyConfig(config: LlmsConfig): void {
+		for (const provider of config.providers) {
+			this.configuredProviders.registerSelectionConfig(provider);
+		}
+		for (const model of config.models ?? []) {
+			this.registerModel(model);
+		}
+		for (const provider of config.customProviders ?? []) {
+			this.registerProvider(provider);
+		}
+		for (const provider of this.configuredProviders.list()) {
+			const providerExists = hasProvider(provider.id);
+			const routedProviderId = this.configuredProviders.createHandlerConfig({
+				providerId: provider.id,
+				modelId: provider.defaultModel,
+			}).routingProviderId;
+			const routedProviderExists =
+				typeof routedProviderId === "string" && hasProvider(routedProviderId);
+			if (!providerExists && !routedProviderExists) {
+				throw new Error(
+					`Provider "${provider.id}" is not known. Register it through customProviders/registerProvider, registerBuiltinProvider, or use a built-in provider ID.`,
+				);
+			}
+		}
+	}
+}
+
+export function createLlmsSdk(config: LlmsConfig): LlmsSdk {
+	return new DefaultLlmsSdk(config);
+}

package/src/llms/runtime-types.ts

@@ -0,0 +1,121 @@
+import type {
+	ApiHandler,
+	BuiltInProviderId,
+	HandlerFactory,
+	LazyHandlerFactory,
+	ModelCollection,
+	ModelInfo,
+	CatalogProviderCapability as ModelProviderCapability,
+	ProviderClient,
+	ProviderConfig,
+	ProviderInfo,
+	ProviderProtocol,
+} from "@clinebot/llms";
+import type { ProviderCapability } from "./provider-settings";
+
+export type ProviderConfigDefaults = Omit<
+	ProviderConfig,
+	"providerId" | "modelId"
+>;
+
+export interface ProviderSelectionConfig {
+	id: string;
+	models: string[];
+	defaultModel?: string;
+	builtinProviderId?: BuiltInProviderId;
+	apiKey?: string;
+	apiKeyEnv?: string;
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	capabilities?: ProviderCapability[];
+	settings?: ProviderConfigDefaults;
+}
+
+export interface AdditionalModelConfig {
+	providerId: string;
+	modelId: string;
+	info: ModelInfo;
+}
+
+export interface CustomProviderConfig {
+	collection: ModelCollection;
+	defaults?: ProviderConfigDefaults;
+	handlerFactory?: HandlerFactory;
+	asyncHandlerFactory?: LazyHandlerFactory;
+}
+
+export interface LlmsConfig {
+	providers: ProviderSelectionConfig[];
+	models?: AdditionalModelConfig[];
+	customProviders?: CustomProviderConfig[];
+}
+
+export interface CreateHandlerInput {
+	providerId: string;
+	modelId?: string;
+	overrides?: ProviderConfigDefaults;
+}
+
+export interface RegisteredProviderSummary {
+	id: string;
+	models: string[];
+	defaultModel: string;
+}
+
+export interface BuiltInProviderSummary
+	extends Pick<
+		ProviderInfo,
+		| "id"
+		| "name"
+		| "description"
+		| "protocol"
+		| "baseUrl"
+		| "capabilities"
+		| "env"
+	> {
+	models: string[];
+	defaultModel: string;
+	modelCount: number;
+}
+
+export interface RegisterBuiltinProviderInput {
+	id: string;
+	builtinProviderId: BuiltInProviderId;
+	models: Record<string, ModelInfo>;
+	name?: string;
+	description?: string;
+	protocol?: ProviderProtocol;
+	baseUrl?: string;
+	client?: ProviderClient;
+	capabilities?: ModelProviderCapability[];
+	env?: string[];
+	defaultModel?: string;
+	defaults?: ProviderConfigDefaults;
+	exposeModels?: string[];
+}
+
+export interface RegisterProviderInput extends CustomProviderConfig {
+	exposeModels?: string[];
+	defaultModel?: string;
+}
+
+export interface RegisterModelInput {
+	providerId: string;
+	modelId: string;
+	info: ModelInfo;
+}
+
+export interface LlmsSdk {
+	createHandler(input: CreateHandlerInput): ApiHandler;
+	createHandlerAsync(input: CreateHandlerInput): Promise<ApiHandler>;
+	registerProvider(input: RegisterProviderInput): void;
+	registerBuiltinProvider(input: RegisterBuiltinProviderInput): void;
+	registerModel(input: RegisterModelInput): void;
+	getProviders(): RegisteredProviderSummary[];
+	getBuiltInProviderIds(): BuiltInProviderId[];
+	getBuiltInProviders(): Promise<BuiltInProviderSummary[]>;
+	getModels(providerId: string): string[];
+	isProviderConfigured(providerId: string): boolean;
+	isModelConfigured(providerId: string, modelId: string): boolean;
+}