@multileaf/ai-workflow 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-13
+
+### Added
+
+- Guided provider onboarding during interactive `aiw install`: each capability (semantic embedding, then decision triage) asks whether to configure it, offers Ollama or an external OpenAI-compatible provider (external only when Ollama is unreachable), lists the locally available models (embedding-only filtering for semantic), asks permission to run `ollama pull embeddinggemma-2` when no embedding models exist, collects endpoint URL, model name, and an optional token environment variable for external providers, and validates the setup with a live request before saving — with retry or skip on failure.
+- External provider support: `semantic` and `decision` settings accept `apiKeyEnv` (an uppercase environment variable name); the token is read from the environment at call time and never stored. Semantic requests go to `<baseUrl>/v1/embeddings` with bearer authentication and decision requests send `Authorization` headers.
+- Model usage reporting: every `aiw scan` states which models were actually used — embedding (chunks indexed or retrieval queries, batch request count, estimated tokens) and interpreter (model, facts inferred, scoped files, estimated tokens) — or reports `Models used: none (deterministic scan).`
+- Per-stage token estimates recorded in `.aiw/usage.yml` (`scan.embedding`, `scan.interpreter`) and inspectable with `aiw token-usage`. Token counts are local project state; telemetry never carries them.
+
+### Fixed
+
+- Interactive onboarding messages shortened to single-line prompts.
+- Embedding-model classification during onboarding now requires positive evidence (model name contains "embed" or Ollama family "embedding"); the previous heuristic misclassified `gpt-oss:20b` as an embedding model.
+## [0.5.0] - 2026-10-08
+
+### Added
+
+- Batched semantic indexing: embedding requests now use the Ollama batch endpoint (`POST /api/embed`) with up to 64 chunks per request instead of one request per chunk, and lockfiles and generated vendor manifests (`package-lock.json`, `yarn.lock`, `go.sum`, and others) are excluded from the index by default (`semantic.excludeLockfiles` overrides).
+- Optional decision-model re-ranking for `aiw semantic query --rerank`: when a decision model is enabled, each retrieved candidate is scored 0-1 for query relevance and the output is reordered with a reported ranking influence; cosine recall without a decision model is unchanged.
+- Semantic interpreter scoping during `aiw scan`: when semantic mapping is enabled and an index exists, the AI interpreter receives deterministic key files plus the top semantically relevant files for a profile-derived query instead of the alphabetically ordered file list, reducing token usage.
+- Built-in OpenAI-compatible `AiProvider` configured through an `ai` section in `.aiw/settings.yml` (for example Ollama `gpt-oss:20b`), so the scoped interpreter works without a host-injected provider; secrets redaction, token ceilings, and scoped-context validation apply unchanged, and missing configuration keeps scans deterministic and offline.
+- Advisory decision-model ranking for `aiw recommend`: when a decision model is enabled, recommendations are ordered by relevance to the confirmed profile and serialized with `decision_relevance` / `decision_confidence`; evidence states never change.
+- Telemetry consent during interactive `aiw install`, asked after the optional model questions with an explicit default of No, stating the exact event payload (command name and outcome only); the decision is recorded in `.aiw/settings.yml` and reversible through `aiw telemetry enable/disable`. Non-interactive installs skip the prompt.
+- Local telemetry buffer: when telemetry is enabled and no host client is present, events accumulate in a rotated `.aiw/telemetry-buffer.jsonl` (retention cap of 200 events); `aiw telemetry status --verbose` displays buffered events and `aiw telemetry disable` purges the buffer. No network transport was added.
+- Local model detection during interactive install: the installer probes the configured Ollama endpoint (`/api/tags`), lists the embedding and decision models actually available, and records the user's selection in `.aiw/settings.yml`; when no server or models are found it continues with defaults.
+
+### Changed
+
+- GitHub Actions now use Node 24-native `actions/checkout@v5` and `actions/setup-node@v5`, and CI runs on Node 24.
 ## [0.4.1] - 2026-10-08
 
 ### Fixed

package/README.md

@@ -19,7 +19,7 @@ AI-assisted development often relies on implicit prompts, duplicated configurati
 
 ## Installation
 
