@123toto/ai-app-assistant-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 123toto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @123toto/ai-app-assistant-server
+
+Framework-neutral Node.js backend for contextual in-app AI documentation.
+
+```bash
+npm install @123toto/ai-app-assistant-server
+```
+
+Node.js 20 or later is required.
+
+## Minimal server
+
+```ts
+import { createAiDocsServer } from "@123toto/ai-app-assistant-server";
+
+const aiDocs = createAiDocsServer({
+  model: "mistral:mistral-small-latest",
+  documents,
+  http: {
+    resolveContext: request => auth.currentUser(request),
+    authorize: user => auth.requireAssistantAccess(user)
+  }
+});
+
+export const POST = (request: Request) => aiDocs.fetch.handle(request);
+```
+
+The selected provider reads its conventional API key from the backend environment. `allowAnonymous: true` is available only for deliberately public prototypes.
+
+## Managed server
+
+`createManagedAiDocsServer()` adds optional administration features without changing the minimal API:
+
+- provider and model discovery;
+- encrypted API-key persistence;
+- connection tests and key revocation;
+- access rules, quotas and audit history;
+- Redis synchronization across instances;
+- aggregated usage and normalized failure telemetry;
+- complete Fetch API handlers for chat and administration.
+
+```ts
+import { createManagedAiDocsServer } from "@123toto/ai-app-assistant-server";
+
+const aiDocs = createManagedAiDocsServer({
+  configuration: {
+    storage: { type: "redis", client: redis },
+    encryptionKey: process.env.AI_DOCS_SECRET_ENCRYPTION_KEY!,
+    defaultConfiguration: {
+      provider: "mistral",
+      model: "mistral-small-latest",
+      access: { mode: "all" }
+    },
+    resolveDefaultApiKey: () => process.env.MISTRAL_API_KEY
+  },
+  documents,
+  http: {
+    resolveIdentity: request => auth.currentUser(request),
+    authorizeAdministration: user => auth.requireAdmin(user)
+  }
+});
+
+await aiDocs.initialize();
+```
+
+Documents may also be loaded after application bootstrap with `aiDocs.setDocuments(documents)`.
+
+## Framework connectors
+
+```ts
+import { createManagedAiDocsExpressHandler } from "@123toto/ai-app-assistant-server/express";
+
+app.use("/api/ai-docs", createManagedAiDocsExpressHandler(aiDocs));
+```
+
+For Nest, import `createManagedAiDocsNestModule` from `@123toto/ai-app-assistant-server/nest`. Nest, RxJS and reflect-metadata are optional peer dependencies and are not required by other consumers.
+
+Native Node and Fetch-compatible runtimes can use `createAiDocsNodeHttpListener` or the standard `Request`/`Response` handlers.
+
+## Providers
+
+OpenAI, Anthropic, Mistral, Google/Gemini and Ollama are supported through `provider:model` identifiers. Consumers may inject any Vercel AI SDK model or implement the provider-neutral `AnswerGenerator` interface.
+
+## Telemetry
+
+The managed server records counts, durations, token usage and normalized failures. It never records questions, HTML, user identities or credentials. Redis persistence is selected automatically when managed Redis storage is configured; use `telemetry: false` to disable it.
+
+Full documentation: [github.com/123toto/ai-docs-asker](https://github.com/123toto/ai-docs-asker)

package/dist/ai-sdk-QImICd56.d.cts

@@ -0,0 +1,188 @@
+import { LanguageModel } from 'ai';
+import { ConversationMessage, EvidenceSource, GeneratedAnswer, TokenUsage } from '@123toto/ai-app-assistant-contracts';
+
+/** Minimal OpenAPI shape used by the optional documentation audit command. */
+interface OpenApiDocument {
+    openapi: string;
+    info?: {
+        title?: string;
+        description?: string;
+    };
+    paths?: Record<string, unknown>;
+    components?: {
+        schemas?: Record<string, unknown>;
+    };
+}
+/**
+ * A trusted document made available to the model for every question.
+ *
+ * `content` accepts JSON-compatible objects so an OpenAPI document can be
+ * supplied directly, without a dedicated integration or preprocessing step.
+ */
+interface DocumentationSource {
+    id: string;
+    title: string;
+    content: string | object;
+    mediaType?: string;
+}
+/** One bounded piece of information that may support the generated answer. */
+interface EvidenceItem {
+    source: EvidenceSource;
+    reference: string;
+    content: string;
+    relevance: number;
+}
+/** Input passed to an LLM adapter after local validation and preparation. */
+interface EvidenceBundle {
+    question: string;
+    locale: string;
+    /** Recent turns used only to resolve follow-up questions. */
+    conversation?: ConversationMessage[];
+    items: EvidenceItem[];
+}
+/** Context limits used to size evidence before it reaches a provider. */
+interface ModelCapabilities {
+    /** Total input and output window advertised by the selected model. */
+    contextWindowTokens: number;
+    /** Tokens kept available for the structured answer. */
+    maxOutputTokens: number;
+    /** Conservative tokenizer-independent estimate used for HTML and JSON. */
+    estimatedCharactersPerToken: number;
+}
+/** Observable progress produced while a provider builds a structured answer. */
+type GenerationProgress = {
+    type: "partial";
+    text: string;
+} | {
+    type: "retry";
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+};
+interface GenerationOptions {
+    signal?: AbortSignal;
+}
+/** Generated content plus optional provider accounting data. */
+type GenerationResult = GeneratedAnswer & {
+    usage?: TokenUsage;
+};
+/** Provider-neutral contract implemented by an LLM adapter. */
+interface AnswerGenerator {
+    readonly modelId: string;
+    /** Optional limits let the assistant adapt automatically to another model. */
+    readonly capabilities?: ModelCapabilities;
+    generate(input: EvidenceBundle, signal?: AbortSignal): Promise<GenerationResult>;
+    /** Optional progressive path. The non-streaming `generate` method remains supported. */
+    stream?(input: EvidenceBundle, options?: GenerationOptions): AsyncGenerator<GenerationProgress, GenerationResult>;
+}
+/** Configuration shared by all calls made through an assistant instance. */
+interface DocsAssistantOptions {
+    generator: AnswerGenerator;
+    /**
+     * Application documentation loaded and serialized once when the assistant is
+     * created. Markdown, OpenAPI JSON, wiki exports and similar text are all valid.
+     */
+    documents?: DocumentationSource[];
+    policies?: {
+        minimumEvidence?: number;
+        /** Maximum characters kept from the selected DOM element. */
+        maxSelectedElementEvidenceChars?: number;
+        /** Maximum characters kept from the complete rendered page. */
+        maxHtmlEvidenceChars?: number;
+        /** Maximum characters kept from one configured document. */
+        maxDocumentEvidenceChars?: number;
+        /** Maximum characters shared by all configured documents. */
+        maxDocumentTotalChars?: number;
+    };
+}
+
+/** Configuration for the Vercel AI SDK adapter. */
+interface AiSdkGeneratorOptions {
+    /**
+     * Native provider and model, or a model instance supplied by the consumer.
+     *
+     * Strings use `provider:model` (or `provider/model`) and read only the active
+     * provider's conventional environment variable. Provider packages are
+     * transitive dependencies, so the consumer installs only `@123toto/ai-app-assistant-server`.
+     */
+    model: LanguageModel;
+    /** Overrides the active provider's environment variable when needed. */
+    apiKey?: string;
+    /** Base URL used by the built-in Ollama connector. */
+    baseURL?: string;
+    /** Optional label exposed in response metadata. It is inferred by default. */
+    modelId?: string;
+    /** Maximum duration of the complete generation, including retries. */
+    timeoutMs?: number;
+    /** Maximum duration of one provider attempt within the total timeout. */
+    attemptTimeoutMs?: number;
+    /** Overrides automatic model context detection for custom or local models. */
+    contextWindowTokens?: number;
+    /** Tokens reserved for the structured response. */
+    maxOutputTokens?: number;
+    /** Actual answer ceiling sent to the provider. Defaults to 1,200 tokens. */
+    responseMaxOutputTokens?: number;
+    /** Automatic retries after the initial call. Defaults to five. */
+    maxRetries?: number;
+    /** Initial retry delay; mainly useful to shorten deterministic tests. */
+    retryBaseDelayMs?: number;
+}
+/** Options for the short real provider call used by configuration screens. */
+type AiSdkConnectionTestOptions = Pick<AiSdkGeneratorOptions, "apiKey" | "baseURL" | "model" | "timeoutMs">;
+/** Safe result that a host backend can return to an administrator. */
+type AiSdkConnectionTestResult = {
+    success: true;
+    model: string;
+    latencyMs: number;
+} | {
+    success: false;
+    model: string;
+    latencyMs: number;
+    error: {
+        code: AiSdkFailureCode;
+        message: string;
+        retryable: boolean;
+        providerStatus?: number;
+    };
+};
+/**
+ * Creates an answer generator backed by the Vercel AI SDK.
+ *
+ * String models call OpenAI, Anthropic, Mistral, Google or Ollama directly with
+ * the corresponding API key. Consumers can still inject any AI SDK
+ * `LanguageModel` instance to override the built-in provider resolution.
+ */
+declare function createAiSdkGenerator(options: AiSdkGeneratorOptions): AnswerGenerator;
+/**
+ * Makes one deliberately small structured-output call to validate credentials,
+ * model access and the capability required by the assistant.
+ */
+declare function testAiSdkConnection(options: AiSdkConnectionTestOptions): Promise<AiSdkConnectionTestResult>;
+/** Configuration error raised before any provider request is sent. */
+declare class AiSdkConfigurationError extends Error {
+    constructor(message: string);
+}
+type AiSdkFailureCode = "AUTHENTICATION" | "CANCELLED" | "CONFIGURATION" | "CONTEXT_LIMIT" | "NETWORK" | "PROVIDER_REJECTED" | "PROVIDER_UNAVAILABLE" | "RATE_LIMIT" | "STRUCTURED_OUTPUT" | "TIMEOUT" | "UNKNOWN";
+/**
+ * Stable diagnostic exposed after retries are exhausted. It carries no prompt,
+ * page HTML or API key, so a host backend can safely put it in operational logs.
+ */
+declare class AiSdkGenerationError extends Error {
+    readonly code: AiSdkFailureCode;
+    readonly attempts: number;
+    readonly retryable: boolean;
+    readonly providerStatus?: number;
+    constructor(input: {
+        code: AiSdkFailureCode;
+        attempts: number;
+        retryable: boolean;
+        message: string;
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+declare function normalizeAiSdkGenerationError(error: unknown, attempts: number): AiSdkGenerationError;
+/** Retries only failures that may succeed unchanged; configuration stays immediate. */
+declare function isRetryableProviderError(error: unknown): boolean;
+
+export { type AnswerGenerator as A, type DocumentationSource as D, type EvidenceBundle as E, type GenerationOptions as G, type ModelCapabilities as M, type OpenApiDocument as O, type DocsAssistantOptions as a, AiSdkConfigurationError as b, type AiSdkConnectionTestOptions as c, type AiSdkConnectionTestResult as d, type AiSdkFailureCode as e, AiSdkGenerationError as f, type AiSdkGeneratorOptions as g, type EvidenceItem as h, type GenerationProgress as i, createAiSdkGenerator as j, isRetryableProviderError as k, normalizeAiSdkGenerationError as n, testAiSdkConnection as t };

package/dist/ai-sdk-QImICd56.d.ts

@@ -0,0 +1,188 @@
+import { LanguageModel } from 'ai';
+import { ConversationMessage, EvidenceSource, GeneratedAnswer, TokenUsage } from '@123toto/ai-app-assistant-contracts';
+
+/** Minimal OpenAPI shape used by the optional documentation audit command. */
+interface OpenApiDocument {
+    openapi: string;
+    info?: {
+        title?: string;
+        description?: string;
+    };
+    paths?: Record<string, unknown>;
+    components?: {
+        schemas?: Record<string, unknown>;
+    };
+}
+/**
+ * A trusted document made available to the model for every question.
+ *
+ * `content` accepts JSON-compatible objects so an OpenAPI document can be
+ * supplied directly, without a dedicated integration or preprocessing step.
+ */
+interface DocumentationSource {
+    id: string;
+    title: string;
+    content: string | object;
+    mediaType?: string;
+}
+/** One bounded piece of information that may support the generated answer. */
+interface EvidenceItem {
+    source: EvidenceSource;
+    reference: string;
+    content: string;
+    relevance: number;
+}
+/** Input passed to an LLM adapter after local validation and preparation. */
+interface EvidenceBundle {
+    question: string;
+    locale: string;
+    /** Recent turns used only to resolve follow-up questions. */
+    conversation?: ConversationMessage[];
+    items: EvidenceItem[];
+}
+/** Context limits used to size evidence before it reaches a provider. */
+interface ModelCapabilities {
+    /** Total input and output window advertised by the selected model. */
+    contextWindowTokens: number;
+    /** Tokens kept available for the structured answer. */
+    maxOutputTokens: number;
+    /** Conservative tokenizer-independent estimate used for HTML and JSON. */
+    estimatedCharactersPerToken: number;
+}
+/** Observable progress produced while a provider builds a structured answer. */
+type GenerationProgress = {
+    type: "partial";
+    text: string;
+} | {
+    type: "retry";
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+};
+interface GenerationOptions {
+    signal?: AbortSignal;
+}
+/** Generated content plus optional provider accounting data. */
+type GenerationResult = GeneratedAnswer & {
+    usage?: TokenUsage;
+};
+/** Provider-neutral contract implemented by an LLM adapter. */
+interface AnswerGenerator {
+    readonly modelId: string;
+    /** Optional limits let the assistant adapt automatically to another model. */
+    readonly capabilities?: ModelCapabilities;
+    generate(input: EvidenceBundle, signal?: AbortSignal): Promise<GenerationResult>;
+    /** Optional progressive path. The non-streaming `generate` method remains supported. */
+    stream?(input: EvidenceBundle, options?: GenerationOptions): AsyncGenerator<GenerationProgress, GenerationResult>;
+}
+/** Configuration shared by all calls made through an assistant instance. */
+interface DocsAssistantOptions {
+    generator: AnswerGenerator;
+    /**
+     * Application documentation loaded and serialized once when the assistant is
+     * created. Markdown, OpenAPI JSON, wiki exports and similar text are all valid.
+     */
+    documents?: DocumentationSource[];
+    policies?: {
+        minimumEvidence?: number;
+        /** Maximum characters kept from the selected DOM element. */
+        maxSelectedElementEvidenceChars?: number;
+        /** Maximum characters kept from the complete rendered page. */
+        maxHtmlEvidenceChars?: number;
+        /** Maximum characters kept from one configured document. */
+        maxDocumentEvidenceChars?: number;
+        /** Maximum characters shared by all configured documents. */
+        maxDocumentTotalChars?: number;
+    };
+}
+
+/** Configuration for the Vercel AI SDK adapter. */
+interface AiSdkGeneratorOptions {
+    /**
+     * Native provider and model, or a model instance supplied by the consumer.
+     *
+     * Strings use `provider:model` (or `provider/model`) and read only the active
+     * provider's conventional environment variable. Provider packages are
+     * transitive dependencies, so the consumer installs only `@123toto/ai-app-assistant-server`.
+     */
+    model: LanguageModel;
+    /** Overrides the active provider's environment variable when needed. */
+    apiKey?: string;
+    /** Base URL used by the built-in Ollama connector. */
+    baseURL?: string;
+    /** Optional label exposed in response metadata. It is inferred by default. */
+    modelId?: string;
+    /** Maximum duration of the complete generation, including retries. */
+    timeoutMs?: number;
+    /** Maximum duration of one provider attempt within the total timeout. */
+    attemptTimeoutMs?: number;
+    /** Overrides automatic model context detection for custom or local models. */
+    contextWindowTokens?: number;
+    /** Tokens reserved for the structured response. */
+    maxOutputTokens?: number;
+    /** Actual answer ceiling sent to the provider. Defaults to 1,200 tokens. */
+    responseMaxOutputTokens?: number;
+    /** Automatic retries after the initial call. Defaults to five. */
+    maxRetries?: number;
+    /** Initial retry delay; mainly useful to shorten deterministic tests. */
+    retryBaseDelayMs?: number;
+}
+/** Options for the short real provider call used by configuration screens. */
+type AiSdkConnectionTestOptions = Pick<AiSdkGeneratorOptions, "apiKey" | "baseURL" | "model" | "timeoutMs">;
+/** Safe result that a host backend can return to an administrator. */
+type AiSdkConnectionTestResult = {
+    success: true;
+    model: string;
+    latencyMs: number;
+} | {
+    success: false;
+    model: string;
+    latencyMs: number;
+    error: {
+        code: AiSdkFailureCode;
+        message: string;
+        retryable: boolean;
+        providerStatus?: number;
+    };
+};
+/**
+ * Creates an answer generator backed by the Vercel AI SDK.
+ *
+ * String models call OpenAI, Anthropic, Mistral, Google or Ollama directly with
+ * the corresponding API key. Consumers can still inject any AI SDK
+ * `LanguageModel` instance to override the built-in provider resolution.
+ */
+declare function createAiSdkGenerator(options: AiSdkGeneratorOptions): AnswerGenerator;
+/**
+ * Makes one deliberately small structured-output call to validate credentials,
+ * model access and the capability required by the assistant.
+ */
+declare function testAiSdkConnection(options: AiSdkConnectionTestOptions): Promise<AiSdkConnectionTestResult>;
+/** Configuration error raised before any provider request is sent. */
+declare class AiSdkConfigurationError extends Error {
+    constructor(message: string);
+}
+type AiSdkFailureCode = "AUTHENTICATION" | "CANCELLED" | "CONFIGURATION" | "CONTEXT_LIMIT" | "NETWORK" | "PROVIDER_REJECTED" | "PROVIDER_UNAVAILABLE" | "RATE_LIMIT" | "STRUCTURED_OUTPUT" | "TIMEOUT" | "UNKNOWN";
+/**
+ * Stable diagnostic exposed after retries are exhausted. It carries no prompt,
+ * page HTML or API key, so a host backend can safely put it in operational logs.
+ */
+declare class AiSdkGenerationError extends Error {
+    readonly code: AiSdkFailureCode;
+    readonly attempts: number;
+    readonly retryable: boolean;
+    readonly providerStatus?: number;
+    constructor(input: {
+        code: AiSdkFailureCode;
+        attempts: number;
+        retryable: boolean;
+        message: string;
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+declare function normalizeAiSdkGenerationError(error: unknown, attempts: number): AiSdkGenerationError;
+/** Retries only failures that may succeed unchanged; configuration stays immediate. */
+declare function isRetryableProviderError(error: unknown): boolean;
+
+export { type AnswerGenerator as A, type DocumentationSource as D, type EvidenceBundle as E, type GenerationOptions as G, type ModelCapabilities as M, type OpenApiDocument as O, type DocsAssistantOptions as a, AiSdkConfigurationError as b, type AiSdkConnectionTestOptions as c, type AiSdkConnectionTestResult as d, type AiSdkFailureCode as e, AiSdkGenerationError as f, type AiSdkGeneratorOptions as g, type EvidenceItem as h, type GenerationProgress as i, createAiSdkGenerator as j, isRetryableProviderError as k, normalizeAiSdkGenerationError as n, testAiSdkConnection as t };