@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/models/core-ai-connection.model.ts

@@ -0,0 +1,330 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Prop, Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiConnectionDocument = CoreAiConnection & Document;
+
+/**
+ * Persisted configuration for an LLM connection (provider endpoint + model + key).
+ *
+ * Connections are the database-backed configuration the user emphasized: admins
+ * manage them at runtime (later via a frontend settings area) instead of editing
+ * `config.env.ts`. The API key is encrypted at rest ({@link AiCryptoService}) and
+ * NEVER returned through the API — only {@link hasApiKey} is exposed.
+ *
+ * The whole model is restricted to {@link RoleEnum.ADMIN}: only administrators may
+ * read or manage connections.
+ */
+@MongooseSchema({ collection: 'aiConnections', timestamps: true })
+@ObjectType({ description: 'AI connection configuration (LLM provider endpoint, model and credentials)' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiConnection extends CorePersistenceModel {
+  // ===================================================================================================================
+  // Properties
+  // ===================================================================================================================
+
+  /**
+   * AES-256-GCM-encrypted API key (`iv.tag.ciphertext`).
+   *
+   * Mongoose-only: NOT a GraphQL field, so it never appears in the GraphQL schema.
+   * It is read internally by the service (e.g. {@link CoreAiConnectionService.resolve})
+   * and stripped from every HTTP response by two layers: {@link securityCheck}
+   * (which also derives {@link hasApiKey}) and the global `secretFields` list
+   * (`apiKeyEncrypted` is a registered secret field). It deliberately carries no
+   * `@Restricted` so it survives the service `checkRestricted` step long enough for
+   * {@link securityCheck} to compute {@link hasApiKey}.
+   */
+  @Prop()
+  apiKeyEncrypted?: string = undefined;
+
+  /**
+   * Name of an environment variable used as API-key fallback when no key is
+   * stored in the database (e.g. 'AI_API_KEY').
+   */
+  @UnifiedField({
+    description: 'Name of the environment variable used as API-key fallback',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  apiKeyEnv?: string = undefined;
+
+  /**
+   * Base URL of the OpenAI-compatible endpoint.
+   */
+  @UnifiedField({
+    description: 'Base URL of the OpenAI-compatible endpoint (e.g. https://llm.example.com/v1)',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  baseUrl: string = undefined;
+
+  /**
+   * Free-form capability tags (e.g. 'analysis', 'ocr', 'both') for routing/UI.
+   */
+  @UnifiedField({
+    description: 'Capability tags of the model (free-form, e.g. analysis, ocr, vision)',
+    isArray: true,
+    isOptional: true,
+    mongoose: [String],
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  capabilities?: string[] = undefined;
+
+  /**
+   * Default maximum number of tokens for completions on this connection.
+   */
+  @UnifiedField({
+    description: 'Default maximum number of tokens for completions',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultMaxTokens?: number = undefined;
+
+  /**
+   * Total context window (input + output tokens) the model supports. Used to budget
+   * the assembled messages and trim/condense history when it would overflow. Falls
+   * back to `ai.contextWindow` config (default 8192) when unset.
+   */
+  @UnifiedField({
+    description: 'Total context window (tokens) the model supports; enables context-overflow handling',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  contextWindow?: number = undefined;
+
+  /**
+   * Default sampling temperature for completions on this connection.
+   */
+  @UnifiedField({
+    description: 'Default sampling temperature for completions',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultTemperature?: number = undefined;
+
+  /**
+   * Provider-side default token quota per user over the configured
+   * {@link defaultUserMaxPeriod}. Used as a soft fallback in the budget
+   * summary when no per-user / per-tenant hard limit is configured — the
+   * admin pins this per connection based on the provider's known plan
+   * (e.g. mittwald 100k tokens/day). Surfaces in the UI's token bar with
+   * `scope: 'llm'` and a "kumulativ" label.
+   *
+   * Zero / undefined disables the fallback for this connection.
+   */
+  @UnifiedField({
+    description: 'Provider-side soft user quota (tokens / period) used when no hard budget is set',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultUserMaxTokens?: number = undefined;
+
+  /**
+   * Aggregation period for {@link defaultUserMaxTokens}. Accepts the same
+   * values as `ai.budget.period` (`'day'`, `'month'`, `'none'`). Defaults
+   * to the configured `ai.budget.period` (or `'day'`) when unset.
+   */
+  @UnifiedField({
+    description: 'Period for the provider-side soft user quota (day | month | none)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  defaultUserMaxPeriod?: string = undefined;
+
+  /**
+   * Human-readable description.
+   */
+  @UnifiedField({
+    description: 'Human-readable description of the connection',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  description?: string = undefined;
+
+  /**
+   * Whether the connection is active and may be used.
+   */
+  @UnifiedField({
+    description: 'Whether the connection is enabled',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /**
+   * Admin-enforced globally: when true, this connection is mandated for all tenants
+   * and overrides any user/client/tenant selection (resolution layer 6).
+   */
+  @UnifiedField({
+    description: 'Admin-enforced for all tenants (overrides user/client/tenant selection)',
+    isOptional: true,
+    mongoose: { default: false },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enforced?: boolean = undefined;
+
+  /**
+   * Admin-enforced for specific tenants: this connection is mandated for the listed
+   * tenants (resolution layer 7, the most specific admin mandate).
+   */
+  @UnifiedField({
+    description: 'Tenant ids for which this connection is admin-enforced',
+    isArray: true,
+    isOptional: true,
+    mongoose: [String],
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  enforcedTenantIds?: string[] = undefined;
+
+  /**
+   * Whether an encrypted API key is currently stored. Computed, read-only;
+   * the plaintext key is never returned.
+   */
+  @UnifiedField({
+    description: 'Whether an API key is currently stored (the key itself is never returned)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  hasApiKey?: boolean = undefined;
+
+  /**
+   * Whether this is the default connection used when no connection is specified.
+   */
+  @UnifiedField({
+    description: 'Whether this is the default connection',
+    isOptional: true,
+    mongoose: { default: false },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  isDefault?: boolean = undefined;
+
+  /**
+   * Model id sent to the backend (e.g. 'gpt-oss-120b').
+   */
+  @UnifiedField({
+    description: 'Model id sent to the backend (e.g. gpt-oss-120b)',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  model: string = undefined;
+
+  /**
+   * Human-readable connection name.
+   */
+  @UnifiedField({
+    description: 'Human-readable connection name',
+    mongoose: { trim: true },
+    roles: RoleEnum.ADMIN,
+  })
+  name: string = undefined;
+
+  /**
+   * Provider implementation key (decides which provider builder is used).
+   */
+  @UnifiedField({
+    description: 'Provider type (e.g. openai-compatible)',
+    isOptional: true,
+    mongoose: { default: 'openai-compatible' },
+    roles: RoleEnum.ADMIN,
+  })
+  providerType?: string = undefined;
+
+  /**
+   * Whether the backend natively supports JSON / structured-output mode.
+   * When false, JSON is requested via the prompt and parsed defensively.
+   * Leave UNDEFINED to auto-detect on first use / on save (no mongoose default,
+   * so "not set" stays distinguishable from an explicit false).
+   */
+  @UnifiedField({
+    description: 'Whether the backend supports native JSON/structured-output mode (undefined = auto-detect)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsJsonResponse?: boolean = undefined;
+
+  /**
+   * Whether the backend natively supports function/tool calling. When false, tool
+   * calling is emulated via the system prompt. Leave UNDEFINED to auto-detect
+   * (no mongoose default, so "not set" stays distinguishable from an explicit false).
+   */
+  @UnifiedField({
+    description: 'Whether the backend supports native function/tool calling (undefined = auto-detect)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsNativeTools?: boolean = undefined;
+
+  /**
+   * Whether the model can process images.
+   */
+  @UnifiedField({
+    description: 'Whether the model supports vision (image input)',
+    isOptional: true,
+    mongoose: { default: false },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsVision?: boolean = undefined;
+
+  /**
+   * Tenants this connection is available to. Empty/undefined = available to ALL
+   * tenants (the global pool); otherwise restricted to the listed tenants. This is
+   * the per-tenant availability restriction of the overall selection.
+   */
+  @UnifiedField({
+    description: 'Tenant ids this connection is available to (empty = all tenants)',
+    isArray: true,
+    isOptional: true,
+    mongoose: [String],
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  tenantIds?: string[] = undefined;
+
+  // ===================================================================================================================
+  // Methods
+  // ===================================================================================================================
+
+  /**
+   * Compute the non-secret {@link hasApiKey} indicator and strip the encrypted
+   * key from every output. Runs via the CheckSecurityInterceptor on responses.
+   */
+  override securityCheck(user?: any, force?: boolean) {
+    this.hasApiKey = !!this.apiKeyEncrypted;
+    this.apiKeyEncrypted = undefined;
+    // Access to the whole model is already gated by @Restricted(ADMIN); nothing
+    // else to filter here. `force` and `user` are kept for signature symmetry.
+    void force;
+    void user;
+    return this;
+  }
+}
+
+export const AiConnectionSchema = SchemaFactory.createForClass(CoreAiConnection);

package/src/core/modules/ai/models/core-ai-conversation.model.ts

@@ -0,0 +1,87 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document, Schema } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+import { CoreAiMessage } from './core-ai-message.model';
+
+export type AiConversationDocument = CoreAiConversation & Document;
+
+/**
+ * A multi-turn AI conversation owned by a user.
+ *
+ * Messages are stored as a Mongoose Mixed subdocument array and only ever
+ * appended via `$push` (never round-tripped through `update()` — see the
+ * subdocument-array rule). Ownership is enforced by {@link securityCheck}:
+ * only the creator (or an admin) may read a conversation.
+ */
+@MongooseSchema({ collection: 'aiConversations', timestamps: true })
+@ObjectType({ description: 'A multi-turn AI conversation' })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiConversation extends CorePersistenceModel {
+  /**
+   * Id of the AI connection used for this conversation.
+   */
+  @UnifiedField({
+    description: 'Id of the AI connection used for this conversation',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.S_USER,
+  })
+  connectionId?: string = undefined;
+
+  /**
+   * Id of the user who created the conversation.
+   */
+  @UnifiedField({
+    description: 'Id of the user who created the conversation',
+    isOptional: true,
+    mongoose: { index: true, ref: 'User', type: Schema.Types.ObjectId },
+    roles: RoleEnum.S_USER,
+    type: () => String,
+  })
+  createdBy?: string = undefined;
+
+  /**
+   * Conversation messages (appended via $push).
+   */
+  @UnifiedField({
+    description: 'Conversation messages',
+    isArray: true,
+    isOptional: true,
+    mongoose: { default: [], type: [Schema.Types.Mixed] },
+    roles: RoleEnum.S_USER,
+    type: () => CoreAiMessage,
+  })
+  messages?: CoreAiMessage[] = undefined;
+
+  /**
+   * Human-readable title.
+   */
+  @UnifiedField({
+    description: 'Human-readable title',
+    isOptional: true,
+    mongoose: { trim: true },
+    roles: RoleEnum.S_USER,
+  })
+  title?: string = undefined;
+
+  /**
+   * Ownership check: only the creator or an admin may read a conversation.
+   */
+  override securityCheck(user?: any, force?: boolean) {
+    if (force) {
+      return this;
+    }
+    if (user && (user.hasRole?.(RoleEnum.ADMIN) || (this.createdBy && String(this.createdBy) === user.id))) {
+      return this;
+    }
+    // Hide conversations owned by other users (filtered out of list responses).
+    return undefined;
+  }
+}
+
+export const AiConversationSchema = SchemaFactory.createForClass(CoreAiConversation);

package/src/core/modules/ai/models/core-ai-interaction.model.ts

@@ -0,0 +1,145 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document, Schema } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { JSON } from '../../../common/scalars/json.scalar';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiInteractionDocument = CoreAiInteraction & Document;
+
+/**
+ * Audit record of a single AI prompt run.
+ *
+ * Persisted when `ai.audit` is enabled. Admin-only (compliance/debugging). The
+ * per-user history surfaced to end users is the conversation feature, not this log.
+ */
+@MongooseSchema({ collection: 'aiInteractions', timestamps: true })
+@ObjectType({ description: 'Audit record of an AI prompt run' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiInteraction extends CorePersistenceModel {
+  /**
+   * Tool actions executed during the run (name + success).
+   */
+  @UnifiedField({
+    description: 'Tool actions executed during the run',
+    isOptional: true,
+    mongoose: { type: Schema.Types.Mixed },
+    roles: RoleEnum.ADMIN,
+    type: () => JSON,
+  })
+  actions?: { name: string; success: boolean }[] = undefined;
+
+  /**
+   * Number of completion (output) tokens.
+   */
+  @UnifiedField({
+    description: 'Number of completion tokens',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  completionTokens?: number = undefined;
+
+  /**
+   * Id of the AI connection used.
+   */
+  @UnifiedField({
+    description: 'Id of the AI connection used',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  connectionId?: string = undefined;
+
+  /**
+   * Number of agent-loop iterations.
+   */
+  @UnifiedField({
+    description: 'Number of agent-loop iterations',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  iterations?: number = undefined;
+
+  /**
+   * The prompt text.
+   */
+  @UnifiedField({
+    description: 'The prompt text',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  prompt?: string = undefined;
+
+  /**
+   * Number of prompt (input) tokens.
+   */
+  @UnifiedField({
+    description: 'Number of prompt tokens',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  promptTokens?: number = undefined;
+
+  /**
+   * The natural-language answer returned to the user.
+   */
+  @UnifiedField({
+    description: 'The natural-language answer returned to the user',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  responseText?: string = undefined;
+
+  /**
+   * Tenant the prompt ran in (auto-set by the tenant plugin; used for per-tenant
+   * budget accounting). No manual index — the tenant plugin indexes `tenantId`.
+   */
+  @UnifiedField({
+    description: 'Tenant id the prompt ran in',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  tenantId?: string = undefined;
+
+  /**
+   * Total number of tokens.
+   */
+  @UnifiedField({
+    description: 'Total number of tokens',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  totalTokens?: number = undefined;
+
+  /**
+   * Id of the user who ran the prompt.
+   */
+  @UnifiedField({
+    // No single-field index: the compound { userId: 1, createdAt: 1 } below already
+    // serves userId-prefix lookups, so a standalone index would be redundant.
+    description: 'Id of the user who ran the prompt',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  userId?: string = undefined;
+}
+
+export const AiInteractionSchema = SchemaFactory.createForClass(CoreAiInteraction);
+// Compound indexes for the budget period query (userId/tenantId + createdAt range).
+AiInteractionSchema.index({ userId: 1, createdAt: 1 });
+AiInteractionSchema.index({ tenantId: 1, createdAt: 1 });

package/src/core/modules/ai/models/core-ai-message.model.ts

@@ -0,0 +1,29 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+
+/**
+ * A single message in an AI conversation (stored as a Mongoose Mixed subdocument).
+ */
+@ObjectType({ description: 'A message in an AI conversation' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class CoreAiMessage {
+  /**
+   * Message content.
+   */
+  @Field(() => String, { description: 'Message content' })
+  content: string;
+
+  /**
+   * Creation timestamp.
+   */
+  @Field(() => Date, { description: 'Creation timestamp', nullable: true })
+  createdAt?: Date;
+
+  /**
+   * Author role ('user' or 'assistant').
+   */
+  @Field(() => String, { description: "Author role ('user' or 'assistant')" })
+  role: string;
+}

package/src/core/modules/ai/models/core-ai-mode.model.ts

@@ -0,0 +1,93 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiModeDocument = CoreAiMode & Document;
+
+/**
+ * Admin-editable **named agent mode** — bundles a curated prompt scope, a
+ * restricted tool set, an optional model override, and optional role
+ * restrictions under a name like `support`, `audit`, `billing`. Activated by
+ * setting `CoreAiPromptInput.mode` to the mode's `name`.
+ *
+ * Modes are an opinionated, end-user-friendly way for admins to ship
+ * domain-specialized assistants without forking the orchestrator. Like every
+ * other ai layer, modes can only ADD restrictions; they cannot relax the
+ * permission model (`@Restricted` / `@Roles` / `authorize()` still apply).
+ */
+@MongooseSchema({ collection: 'aiModes', timestamps: true })
+@ObjectType({ description: 'Named agent mode' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiMode extends CorePersistenceModel {
+  /** Restrict the assistant to this whitelist of tool names. Empty = all role-permitted tools. */
+  @UnifiedField({
+    description: 'Whitelist of tool names available in this mode (empty = all role-permitted tools)',
+    isOptional: true,
+    mongoose: { default: [] },
+    roles: RoleEnum.ADMIN,
+    type: () => [String],
+  })
+  allowedTools?: string[] = undefined;
+
+  /** Force a specific LLM connection (overrides the resolution chain). */
+  @UnifiedField({
+    description: 'Force a specific LLM connection id when this mode is active',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  connectionId?: string = undefined;
+
+  /** Admin-facing description shown in any mode picker. */
+  @UnifiedField({
+    description: 'Admin-facing description',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  description?: string = undefined;
+
+  /** Whether the mode is active. */
+  @UnifiedField({
+    description: 'Whether the mode is enabled',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /** Unique mode name (used as `input.mode`). */
+  @UnifiedField({
+    description: 'Unique mode name',
+    mongoose: { unique: true },
+    roles: RoleEnum.ADMIN,
+  })
+  name: string = undefined;
+
+  /** Optional system-prompt override appended to the assembled base prompt. */
+  @UnifiedField({
+    description: 'Optional system-prompt addendum injected when the mode is active',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  promptAddendum?: string = undefined;
+
+  /** Restrict mode activation to users who have at least one of these roles. */
+  @UnifiedField({
+    description: 'Restrict the mode to users with at least one of these roles',
+    isOptional: true,
+    mongoose: { default: [] },
+    roles: RoleEnum.ADMIN,
+    type: () => [String],
+  })
+  roles?: string[] = undefined;
+}
+
+export const AiModeSchema = SchemaFactory.createForClass(CoreAiMode);