-The published package supports Node.js 18 or newer. Full development checks require Node.js 20.19 or newer for the current lint and test toolchain; CI runs on Node.js 20 and release validation runs on Node.js 24. Node.js 18 remains the declared runtime floor but is not currently in the release validation matrix.
+The published package supports Node.js 18 or newer. Full development checks require Node.js 20.19 or newer for the current lint and test toolchain; CI and release validation run on Node.js 24. Node.js 18 remains the declared runtime floor but is not currently in the release validation matrix.
 
 ```bash
 npx @multileaf/ai-workflow install --target codex
@@ -27,6 +27,8 @@ npx @multileaf/ai-workflow install --target codex
 
 Then run `/ai-init` in Codex. The bootstrap scans the repository, explains project-specific recommendations, and waits for the user's selections before installing optional resources.
 
+During an interactive install, AI Workflow also offers optional local capabilities after the base installation: it probes the configured Ollama endpoint, offers Ollama or an external OpenAI-compatible provider (endpoint URL plus an optional token environment variable), lists the embedding and decision models actually available, can run `ollama pull` for a default embedding model when none exist, and validates the chosen setup with a live request before recording it in `.aiw/settings.yml`. It then asks for telemetry consent with an explicit default of No (see [Privacy and security](#privacy-and-security)). Non-interactive installs skip every prompt.
+
 Supported targets are `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `universal`. Every command uses the same entry point:
 
 ```bash
@@ -241,6 +243,18 @@ Analysis uses two complementary layers:
 
 Detected facts cannot be replaced by conflicting AI output. Inferred facts remain unconfirmed until the user accepts, rejects, or edits them. Context selection excludes known sensitive filenames, binaries, dependencies, Git internals, generated output, and checkpoints, then applies pattern-based redaction. This is a defense-in-depth filter, not a general secret scanner; review eligible text before enabling an external AI provider.
 
+The interpreter accepts an injected provider from a host application, or a built-in OpenAI-compatible provider configured through an `ai` section in `.aiw/settings.yml` — for example a local Ollama model such as `gpt-oss:20b` — so scans can interpret projects without any host integration. Without the section, scans stay deterministic and offline. See [Project Intelligence](docs/project-intelligence.md).
+
+## Optional local models
+
+AI Workflow can use local models served by an OpenAI-compatible endpoint (Ollama by default) for three opt-in capabilities, all gated by `.aiw/settings.yml` sections and disabled by default:
+
+- **Semantic mapping** (`semantic` section): `aiw scan` builds a versioned chunk index with batched embedding requests, skipping lockfiles and generated vendor manifests; `aiw semantic query` returns ranked matches and can optionally re-rank them with the decision model (`--rerank`). When an index exists, the AI interpreter's context is scoped to deterministic key files plus the top semantically relevant files, reducing token usage. See [Semantic Mapping](docs/semantic-mapping.md).
+- **Advisory decision triage** (`decision` section): `aiw decision triage` returns advisory evidence-completeness and gate decisions with confidence, and `aiw recommend` orders capability recommendations by decision-model relevance to the confirmed profile. Ranking is advisory and never changes evidence states or bypasses human approval. See [Decision Model Evaluation](docs/decision-model-evaluation.md).
+- **Built-in AI interpretation** (`ai` section): the scoped project interpreter works without a host-injected provider.
+
+All model-driven features verify model availability before use and degrade to fully deterministic behavior when unconfigured. Every `aiw scan` reports which models were actually used — embedding (chunks indexed or retrieval queries) and interpreter (facts inferred, estimated tokens) — and records token estimates per stage in `.aiw/usage.yml`, inspectable with `aiw token-usage`. Token accounting is local project state; telemetry never carries token counts or any content.
+
 ## Resource packages and recommendations
 
 Resources are distributed as versioned packages that may contain:
@@ -326,10 +340,10 @@ The typed SDK is available from `@multileaf/ai-workflow/plugin-sdk`. It exports
 
 ## Privacy and security
 
-Telemetry is disabled by default and requires explicit consent. It records only approved aggregate fields through an injectable transport.
+Telemetry is disabled by default and requires explicit consent — offered once during interactive installation with an explicit default of No. Each event contains only the command name and its outcome; never arguments, file paths, or file contents. When telemetry is enabled but no host transport is configured, events accumulate in a rotated local buffer (`.aiw/telemetry-buffer.jsonl`, 200-event cap) that `aiw telemetry status --verbose` can inspect and `aiw telemetry disable` purges.
 
 ```bash
