The minimalistic document archiving platform.
feat(ai-credits): add AI credit consumption system (#1380)
Corentin Thomasset9aa4541a6fba
diff --git a/apps/papra-server/src/migrations/list/0027-ai-credits.migration.ts b/apps/papra-server/src/migrations/list/0027-ai-credits.migration.tsnew file mode 100644index 00000000..da7ffe96--- /dev/null+++ b/apps/papra-server/src/migrations/list/0027-ai-credits.migration.ts@@ -0,0 +1,35 @@+import type { Migration } from '../migrations.types';+import { sql } from 'drizzle-orm';++export const aiCreditsMigration = {+ name: 'ai-credits',++ up: async ({ db }) => {+ await db.batch([+ db.run(sql`CREATE TABLE IF NOT EXISTS "organization_ai_credits_usage" (+ "id" text PRIMARY KEY NOT NULL,+ "created_at" integer NOT NULL,+ "updated_at" integer NOT NULL,+ "organization_id" text NOT NULL,+ "credits_consumed" integer NOT NULL,+ "usage" text NOT NULL,+ "source" text NOT NULL,+ FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade+ )`),++ // Current period credits count: sum where organization_id = ? and created_at >= ?+ db.run(+ sql`CREATE INDEX IF NOT EXISTS "organization_ai_credits_usage_organization_id_created_at_index" ON "organization_ai_credits_usage" ("organization_id", "created_at")`,+ ),++ // Cascade index+ db.run(+ sql`CREATE INDEX IF NOT EXISTS "organization_ai_credits_usage_organization_id_index" ON "organization_ai_credits_usage" ("organization_id")`,+ ),+ ]);+ },++ down: async ({ db }) => {+ await db.batch([db.run(sql`DROP TABLE IF EXISTS "organization_ai_credits_usage"`)]);+ },+} satisfies Migration;diff --git a/apps/papra-server/src/migrations/migrations.registry.test.ts b/apps/papra-server/src/migrations/migrations.registry.test.tsindex 0ba95e15..f1502400 100644--- a/apps/papra-server/src/migrations/migrations.registry.test.ts+++ b/apps/papra-server/src/migrations/migrations.registry.test.ts@@ -114,6 +114,8 @@ describe('migrations registry', () => {CREATE INDEX "key_hash_index" ON "api_keys" ("key_hash");CREATE INDEX migrations_name_index ON migrations (name);CREATE INDEX migrations_run_at_index ON migrations (run_at);+ CREATE INDEX "organization_ai_credits_usage_organization_id_created_at_index" ON "organization_ai_credits_usage" ("organization_id", "created_at");+ CREATE INDEX "organization_ai_credits_usage_organization_id_index" ON "organization_ai_credits_usage" ("organization_id");CREATE UNIQUE INDEX "organization_invitations_organization_email_unique" ON "organization_invitations" ("organization_id","email");CREATE INDEX "organization_members_user_id_index" ON "organization_members" ("user_id");CREATE UNIQUE INDEX "organization_members_user_organization_unique" ON "organization_members" ("organization_id","user_id");@@ -155,6 +157,7 @@ describe('migrations registry', () => {CREATE TABLE "intake_emails" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "email_address" text NOT NULL, "organization_id" text NOT NULL, "allowed_origins" text DEFAULT '[]' NOT NULL, "is_enabled" integer DEFAULT true NOT NULL, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade );CREATE TABLE "kv_store" ( "key" text PRIMARY KEY NOT NULL, "value" text NOT NULL, "expires_at" integer );CREATE TABLE migrations (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, run_at INTEGER NOT NULL);+ CREATE TABLE "organization_ai_credits_usage" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "credits_consumed" integer NOT NULL, "usage" text NOT NULL, "source" text NOT NULL, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade );CREATE TABLE "organization_invitations" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "email" text NOT NULL, "role" text NOT NULL, "status" text NOT NULL DEFAULT 'pending', "expires_at" integer NOT NULL, "inviter_id" text NOT NULL, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade, FOREIGN KEY ("inviter_id") REFERENCES "users"("id") ON UPDATE cascade ON DELETE cascade );CREATE TABLE "organization_members" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "user_id" text NOT NULL, "role" text NOT NULL, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade, FOREIGN KEY ("user_id") REFERENCES "users"("id") ON UPDATE cascade ON DELETE cascade );CREATE TABLE "organization_settings" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "ai_auto_tagging_enabled" integer, "ai_auto_tagging_can_create_new_tags" integer, "ai_auto_tagging_max_tags" integer, "ai_auto_tagging_model_id" text, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade, UNIQUE("organization_id") );diff --git a/apps/papra-server/src/migrations/migrations.registry.ts b/apps/papra-server/src/migrations/migrations.registry.tsindex 0973214e..9337a48b 100644--- a/apps/papra-server/src/migrations/migrations.registry.ts+++ b/apps/papra-server/src/migrations/migrations.registry.ts@@ -26,6 +26,7 @@ import { documentViewsMigration } from './list/0023-document-views.migration';import { userPlanEntitlementsMigration } from './list/0024-user-plan-entitlements.migration';import { addOrganizationSettingsTableMigration } from './list/0025-add-organization-settings-table.migration';import { addIndexesMigration } from './list/0026-add-indexes.migration';+import { aiCreditsMigration } from './list/0027-ai-credits.migration';export const migrations: Migration[] = [initialSchemaSetupMigration,@@ -54,4 +55,5 @@ export const migrations: Migration[] = [userPlanEntitlementsMigration,addOrganizationSettingsTableMigration,addIndexesMigration,+ aiCreditsMigration,];diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.test.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.test.tsnew file mode 100644index 00000000..bdc71b0c--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.test.ts@@ -0,0 +1,93 @@+import { describe, expect, test } from 'vitest';+import { parseUsageInfo } from './ai-credits.middlewares';+import { createTestLogger } from '../shared/logger/logger.test-utils';++describe('ai-credits.middlewares', () => {+ describe('parseUsageInfo', () => {+ test('given tanstack-ai usage reports, it resolve input token from promptTokens, and output tokens from completionTokens', () => {+ const { getLogs, logger } = createTestLogger();++ expect(+ parseUsageInfo(+ {+ promptTokens: 20,+ completionTokens: 10,+ totalTokens: 30,+ },+ logger,+ ),+ ).to.eql({+ inputTokens: 20,+ outputTokens: 10,+ });++ expect(getLogs()).to.eql([]);+ });++ test('when the totalToken count does not match the sum of promptTokens and completionTokens, it logs a warning and resolves input tokens from totalTokens - outputTokens', () => {+ const { getLogs, logger } = createTestLogger();++ expect(+ parseUsageInfo(+ {+ promptTokens: 20,+ completionTokens: 10,+ totalTokens: 25,+ },+ logger,+ ),+ ).to.eql({+ inputTokens: 15,+ outputTokens: 10,+ });++ expect(getLogs({ excludeTimestampMs: true })).to.eql([+ {+ data: {+ usage: {+ completionTokens: 10,+ promptTokens: 20,+ totalTokens: 25,+ },+ },+ level: 'warn',+ message: 'Usage info does not match total tokens',+ namespace: 'test',+ },+ ]);+ });++ test("when the totalToken count doesn't match the sum, and for some reason the difference is negative, it logs a warning and resolves input tokens to 0", () => {+ const { getLogs, logger } = createTestLogger();++ expect(+ parseUsageInfo(+ {+ promptTokens: 20,+ completionTokens: 10,+ totalTokens: 5,+ },+ logger,+ ),+ ).to.eql({+ inputTokens: 0,+ outputTokens: 10,+ });++ expect(getLogs({ excludeTimestampMs: true })).to.eql([+ {+ data: {+ usage: {+ completionTokens: 10,+ promptTokens: 20,+ totalTokens: 5,+ },+ },+ level: 'warn',+ message: 'Usage info does not match total tokens',+ namespace: 'test',+ },+ ]);+ });+ });+});diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.tsnew file mode 100644index 00000000..1ed8cbff--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.middlewares.ts@@ -0,0 +1,90 @@+import type { ChatMiddleware, UsageInfo } from '@tanstack/ai';+import { registerAiCreditLlmUsage } from './ai-credits.usecases';+import type { AiCreditsUsageSource } from './ai-credits.types';+import type { AiCreditsRepository } from './ai-credits.repository';+import type { Logger } from '@crowlog/logger';+import { safely } from '@corentinth/chisels';++export function createAiCreditsMiddleware({+ modelId,+ organizationId,+ source,+ aiCreditsRepository,+ logger,+}: {+ modelId: string;+ organizationId: string;+ source: AiCreditsUsageSource;+ aiCreditsRepository: AiCreditsRepository;+ logger: Logger;+}): ChatMiddleware {+ return {+ name: 'ai-credits',+ onUsage: (ctx, usage) => {+ ctx.defer(+ handleOnUsage({+ modelId,+ organizationId,+ usage,+ source,+ logger,+ aiCreditsRepository,+ }),+ );+ },+ };+}++export function parseUsageInfo(+ usage: UsageInfo,+ logger: Logger,+): { inputTokens: number; outputTokens: number } {+ const inputTokens = usage.promptTokens;+ const outputTokens = usage.completionTokens;++ if (inputTokens + outputTokens !== usage.totalTokens) {+ logger.warn({ usage }, 'Usage info does not match total tokens');++ return {+ inputTokens: Math.max(0, usage.totalTokens - outputTokens),+ outputTokens,+ };+ }++ return { inputTokens, outputTokens };+}++async function handleOnUsage({+ modelId,+ organizationId,+ source,+ usage,+ aiCreditsRepository,+ logger,+}: {+ modelId: string;+ organizationId: string;+ source: AiCreditsUsageSource;+ usage: UsageInfo;+ logger: Logger;+ aiCreditsRepository: AiCreditsRepository;+}) {+ const { inputTokens, outputTokens } = parseUsageInfo(usage, logger);++ const [, error] = await safely(+ registerAiCreditLlmUsage({+ modelId,+ organizationId,+ usage: { inputTokens, outputTokens },+ source,+ aiCreditsRepository,+ }),+ );++ if (error) {+ logger.error(+ { error, modelId, organizationId, source, usage },+ 'Failed to register AI credit usage',+ );+ }+}diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.repository.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.repository.tsnew file mode 100644index 00000000..5cd4de65--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.repository.ts@@ -0,0 +1,78 @@+import { injectArguments } from '@corentinth/chisels';+import type { Database } from '../app/database/database.types';+import { organizationAiCreditsUsageTable } from './ai-credits.tables';+import type { AiCreditsUsageDetails, AiCreditsUsageSource } from './ai-credits.types';+import { and, eq, gte, sum } from 'drizzle-orm';+import { systemClock } from '../shared/clock/clock';+import type { Clock } from '../shared/clock/clock.types';++export type AiCreditsRepository = ReturnType<typeof createAiCreditsRepository>;++export function createAiCreditsRepository({ db }: { db: Database }) {+ return injectArguments(+ {+ registerCreditConsumption,+ getCurrentPeriodOrganizationAiCreditsCount,+ },+ {+ db,+ },+ );+}++async function registerCreditConsumption({+ organizationId,+ creditsConsumed,+ source,+ usage,++ db,+}: {+ organizationId: string;+ creditsConsumed: number;+ source: AiCreditsUsageSource;+ usage: AiCreditsUsageDetails;++ db: Database;+}) {+ await db.insert(organizationAiCreditsUsageTable).values({+ organizationId,+ creditsConsumed,+ source,+ usage,+ });+}++async function getCurrentPeriodOrganizationAiCreditsCount({+ organizationId,+ db,+ clock = systemClock,+}: {+ organizationId: string;+ db: Database;+ clock?: Clock;+}) {+ const startOfMonth = clock+ .now()+ .toZonedDateTimeISO('UTC')+ .with({ day: 1 })+ .startOfDay().epochMilliseconds;++ const result = await db+ .select({+ totalCreditsConsumed: sum(organizationAiCreditsUsageTable.creditsConsumed),+ })+ .from(organizationAiCreditsUsageTable)+ .where(+ and(+ eq(organizationAiCreditsUsageTable.organizationId, organizationId),+ gte(organizationAiCreditsUsageTable.createdAt, new Date(startOfMonth)),+ ),+ );++ const [{ totalCreditsConsumed } = {}] = result;++ return {+ creditsConsumed: Number(totalCreditsConsumed ?? 0),+ };+}diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.tables.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.tables.tsnew file mode 100644index 00000000..9e8caed4--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.tables.ts@@ -0,0 +1,19 @@+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';+import { createPrimaryKeyField, createTimestampColumns } from '../shared/db/columns.helpers';+import { organizationsTable } from '../organizations/organizations.table';+import type { AiCreditsUsageDetails, AiCreditsUsageSource } from './ai-credits.types';++export const organizationAiCreditsUsageTable = sqliteTable('organization_ai_credits_usage', {+ ...createPrimaryKeyField({ prefix: 'aicu' }),+ ...createTimestampColumns(),++ organizationId: text('organization_id')+ .notNull()+ .references(() => organizationsTable.id, { onDelete: 'cascade', onUpdate: 'cascade' }),++ creditsConsumed: integer('credits_consumed').notNull(),++ usage: text('usage', { mode: 'json' }).notNull().$type<AiCreditsUsageDetails>(),++ source: text('source').notNull().$type<AiCreditsUsageSource>(),+});diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.types.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.types.tsnew file mode 100644index 00000000..be045eee--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.types.ts@@ -0,0 +1,18 @@+import type { ContentExtractionCreditRate, ModelCreditRate } from './rates/ai-credits.rates';++export type AiCreditsUsageDetails =+ | {+ type: 'llm-model';+ modelId: string;+ inputTokens: number;+ outputTokens: number;+ creditsRate: ModelCreditRate;+ }+ | {+ type: 'content-extraction';+ modelId: string;+ pageCount: number;+ creditsRate: ContentExtractionCreditRate;+ };++export type AiCreditsUsageSource = 'auto-tagging' | 'content-extraction';diff --git a/apps/papra-server/src/modules/ai-credits/ai-credits.usecases.ts b/apps/papra-server/src/modules/ai-credits/ai-credits.usecases.tsnew file mode 100644index 00000000..98c9a17a--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/ai-credits.usecases.ts@@ -0,0 +1,92 @@+import type { ModelUsage } from '../ai/ai.type';+import type { GetOrganizationPlanUsecase } from '../plans/plans.usecases';+import { systemClock } from '../shared/clock/clock';+import type { Clock } from '../shared/clock/clock.types';+import { createError } from '../shared/errors/errors';+import type { AiCreditsRepository } from './ai-credits.repository';+import type { AiCreditsUsageSource } from './ai-credits.types';+import { getCreditsCostForUsage } from './rates/ai-credits.rates.models';++export async function registerAiCreditLlmUsage({+ modelId,+ organizationId,+ usage,+ source,++ aiCreditsRepository,+}: {+ modelId: string;+ organizationId: string;+ usage: ModelUsage;+ source: AiCreditsUsageSource;++ aiCreditsRepository: AiCreditsRepository;+}) {+ const { credits, creditsRate } = getCreditsCostForUsage({ modelId, usage });++ await aiCreditsRepository.registerCreditConsumption({+ organizationId,+ creditsConsumed: credits,+ source,+ usage: {+ type: 'llm-model',+ modelId,+ inputTokens: usage.inputTokens,+ outputTokens: usage.outputTokens,+ creditsRate,+ },+ });+}++export async function getOrganizationAiCreditsUsage({+ organizationId,+ aiCreditsRepository,+ getOrganizationPlan,+ clock = systemClock,+}: {+ organizationId: string;+ aiCreditsRepository: AiCreditsRepository;+ getOrganizationPlan: GetOrganizationPlanUsecase;+ clock?: Clock;+}) {+ const [{ creditsConsumed }, { organizationPlan }] = await Promise.all([+ aiCreditsRepository.getCurrentPeriodOrganizationAiCreditsCount({ organizationId, clock }),+ getOrganizationPlan({ organizationId }),+ ]);++ const remainingCredits = Math.max(0, organizationPlan.limits.aiCreditsPerMonth - creditsConsumed);++ return {+ creditsConsumed,+ creditsLimit: organizationPlan.limits.aiCreditsPerMonth,+ remainingCredits,+ hasExceededLimit: remainingCredits <= 0,+ };+}++export async function checkOrganizationHasSufficientAiCredits({+ organizationId,+ aiCreditsRepository,+ getOrganizationPlan,+ clock = systemClock,+}: {+ organizationId: string;+ aiCreditsRepository: AiCreditsRepository;+ getOrganizationPlan: GetOrganizationPlanUsecase;+ clock?: Clock;+}) {+ const { hasExceededLimit } = await getOrganizationAiCreditsUsage({+ organizationId,+ aiCreditsRepository,+ getOrganizationPlan,+ clock,+ });++ if (hasExceededLimit) {+ throw createError({+ code: 'ai_credits.limit_exceeded',+ message: 'You have exceeded your AI credits limit for this month.',+ statusCode: 402,+ });+ }+}diff --git a/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.errors.ts b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.errors.tsnew file mode 100644index 00000000..6104f315--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.errors.ts@@ -0,0 +1,8 @@+import { createErrorFactory } from '../../shared/errors/errors';++export const createModelCreditRateNotFoundError = createErrorFactory({+ code: 'ai-credits.model-credit-rate-not-found',+ message: 'Model credit rate not found',+ statusCode: 500,+ isInternal: true,+});diff --git a/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.test.ts b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.test.tsnew file mode 100644index 00000000..f33f1fda--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.test.ts@@ -0,0 +1,85 @@+import { describe, expect, test } from 'vitest';+import { computeCreditsForTokens, getCreditsCostForUsage } from './ai-credits.rates.models';+import { createModelCreditRateNotFoundError } from './ai-credits.rates.errors';++describe('ai-credits.rates.models', () => {+ describe('computeCreditsForTokens', () => {+ test('given a credit rate and a number of input and output tokens, the consumed is the sum of the input and output credits calculated from the credit rate', () => {+ expect(+ computeCreditsForTokens({+ inputTokens: 10_000,+ outputTokens: 20_000,+ creditsRate: {+ creditsPerMillionInputTokens: 5_000,+ creditsPerMillionOutputTokens: 7_000,+ },+ }),+ ).to.eql(190); // (10k / 1M * 5k) + (20k / 1M * 7k) = 50 + 140 = 190+ });++ test('when the calculated credits is less than 1, it returns 1', () => {+ expect(+ computeCreditsForTokens({+ inputTokens: 1,+ outputTokens: 2,+ creditsRate: {+ creditsPerMillionInputTokens: 0.0001,+ creditsPerMillionOutputTokens: 0.0002,+ },+ }),+ ).to.eql(1);+ });++ test('when the calculated credits is a decimal, it returns the ceiling of the value', () => {+ expect(+ computeCreditsForTokens({+ inputTokens: 500_000,+ outputTokens: 1_000_000,+ creditsRate: {+ creditsPerMillionInputTokens: 1,+ creditsPerMillionOutputTokens: 1,+ },+ }),+ ).to.eql(2); // (0.5 + 1) = 1.5 => ceil(1.5) = 2+ });+ });++ describe('getCreditsCostForUsage', () => {+ test('given a modelId and a usage, it returns the credits cost for the usage', () => {+ expect(+ getCreditsCostForUsage({+ modelId: 'provider://dummy',+ usage: {+ inputTokens: 10_000,+ outputTokens: 20_000,+ },+ modelRates: {+ 'provider://dummy': {+ creditsPerMillionInputTokens: 5_000,+ creditsPerMillionOutputTokens: 7_000,+ },+ },+ }),+ ).to.eql({+ credits: 190,+ creditsRate: {+ creditsPerMillionInputTokens: 5_000,+ creditsPerMillionOutputTokens: 7_000,+ },+ });+ });++ test('when no rate exists for the given modelId, it throws a ModelCreditRateNotFoundError', () => {+ expect(() =>+ getCreditsCostForUsage({+ modelId: 'provider://unknown',+ usage: {+ inputTokens: 10_000,+ outputTokens: 20_000,+ },+ modelRates: {},+ }),+ ).toThrow(createModelCreditRateNotFoundError());+ });+ });+});diff --git a/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.ts b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.tsnew file mode 100644index 00000000..9d8fc132--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.models.ts@@ -0,0 +1,50 @@+import type { ModelUsage } from '../../ai/ai.type';+import { isNil } from '../../shared/utils';+import type { ModelCreditRate } from './ai-credits.rates';+import { modelCreditRates } from './ai-credits.rates';+import { createModelCreditRateNotFoundError } from './ai-credits.rates.errors';++export function getCreditsCostForUsage({+ modelId,+ usage,+ modelRates = modelCreditRates,+}: {+ modelId: string;+ usage: ModelUsage;+ modelRates?: Record<string, ModelCreditRate>;+}): {+ credits: number;+ creditsRate: ModelCreditRate;+} {+ const creditsRate = modelRates[modelId];++ if (isNil(creditsRate)) {+ throw createModelCreditRateNotFoundError();+ }++ const credits = computeCreditsForTokens({+ inputTokens: usage.inputTokens,+ outputTokens: usage.outputTokens,+ creditsRate,+ });++ return {+ credits,+ creditsRate,+ };+}++export function computeCreditsForTokens({+ inputTokens,+ outputTokens,+ creditsRate,+}: {+ inputTokens: number;+ outputTokens: number;+ creditsRate: ModelCreditRate;+}): number {+ const inputCredits = (inputTokens / 1_000_000) * creditsRate.creditsPerMillionInputTokens;+ const outputCredits = (outputTokens / 1_000_000) * creditsRate.creditsPerMillionOutputTokens;++ return Math.max(1, Math.ceil(inputCredits + outputCredits));+}diff --git a/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.ts b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.tsnew file mode 100644index 00000000..9e6632ba--- /dev/null+++ b/apps/papra-server/src/modules/ai-credits/rates/ai-credits.rates.ts@@ -0,0 +1,29 @@+export type ModelCreditRate = {+ creditsPerMillionInputTokens: number;+ creditsPerMillionOutputTokens: number;+};++export type ContentExtractionCreditRate = {+ creditsPerPage: number;+};++export const modelCreditRates: Record<string, ModelCreditRate> = {+ // checked on 2026-07-22 https://mistral.ai/pricing/api/+ 'mistral://mistral-medium-3-5': {+ creditsPerMillionInputTokens: 15_000,+ creditsPerMillionOutputTokens: 75_000,+ },+ // checked on 2026-07-22 https://mistral.ai/pricing/api/+ 'mistral://mistral-small-2603': {+ creditsPerMillionInputTokens: 1_500,+ creditsPerMillionOutputTokens: 6_000,+ },+};++// TODO: handle content extraction credit+// export const contentExtractionCreditRates: Record<string, ContentExtractionCreditRate> = {+// // checked on 2026-07-22 https://mistral.ai/pricing/api/+// 'mistral-ocr': {+// creditsPerPage: 40,+// },+// };diff --git a/apps/papra-server/src/modules/ai/ai.services.ts b/apps/papra-server/src/modules/ai/ai.services.tsindex eac24b48..381d255f 100644--- a/apps/papra-server/src/modules/ai/ai.services.ts+++ b/apps/papra-server/src/modules/ai/ai.services.ts@@ -6,14 +6,33 @@ import type { ChatMiddleware } from '@tanstack/ai';import { toStandardJsonSchema } from '@valibot/to-json-schema';import type { GenericSchema, InferOutput } from 'valibot';import { createLogger } from '../shared/logger/logger';+import { createAiCreditsMiddleware } from '../ai-credits/ai-credits.middlewares';+import type { AiCreditsUsageSource } from '../ai-credits/ai-credits.types';+import type { AiCreditsRepository } from '../ai-credits/ai-credits.repository';+import { checkOrganizationHasSufficientAiCredits } from '../ai-credits/ai-credits.usecases';+import { createGetOrganizationPlanUsecase } from '../plans/plans.usecases';+import type { PlansRepository } from '../plans/plans.repository';+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';+import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';+import type { SubscriptionsRepository } from '../subscriptions/subscriptions.repository';export type AiServices = ReturnType<typeof createAiServices>;export function createAiServices({config,+ aiCreditsRepository,+ plansRepository,+ planEntitlementDefinitionRegistry,+ planEntitlementsRepository,+ subscriptionsRepository,logger = createLogger({ namespace: 'ai.services' }),}: {config: Config;+ aiCreditsRepository: AiCreditsRepository;+ plansRepository: PlansRepository;+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;+ planEntitlementsRepository: PlanEntitlementsRepository;+ subscriptionsRepository: SubscriptionsRepository;logger?: Logger;}) {// Not using injectArguments here: it relies on Parameters/ReturnType, which collapse the@@ -25,7 +44,19 @@ export function createAiServices({schema: Schema;userPrompt: string;systemPrompt?: string;- }): Promise<InferOutput<Schema>> => generateStructuredData({ ...args, config, logger }),+ source: AiCreditsUsageSource;+ organizationId: string;+ }): Promise<InferOutput<Schema>> =>+ generateStructuredData({+ ...args,+ config,+ logger,+ aiCreditsRepository,+ plansRepository,+ planEntitlementDefinitionRegistry,+ planEntitlementsRepository,+ subscriptionsRepository,+ }),};}@@ -34,21 +65,46 @@ async function generateStructuredData<Schema extends GenericSchema>({schema,userPrompt,systemPrompt,+ source,+ organizationId,+ aiCreditsRepository,config,logger,+ plansRepository,+ planEntitlementDefinitionRegistry,+ planEntitlementsRepository,+ subscriptionsRepository,}: {modelId: string;schema: Schema;userPrompt: string;systemPrompt?: string;+ source: AiCreditsUsageSource;+ organizationId: string;config: Config;logger: Logger;+ aiCreditsRepository: AiCreditsRepository;+ plansRepository: PlansRepository;+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;+ planEntitlementsRepository: PlanEntitlementsRepository;+ subscriptionsRepository: SubscriptionsRepository;}): Promise<InferOutput<Schema>> {const adapter = resolveTextAdapter({modelId,config,});+ await checkOrganizationHasSufficientAiCredits({+ organizationId,+ aiCreditsRepository,+ getOrganizationPlan: createGetOrganizationPlanUsecase({+ plansRepository,+ planEntitlementDefinitionRegistry,+ planEntitlementsRepository,+ subscriptionsRepository,+ }),+ });+const jsonSchema = toStandardJsonSchema(schema);const data = await tanstackChat({@@ -56,7 +112,16 @@ async function generateStructuredData<Schema extends GenericSchema>({messages: userPrompt ? [{ role: 'user', content: userPrompt }] : undefined,outputSchema: jsonSchema,systemPrompts: systemPrompt ? [systemPrompt] : undefined,- middleware: [createLogMiddleware({ logger, context: { modelId } })],+ middleware: [+ createLogMiddleware({ logger, context: { modelId } }),+ createAiCreditsMiddleware({+ modelId,+ organizationId,+ source,+ logger,+ aiCreditsRepository,+ }),+ ],});return data;diff --git a/apps/papra-server/src/modules/ai/ai.type.ts b/apps/papra-server/src/modules/ai/ai.type.tsindex ea525fc6..dd13ac27 100644--- a/apps/papra-server/src/modules/ai/ai.type.ts+++ b/apps/papra-server/src/modules/ai/ai.type.ts@@ -2,3 +2,8 @@ export type ModelConfig = {modelName: string;adapterId?: string;};++export type ModelUsage = {+ inputTokens: number;+ outputTokens: number;+};diff --git a/apps/papra-server/src/modules/app/server.test-utils.ts b/apps/papra-server/src/modules/app/server.test-utils.tsindex e094ae37..e7b136ee 100644--- a/apps/papra-server/src/modules/app/server.test-utils.ts+++ b/apps/papra-server/src/modules/app/server.test-utils.ts@@ -19,6 +19,10 @@ import { createEventServices } from './events/events.services';import { createGracefulShutdownService } from './graceful-shutdown/graceful-shutdown.services';import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';import { createAiServices } from '../ai/ai.services';+import { createAiCreditsRepository } from '../ai-credits/ai-credits.repository';+import { createPlansRepository } from '../plans/plans.repository';+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';+import { createSubscriptionsRepository } from '../subscriptions/subscriptions.repository';export function createTestServerDependencies(overrides: Partial<GlobalDependencies> = {},@@ -50,7 +54,16 @@ export function createTestServerDependencies(const planEntitlementDefinitionRegistry =overrides.planEntitlementDefinitionRegistry ??createPlanEntitlementDefinitionRegistry({ config });- const aiServices = overrides.aiServices ?? createAiServices({ config });+ const aiServices =+ overrides.aiServices ??+ createAiServices({+ config,+ aiCreditsRepository: createAiCreditsRepository({ db }),+ planEntitlementDefinitionRegistry,+ plansRepository: createPlansRepository({ config }),+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),+ subscriptionsRepository: createSubscriptionsRepository({ db }),+ });registerEventHandlers({eventServices,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 2bb03763..fe9163f4 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@@ -27,7 +27,7 @@ export async function promptForAutoTagging({modelId,}: {aiServices: AiServices;- document: { content: string; name: string };+ document: { content: string; name: string; organizationId: string };existingTags: { id: string; name: string; description?: string | null }[];canCreateNewTags: boolean;maxTags: number;@@ -35,6 +35,8 @@ export async function promptForAutoTagging({}) {const autoTaggingResponse = await aiServices.generateStructuredData({modelId,+ organizationId: document.organizationId,+ source: 'auto-tagging',schema: buildAutoTaggingSchema({ existingTags, canCreateNewTags }),systemPrompt: buildAutoTaggingSystemPrompt({ existingTags, canCreateNewTags, maxTags }),userPrompt: buildAutoTaggingUserPrompt({ document }),diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/anthropic.auto-tagging.int.test.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/anthropic.auto-tagging.int.test.tsindex 81f83a07..c2b9fe69 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/anthropic.auto-tagging.int.test.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/anthropic.auto-tagging.int.test.ts@@ -6,8 +6,8 @@ const apiKey = process.env.TEST_ANTHROPIC_API_KEY;const modelId = process.env.TEST_ANTHROPIC_MODEL_ID;describe('auto-tagging ai integration', () => {- describe.skipIf(!apiKey || !modelId)('anthropic', () => {- runAutoTaggingTestSuite({+ describe.skipIf(!apiKey || !modelId)('anthropic', async () => {+ await runAutoTaggingTestSuite({modelId: modelId!,config: overrideConfig({ ai: { adapters: { anthropic: { apiKey } } } }),});diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/auto-tagging.int.test-suites.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/auto-tagging.int.test-suites.tsindex 64bf9f10..59d41ac4 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/auto-tagging.int.test-suites.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/auto-tagging.int.test-suites.ts@@ -3,6 +3,12 @@ import type { Config } from '../../config/config.types';import { createAiServices } from '../../ai/ai.services';import { promptForAutoTagging } from '../auto-tagging.usecases';import type { Logger } from '@crowlog/logger';+import { createAiCreditsRepository } from '../../ai-credits/ai-credits.repository';+import { createInMemoryDatabase } from '../../app/database/database.test-utils';+import { createPlanEntitlementsRepository } from '../../plan-entitlements/plan-entitlements.repository';+import { createPlansRepository } from '../../plans/plans.repository';+import { createSubscriptionsRepository } from '../../subscriptions/subscriptions.repository';+import { createPlanEntitlementDefinitionRegistry } from '../../plan-entitlements/plan-entitlements.registry';const document = {name: 'acme-invoice-2026-06.pdf',@@ -13,6 +19,7 @@ const document = {'Web hosting services, June 2026','Total due: $1,250.00 - payment within 30 days',].join('\n'),+ organizationId: 'org_1',};const existingTags = [@@ -22,7 +29,7 @@ const existingTags = [{ id: 'tag_4', name: 'garden', description: 'Gardening and landscaping' },];-export function runAutoTaggingTestSuite({+export async function runAutoTaggingTestSuite({modelId,config,timeout = 20_000,@@ -31,8 +38,18 @@ export function runAutoTaggingTestSuite({config: Config;timeout?: number;}) {- // oxlint-disable-next-line no-console- const aiServices = createAiServices({ config, logger: { error: console.error } as Logger });+ const { db } = await createInMemoryDatabase();++ const aiServices = createAiServices({+ config,+ // oxlint-disable-next-line no-console+ logger: { error: console.error } as Logger,+ aiCreditsRepository: createAiCreditsRepository({ db }),+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),+ plansRepository: createPlansRepository({ config }),+ subscriptionsRepository: createSubscriptionsRepository({ db }),+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),+ });test('auto-tagging should correctly identify tags for a document', { timeout }, async () => {const { tagIdsToAdd, tagsToCreate } = await promptForAutoTagging({diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/deepseek.auto-tagging.int.test.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/deepseek.auto-tagging.int.test.tsindex 6b7eeeab..62568fd0 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/deepseek.auto-tagging.int.test.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/deepseek.auto-tagging.int.test.ts@@ -6,8 +6,8 @@ const apiKey = process.env.TEST_DEEPSEEK_API_KEY;const modelId = process.env.TEST_DEEPSEEK_MODEL_ID;describe('auto-tagging ai integration', () => {- describe.skipIf(!apiKey || !modelId)('deepseek', () => {- runAutoTaggingTestSuite({+ describe.skipIf(!apiKey || !modelId)('deepseek', async () => {+ await runAutoTaggingTestSuite({modelId: modelId!,config: overrideConfig({ ai: { adapters: { deepseek: { apiKey } } } }),});diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/mistral.auto-tagging.int.test.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/mistral.auto-tagging.int.test.tsindex 1be2e4c1..4928828f 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/mistral.auto-tagging.int.test.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/mistral.auto-tagging.int.test.ts@@ -6,8 +6,8 @@ const apiKey = process.env.TEST_MISTRAL_API_KEY;const modelId = process.env.TEST_MISTRAL_MODEL_ID;describe('auto-tagging ai integration', () => {- describe.skipIf(!apiKey || !modelId)('mistral', () => {- runAutoTaggingTestSuite({+ describe.skipIf(!apiKey || !modelId)('mistral', async () => {+ await runAutoTaggingTestSuite({modelId: modelId!,config: overrideConfig({ ai: { adapters: { mistral: { apiKey } } } }),});diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/ollama.auto-tagging.int.test.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/ollama.auto-tagging.int.test.tsindex 320a7f38..ad428b42 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/ollama.auto-tagging.int.test.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/ollama.auto-tagging.int.test.ts@@ -6,8 +6,8 @@ const baseUrl = process.env.TEST_OLLAMA_BASE_URL;const modelId = process.env.TEST_OLLAMA_MODEL_ID;describe('auto-tagging ai integration', () => {- describe.skipIf(!baseUrl || !modelId)('ollama', () => {- runAutoTaggingTestSuite({+ describe.skipIf(!baseUrl || !modelId)('ollama', async () => {+ await runAutoTaggingTestSuite({modelId: modelId!,config: overrideConfig({ ai: { adapters: { ollama: { baseUrl } } } }),});diff --git a/apps/papra-server/src/modules/auto-tagging/int-tests/openai.auto-tagging.int.test.ts b/apps/papra-server/src/modules/auto-tagging/int-tests/openai.auto-tagging.int.test.tsindex 01b62611..9d349fae 100644--- a/apps/papra-server/src/modules/auto-tagging/int-tests/openai.auto-tagging.int.test.ts+++ b/apps/papra-server/src/modules/auto-tagging/int-tests/openai.auto-tagging.int.test.ts@@ -6,8 +6,8 @@ const apiKey = process.env.TEST_OPENAI_API_KEY;const modelId = process.env.TEST_OPENAI_MODEL_ID;describe('auto-tagging ai integration', () => {- describe.skipIf(!apiKey || !modelId)('openai', () => {- runAutoTaggingTestSuite({+ describe.skipIf(!apiKey || !modelId)('openai', async () => {+ await runAutoTaggingTestSuite({modelId: modelId!,config: overrideConfig({ ai: { adapters: { openai: { apiKey } } } }),});diff --git a/apps/papra-server/src/modules/plans/plans.repository.test.ts b/apps/papra-server/src/modules/plans/plans.repository.test.tsindex 64075326..213632bf 100644--- a/apps/papra-server/src/modules/plans/plans.repository.test.ts+++ b/apps/papra-server/src/modules/plans/plans.repository.test.ts@@ -37,6 +37,7 @@ describe('plans repository', () => {maxIntakeEmailsCount: Number.POSITIVE_INFINITY,maxOrganizationsMembersCount: Number.POSITIVE_INFINITY,maxFileSize: Number.POSITIVE_INFINITY,+ aiCreditsPerMonth: Number.POSITIVE_INFINITY,});});});diff --git a/apps/papra-server/src/modules/plans/plans.repository.ts b/apps/papra-server/src/modules/plans/plans.repository.tsindex 4ea9c864..5247d1a5 100644--- a/apps/papra-server/src/modules/plans/plans.repository.ts+++ b/apps/papra-server/src/modules/plans/plans.repository.ts@@ -26,7 +26,7 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {const { isFreePlanUnlimited } = config.organizationPlans;const { maxUploadSize } = config.documentsStorage;- const freePlanLimits = {+ const freePlanLimits: OrganizationPlanRecord['limits'] = {maxDocumentStorageBytes: isFreePlanUnlimited? Number.POSITIVE_INFINITY: 500 * IN_BYTES.MEGABYTE,@@ -35,6 +35,7 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {maxFileSize: isDocumentSizeLimitEnabled({ maxUploadSize })? maxUploadSize: Number.POSITIVE_INFINITY,+ aiCreditsPerMonth: isFreePlanUnlimited ? Number.POSITIVE_INFINITY : 1_000,};const organizationPlans: Record<string, OrganizationPlanRecord> = {@@ -47,10 +48,10 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {id: PLAN_IDS.FREE_EXTENDED,name: 'Free Extended',limits: {+ ...freePlanLimits,maxDocumentStorageBytes: freePlanLimits.maxDocumentStorageBytes * 2,maxIntakeEmailsCount: freePlanLimits.maxIntakeEmailsCount * 2,maxOrganizationsMembersCount: freePlanLimits.maxOrganizationsMembersCount * 2,- maxFileSize: freePlanLimits.maxFileSize, // Same file size limit as Free plan},},[PLAN_IDS.PLUS]: {@@ -63,6 +64,7 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {maxIntakeEmailsCount: 10,maxOrganizationsMembersCount: 10,maxFileSize: 100 * IN_BYTES.MEGABYTE, // 100 MiB+ aiCreditsPerMonth: 5_000,},},[PLAN_IDS.PRO]: {@@ -75,6 +77,7 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {maxIntakeEmailsCount: 100,maxOrganizationsMembersCount: 50,maxFileSize: 500 * IN_BYTES.MEGABYTE, // 500 MiB+ aiCreditsPerMonth: 50_000,},},};diff --git a/apps/papra-server/src/modules/plans/plans.types.ts b/apps/papra-server/src/modules/plans/plans.types.tsindex 4357fd02..ec003054 100644--- a/apps/papra-server/src/modules/plans/plans.types.ts+++ b/apps/papra-server/src/modules/plans/plans.types.ts@@ -8,5 +8,6 @@ export type OrganizationPlanRecord = {maxFileSize: number;maxIntakeEmailsCount: number;maxOrganizationsMembersCount: number;+ aiCreditsPerMonth: number;};};diff --git a/apps/papra-server/src/modules/plans/plans.usecases.ts b/apps/papra-server/src/modules/plans/plans.usecases.tsindex b1d5d660..725db44b 100644--- a/apps/papra-server/src/modules/plans/plans.usecases.ts+++ b/apps/papra-server/src/modules/plans/plans.usecases.ts@@ -7,6 +7,30 @@ import { getApplyablePlanId } from './plans.models';import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';+export function createGetOrganizationPlanUsecase({+ subscriptionsRepository,+ plansRepository,+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+}: {+ subscriptionsRepository: SubscriptionsRepository;+ plansRepository: PlansRepository;+ planEntitlementsRepository: PlanEntitlementsRepository;+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;+}) {+ return async function getOrganizationPlanUsecase({ organizationId }: { organizationId: string }) {+ return getOrganizationPlan({+ organizationId,+ subscriptionsRepository,+ plansRepository,+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ });+ };+}++export type GetOrganizationPlanUsecase = ReturnType<typeof createGetOrganizationPlanUsecase>;+export async function getOrganizationPlan({organizationId,subscriptionsRepository,diff --git a/apps/papra-server/src/start.ts b/apps/papra-server/src/start.tsindex a54ab901..d41d973c 100644--- a/apps/papra-server/src/start.ts+++ b/apps/papra-server/src/start.ts@@ -26,6 +26,10 @@ import { createWebhookRepository } from './modules/webhooks/webhooks.repository'import { createWebhookTriggerServices } from './modules/webhooks/webhooks.trigger.services';import { createPlanEntitlementDefinitionRegistry } from './modules/plan-entitlements/plan-entitlements.registry';import { createAiServices } from './modules/ai/ai.services';+import { createAiCreditsRepository } from './modules/ai-credits/ai-credits.repository';+import { createPlansRepository } from './modules/plans/plans.repository';+import { createPlanEntitlementsRepository } from './modules/plan-entitlements/plan-entitlements.repository';+import { createSubscriptionsRepository } from './modules/subscriptions/subscriptions.repository';async function startWebMode({ logger, ...dependencies }: { logger: Logger } & GlobalDependencies) {const server = createServer(dependencies);@@ -74,7 +78,14 @@ async function buildServices({ config }: { config: Config }): Promise<GlobalDepe});const kvStore = buildKvStore({ config, db });const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });- const aiServices = createAiServices({ config });+ const aiServices = createAiServices({+ config,+ aiCreditsRepository: createAiCreditsRepository({ db }),+ planEntitlementDefinitionRegistry,+ plansRepository: createPlansRepository({ config }),+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),+ subscriptionsRepository: createSubscriptionsRepository({ db }),+ });// --- Services initializationawait taskServices.initialize();