@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/interfaces/llm-provider.interface.ts

@@ -0,0 +1,187 @@
+/**
+ * Abstraction layer for Large Language Model (LLM) providers.
+ *
+ * A provider encapsulates the transport to an LLM backend — local runtimes or
+ * hosted endpoints, with or without native tool/JSON support. The orchestrator
+ * ({@link CoreAiService}) talks only to this interface, so backends can be
+ * swapped or extended without touching the agent loop. Nothing here is tied to a
+ * specific vendor.
+ *
+ * ## Capability gradations
+ *
+ * Backends differ in what they support. Providers therefore declare their
+ * {@link LlmCapabilities}, and the orchestrator compensates across the whole
+ * spectrum:
+ * - `nativeTools: true`  → tool schemas are passed natively and `toolCalls` are
+ *   read from the response.
+ * - `nativeTools: false` → tool calling is emulated: the tool catalog is injected
+ *   into the system prompt and a structured JSON block is parsed from the text.
+ * - `jsonResponse: true` → a JSON/structured-output mode is requested; otherwise
+ *   JSON is requested via the prompt and parsed defensively.
+ */
+export type LlmMessageRole = 'assistant' | 'system' | 'tool' | 'user';
+
+/**
+ * Capabilities a provider/backend supports. Used by the orchestrator to decide
+ * between native and emulated handling, so every gradation is supported.
+ */
+export interface LlmCapabilities {
+  /** Native JSON / structured-output mode (e.g. `response_format`). */
+  jsonResponse: boolean;
+
+  /** Native function/tool calling (the `tools` parameter). */
+  nativeTools: boolean;
+
+  /** Support for a `system` role message (true for virtually all backends). */
+  systemPrompt: boolean;
+}
+
+/**
+ * A multi-modal attachment (image / file) on a message. Providers that support
+ * vision/file inputs translate this into their native format (e.g. OpenAI's
+ * content-parts array with `image_url`); others ignore it.
+ */
+export interface LlmAttachment {
+  /** Inline base64 data — `data:<mime>;base64,<...>`. */
+  dataUrl?: string;
+  /** MIME type (e.g. `image/png`, `application/pdf`). */
+  mimeType: string;
+  /** Optional human-readable name. */
+  name?: string;
+  /** Public URL (alternative to `dataUrl`). */
+  url?: string;
+}
+
+/**
+ * A single chat message exchanged with the LLM.
+ */
+export interface LlmMessage {
+  /** Optional multi-modal attachments (images, files). */
+  attachments?: LlmAttachment[];
+
+  /** Plain-text content of the message. */
+  content: string;
+
+  /** Author role of the message. */
+  role: LlmMessageRole;
+}
+
+/**
+ * JSON-schema description of a tool the LLM may call.
+ */
+export interface LlmToolSchema {
+  /** Human-readable description used by the model to decide when to call the tool. */
+  description: string;
+
+  /** Unique tool name (snake_case recommended). */
+  name: string;
+
+  /** JSON schema of the tool's input arguments. */
+  parameters: Record<string, any>;
+}
+
+/**
+ * A tool invocation requested by the LLM.
+ */
+export interface LlmToolCall {
+  /** Parsed arguments for the tool. */
+  arguments: Record<string, any>;
+
+  /** Optional provider-specific call id (used by native tool calling). */
+  id?: string;
+
+  /** Name of the tool to call. */
+  name: string;
+}
+
+/**
+ * Token usage reported by the provider (best effort).
+ */
+export interface LlmUsage {
+  completionTokens?: number;
+  promptTokens?: number;
+  totalTokens?: number;
+}
+
+/**
+ * Per-request completion options. Values fall back to the connection defaults
+ * when omitted.
+ */
+export interface LlmCompletionOptions {
+  /** Maximum number of tokens to generate. */
+  maxTokens?: number;
+
+  /** Overrides the model id of the resolved connection. */
+  model?: string;
+
+  /** Sampling temperature. */
+  temperature?: number;
+
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number;
+}
+
+/**
+ * Normalized response of a single LLM completion.
+ */
+export interface LlmResponse {
+  /** Raw provider payload (for debugging/audit, never sent to clients). */
+  raw?: unknown;
+
+  /** Natural-language text content of the response. */
+  text: string;
+
+  /** Tool calls (only populated when {@link ILlmProvider.supportsNativeTools} is true). */
+  toolCalls?: LlmToolCall[];
+
+  /** Token usage (best effort). */
+  usage?: LlmUsage;
+}
+
+/**
+ * Result of capability auto-detection. Only the probed (previously undefined)
+ * flags are present; explicit flags are authoritative and never probed.
+ */
+export interface LlmDetectedCapabilities {
+  /** Detected `response_format` / JSON-mode support, or undefined if not probed. */
+  jsonResponse?: boolean;
+
+  /** Detected native tool-calling support, or undefined if not probed. */
+  nativeTools?: boolean;
+}
+
+/**
+ * Provider abstraction. Implementations are created per request by the
+ * {@link LlmProviderFactory} from a persisted {@link CoreAiConnection}.
+ */
+export interface ILlmProvider {
+  /** Declared capabilities of the backend (drives native vs. emulated handling). */
+  readonly capabilities: LlmCapabilities;
+
+  /** Identifier of the provider implementation (e.g. 'openai-compatible'). */
+  readonly name: string;
+
+  /**
+   * Run a chat completion.
+   *
+   * @param messages Conversation so far (system + user + assistant + tool).
+   * @param tools Tool schemas the model may use (ignored when not supported).
+   * @param options Per-request completion options.
+   */
+  chat(messages: LlmMessage[], tools: LlmToolSchema[], options?: LlmCompletionOptions): Promise<LlmResponse>;
+
+  /**
+   * Optionally probe the backend to auto-detect capabilities for connection flags
+   * that were left undefined (provider-agnostic best effort). Implementations that
+   * cannot probe simply omit this method. Should resolve only the undefined flags
+   * and throw on a transport error so callers can treat the connection as undetected.
+   */
+  detectCapabilities?(): Promise<LlmDetectedCapabilities>;
+
+  /**
+   * Optionally determine the model's total context window (tokens) automatically —
+   * e.g. from a known-model table or backend metadata. Returns `undefined` when it
+   * cannot be determined. Implementations that cannot detect it omit this method.
+   */
+  detectContextWindow?(): Promise<number | undefined>;
+}

