@mfittko/repo-wiki 0.2.1

package/dist/src/llm-provider.d.ts

@@ -0,0 +1,267 @@
+/**
+ * LLM provider boundary for wiki synthesis.
+ *
+ * Defines provider request/response interfaces, structured error handling,
+ * a deterministic mock provider for tests and local CI, and a factory that
+ * selects the correct provider from configuration.
+ *
+ * Usage (tests / CI without network):
+ *   const provider = createProvider();                  // defaults to mock
+ *   const provider = createProvider({ provider: 'mock' });
+ *
+ * Usage (OpenAI-compatible hosted provider):
+ *   const provider = createProvider({ provider: 'openai-compatible', apiKey: '...', model: '...' });
+ */
+import { type PageArchetype, type PromptContext } from './prompts.js';
+export declare const LLM_DEFAULTS: {
+    readonly provider: "mock";
+    readonly hostedProvider: "openai-compatible";
+    readonly model: "gpt-4.1-mini";
+    readonly baseUrl: "https://api.openai.com/v1";
+    readonly apiKeyEnv: "LLMWIKI_LLM_API_KEY";
+    readonly systemPrompt: "You compile source-grounded GitHub Wiki pages.";
+    readonly temperature: 0.1;
+    readonly maxOutputTokens: 4000;
+    readonly timeoutMs: 60000;
+    readonly retries: 2;
+    readonly validationRetries: 1;
+    readonly reasoningEffort: any;
+};
+export type { PageArchetype };
+export type { PromptContext };
+/** Input sent to an LLM provider for a single wiki page synthesis. */
+export interface LLMRequest {
+    /** Page archetype that selected the prompt template. */
+    archetype: PageArchetype;
+    /** Wiki page slug/filename without .md (e.g. "Module-Auth"). */
+    pageName: string;
+    /** Human-readable page title (e.g. "Auth"). */
+    pageTitle: string;
+    /** System-level instructions (authority rules, output contract). */
+    systemPrompt: string;
+    /** Page-specific user prompt including source cards and context. */
+    userPrompt: string;
+    /** Source commit for generated-page provenance. */
+    sourceCommit?: string;
+    /** Source repository remote for generated-page provenance. */
+    sourceRepo?: string;
+    /** Source paths cited by the assembled prompt context. */
+    sourcePaths?: string[];
+    /** Optional token budget for the completion. */
+    maxTokens?: number;
+    /** Optional sampling temperature. */
+    temperature?: number;
+    /** Optional reasoning effort for supported reasoning-family models. */
+    reasoningEffort?: ReasoningEffort;
+}
+/** Output returned by an LLM provider after synthesis. */
+export interface LLMResponse {
+    /** Generated markdown page content. */
+    content: string;
+    /** Identifier of the provider that produced the response. */
+    provider: string;
+    /** Prompt tokens consumed (informational; may be undefined for mock). */
+    promptTokens?: number;
+    /** Completion tokens consumed (informational; may be undefined for mock). */
+    completionTokens?: number;
+}
+/** Common interface every LLM backend must implement. */
+export interface LLMProvider {
+    /** Stable identifier for logging and frontmatter. */
+    readonly name: string;
+    /**
+     * Synthesise wiki page content for the given request.
+     * Throws `LLMProviderError` on unrecoverable failure.
+     */
+    complete(request: LLMRequest): Promise<LLMResponse>;
+}
+/**
+ * Thrown by providers and the factory for all LLM-related failures.
+ *
+ *   try { … } catch (err) {
+ *     if (err instanceof LLMProviderError && err.retryable) { … }
+ *   }
+ */
+export declare class LLMProviderError extends Error {
+    /** Identifier of the provider that raised the error. */
+    readonly provider: string;
+    /** Machine-readable code (e.g. 'MISSING_API_KEY', 'RATE_LIMIT'). */
+    readonly code: string | undefined;
+    /** True when the call may be retried after a short back-off. */
+    readonly retryable: boolean;
+    constructor(message: string, provider: string, code?: string, retryable?: boolean);
+}
+/**
+ * Deterministic provider for tests and local CI.
+ * Returns a minimal, reproducible markdown page for any request without
+ * making network calls or requiring API credentials.
+ */
+export declare class MockLLMProvider implements LLMProvider {
+    readonly name = "mock";
+    complete(request: LLMRequest): Promise<LLMResponse>;
+}
+export declare class OpenAICompatibleProvider implements LLMProvider {
+    readonly name = "openai-compatible";
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly timeoutMs: number;
+    readonly retries: number;
+    private readonly apiKey;
+    constructor(config: Required<Pick<LLMProviderConfig, 'apiKey' | 'model' | 'baseUrl' | 'timeoutMs' | 'retries'>>);
+    complete(request: LLMRequest): Promise<LLMResponse>;
+    private postWithRetries;
+    private post;
+}
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+/** Per-archetype LLM overrides for architecture synthesis requests. */
+export interface ArchitecturePageBudget {
+    /** Model override for architecture synthesis. */
+    model?: string;
+    /** Output-token budget override for architecture synthesis. */
+    max_output_tokens?: number;
+    /** Timeout override for architecture synthesis. */
+    timeout_ms?: number;
+    /** Reasoning effort override for architecture synthesis. */
+    reasoning_effort?: ReasoningEffort;
+}
+/** Per-archetype LLM override configuration. */
+export interface PageBudgets {
+    /** Overrides applied when synthesizing the Architecture page. */
+    architecture?: ArchitecturePageBudget;
+}
+/** Configuration passed to `createProvider`. */
+export interface LLMProviderConfig {
+    /**
+     * Provider identifier.
+     * Defaults to `"mock"` so that tests and non-LLM runs work without any
+     * further configuration.
+     */
+    provider?: string;
+    /** API key required by hosted providers. Not used by the mock provider. */
+    apiKey?: string;
+    /** Environment variable that contains the hosted provider API key. */
+    apiKeyEnv?: string;
+    /** JSON config alias for `apiKeyEnv`. */
+    api_key_env?: string;
+    /** Model identifier passed to hosted providers. */
+    model?: string;
+    /** Optional base URL override for self-hosted or proxy endpoints. */
+    baseUrl?: string;
+    /** JSON config alias for `baseUrl`. */
+    base_url?: string;
+    /** Optional system prompt override. */
+    systemPrompt?: string;
+    /** JSON config alias for `systemPrompt`. */
+    system_prompt?: string;
+    /** Optional file containing a system prompt override. */
+    systemPromptFile?: string;
+    /** JSON config alias for `systemPromptFile`. */
+    system_prompt_file?: string;
+    /** Optional sampling temperature. */
+    temperature?: number;
+    /** Optional output-token budget. */
+    maxOutputTokens?: number;
+    /** JSON config alias for `maxOutputTokens`. */
+    max_output_tokens?: number;
+    /** Hosted provider request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** JSON config alias for `timeoutMs`. */
+    timeout_ms?: number;
+    /** Optional reasoning effort for supported reasoning-family models. */
+    reasoningEffort?: ReasoningEffort;
+    /** JSON config alias for `reasoningEffort`. */
+    reasoning_effort?: ReasoningEffort;
+    /** Number of retries for retryable hosted provider failures. */
+    retries?: number;
+    /** Number of corrective retries after wiki patch validation failures. */
+    validationRetries?: number;
+    /** JSON config alias for `validationRetries`. */
+    validation_retries?: number;
+    /** Compiler mode alias used when callers pass the whole compiler config. */
+    mode?: string;
+    /** Nested LLM settings used when callers pass the whole compiler config. */
+    llm?: LLMProviderConfig;
+    /** Per-archetype LLM overrides (model, output budget, timeout, reasoning effort). */
+    page_budgets?: PageBudgets;
+}
+export interface ResolvedLLMProviderConfig extends LLMProviderConfig {
+    provider: string;
+    model: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    systemPrompt: string;
+    temperature: number;
+    maxOutputTokens: number;
+    timeoutMs: number;
+    reasoningEffort: ReasoningEffort | undefined;
+    retries: number;
+    validationRetries: number;
+}
+/**
+ * Create an `LLMProvider` from configuration resolved with environment overrides.
+ *
+ * - Omitting `config` returns the mock provider unless `LLMWIKI_LLM_PROVIDER`
+ *   or `LLMWIKI_COMPILER_MODE` selects a hosted provider.
+ * - Explicit `provider: "mock"` remains mock unless `LLMWIKI_LLM_PROVIDER` overrides it.
+ * - Specifying an OpenAI-compatible provider without an API key throws
+ *   `LLMProviderError` with `code: "MISSING_API_KEY"`.
+ * - Specifying an unknown provider name throws
+ *   `LLMProviderError` with `code: "UNKNOWN_PROVIDER"`.
+ *
+ * This makes missing configuration fail loudly rather than silently falling
+ * back to an unexpected behaviour.
+ */
+export declare function createProvider(config?: LLMProviderConfig): LLMProvider;
+/**
+ * Create an `LLMProvider` from an already-resolved config without re-reading
+ * environment variables. Use this when a caller has applied page/archetype
+ * overrides that must not be superseded by global env resolution a second time.
+ */
+export declare function createProviderFromResolvedConfig(resolved: ResolvedLLMProviderConfig): LLMProvider;
+/** Resolve provider configuration from defaults, explicit config, and env vars. */
+export declare function resolveProviderConfig(config?: LLMProviderConfig, env?: NodeJS.ProcessEnv): ResolvedLLMProviderConfig;
+export interface BuildRequestOptions extends Pick<LLMProviderConfig, 'systemPrompt' | 'temperature' | 'maxOutputTokens' | 'reasoningEffort'> {
+    /** Optional completion-token budget for the provider. */
+    maxTokens?: number;
+}
+/**
+ * Assemble an `LLMRequest` from a `PromptContext` using the standard prompt
+ * templates.  Callers can then pass the result directly to
+ * `provider.complete(request)`.
+ *
+ * @param archetype - Page archetype that selects the prompt template.
+ * @param context   - Assembled page context (source cards, doc cards, etc.).
+ * @param options   - Optional request-level prompt and generation settings.
+ */
+export declare function buildRequest(archetype: PageArchetype, context: PromptContext, options?: BuildRequestOptions): LLMRequest;
+export declare function buildRequest(archetype: PageArchetype, context: PromptContext, maxTokens?: number, config?: Pick<LLMProviderConfig, 'systemPrompt' | 'temperature' | 'maxOutputTokens' | 'reasoningEffort'>): LLMRequest;
+/**
+ * Resolved per-architecture overrides for model, output token budget, timeout,
+ * and reasoning effort. These supplement (not replace) the global provider
+ * config.
+ */
+export interface ResolvedArchitectureOverrides {
+    /** Architecture-specific model override, or undefined if not set. */
+    model: string | undefined;
+    /** Architecture-specific max output tokens override, or undefined if not set. */
+    maxOutputTokens: number | undefined;
+    /** Architecture-specific timeout override, or undefined if not set. */
+    timeoutMs: number | undefined;
+    /** Architecture-specific reasoning effort override, or undefined if not set. */
+    reasoningEffort: ReasoningEffort | undefined;
+}
+/**
+ * Resolve architecture-specific model, output-token, timeout, and
+ * reasoning-effort overrides.
+ *
+ * Precedence (highest to lowest):
+ * 1. Architecture-specific env vars (`LLMWIKI_LLM_ARCHITECTURE_*`)
+ * 2. Global env vars for the same setting (already applied by resolveProviderConfig)
+ * 3. `.llmwiki/config.json` `compiler.llm.page_budgets.architecture` overrides
+ * 4. Global config defaults (already applied by resolveProviderConfig)
+ * 5. Built-in defaults
+ *
+ * Returns only the fields that are explicitly overridden; callers fall back to
+ * the global resolved config for fields that are not set.
+ */
+export declare function resolveArchitectureOverrides(config?: LLMProviderConfig, env?: NodeJS.ProcessEnv): ResolvedArchitectureOverrides;