@shrkcrft/ai 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/pipeline/enhancement-pipeline.js

@@ -0,0 +1,339 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AiMessageRole } from "../ai-request.js";
+/**
+ * Identifier for a stage in the multi-pass enhancement pipeline.
+ *
+ * The default Claude-agent-oriented pipeline runs `draft → critique →
+ * refine → polish`. Callers may pass a custom stage list to truncate,
+ * extend, or rearrange the flow.
+ */
+export var EnhancementStageKind;
+(function (EnhancementStageKind) {
+    EnhancementStageKind["Draft"] = "draft";
+    EnhancementStageKind["Critique"] = "critique";
+    EnhancementStageKind["Refine"] = "refine";
+    EnhancementStageKind["Polish"] = "polish";
+})(EnhancementStageKind || (EnhancementStageKind = {}));
+/**
+ * Multi-pass refinement pipeline that turns a deterministic brief into
+ * a denser, more agent-ready artefact by making the LLM critique and
+ * rewrite its own work.
+ *
+ * Design contract:
+ *   - When no provider is supplied, the pipeline returns the
+ *     `originalContext` unchanged and flags `deterministicFallback`.
+ *     The deterministic engine remains the source of truth.
+ *   - When a provider is supplied, every stage call is retried-once on
+ *     failure; a permanently-failed stage degrades to the previous
+ *     stage's output (the pipeline never throws and never produces
+ *     less than the deterministic input).
+ *   - Stages compose: a caller can pass a 2-stage `[draft, polish]`
+ *     pipeline for fast paths, or extend with custom critique prompts
+ *     for project-specific quality bars.
+ *
+ * Why a pipeline (vs. a single rich prompt): small local models behave
+ * dramatically better when asked to "find the gaps in this draft" than
+ * when asked to "write the perfect brief in one shot". The critique
+ * pass surfaces vague claims and missing evidence; the refine pass
+ * fixes them; the polish pass enforces Claude-agent ergonomics
+ * (file:line refs, explicit next commands, terse bullets).
+ */
+export class EnhancementPipeline {
+    stages;
+    constructor(stages) {
+        this.stages = stages;
+    }
+    async run(input, provider, options = {}) {
+        if (!provider) {
+            return ok({
+                finalOutput: input.originalContext,
+                stages: [],
+                totalUsage: { inputTokens: 0, outputTokens: 0 },
+                deterministicFallback: true,
+                budgetExhausted: false,
+            });
+        }
+        const cap = options.maxPasses ?? this.stages.length;
+        const plan = this.stages.slice(0, Math.max(1, cap));
+        const stagesOut = [];
+        const totalUsage = { inputTokens: 0, outputTokens: 0 };
+        let previous = '';
+        let lastCritique;
+        let lastGood = input.originalContext;
+        const startedAt = Date.now();
+        let budgetExhausted = false;
+        for (let i = 0; i < plan.length; i += 1) {
+            // Wall-clock budget guard: stop before starting a stage we have no time
+            // for, and keep the best output produced so far.
+            const remaining = options.budgetMs !== undefined ? options.budgetMs - (Date.now() - startedAt) : undefined;
+            if (remaining !== undefined && remaining <= MIN_STAGE_BUDGET_MS) {
+                budgetExhausted = true;
+                break;
+            }
+            const stage = plan[i];
+            const messages = stage.buildMessages({
+                originalContext: input.originalContext,
+                task: input.task,
+                previous,
+                lastCritique,
+            });
+            // Effective per-call timeout = min(configured per-stage, remaining budget).
+            const perStageTimeout = effectiveTimeout(options.perStageTimeoutMs, remaining);
+            const stageResult = await callOnceWithRetry(provider, {
+                messages,
+                maxTokens: options.maxTokensPerStage ?? 4096,
+                temperature: options.temperature ?? 0.2,
+                ...(options.model ? { model: options.model } : {}),
+                ...(perStageTimeout !== undefined ? { timeoutMs: perStageTimeout } : {}),
+            });
+            const onStage = options.onStage;
+            if (!stageResult.ok) {
+                stagesOut.push({
+                    kind: stage.kind,
+                    content: lastGood,
+                    model: options.model ?? '',
+                    degraded: true,
+                    errorMessage: stageResult.error.message,
+                });
+                if (onStage)
+                    onStage({ kind: stage.kind, ok: false, pass: i + 1, total: plan.length });
+                // Stage failed: keep last-good output but allow the pipeline to
+                // continue. A failed `critique` is recoverable (`refine` just
+                // gets no critique). A failed `refine` falls back to the prior
+                // draft. A failed `polish` returns the refined draft.
+                previous = lastGood;
+                continue;
+            }
+            const content = (stageResult.value.content ?? '').trim();
+            const usage = stageResult.value.usage ?? {};
+            if (typeof usage.inputTokens === 'number')
+                totalUsage.inputTokens += usage.inputTokens;
+            if (typeof usage.outputTokens === 'number')
+                totalUsage.outputTokens += usage.outputTokens;
+            stagesOut.push({
+                kind: stage.kind,
+                content,
+                model: stageResult.value.model,
+                ...(usage.inputTokens || usage.outputTokens ? { usage } : {}),
+            });
+            if (stage.kind === EnhancementStageKind.Critique) {
+                lastCritique = content;
+                // Critique is not a candidate for `finalOutput` — keep the
+                // previous draft as the running best.
+            }
+            else {
+                previous = content;
+                lastGood = content;
+            }
+            if (onStage)
+                onStage({ kind: stage.kind, ok: true, pass: i + 1, total: plan.length });
+        }
+        return ok({
+            finalOutput: lastGood,
+            stages: stagesOut,
+            totalUsage,
+            deterministicFallback: false,
+            budgetExhausted,
+        });
+    }
+}
+/** Don't start a stage with less than this much budget left (a call needs at
+ * least this long to have any chance of returning). */
+const MIN_STAGE_BUDGET_MS = 250;
+/**
+ * Effective per-call timeout: the tighter of an explicit per-stage cap and the
+ * remaining wall-clock budget. Returns undefined when neither is set.
+ */
+function effectiveTimeout(perStage, remaining) {
+    const candidates = [perStage, remaining].filter((n) => typeof n === 'number' && n > 0);
+    if (candidates.length === 0)
+        return undefined;
+    return Math.min(...candidates);
+}
+/**
+ * The default stage set for "make this brief more useful to the Claude
+ * agent". Tuned for small local models (Qwen2.5-Coder-3B, Llama-3.1-8B).
+ *
+ * Each stage's user message is intentionally short and concrete; the
+ * heavy lifting (the deterministic seed) lives in the system role
+ * and is reused verbatim across stages so the model never loses
+ * grounding.
+ */
+export function buildDefaultEnhancementStages() {
+    return [
+        new DraftStage(),
+        new CritiqueStage(),
+        new RefineStage(),
+        new PolishStage(),
+    ];
+}
+/**
+ * The fast default for interactive use: `draft → polish` (2 calls). Skips the
+ * slow critique + refine round-trip (the two passes small/large local models
+ * spend the most wall-clock on) while still applying the polish pass that
+ * gives the agent file:line refs and terse imperative bullets. Materially
+ * better than a single shot, ~half the calls of the full pipeline. Callers who
+ * want maximal density opt into `buildDefaultEnhancementStages()` (the
+ * `--plus` path).
+ */
+export function buildFastEnhancementStages() {
+    return [new DraftStage(), new PolishStage()];
+}
+class DraftStage {
+    kind = EnhancementStageKind.Draft;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft, a deterministic, local-first code-intelligence engine.',
+                    'Your job is to write a concise, Claude-agent-ready brief for the supplied task.',
+                    'Treat the repository context below as the ONLY ground truth. Do NOT invent file paths, symbols, or commands.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Task`,
+                    input.task.trim(),
+                    '',
+                    '# Write the draft brief',
+                    'Sections, in order:',
+                    '1. **Goal** — one sentence.',
+                    '2. **Files to read** — bullet list, `path` (no line numbers, just path) with one-line rationale.',
+                    '3. **Files likely to modify** — bullet list, same format.',
+                    '4. **Implementation sketch** — 3–6 bullets, imperative.',
+                    '5. **Risks / unknowns** — bullets; mark each "RISK" or "UNKNOWN".',
+                    '6. **First commands** — fenced bash, one command per line.',
+                    '',
+                    'Be terse. Skip prose. Skip preambles. Skip "I will now…".',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class CritiqueStage {
+    kind = EnhancementStageKind.Critique;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are a code-review style critic for SharkCraft briefs.',
+                    'Treat the repository context below as the ONLY ground truth.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Draft brief to critique`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    '# Critique',
+                    'Find concrete issues. For each issue: one line, prefixed with one of:',
+                    '- `GAP:` — something important the brief omits.',
+                    '- `VAGUE:` — a claim that lacks an exact file path, symbol, or command.',
+                    '- `WRONG:` — a claim that contradicts the repository context.',
+                    '- `MISSING-EVIDENCE:` — a claim with no file:line or knowledge-entry id behind it.',
+                    '',
+                    'If the draft is already strong, output a single line: `OK`.',
+                    'Do NOT rewrite the brief. Critique only.',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class RefineStage {
+    kind = EnhancementStageKind.Refine;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft. Rewrite the draft brief to address the critique, while staying strictly grounded in the repository context.',
+                    '',
+                    '## Repository context',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Draft brief`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    `# Critique to address`,
+                    (input.lastCritique ?? 'OK').trim(),
+                    '',
+                    '# Rewrite the brief',
+                    'Same section layout as the draft. Resolve every GAP/VAGUE/WRONG/MISSING-EVIDENCE line by adding an exact file path or removing the claim. Keep it terse.',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+class PolishStage {
+    kind = EnhancementStageKind.Polish;
+    buildMessages(input) {
+        return [
+            {
+                role: AiMessageRole.System,
+                content: [
+                    'You are SharkCraft. Final polish pass — improve readability for an AI coding agent (e.g. Claude Code) that will consume this brief.',
+                    'Keep the meaning intact. Do not add new facts.',
+                    '',
+                    '## Repository context (reference only — do not extend)',
+                    input.originalContext.trim(),
+                ].join('\n'),
+            },
+            {
+                role: AiMessageRole.User,
+                content: [
+                    `# Original task`,
+                    input.task.trim(),
+                    '',
+                    `# Brief to polish`,
+                    input.previous.trim() || '(empty)',
+                    '',
+                    '# Polish pass',
+                    'Rules:',
+                    '- Convert any `path` reference to `path:lineNumber` when a line number appears in the context (do not invent line numbers).',
+                    '- Keep each bullet to one line.',
+                    '- Promote any imperative verb to the start of the bullet (`Add`, `Wire`, `Replace`, …).',
+                    '- Surface any RISK / UNKNOWN as a short, scannable bullet.',
+                    '- Output the brief only — no meta commentary, no "Here is the polished version".',
+                ].join('\n'),
+            },
+        ];
+    }
+}
+async function callOnceWithRetry(provider, request) {
+    const first = await provider.send(request);
+    if (first.ok) {
+        return ok({ content: first.value.content, model: first.value.model, usage: first.value.usage });
+    }
+    // Don't retry a timeout — the model is too slow for the budget, so a second
+    // attempt just burns another timeout period. Surface the timeout immediately.
+    if (first.error.code === ERROR_CODES.TIMEOUT) {
+        return first;
+    }
+    // One retry — small local models routinely 500 on the first request
+    // after a daemon start. Idempotent reissue is safe.
+    const second = await provider.send(request);
+    if (second.ok) {
+        return ok({ content: second.value.content, model: second.value.model, usage: second.value.usage });
+    }
+    return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Enhancement-pipeline stage failed twice: ${second.error.message}`, { cause: second.error }));
+}

package/dist/provider-resolver.d.ts

@@ -0,0 +1,28 @@
+import type { IAiProvider } from './ai-provider.js';
+export type AiProviderKind = 'auto' | 'claude' | 'gemini' | 'ollama' | 'llamacpp';
+/**
+ * Resolve an AI provider by kind.
+ *
+ * The selector is layered so callers can stay terse:
+ *   - `selectAiProvider('llamacpp' | 'ollama' | 'claude' | 'gemini')`
+ *     → explicit pick. Returned even when `isReady()` is true; the
+ *     caller decides what to do with a non-ready provider.
+ *   - `selectAiProvider('auto')` (or `undefined`) → walk the local-first
+ *     readiness chain: `llamacpp → ollama`. This is the default for
+ *     SharkCraft: privacy + offline first, no surprise network calls
+ *     to hosted APIs.
+ *
+ * Gemini and Claude are deliberately excluded from the `auto` chain.
+ * They are still callable via explicit `--provider gemini` /
+ * `--provider claude` (or `AI_PROVIDER=gemini` / `AI_PROVIDER=claude`)
+ * for users who keep API keys around — but the system never reaches
+ * out to a hosted LLM on its own.
+ *
+ * An unrecognised kind collapses to `'auto'` so the caller never has
+ * to validate user input twice.
+ */
+export declare function selectAiProvider(kind?: string): {
+    requested: AiProviderKind;
+    provider: IAiProvider | null;
+};
+//# sourceMappingURL=provider-resolver.d.ts.map

package/dist/provider-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.d.ts","sourceRoot":"","sources":["../src/provider-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAmB7D"}

package/dist/provider-resolver.js

@@ -0,0 +1,80 @@
+import { ClaudeProvider } from "./claude/claude-provider.js";
+import { GeminiProvider } from "./gemini/gemini-provider.js";
+import { OllamaProvider } from "./ollama/ollama-provider.js";
+import { LlamaCppProvider } from "./llamacpp/llama-cpp-provider.js";
+/**
+ * Resolve an AI provider by kind.
+ *
+ * The selector is layered so callers can stay terse:
+ *   - `selectAiProvider('llamacpp' | 'ollama' | 'claude' | 'gemini')`
+ *     → explicit pick. Returned even when `isReady()` is true; the
+ *     caller decides what to do with a non-ready provider.
+ *   - `selectAiProvider('auto')` (or `undefined`) → walk the local-first
+ *     readiness chain: `llamacpp → ollama`. This is the default for
+ *     SharkCraft: privacy + offline first, no surprise network calls
+ *     to hosted APIs.
+ *
+ * Gemini and Claude are deliberately excluded from the `auto` chain.
+ * They are still callable via explicit `--provider gemini` /
+ * `--provider claude` (or `AI_PROVIDER=gemini` / `AI_PROVIDER=claude`)
+ * for users who keep API keys around — but the system never reaches
+ * out to a hosted LLM on its own.
+ *
+ * An unrecognised kind collapses to `'auto'` so the caller never has
+ * to validate user input twice.
+ */
+export function selectAiProvider(kind) {
+    const normalised = normaliseKind(kind);
+    if (normalised === 'claude') {
+        const provider = new ClaudeProvider();
+        return { requested: 'claude', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'gemini') {
+        const provider = new GeminiProvider();
+        return { requested: 'gemini', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'ollama') {
+        const provider = new OllamaProvider();
+        return { requested: 'ollama', provider: provider.isReady() ? provider : null };
+    }
+    if (normalised === 'llamacpp') {
+        const provider = new LlamaCppProvider();
+        return { requested: 'llamacpp', provider: provider.isReady() ? provider : null };
+    }
+    return autoSelect();
+}
+function normaliseKind(kind) {
+    const known = new Set(['claude', 'gemini', 'ollama', 'llamacpp']);
+    if (kind !== undefined) {
+        const explicit = kind.trim().toLowerCase();
+        if (known.has(explicit))
+            return explicit;
+    }
+    const envCandidate = (process.env.AI_PROVIDER ?? '').trim().toLowerCase();
+    if (known.has(envCandidate))
+        return envCandidate;
+    return 'auto';
+}
+function autoSelect() {
+    for (const kind of defaultAutoChain()) {
+        if (kind === 'llamacpp') {
+            const provider = new LlamaCppProvider();
+            if (provider.isReady())
+                return { requested: 'auto', provider };
+        }
+        else if (kind === 'ollama') {
+            const provider = new OllamaProvider();
+            if (provider.isReady())
+                return { requested: 'auto', provider };
+        }
+    }
+    return { requested: 'auto', provider: null };
+}
+/**
+ * Local-first chain. Hosted providers (Gemini, Claude) are
+ * intentionally absent — opting into a hosted API has to be explicit
+ * via `--provider <name>` or `AI_PROVIDER=<name>`.
+ */
+function defaultAutoChain() {
+    return ['llamacpp', 'ollama'];
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/ai",
-  "version": "0.1.0-alpha.2",
-  "description": "SharkCraft AI provider abstraction: Claude HTTP + Claude CLI adapters.",
+  "version": "0.1.0-alpha.21",
+  "description": "SharkCraft local LLM provider abstraction: Ollama (HTTP) + llama.cpp (in-process) + multi-pass enhancement pipeline.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -43,8 +43,9 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.2",
-    "@shrkcrft/context": "^0.1.0-alpha.2"
+    "@shrkcrft/core": "^0.1.0-alpha.21",
+    "@shrkcrft/context": "^0.1.0-alpha.21",
+    "node-llama-cpp": "^3.16.0"
   },
   "publishConfig": {
     "access": "public"