package/src/core/modules/ai/interfaces/resolved-ai-connection.interface.ts

@@ -0,0 +1,55 @@
+/**
+ * A fully resolved AI connection ready to instantiate a provider.
+ *
+ * This is the runtime shape produced by {@link CoreAiConnectionService.resolve}
+ * after reading the persisted {@link CoreAiConnection} and decrypting its API
+ * key. It is system-internal and MUST NOT be returned to clients (it carries the
+ * plaintext API key).
+ */
+export interface ResolvedAiConnection {
+  /** Plaintext API key (decrypted or read from the env fallback). May be empty for keyless local backends. */
+  apiKey: string;
+
+  /** Base URL of the OpenAI-compatible endpoint (e.g. 'https://llm.example.com/v1'). */
+  baseUrl: string;
+
+  /** Total context window (input + output tokens) the model supports, if known. */
+  contextWindow?: number;
+
+  /** Default maximum number of tokens for completions. */
+  defaultMaxTokens?: number;
+
+  /** Default sampling temperature. */
+  defaultTemperature?: number;
+
+  /**
+   * Provider-side soft user quota (tokens) over {@link defaultUserMaxPeriod}.
+   * Used as a fallback in the budget summary when no user / tenant hard limit
+   * is configured.
+   */
+  defaultUserMaxTokens?: number;
+
+  /** Period for {@link defaultUserMaxTokens} (`day` | `month` | `none`). */
+  defaultUserMaxPeriod?: string;
+
+  /** Connection id (for audit/logging). */
+  id: string;
+
+  /** Model id sent to the backend (e.g. 'gpt-oss-120b'). */
+  model: string;
+
+  /** Human-readable connection name. */
+  name: string;
+
+  /** Provider implementation key (e.g. 'openai-compatible'). */
+  providerType: string;
+
+  /** Whether the backend natively supports JSON/structured-output mode. */
+  supportsJsonResponse?: boolean;
+
+  /** Whether the backend natively supports function/tool calling. */
+  supportsNativeTools?: boolean;
+
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number;
+}

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

