The minimalistic document archiving platform.
refactor(ai): require explicit adapter id in model (#1300)
Corentin Thomasset756dfe728dd5
diff --git a/apps/papra-server/src/modules/ai/adapters/ai-adapters.constants.ts b/apps/papra-server/src/modules/ai/adapters/ai-adapters.constants.tsindex 461eb10b..5c666e5a 100644--- a/apps/papra-server/src/modules/ai/adapters/ai-adapters.constants.ts+++ b/apps/papra-server/src/modules/ai/adapters/ai-adapters.constants.ts@@ -3,5 +3,3 @@ import { OPENAI_COMPATIBLE_ADAPTERS } from './openai-compatible/openai-compatiblexport const AI_ADAPTERS_NAMES = [...objectKeys(OPENAI_COMPATIBLE_ADAPTERS), 'anthropic'] as const;export type AiAdapterName = (typeof AI_ADAPTERS_NAMES)[number];--export const AI_DEFAULT_ADAPTER_NAME = 'openai' satisfies AiAdapterName;diff --git a/apps/papra-server/src/modules/ai/adapters/ai-adapters.usecases.ts b/apps/papra-server/src/modules/ai/adapters/ai-adapters.usecases.tsindex 6746dc1b..1aaaf1c2 100644--- a/apps/papra-server/src/modules/ai/adapters/ai-adapters.usecases.ts+++ b/apps/papra-server/src/modules/ai/adapters/ai-adapters.usecases.ts@@ -1,5 +1,5 @@import type { Config } from '../../config/config.types';-import { parseModelId } from '../ai.schemas.models';+import { parseModelId } from '../ai.models';import { modelAdapterFactories } from './ai-adapters.registry';import type { ModelAdapterNames } from './ai-adapters.registry';import { createError } from '../../shared/errors/errors';@@ -9,17 +9,15 @@ export function resolveAdapter({adapterId,config,}: {- adapterId?: string;+ adapterId: string;config: Config;}): AiAdapter {- const adapterName = adapterId ?? config.ai.defaultAdapterName;-- const adapterFactory = modelAdapterFactories[adapterName as ModelAdapterNames];+ const adapterFactory = modelAdapterFactories[adapterId as ModelAdapterNames];if (!adapterFactory) {throw createError({code: 'ai.adapterNotFound',- message: `No adapter found for adapter name "${adapterName}"`,+ message: `No adapter found for adapter name "${adapterId}"`,statusCode: 500,isInternal: true,});diff --git a/apps/papra-server/src/modules/ai/ai.config.ts b/apps/papra-server/src/modules/ai/ai.config.tsindex e4236987..8e8fe328 100644--- a/apps/papra-server/src/modules/ai/ai.config.ts+++ b/apps/papra-server/src/modules/ai/ai.config.ts@@ -3,7 +3,6 @@ import { booleanishSchema } from '../config/config.schemas';import type { AppConfigDefinition } from '../config/config.types';import * as v from 'valibot';import { AI_DEFAULT_MODEL_ENV_KEY } from './ai.constants';-import { AI_ADAPTERS_NAMES, AI_DEFAULT_ADAPTER_NAME } from './adapters/ai-adapters.constants';import { openAiAdaptersConfig } from './adapters/openai-compatible/openai-compatible.config';import { anthropicAdaptersConfig } from './adapters/anthropic/anthropic.ai-adapters.config';@@ -19,18 +18,11 @@ export const aiConfig = {anthropic: anthropicAdaptersConfig,...openAiAdaptersConfig,},- defaultAdapterName: {- doc: `Default AI adapter to use when no specific adapter is specified in the model id. Available adapters: ${AI_ADAPTERS_NAMES.join(', ')}`,- schema: v.picklist(AI_ADAPTERS_NAMES),- env: 'AI_DEFAULT_ADAPTER',- default: AI_DEFAULT_ADAPTER_NAME,- showInDocumentation: false,- },defaultModelId: {- doc: 'Default AI model to use when no specific model is specified, the format is <adapterId>://<modelName>, e.g. "ollama://llama3.1:8b". The adapterId can be omitted, like "llama3.1:8b", in which case the default adapter will be used.',- schema: aiModelIdSchema,+ doc: 'Default AI model to use when no specific model is specified, the format is <adapterId>://<modelName>, e.g. "ollama://llama3.1:8b".',+ schema: v.optional(aiModelIdSchema),env: AI_DEFAULT_MODEL_ENV_KEY,- default: 'unknown',+ default: undefined,showInDocumentation: false,},} as const satisfies AppConfigDefinition;diff --git a/apps/papra-server/src/modules/ai/ai.schemas.models.test.ts b/apps/papra-server/src/modules/ai/ai.models.test.tssimilarity index 57%rename from apps/papra-server/src/modules/ai/ai.schemas.models.test.tsrename to apps/papra-server/src/modules/ai/ai.models.test.tsindex 570ff747..05c36077 100644--- a/apps/papra-server/src/modules/ai/ai.schemas.models.test.ts+++ b/apps/papra-server/src/modules/ai/ai.models.test.ts@@ -1,7 +1,7 @@import { describe, expect, test } from 'vitest';-import { parseModelId } from './ai.schemas.models';+import { parseModelId, isValidModelId } from './ai.models';-describe('ai.schemas.models', () => {+describe('ai.models', () => {describe('parseModelId', () => {test('given a model id in the format "adapter://modelName", it parses and returns the modelName and adapterId', () => {expect(parseModelId('openai://gpt-4')).to.eql({@@ -17,11 +17,10 @@ describe('ai.schemas.models', () => {});});- test('the adapterId is optional, so if the model id does not contain "://" it returns the modelName and undefined adapterId', () => {- expect(parseModelId('gpt-4')).to.eql({- adapterId: undefined,- modelName: 'gpt-4',- });+ test('the adapterId is required, so if the model id does not contain "://" it throws an error', () => {+ expect(() => parseModelId('gpt-4')).to.throw(+ 'Invalid model identifier: "gpt-4". Expected format is "adapterId://modelName"',+ );});test('if the model id is in the format "adapter://", it throws an error', () => {@@ -38,4 +37,16 @@ describe('ai.schemas.models', () => {);});});++ describe('isValidModelId', () => {+ test('a valid model must be in the format "adapter://modelName"', () => {+ expect(isValidModelId('openai://gpt-4')).to.eql(true);+ expect(isValidModelId('openrouter://openai/gpt-4')).to.eql(true);+ expect(isValidModelId('adapter://foo:bar://baz')).to.eql(true);++ expect(isValidModelId('gpt-4')).to.eql(false);+ expect(isValidModelId('adapter://')).to.eql(false);+ expect(isValidModelId('')).to.eql(false);+ });+ });});diff --git a/apps/papra-server/src/modules/ai/ai.models.ts b/apps/papra-server/src/modules/ai/ai.models.tsindex dae99bab..dba70bf1 100644--- a/apps/papra-server/src/modules/ai/ai.models.ts+++ b/apps/papra-server/src/modules/ai/ai.models.ts@@ -1,7 +1,8 @@import { createError } from '../shared/errors/errors';-import type { ModelConfig } from './ai.type';+import { isNilOrEmptyString } from '../shared/utils';+import { ADAPTER_MODEL_SEPARATOR } from './ai.constants';-export function ensureModel(model: ModelConfig | undefined | null): ModelConfig {+export function ensureModelId(model: string | undefined | null): string {if (!model) {throw createError({code: 'ai.model_not_configured',@@ -13,3 +14,32 @@ export function ensureModel(model: ModelConfig | undefined | null): ModelConfigreturn model;}++export function parseModelId(modelId: string): { adapterId: string; modelName: string } {+ if (isNilOrEmptyString(modelId) || !modelId.includes(ADAPTER_MODEL_SEPARATOR)) {+ throw new Error(+ `Invalid model identifier: "${modelId}". Expected format is "adapterId${ADAPTER_MODEL_SEPARATOR}modelName"`,+ );+ }++ const [adapterId, ...modelNameParts] = modelId.split(ADAPTER_MODEL_SEPARATOR);+ const modelName = modelNameParts.join(ADAPTER_MODEL_SEPARATOR);++ if (isNilOrEmptyString(modelName) || isNilOrEmptyString(adapterId)) {+ throw new Error(+ `Invalid model identifier: "${modelId}". Expected format is "adapterId${ADAPTER_MODEL_SEPARATOR}modelName"`,+ );+ }++ return { adapterId, modelName };+}++export function isValidModelId(modelId: string): boolean {+ try {+ parseModelId(modelId);++ return true;+ } catch {+ return false;+ }+}diff --git a/apps/papra-server/src/modules/ai/ai.schemas.models.ts b/apps/papra-server/src/modules/ai/ai.schemas.models.tsdeleted file mode 100644index 94d5d3e2..00000000--- a/apps/papra-server/src/modules/ai/ai.schemas.models.ts+++ /dev/null@@ -1,33 +0,0 @@-import { isNilOrEmptyString } from '../shared/utils';-import { ADAPTER_MODEL_SEPARATOR } from './ai.constants';--export function parseModelId(modelId: string): { adapterId?: string; modelName: string } {- if (isNilOrEmptyString(modelId)) {- throw new Error(- `Invalid model identifier: "${modelId}". Expected format is "adapterId${ADAPTER_MODEL_SEPARATOR}modelName"`,- );- }-- if (!modelId.includes(ADAPTER_MODEL_SEPARATOR)) {- return { adapterId: undefined, modelName: modelId };- }-- const [adapterId, ...modelNameParts] = modelId.split(ADAPTER_MODEL_SEPARATOR);- const modelName = modelNameParts.join(ADAPTER_MODEL_SEPARATOR);-- if (isNilOrEmptyString(modelName)) {- throw new Error(- `Invalid model identifier: "${modelId}". Expected format is "adapterId${ADAPTER_MODEL_SEPARATOR}modelName"`,- );- }-- return { adapterId, modelName };-}--export function parseOptionalModelId(modelId: string | undefined | null) {- if (isNilOrEmptyString(modelId)) {- return undefined;- }-- return parseModelId(modelId);-}diff --git a/apps/papra-server/src/modules/ai/ai.schemas.ts b/apps/papra-server/src/modules/ai/ai.schemas.tsindex ef485f63..72b753e6 100644--- a/apps/papra-server/src/modules/ai/ai.schemas.ts+++ b/apps/papra-server/src/modules/ai/ai.schemas.ts@@ -1,3 +1,10 @@import * as v from 'valibot';+import { isValidModelId } from './ai.models';-export const aiModelIdSchema = v.string();+export const aiModelIdSchema = v.pipe(+ v.string(),+ v.check(+ isValidModelId,+ 'Invalid model identifier. Expected format is "adapterId://modelName", e.g. "openai://gpt-4"',+ ),+);diff --git a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.tsindex ff649954..9184b12a 100644--- a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts+++ b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts@@ -16,6 +16,7 @@ import {buildAutoTaggingUserPrompt,getTagsActions,} from './auto-tagging.models';+import { ensureModelId } from '../ai/ai.models';export async function autoTagDocument({aiServices,@@ -73,7 +74,7 @@ export async function autoTagDocument({const startedAt = Date.now();const response = await aiServices.generateStructuredData({- modelId: organizationSettings.ai.autoTagging.modelId,+ modelId: ensureModelId(organizationSettings.ai.autoTagging.modelId),schema: buildAutoTaggingSchema({ existingTags, canCreateNewTags, maxTags }),systemPrompt: buildAutoTaggingSystemPrompt({ existingTags, canCreateNewTags, maxTags }),userPrompt: buildAutoTaggingUserPrompt({ document }),diff --git a/apps/papra-server/src/modules/organizations/organization-settings/organization-settings.types.ts b/apps/papra-server/src/modules/organizations/organization-settings/organization-settings.types.tsindex d427cb46..a838d9e5 100644--- a/apps/papra-server/src/modules/organizations/organization-settings/organization-settings.types.ts+++ b/apps/papra-server/src/modules/organizations/organization-settings/organization-settings.types.ts@@ -6,7 +6,7 @@ export type OrganizationSettings = {isEnabled: boolean;canCreateNewTags: boolean;maxTags: number;- modelId: string;+ modelId?: string;};};};