-npx @multileaf/ai-workflow telemetry status
+npx @multileaf/ai-workflow telemetry status --verbose
 npx @multileaf/ai-workflow telemetry enable
 npx @multileaf/ai-workflow telemetry disable
 ```
@@ -364,6 +378,9 @@ npm run release:check
 - [Quality and testing](docs/quality.md)
 - [Token efficiency](docs/token-efficiency.md)
 - [Multi-agent orchestration](docs/orchestration.md)
+- [Semantic mapping](docs/semantic-mapping.md)
+- [Decision model evaluation](docs/decision-model-evaluation.md)
+- [Telemetry and privacy](docs/telemetry.md)
 - [Release process](docs/release-process.md)
 
 ## License

package/dist/decision.d.ts

@@ -3,6 +3,7 @@ export type DecisionConfig = {
     enabled: boolean;
     model: string;
     baseUrl: string;
+    apiKeyEnv?: string;
 };
 export type DecisionQuestion = {
     type: "noul";
@@ -47,5 +48,18 @@ export declare function serializeDecisionConfig(config: DecisionConfig): string;
 export declare function parseDecisionConfig(text: string): DecisionConfig;
 export declare function loadDecisionConfig(fs: FileSystem, aiwPath: string): DecisionConfig | undefined;
 export declare function parseDecisionResponse(text: string): DecisionResponse;
-export declare function createOllamaDecisionProvider(config: DecisionConfig): DecisionProvider;
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare function createOllamaDecisionProvider(config: DecisionConfig, fetchImpl?: FetchLike, env?: Readonly<Record<string, string | undefined>>): DecisionProvider;
+export type RecommendationRankingCandidate = {
+    id: string;
+    rationale: string;
+    evidence: string[];
+};
+export declare function buildRecommendationRankingRequest(profileSummary: string, candidates: RecommendationRankingCandidate[]): DecisionRequest;
+export type SemanticRerankCandidate = {
+    id: string;
+    text: string;
+};
+export declare function buildSemanticRerankRequest(query: string, candidates: SemanticRerankCandidate[]): DecisionRequest;
 export declare function buildEvidenceTriageRequest(artifact: string): DecisionRequest;
+export {};

package/dist/decision.js

@@ -13,18 +13,22 @@ export function parseDecisionMapping(raw) {
     const enabled = record.enabled;
     const model = record.model;
     const baseUrl = record.baseUrl;
+    const apiKeyEnv = record.apiKeyEnv;
     if (typeof enabled !== "boolean")
         throw new Error("decision.enabled must be a boolean");
     if (!enabled)
         return { ...DEFAULT_DECISION_CONFIG, enabled: false };
+    if (apiKeyEnv !== undefined &&
+        (typeof apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)))
+        throw new Error("decision.apiKeyEnv must be an uppercase environment variable name");
     if (typeof model !== "string" || model.trim() === "")
         throw new Error("decision.model must be a non-empty string when decision mapping is enabled");
     if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
         throw new Error("decision.baseUrl must be an http(s) URL when decision mapping is enabled");
-    return { enabled: true, model, baseUrl };
+    return { enabled: true, model, baseUrl, ...(apiKeyEnv ? { apiKeyEnv } : {}) };
 }
 export function serializeDecisionConfig(config) {
-    return `decision:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}\n`;
+    return `decision:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}${config.apiKeyEnv ? `\n  apiKeyEnv: ${config.apiKeyEnv}` : ""}\n`;
 }
 export function parseDecisionConfig(text) {
     const document = parseDocument(text);
@@ -60,11 +64,19 @@ export function parseDecisionResponse(text) {
         result[key] = parseAnswer(value);
     return { model: parsed.model, answers: result };
 }
-export function createOllamaDecisionProvider(config) {
+export function createOllamaDecisionProvider(config, fetchImpl = (url, init) => fetch(url, init), env = process.env) {
+    const externalToken = config.apiKeyEnv ? env[config.apiKeyEnv] : undefined;
+    const authHeaders = (extra = {}) => externalToken ? { ...extra, authorization: `Bearer ${externalToken}` } : extra;
     return {
         async available() {
             try {
-                const response = await fetch(`${config.baseUrl}/api/tags`);
+                if (config.apiKeyEnv !== undefined) {
+                    const response = await fetchImpl(`${config.baseUrl}/v1/models`, {
+                        headers: authHeaders(),
+                    });
+                    return response.ok;
+                }
+                const response = await fetchImpl(`${config.baseUrl}/api/tags`);
                 if (!response.ok)
                     return false;
                 const body = (await response.json());
@@ -81,9 +93,9 @@ export function createOllamaDecisionProvider(config) {
             const questionCount = Object.keys(request.questions).length;
             if (questionCount === 0 || questionCount > 64)
                 throw new Error("Decision requests must contain between 1 and 64 questions");
-            const response = await fetch(`${config.baseUrl}/v1/systemone`, {
+            const response = await fetchImpl(`${config.baseUrl}/v1/systemone`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: authHeaders({ "content-type": "application/json" }),
                 body: JSON.stringify({
                     model: config.model,
                     state: request.state,
@@ -96,6 +108,31 @@ export function createOllamaDecisionProvider(config) {
         },
     };
 }
+export function buildRecommendationRankingRequest(profileSummary, candidates) {
+    const questions = {};
+    for (const candidate of candidates) {
+        questions[candidate.id] = {
+            type: "score",
+            instructions: `Confirmed project profile: ${profileSummary}.\nRate from 0 to 1 how relevant this capability recommendation is to that profile.\n\nRecommendation ${candidate.id}: ${candidate.rationale}\nEvidence: ${candidate.evidence.join(", ")}`,
+            criteria: [
+                "0 = irrelevant to the confirmed profile",
+                "1 = highly relevant to the confirmed profile",
+            ],
+        };
+    }
+    return { state: `Capability recommendation ranking for: ${profileSummary}`, questions };
+}
+export function buildSemanticRerankRequest(query, candidates) {
+    const questions = {};
+    for (const candidate of candidates) {
+        questions[candidate.id] = {
+            type: "score",
+            instructions: `Rate from 0 to 1 how well this retrieval candidate answers the user query "${query}".\n\nCandidate:\n${candidate.text}`,
+            criteria: ["0 = irrelevant to the query", "1 = directly and completely answers the query"],
+        };
+    }
+    return { state: `Semantic retrieval rerank for query: ${query}`, questions };
+}
 export function buildEvidenceTriageRequest(artifact) {
     return {
         state: artifact,

package/dist/interpreter.d.ts

@@ -1,5 +1,6 @@
 import type { EvidenceFact } from "./evidence.js";
 import type { ProjectProfile } from "./profile.js";
+import type { FileSystem } from "./types.js";
 export type InterpretationRequest = {
     profile: ProjectProfile;
     files: string[];
@@ -19,5 +20,20 @@ export type AiProvider = {
     generate(request: AiProviderRequest): Promise<string>;
 };
 export type ContextReader = (absolutePath: string) => Promise<string>;
-export declare function createInterpretationRequest(profile: ProjectProfile, files: string[], maxTokens?: number): InterpretationRequest;
+export type AiProviderConfig = {
+    enabled: boolean;
+    model: string;
+    baseUrl: string;
+    apiKeyEnv?: string;
+};
+export declare const DEFAULT_AI_PROVIDER_CONFIG: AiProviderConfig;
+export declare function parseAiProviderMapping(raw: unknown): AiProviderConfig;
+export declare function createInterpretationRequest(profile: ProjectProfile, files: string[], maxTokens?: number, priorityFiles?: string[]): InterpretationRequest;
+export declare const INTERPRETER_KEY_FILE_NAMES: string[];
+export declare function selectInterpreterKeyFiles(files: string[]): string[];
+export declare function buildInterpreterQuery(profile: ProjectProfile): string;
+type AiFetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare function loadAiProviderConfig(fs: FileSystem, aiwPath: string): AiProviderConfig | undefined;
+export declare function createOpenAiCompatibleProvider(config: AiProviderConfig, fetchImpl?: AiFetchLike, env?: Readonly<Record<string, string | undefined>>): AiProvider;
 export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader): Interpreter;
+export {};

package/dist/interpreter.js

@@ -1,5 +1,32 @@
 import { lstat, readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
+import { loadSettings } from "./settings.js";
+export const DEFAULT_AI_PROVIDER_CONFIG = {
+    enabled: false,
+    model: "gpt-oss:20b",
+    baseUrl: "http://localhost:11434",
+};
+export function parseAiProviderMapping(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("ai must be a YAML mapping");
+    const record = raw;
+    const enabled = record.enabled;
+    const model = record.model;
+    const baseUrl = record.baseUrl;
+    const apiKeyEnv = record.apiKeyEnv;
+    if (typeof enabled !== "boolean")
+        throw new Error("ai.enabled must be a boolean");
+    if (!enabled)
+        return { ...DEFAULT_AI_PROVIDER_CONFIG, enabled: false };
+    if (typeof model !== "string" || model.trim() === "")
+        throw new Error("ai.model must be a non-empty string when the AI provider is enabled");
+    if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
+        throw new Error("ai.baseUrl must be an http(s) URL when the AI provider is enabled");
+    if (apiKeyEnv !== undefined &&
+        (typeof apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)))
+        throw new Error("ai.apiKeyEnv must be an uppercase environment variable name");
+    return { enabled: true, model, baseUrl, ...(apiKeyEnv ? { apiKeyEnv } : {}) };
+}
 const EXCLUDED_SEGMENT = /(^|\/)(\.git|node_modules|vendor|\.venv|venv|dist|build|coverage|out|target|\.next|\.nuxt|\.output)(\/|$)/i;
 const EXCLUDED_AIW = /(^|\/)\.aiw\/(generated|checkpoints)(\/|$)/i;
 const SENSITIVE = /(^|\/)\.env(?:\.[^/]*)?$|\.(pem|key|p12|pfx|secret)$/i;
@@ -58,19 +85,62 @@ function isBinary(content) {
             (code >= 14 && code <= 31));
     });
 }
-export function createInterpretationRequest(profile, files, maxTokens = 4000) {
+export function createInterpretationRequest(profile, files, maxTokens = 4000, priorityFiles) {
     if (!Number.isInteger(maxTokens) || maxTokens <= 0)
         throw new Error("maxTokens must be a positive integer");
-    const selectedFiles = [
-        ...new Set(files.filter(safeFile).map((file) => file.replaceAll("\\", "/"))),
-    ].sort();
+    const safe = [...new Set(files.filter(safeFile).map((file) => file.replaceAll("\\", "/")))];
+    const priority = priorityFiles?.map((file) => file.replaceAll("\\", "/"));
+    const ordered = priority
+        ? [
+            ...new Set(priority.filter((file) => safe.includes(file))),
+            ...safe.filter((file) => !priority.includes(file)).sort(),
+        ]
+        : [...safe].sort();
     return {
         profile,
-        files: selectedFiles,
+        files: ordered,
         maxTokens,
-        estimatedTokens: Math.min(maxTokens, JSON.stringify(profile).length + selectedFiles.join("\n").length),
+        estimatedTokens: Math.min(maxTokens, JSON.stringify(profile).length + ordered.join("\n").length),
     };
 }
+export const INTERPRETER_KEY_FILE_NAMES = [
+    "readme.md",
+    "contributing.md",
+    "architecture.md",
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "go.mod",
+    "cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "composer.json",
+    "gemfile",
+    "deno.json",
+    "mix.exs",
+];
+export function selectInterpreterKeyFiles(files) {
+    const byBasename = new Map();
+    for (const file of files) {
+        const normalized = file.replaceAll("\\", "/");
+        const basename = normalized.split("/").pop()?.toLowerCase() ?? "";
+        if (basename && !byBasename.has(basename))
+            byBasename.set(basename, normalized);
+    }
+    return INTERPRETER_KEY_FILE_NAMES.flatMap((name) => {
+        const match = byBasename.get(name);
+        return match ? [match] : [];
+    });
+}
+export function buildInterpreterQuery(profile) {
+    const parts = [
+        profile.runtime.languages.join(", "),
+        profile.frameworks.join(", "),
+        profile.packageManager,
+    ].filter((part) => part && part !== "unknown");
+    return `Project conventions, architecture, and coding standards${parts.length > 0 ? ` for ${parts.join(" with ")}` : ""}`;
+}
 function parseFacts(output, allowedFiles) {
     let value;
     try {
@@ -109,6 +179,46 @@ function parseFacts(output, allowedFiles) {
         };
     });
 }
+export function loadAiProviderConfig(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings === undefined || !("ai" in settings))
+        return undefined;
+    return parseAiProviderMapping(settings.ai);
+}
+export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) => fetch(url, init), env = process.env) {
+    return {
+        async generate(request) {
+            const headers = { "content-type": "application/json" };
+            if (config.apiKeyEnv) {
+                const key = env[config.apiKeyEnv];
+                if (key)
+                    headers.authorization = `Bearer ${key}`;
+            }
+            const response = await fetchImpl(`${config.baseUrl}/v1/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    model: config.model,
+                    messages: [
+                        { role: "system", content: request.system },
+                        { role: "user", content: request.prompt },
+                    ],
+                    max_tokens: request.maxTokens,
+                    ...(request.responseFormat === "json"
+                        ? { response_format: { type: "json_object" } }
+                        : {}),
+                }),
+            });
+            if (!response.ok)
+                throw new Error(`AI provider request failed for model ${config.model}: ${await response.text()}`);
+            const body = (await response.json());
+            const content = body.choices?.[0]?.message?.content;
+            if (typeof content !== "string")
+                throw new Error(`AI provider ${config.model} returned no message content`);
+            return content;
+        },
+    };
+}
 export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path))) {
     const projectRoot = resolve(root);
     return {

package/dist/model-onboarding.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystem } from "./types.js";
+export type ConfirmQuestion = (question: string) => Promise<string>;
+export type OllamaModel = {
+    name: string;
+    embedding: boolean;
+};
+export type OnboardingRuntime = {
+    listOllamaModels(baseUrl: string): Promise<OllamaModel[] | undefined>;
+    pullOllamaModel(model: string): Promise<boolean>;
+    validateEmbedding(config: {
+        baseUrl: string;
+        model: string;
+        apiKeyEnv?: string;
+    }): Promise<boolean>;
+    validateDecision(config: {
+        baseUrl: string;
+        model: string;
+        apiKeyEnv?: string;
+    }): Promise<boolean>;
+};
+export declare const defaultOnboardingRuntime: OnboardingRuntime;
+export declare function configureOptionalModels(fs: FileSystem, aiwPath: string, answer: ConfirmQuestion, runtime?: OnboardingRuntime): Promise<string[]>;

package/dist/model-onboarding.js

@@ -0,0 +1,200 @@
+import { execFile } from "node:child_process";
+import { loadSettings, saveSettingsSection } from "./settings.js";
+import { DEFAULT_SEMANTIC_CONFIG, createOllamaEmbeddingProvider } from "./semantic.js";
+import { DEFAULT_DECISION_CONFIG, createOllamaDecisionProvider } from "./decision.js";
+const OLLAMA_BASE_URL = "http://localhost:11434";
+function isEmbeddingModel(name, families) {
+    if (name.toLowerCase().includes("embed"))
+        return true;
+    return families.some((family) => family.toLowerCase() === "embedding");
+}
+export const defaultOnboardingRuntime = {
+    async listOllamaModels(baseUrl) {
+        try {
+            const response = await fetch(`${baseUrl}/api/tags`);
+            if (!response.ok)
+                return undefined;
+            const body = (await response.json());
+            const models = (body.models ?? [])
+                .filter((entry) => typeof entry?.name === "string")
+                .map((entry) => ({
+                name: entry.name,
+                embedding: isEmbeddingModel(entry.name, entry.details?.families ?? []),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            return models;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    pullOllamaModel(model) {
+        return new Promise((resolve) => {
+            execFile("ollama", ["pull", model], { timeout: 10 * 60_000 }, (error) => resolve(error === null));
+        });
+    },
+    async validateEmbedding(config) {
+        try {
+            const provider = createOllamaEmbeddingProvider({
+                enabled: true,
+                model: config.model,
+                baseUrl: config.baseUrl,
+                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
+                topK: DEFAULT_SEMANTIC_CONFIG.topK,
+                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
+                ...(config.apiKeyEnv ? { apiKeyEnv: config.apiKeyEnv } : {}),
+            });
+            if (!(await provider.available()))
+                return false;
+            const vectors = await provider.embed(["aiw onboarding validation"]);
+            return vectors.length === 1 && vectors[0].length > 0;
+        }
+        catch {
+            return false;
+        }
+    },
+    async validateDecision(config) {
+        try {
+            const provider = createOllamaDecisionProvider({
+                enabled: true,
+                model: config.model,
+                baseUrl: config.baseUrl,
+                ...(config.apiKeyEnv ? { apiKeyEnv: config.apiKeyEnv } : {}),
+            });
+            return await provider.available();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+async function askYesNo(answer, question) {
+    const response = (await answer(question)).trim().toLowerCase();
+    return response === "y" || response === "yes";
+}
+async function pickFromList(answer, label, options, fallback) {
+    const menu = options.map((option, index) => `${index + 1}) ${option}`).join("\n");
+    const response = (await answer(`${menu}\nSelect ${label} [${fallback}]: `)).trim();
+    if (response === "")
+        return fallback;
+    const numeric = Number.parseInt(response, 10);
+    if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length)
+        return options[numeric - 1];
+    return options.includes(response) ? response : fallback;
+}
+function isValidEnvName(value) {
+    return /^[A-Z_][A-Z0-9_]*$/.test(value);
+}
+async function gatherCapabilitySetup(answer, runtime, options) {
+    const models = await runtime.listOllamaModels(OLLAMA_BASE_URL);
+    const ollamaUp = models !== undefined;
+    const provider = ollamaUp
+        ? (await pickFromList(answer, "provider", ["ollama", "external"], "ollama")) === "external"
+            ? "external"
+            : "ollama"
+        : (await answer(`Ollama not reachable at ${OLLAMA_BASE_URL}. Use an external provider. [Enter] `),
+            "external");
+    if (provider === "ollama") {
+        let candidates = (models ?? []).filter((model) => options.onlyEmbedding ? model.embedding : true);
+        if (candidates.length === 0 && options.onlyEmbedding) {
+            const pull = await askYesNo(answer, `No embedding models found. Pull ${options.pullModel}? [y/N] `);
+            if (pull) {
+                await answer(`Pulling ${options.pullModel}... [Enter] `);
+                const pulled = await runtime.pullOllamaModel(options.pullModel);
+                if (pulled) {
+                    const refreshed = await runtime.listOllamaModels(OLLAMA_BASE_URL);
+                    candidates = (refreshed ?? []).filter((model) => model.embedding);
+                }
+                else {
+                    await answer("Pull failed. Enter a model manually. [Enter] ");
+                }
+            }
+            if (candidates.length === 0) {
+                const manual = (await answer(`Model name to use [${options.pullModel}]: `)).trim();
+                if (manual.length === 0)
+                    return undefined;
+                return { baseUrl: OLLAMA_BASE_URL, model: manual };
+            }
+        }
+        const names = candidates.map((candidate) => candidate.name);
+        const fallback = names.includes(options.fallbackModel) ? options.fallbackModel : names[0];
+        const model = await pickFromList(answer, `${options.shortLabel} model`, names, fallback);
+        return { baseUrl: OLLAMA_BASE_URL, model };
+    }
+    const endpoint = (await answer(`Endpoint URL: `)).trim();
+    if (!/^https?:\/\//i.test(endpoint)) {
+        await answer("Invalid URL. [Enter] ");
+        return undefined;
+    }
+    const model = (await answer(`Model name: `)).trim();
+    if (model.length === 0) {
+        await answer("Model name required. [Enter] ");
+        return undefined;
+    }
+    const rawEnv = (await answer(`Token env var (empty for none): `)).trim();
+    if (rawEnv.length > 0 && !isValidEnvName(rawEnv)) {
+        await answer("Invalid env var name. [Enter] ");
+        return undefined;
+    }
+    return { baseUrl: endpoint, model, ...(rawEnv ? { apiKeyEnv: rawEnv } : {}) };
+}
+async function configureCapability(fs, aiwPath, answer, runtime, options) {
+    const wants = await askYesNo(answer, `Configure ${options.label}? [y/N] `);
+    if (!wants)
+        return [];
+    for (;;) {
+        const setup = await gatherCapabilitySetup(answer, runtime, options);
+        if (!setup)
+            return [];
+        const valid = options.section === "semantic"
+            ? await runtime.validateEmbedding(setup)
+            : await runtime.validateDecision(setup);
+        if (valid) {
+            saveSettingsSection(fs, aiwPath, options.section, options.serialize(setup));
+            return [
+                `${options.section} (${setup.model}${setup.apiKeyEnv ? ` via ${setup.baseUrl}` : ""})`,
+            ];
+        }
+        const retry = await askYesNo(answer, `Validation failed for ${setup.model}. Retry? [y/N] (No = skip for now) `);
+        if (!retry)
+            return [];
+    }
+}
+export async function configureOptionalModels(fs, aiwPath, answer, runtime = defaultOnboardingRuntime) {
+    const enabled = [];
+    const settings = loadSettings(fs, aiwPath) ?? {};
+    if (!("semantic" in settings))
+        enabled.push(...(await configureCapability(fs, aiwPath, answer, runtime, {
+            section: "semantic",
+            label: "semantic embedding",
+            shortLabel: "embedding",
+            onlyEmbedding: true,
+            fallbackModel: DEFAULT_SEMANTIC_CONFIG.model,
+            pullModel: DEFAULT_SEMANTIC_CONFIG.model,
+            serialize: (setup) => ({
+                enabled: true,
+                model: setup.model,
+                baseUrl: setup.baseUrl,
+                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
+                topK: DEFAULT_SEMANTIC_CONFIG.topK,
+                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
+                ...(setup.apiKeyEnv ? { apiKeyEnv: setup.apiKeyEnv } : {}),
+            }),
+        })));
+    if (!("decision" in settings))
+        enabled.push(...(await configureCapability(fs, aiwPath, answer, runtime, {
+            section: "decision",
+            label: "advisory decision triage",
+            shortLabel: "decision",
+            onlyEmbedding: false,
+            fallbackModel: DEFAULT_DECISION_CONFIG.model,
+            pullModel: DEFAULT_DECISION_CONFIG.model,
+            serialize: (setup) => ({
+                enabled: true,
+                model: setup.model,
+                baseUrl: setup.baseUrl,
+                ...(setup.apiKeyEnv ? { apiKeyEnv: setup.apiKeyEnv } : {}),
+            }),
+        })));
+    return enabled;
+}

package/dist/recommendations.d.ts

@@ -16,5 +16,20 @@ export type CapabilityRecommendation = {
     requires?: string[];
 };
 export declare function recommendCapabilities(profile: ProjectProfile): CapabilityRecommendation[];
+export type RecommendationRanking = {
+    id: string;
+    relevance: number;
+    confidence?: number;
+};
+export type RankedRecommendations = {
+    items: CapabilityRecommendation[];
+    ranking: RecommendationRanking[];
+    changedPositions: number;
+};
+export type DecisionRanker = (profile: ProjectProfile, recommendations: CapabilityRecommendation[]) => Promise<Record<string, {
+    relevance?: number;
+    confidence?: number;
+}>>;
+export declare function rankRecommendations(items: CapabilityRecommendation[], profile: ProjectProfile, ranker: DecisionRanker): Promise<RankedRecommendations>;
 export declare function resourcesForCapabilities(ids: string[]): RecommendedResource[];
-export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[]): string;
+export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[], ranking?: RecommendationRanking[]): string;