@@ -0,0 +1,37 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { JSON } from '../../../common/scalars/json.scalar';
+
+/**
+ * A single tool execution performed during an AI prompt — surfaced to the
+ * frontend for transparency (what the assistant actually did).
+ */
+@ObjectType({ description: 'A tool action executed during an AI prompt' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class CoreAiAction {
+  /**
+   * Arguments the tool was called with.
+   */
+  @Field(() => JSON, { description: 'Arguments the tool was called with', nullable: true })
+  arguments?: Record<string, any>;
+
+  /**
+   * Name of the executed tool.
+   */
+  @Field(() => String, { description: 'Name of the executed tool' })
+  name: string;
+
+  /**
+   * Result payload returned by the tool (already permission-filtered).
+   */
+  @Field(() => JSON, { description: 'Result returned by the tool', nullable: true })
+  result?: unknown;
+
+  /**
+   * Whether the tool executed successfully.
+   */
+  @Field(() => Boolean, { description: 'Whether the tool executed successfully' })
+  success: boolean;
+}

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

@@ -0,0 +1,42 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+
+/**
+ * A connection the current user/tenant may use, in a non-sensitive shape safe to
+ * return to any authenticated user (no API key, no base URL).
+ *
+ * Returned by the `aiAvailableConnections` query / `GET /ai/connections/available`
+ * so a client can offer a connection picker. `selected` marks the connection that
+ * the resolution chain currently resolves to for the caller; `locked` signals that
+ * the selection is dictated by a mandatory layer (admin- or tenant-enforced) and
+ * cannot be overridden by the user.
+ */
+@ObjectType({ description: 'An AI connection available to the current user/tenant' })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiAvailableConnection {
+  /** The connection id. */
+  @Field(() => String, { description: 'The connection id' })
+  id: string;
+
+  /** Whether this is the global default connection. */
+  @Field(() => Boolean, { description: 'Whether this is the global default connection' })
+  isDefault: boolean;
+
+  /** Whether the selection is dictated by a mandatory layer (cannot be changed by the user). */
+  @Field(() => Boolean, { description: 'Whether the selection is enforced and cannot be changed by the user' })
+  locked: boolean;
+
+  /** The model id used by the connection (for display). */
+  @Field(() => String, { description: 'The model id used by the connection', nullable: true })
+  model?: string;
+
+  /** The display name of the connection. */
+  @Field(() => String, { description: 'The display name of the connection', nullable: true })
+  name?: string;
+
+  /** Whether this connection is the one currently resolved for the caller. */
+  @Field(() => Boolean, { description: 'Whether this connection is currently resolved for the caller' })
+  selected: boolean;
+}

package/src/core/modules/ai/models/core-ai-budget-limit.model.ts

@@ -0,0 +1,82 @@
+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 AiBudgetLimitDocument = CoreAiBudgetLimit & Document;
+
+/**
+ * Admin-configured token/prompt limit override for a specific user or tenant.
+ *
+ * Overrides the config defaults (`ai.budget.user` / `ai.budget.tenant`). A missing
+ * or `0`/undefined `maxTokens`/`maxPrompts` means unlimited for that dimension.
+ * Deliberately has NO `tenantId` path so it is NOT tenant-scoped — admins manage
+ * all limits globally.
+ */
+@MongooseSchema({ collection: 'aiBudgetLimits', timestamps: true })
+@ObjectType({ description: 'Admin-configured AI token/prompt limit for a user or tenant' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiBudgetLimit extends CorePersistenceModel {
+  /**
+   * Maximum number of prompts per reset period (undefined/0 = unlimited).
+   */
+  @UnifiedField({
+    description: 'Maximum number of prompts per reset period (0/undefined = unlimited)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  maxPrompts?: number = undefined;
+
+  /**
+   * Maximum number of tokens per reset period (undefined/0 = unlimited).
+   */
+  @UnifiedField({
+    description: 'Maximum number of tokens per reset period (0/undefined = unlimited)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  maxTokens?: number = undefined;
+
+  /**
+   * Reset period: 'day', 'month' or 'none' (no reset). Defaults to the config period.
+   */
+  @UnifiedField({
+    description: "Reset period: 'day', 'month' or 'none'",
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  period?: string = undefined;
+
+  /**
+   * Id of the user or tenant this limit applies to.
+   */
+  @UnifiedField({
+    description: 'Id of the user or tenant this limit applies to',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  refId: string = undefined;
+
+  /**
+   * Scope of the limit: 'user' or 'tenant'.
+   */
+  @UnifiedField({
+    description: "Scope of the limit: 'user' or 'tenant'",
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  scope: string = undefined;
+}
+
+export const AiBudgetLimitSchema = SchemaFactory.createForClass(CoreAiBudgetLimit);
+// Compound index: one limit per (scope, refId).
+AiBudgetLimitSchema.index({ scope: 1, refId: 1 }, { unique: true });

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

@@ -0,0 +1,72 @@
+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 AiConnectionPreferenceDocument = CoreAiConnectionPreference & Document;
+
+/**
+ * A connection preference for a tenant or a user — the configurable layers of the
+ * connection-resolution chain that are NOT platform-admin connection flags:
+ *
+ * - `scope: 'tenant'`, `enforced: false` → the tenant's default connection (layer 2)
+ * - `scope: 'user'` → the user's default connection (layer 3)
+ * - `scope: 'tenant'`, `enforced: true` → tenant-enforced connection (layer 5)
+ *
+ * `refId` is the tenant id or user id. Unique per `(scope, refId)`.
+ */
+@MongooseSchema({ collection: 'aiConnectionPreferences', timestamps: true })
+@ObjectType({ description: 'AI connection preference for a tenant or user' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiConnectionPreference extends CorePersistenceModel {
+  /**
+   * The selected connection id.
+   */
+  @UnifiedField({
+    description: 'The selected connection id',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  connectionId: string = undefined;
+
+  /**
+   * For tenant scope: whether the connection is enforced (mandatory for the tenant's
+   * users, overriding user/client selection). Ignored for user scope.
+   */
+  @UnifiedField({
+    description: 'Whether the tenant connection is enforced (tenant scope only)',
+    isOptional: true,
+    mongoose: { default: false },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enforced?: boolean = undefined;
+
+  /**
+   * The tenant id or user id this preference belongs to.
+   */
+  @UnifiedField({
+    description: 'The tenant id or user id this preference belongs to',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  refId: string = undefined;
+
+  /**
+   * Scope of the preference: 'tenant' or 'user'.
+   */
+  @UnifiedField({
+    description: "Scope of the preference: 'tenant' or 'user'",
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  scope: string = undefined;
+}
+
+export const AiConnectionPreferenceSchema = SchemaFactory.createForClass(CoreAiConnectionPreference);
+// One preference per (scope, refId).
+AiConnectionPreferenceSchema.index({ scope: 1, refId: 1 }, { unique: true });