@shrkcrft/ai 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export * from './ollama/ollama-provider.js';
 export * from './llamacpp/llama-cpp-provider.js';
 export * from './provider-resolver.js';
 export * from './pipeline/enhancement-pipeline.js';
+export * from './llm-hints.js';
+export * from './llm-recommendations.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -8,3 +8,5 @@ export * from "./ollama/ollama-provider.js";
 export * from "./llamacpp/llama-cpp-provider.js";
 export * from "./provider-resolver.js";
 export * from "./pipeline/enhancement-pipeline.js";
+export * from "./llm-hints.js";
+export * from "./llm-recommendations.js";

package/dist/llm-hints.d.ts

@@ -0,0 +1,36 @@
+import type { AiProviderKind } from './provider-resolver.js';
+import type { IAiProvider } from './ai-provider.js';
+export type AiHintLevel = 'setup' | 'upgrade' | 'info';
+export interface IAiHint {
+    level: AiHintLevel;
+    title: string;
+    steps: readonly string[];
+}
+export interface IAiBlock {
+    reachable: boolean;
+    requestedProvider: AiProviderKind;
+    providerId: string | null;
+    enhancementSkipped: boolean;
+    hints: readonly IAiHint[];
+}
+export interface IBuildAiBlockInput {
+    /** What `selectAiProvider` returned, or null if the caller didn't try. */
+    selection?: {
+        requested: AiProviderKind;
+        provider: IAiProvider | null;
+    } | null;
+    /** True when --no-enhance was passed (user opted out — don't nag). */
+    userOptedOut?: boolean;
+}
+/**
+ * Produces the structured `ai` block that lives on every audit report
+ * and any command using `enrichWithLlmRecommendations`. Without the
+ * AI block, `--no-enhance` and "no provider reachable" look the same
+ * to a downstream agent. The block disambiguates.
+ *
+ * Lives in `@shrkcrft/ai` so any package (CLI, packs, MCP server's
+ * read-only surfaces) can construct the same shape.
+ */
+export declare function buildAiBlock(input?: IBuildAiBlockInput): IAiBlock;
+export declare function renderAiBlockMarkdown(block: IAiBlock): string;
+//# sourceMappingURL=llm-hints.d.ts.map

package/dist/llm-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-hints.d.ts","sourceRoot":"","sources":["../src/llm-hints.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,cAAc,CAAC;IAClC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/E,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,kBAAuB,GAAG,QAAQ,CAiErE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAiB7D"}

package/dist/llm-hints.js

