Skip to content

armgit / papra

Public Imported from GitHub
0

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.ts
index 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-compatibl
export 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.ts
index 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.ts
index 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.ts
similarity index 57%
rename from apps/papra-server/src/modules/ai/ai.schemas.models.test.ts
rename to apps/papra-server/src/modules/ai/ai.models.test.ts
index 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.ts
index 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): ModelConfig
return 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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;
};
};
};