@@ -0,0 +1,92 @@
+import { selectAiProvider } from "./provider-resolver.js";
+/**
+ * Produces the structured `ai` block that lives on every audit report
+ * and any command using `enrichWithLlmRecommendations`. Without the
+ * AI block, `--no-enhance` and "no provider reachable" look the same
+ * to a downstream agent. The block disambiguates.
+ *
+ * Lives in `@shrkcrft/ai` so any package (CLI, packs, MCP server's
+ * read-only surfaces) can construct the same shape.
+ */
+export function buildAiBlock(input = {}) {
+    // Honour an explicitly-passed selection (including {provider: null} when
+    // --no-enhance is in play) without re-probing the auto chain. Only fall
+    // back to live probing when the caller didn't supply a selection at all.
+    const selection = input.selection !== undefined && input.selection !== null
+        ? input.selection
+        : input.userOptedOut
+            ? { requested: 'auto', provider: null }
+            : selectAiProvider(undefined);
+    const reachable = selection.provider !== null;
+    const providerId = selection.provider?.id ?? null;
+    const requested = selection.requested;
+    const userOptedOut = Boolean(input.userOptedOut);
+    const hints = [];
+    if (!reachable && !userOptedOut) {
+        hints.push({
+            level: 'setup',
+            title: 'Enable LLM enrichment for deeper analysis',
+            steps: [
+                'Local-first: install Ollama (https://ollama.com/download) or set LLAMACPP_MODEL_PATH for in-process inference.',
+                'Pull a model that fits your machine — e.g. `ollama pull llama3.2` (good general-purpose) or `ollama pull qwen2.5-coder:7b` (code-aware).',
+                'Optional: export OLLAMA_HOST=http://localhost:11434 (default) or point at a remote daemon.',
+                'Optional: export OLLAMA_MODEL=<id> to pin the model used by shrk.',
+                'Re-run without --no-enhance. The deterministic findings are unchanged; LLM critique appears under `llmFindings`.',
+            ],
+        });
+    }
+    else if (!reachable && userOptedOut) {
+        hints.push({
+            level: 'info',
+            title: 'LLM enrichment disabled by --no-enhance',
+            steps: [
+                'Deterministic findings are first-class; LLM is purely additive.',
+                'Drop --no-enhance to layer LLM critique on top when a provider is available.',
+            ],
+        });
+    }
+    else {
+        hints.push({
+            level: 'info',
+            title: `LLM enrichment active via ${providerId}`,
+            steps: [
+                'LLM-derived findings appear with `[llm]` tags and a confidence score.',
+                'Tune behavior: --provider ollama|llamacpp, --model <id>, AI_PROVIDER env var (overrides --provider when unset).',
+            ],
+        });
+        hints.push({
+            level: 'upgrade',
+            title: 'Sharpen LLM output if findings feel thin',
+            steps: [
+                'Prefer a code-aware model for technical staleness checks (e.g. qwen2.5-coder:7b, deepseek-coder-v2).',
+                'Larger models notice more drift but cost latency — try 7B for code, 14B+ for nuanced doc-content review.',
+                'For fix-plan enrichment, the same provider is reused; no separate config needed.',
+            ],
+        });
+    }
+    return {
+        reachable,
+        requestedProvider: requested,
+        providerId,
+        enhancementSkipped: userOptedOut,
+        hints,
+    };
+}
+export function renderAiBlockMarkdown(block) {
+    const out = [];
+    const status = block.reachable
+        ? `active via \`${block.providerId}\``
+        : block.enhancementSkipped
+            ? 'disabled by `--no-enhance`'
+            : 'unavailable (no local LLM detected)';
+    out.push(`## AI configuration — ${status}`);
+    out.push('');
+    for (const hint of block.hints) {
+        out.push(`### [${hint.level}] ${hint.title}`);
+        for (const step of hint.steps) {
+            out.push(`- ${step}`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}

package/dist/llm-recommendations.d.ts

@@ -0,0 +1,72 @@
+import type { IAiProvider } from './ai-provider.js';
+import { type IAiBlock } from './llm-hints.js';
+export type RecommendationSeverity = 'info' | 'warn' | 'error';
+export interface ILlmRecommendation {
+    severity: RecommendationSeverity;
+    category: string;
+    /** Short, one-sentence description of what's recommended. */
+    title: string;
+    /** Detailed prose; typically 1-3 sentences with concrete next-steps. */
+    detail: string;
+    /** Optional target identifier (rule id, template id, file path) the recommendation applies to. */
+    target?: string;
+    /** Confidence in [0, 1]; lower for fuzzier judgments. */
+    confidence: number;
+}
+export interface IRecommendationEnvelope {
+    /** Always present, even when LLM is unavailable. */
+    ai: IAiBlock;
+    recommendations: readonly ILlmRecommendation[];
+}
+export interface IEnrichWithLlmRecommendationsInput {
+    /**
+     * The shape of the deterministic surface (e.g., 'doctor', 'templates-drift').
+     * Used in the LLM prompt so the model knows what it's looking at.
+     */
+    surface: string;
+    /**
+     * Human-readable description of the deterministic findings (what's already
+     * known). Should be tight — the prompt fits into one LLM call.
+     */
+    deterministicSummary: string;
+    /**
+     * Provider kind to request. Defaults to 'auto' (local-first walk).
+     */
+    providerKind?: string;
+    /**
+     * Override the auto-selection by passing an already-resolved provider
+     * (useful for tests).
+     */
+    providerOverride?: IAiProvider | null;
+    /**
+     * True when the caller's --no-enhance equivalent was passed.
+     * When true, no LLM call is made and the AI block records the opt-out.
+     */
+    userOptedOut?: boolean;
+    /**
+     * Per-surface ask: what should the LLM produce on top of the
+     * deterministic summary? E.g. "for each warning, produce one concrete
+     * next-step the user can run from the CLI."
+     */
+    ask: string;
+    /**
+     * Optional override for the model used by the provider.
+     */
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Shared utility for layering LLM recommendations onto any deterministic
+ * surface. The deterministic portion is the caller's responsibility; this
+ * helper only adds the `ai` block and a structured `recommendations` array.
+ *
+ * Hard guarantee: if no LLM is reachable (or `userOptedOut` is true), the
+ * call is a no-op apart from emitting the `ai` block with setup hints.
+ *
+ * Lives in `@shrkcrft/ai` so any callable surface (CLI commands, packs,
+ * read-only MCP tools that want recommendations alongside their data)
+ * can reuse the same envelope shape.
+ */
+export declare function enrichWithLlmRecommendations(input: IEnrichWithLlmRecommendationsInput): Promise<IRecommendationEnvelope>;
+export declare function renderRecommendationsMarkdown(envelope: IRecommendationEnvelope): string;
+//# sourceMappingURL=llm-recommendations.d.ts.map

package/dist/llm-recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-recommendations.d.ts","sourceRoot":"","sources":["../src/llm-recommendations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,uBAAuB,CAAC,CAoClC;AA2FD,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,CA+BvF"}

package/dist/llm-recommendations.js

@@ -0,0 +1,188 @@
+import { AiMessageRole } from "./ai-request.js";
+import { selectAiProvider } from "./provider-resolver.js";
+import { buildAiBlock } from "./llm-hints.js";
+/**
+ * Shared utility for layering LLM recommendations onto any deterministic
+ * surface. The deterministic portion is the caller's responsibility; this
+ * helper only adds the `ai` block and a structured `recommendations` array.
+ *
+ * Hard guarantee: if no LLM is reachable (or `userOptedOut` is true), the
+ * call is a no-op apart from emitting the `ai` block with setup hints.
+ *
+ * Lives in `@shrkcrft/ai` so any callable surface (CLI commands, packs,
+ * read-only MCP tools that want recommendations alongside their data)
+ * can reuse the same envelope shape.
+ */
+export async function enrichWithLlmRecommendations(input) {
+    if (input.userOptedOut) {
+        const aiBlock = buildAiBlock({
+            selection: { requested: normaliseKind(input.providerKind), provider: null },
+            userOptedOut: true,
+        });
+        return { ai: aiBlock, recommendations: [] };
+    }
+    const selection = input.providerOverride !== undefined
+        ? { requested: normaliseKind(input.providerKind), provider: input.providerOverride }
+        : selectAiProvider(input.providerKind);
+    if (!selection.provider) {
+        const aiBlock = buildAiBlock({ selection, userOptedOut: false });
+        return { ai: aiBlock, recommendations: [] };
+    }
+    if (input.model)
+        selection.provider.configure({ model: input.model });
+    const messages = buildRecommendationMessages(input);
+    let recommendations = [];
+    try {
+        const res = await selection.provider.send({
+            messages,
+            maxTokens: input.maxTokens ?? 1024,
+        });
+        if (res.ok) {
+            recommendations = parseRecommendations(res.value.content);
+        }
+    }
+    catch {
+        // Swallow — recommendations stay empty; ai block still carries provider info.
+    }
+    const aiBlock = buildAiBlock({ selection, userOptedOut: false });
+    return { ai: aiBlock, recommendations };
+}
+function buildRecommendationMessages(input) {
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            `You are a critic layering concrete next-step recommendations on top of a deterministic SharkCraft "${input.surface}" report.`,
+            'The deterministic report is supplied verbatim — treat its findings as facts. Your job is to translate them into actions a developer (or an AI coding agent) can take immediately.',
+            '',
+            'The user-specified ask is:',
+            input.ask,
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no fences:',
+            '{',
+            '  "recommendations": [',
+            '    {',
+            '      "severity": "info" | "warn" | "error",',
+            '      "category": "<short kebab-case category>",',
+            '      "title": "<one-sentence summary>",',
+            '      "detail": "<one to three sentences with concrete next-steps; name files, commands, or symbols when possible>",',
+            '      "target": "<optional id or path>",',
+            '      "confidence": 0.0',
+            '    }',
+            '  ]',
+            '}',
+            'Skip the bullet entirely if you cannot say anything specific. Better silence than ceremony.',
+        ].join('\n'),
+    };
+    const user = {
+        role: AiMessageRole.User,
+        content: [`# Deterministic ${input.surface} summary`, '', input.deterministicSummary].join('\n'),
+    };
+    return [system, user];
+}
+function parseRecommendations(raw) {
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const first = jsonText.indexOf('{');
+        const last = jsonText.lastIndexOf('}');
+        if (first < 0 || last <= first)
+            return [];
+        try {
+            parsed = JSON.parse(jsonText.slice(first, last + 1));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const list = parsed.recommendations;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const severity = coerceSeverity(obj.severity);
+        const category = typeof obj.category === 'string' && obj.category.trim()
+            ? obj.category.trim()
+            : 'other';
+        const title = typeof obj.title === 'string' ? obj.title.trim() : '';
+        const detail = typeof obj.detail === 'string' ? obj.detail.trim() : '';
+        if (!title || !detail)
+            continue;
+        const confidence = typeof obj.confidence === 'number' && obj.confidence >= 0 && obj.confidence <= 1
+            ? obj.confidence
+            : 0.5;
+        const target = typeof obj.target === 'string' && obj.target.trim() ? obj.target.trim() : undefined;
+        out.push({ severity, category, title, detail, confidence, ...(target ? { target } : {}) });
+    }
+    return out;
+}
+function coerceSeverity(value) {
+    if (value === 'error' || value === 'warn' || value === 'info')
+        return value;
+    if (value === 'warning')
+        return 'warn';
+    return 'info';
+}
+function normaliseKind(kind) {
+    const known = new Set(['claude', 'gemini', 'ollama', 'llamacpp']);
+    if (kind && known.has(kind.toLowerCase()))
+        return kind.toLowerCase();
+    return 'auto';
+}
+export function renderRecommendationsMarkdown(envelope) {
+    const out = [];
+    if (envelope.recommendations.length === 0) {
+        out.push('## LLM recommendations');
+        out.push('');
+        out.push(envelope.ai.reachable
+            ? '(LLM returned no actionable recommendations — the deterministic output already covers the surface.)'
+            : '(LLM unavailable — see the AI configuration block below to enable.)');
+        out.push('');
+    }
+    else {
+        out.push(`## LLM recommendations (${envelope.recommendations.length})`);
+        out.push('');
+        const order = ['error', 'warn', 'info'];
+        for (const sev of order) {
+            const group = envelope.recommendations.filter((r) => r.severity === sev);
+            if (group.length === 0)
+                continue;
+            for (const rec of group) {
+                out.push(`- **[${sev}]** \`${rec.category}\`${rec.target ? ` (${rec.target})` : ''} — ${rec.title} _(confidence ${rec.confidence.toFixed(2)})_`);
+                out.push(`  - ${rec.detail}`);
+            }
+        }
+        out.push('');
+    }
+    out.push('---');
+    out.push('');
+    out.push(renderAiHintsCompact(envelope.ai));
+    return out.join('\n');
+}
+function renderAiHintsCompact(ai) {
+    const out = [];
+    const status = ai.reachable
+        ? `active via \`${ai.providerId}\``
+        : ai.enhancementSkipped
+            ? 'disabled by user'
+            : 'unavailable';
+    out.push(`### AI configuration — ${status}`);
+    for (const hint of ai.hints) {
+        out.push(`- [${hint.level}] **${hint.title}**`);
+        for (const step of hint.steps) {
+            out.push(`  - ${step}`);
+        }
+    }
+    return out.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/ai",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "SharkCraft local LLM provider abstraction: Ollama (HTTP) + llama.cpp (in-process) + multi-pass enhancement pipeline.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,8 +43,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.12",
-    "@shrkcrft/context": "^0.1.0-alpha.12",
+    "@shrkcrft/core": "^0.1.0-alpha.13",
+    "@shrkcrft/context": "^0.1.0-alpha.13",
     "node-llama-cpp": "^3.16.0"
   },
   "publishConfig": {