akm-cli 0.6.1 → 0.7.0-rc1

package/dist/src/llm/graph-extract.js

@@ -0,0 +1,107 @@
+/**
+ * LLM helper for the `akm index` graph-extraction pass (#207).
+ *
+ * Given a single asset body (typically a `memory:` or `knowledge:` file),
+ * asks the configured LLM to surface the entities mentioned in it and the
+ * relations between them. The pass itself
+ * (`src/indexer/graph-extraction.ts`) is responsible for deciding which
+ * files to extract, persisting the resulting nodes/edges to a stash-local
+ * `graph.json` artifact, and feeding the artifact into the FTS5+boosts
+ * search pipeline as a single boost component.
+ *
+ * This module is intentionally tiny and stateless so tests can stub it via
+ * `mock.module("../src/llm/graph-extract", ...)` without hitting a network.
+ *
+ * Locked v1 contract (#208): the LLM connection always comes from the
+ * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * the connection via `resolveIndexPassLLM("graph", config)` and pass it
+ * straight through.
+ */
+import { toErrorMessage } from "../core/common";
+import { warn } from "../core/warn";
+import { chatCompletion, parseJsonResponse } from "./client";
+/** Hard cap on body chars sent to the model. */
+const MAX_BODY_CHARS = 4000;
+/** Hard cap on entities returned per asset — guards against runaway LLM output. */
+const MAX_ENTITIES_PER_ASSET = 32;
+/** Hard cap on relations returned per asset. */
+const MAX_RELATIONS_PER_ASSET = 32;
+/** Hard timeout for the LLM call; an `akm index` run must not hang on a misbehaving endpoint. */
+const LLM_TIMEOUT_MS = 30_000;
+const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return only valid JSON. " + "No prose, no markdown fences.";
+const USER_PROMPT_PREFIX = `Extract entities and relations from the asset body below.
+
+Rules:
+- Output ONLY a JSON object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}.
+- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).
+- Relations connect two entities that both appear in the entities array.
+- "type" is a short verb phrase (e.g. "uses", "depends on", "owns", "documents"). Optional; omit when unsure.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Limit to at most ${MAX_ENTITIES_PER_ASSET} entities and ${MAX_RELATIONS_PER_ASSET} relations per asset.
+- Return {"entities": [], "relations": []} if the body has no extractable graph content.
+
+Asset body:
+`;
+/**
+ * Extract entities and relations from a single asset body via the configured LLM.
+ *
+ * Returns `{entities: [], relations: []}` on any failure (timeout, invalid
+ * JSON, empty response). Errors are logged via `warn()` but never thrown — a
+ * failed extraction for one asset must not abort the rest of the index pass.
+ */
+export async function extractGraphFromBody(llmConfig, body) {
+    const empty = { entities: [], relations: [] };
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return empty;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    let timeoutHandle;
+    try {
+        const raw = await Promise.race([
+            chatCompletion(llmConfig, [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userPrompt },
+            ], { maxTokens: 1024, temperature: 0.1 }),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("graph extraction timed out")), LLM_TIMEOUT_MS);
+            }),
+        ]);
+        if (!raw)
+            return empty;
+        const parsed = parseJsonResponse(raw);
+        if (!parsed) {
+            warn("graph extraction: invalid JSON response from LLM; skipping asset.");
+            return empty;
+        }
+        const entities = Array.isArray(parsed.entities)
+            ? parsed.entities
+                .filter((e) => typeof e === "string")
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0)
+                .slice(0, MAX_ENTITIES_PER_ASSET)
+            : [];
+        const entitySet = new Set(entities);
+        const relations = Array.isArray(parsed.relations)
+            ? parsed.relations
+                .filter((r) => typeof r === "object" && r !== null && !Array.isArray(r))
+                .map((r) => ({
+                from: typeof r.from === "string" ? r.from.trim() : "",
+                to: typeof r.to === "string" ? r.to.trim() : "",
+                type: typeof r.type === "string" && r.type.trim() ? r.type.trim() : undefined,
+            }))
+                // Both endpoints must be non-empty AND mentioned in entities[];
+                // dangling relations are noise and inflate the boost component.
+                .filter((r) => r.from && r.to && entitySet.has(r.from) && entitySet.has(r.to))
+                .slice(0, MAX_RELATIONS_PER_ASSET)
+            : [];
+        return { entities, relations };
+    }
+    catch (err) {
+        warn(`graph extraction failed: ${toErrorMessage(err)}`);
+        return empty;
+    }
+    finally {
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+    }
+}

package/dist/src/llm/index-passes.js

@@ -0,0 +1,35 @@
+/**
+ * Per-pass LLM config resolution for `akm index`.
+ *
+ * Locked v1 contract (#208):
+ * - There is exactly one provider/model configuration: `akm.llm`.
+ * - Every LLM-using pass inside `akm index` defaults to that block.
+ * - A pass can be opted out individually with `index.<passName>.llm = false`.
+ * - Any attempt to supply provider/model fields under `index.<passName>` is
+ *   rejected at config-load time by `parseIndexConfig` in
+ *   {@link ../core/config.ts} (`ConfigError("INVALID_CONFIG_FILE")`).
+ *
+ * Passes plug in by calling {@link resolveIndexPassLLM} with their pass
+ * name (e.g. `"memory"` for #201's memory-inference pass, `"graph"` for
+ * #207's graph-extraction pass). They do not read `config.llm` directly.
+ * This keeps the config surface small and the wiring uniform.
+ */
+/**
+ * Resolve the {@link LlmConnectionConfig} a single index pass should use, or
+ * `undefined` when the pass should run without an LLM.
+ *
+ * Returns `undefined` if any of:
+ * - No top-level `akm.llm` block is configured.
+ * - The pass is explicitly opted out (`index.<passName>.llm === false`).
+ *
+ * Otherwise returns the shared `akm.llm` config. There is no per-pass
+ * provider override; that decision is locked by §9 of the v1 spec.
+ */
+export function resolveIndexPassLLM(passName, config) {
+    if (!config.llm)
+        return undefined;
+    const passConfig = config.index?.[passName];
+    if (passConfig?.llm === false)
+        return undefined;
+    return config.llm;
+}

package/dist/src/llm/memory-infer.js

@@ -0,0 +1,86 @@
+/**
+ * LLM helper for the `akm index` memory-inference pass (#201).
+ *
+ * Splits a single memory body into a list of atomic facts. The pass itself
+ * (in `src/indexer/memory-inference.ts`) is responsible for deciding which
+ * memories are pending, persisting the resulting atomic memories with the
+ * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and
+ * marking the parent as processed for idempotency.
+ *
+ * This module is intentionally tiny and stateless so tests can stub it via
+ * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
+ *
+ * Locked v1 contract (#208): the LLM connection always comes from the
+ * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * the connection via `resolveIndexPassLLM("memory", config)` and pass it
+ * straight through.
+ */
+import { toErrorMessage } from "../core/common";
+import { warn } from "../core/warn";
+import { chatCompletion, parseJsonResponse } from "./client";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+/** Hard cap on the number of atomic facts returned per memory. */
+const MAX_FACTS_PER_MEMORY = 16;
+/** Hard timeout for the LLM call. The index run must not hang on a misbehaving endpoint. */
+const LLM_TIMEOUT_MS = 30_000;
+const SYSTEM_PROMPT = "You split a developer memory into atomic, self-contained facts. " +
+    "Return only valid JSON. No prose, no markdown fences.";
+const USER_PROMPT_PREFIX = `Split the memory below into a JSON array of short, self-contained atomic facts.
+
+Rules:
+- Output ONLY a JSON object: {"facts": ["fact one", "fact two", ...]}.
+- Each fact is a single complete sentence, decontextualized so it stands alone.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Preserve technical specifics (names, versions, identifiers) verbatim.
+- If the memory is already a single atomic fact, return it as the only entry.
+- Limit to at most ${MAX_FACTS_PER_MEMORY} facts.
+
+Memory:
+`;
+/**
+ * Split a single memory body into atomic facts via the configured LLM.
+ *
+ * Returns `[]` on any failure (timeout, invalid JSON, empty response). Errors
+ * are logged via `warn()` but never thrown — a failed split for one memory
+ * must not abort the rest of the index pass.
+ */
+export async function splitMemoryIntoAtomicFacts(llmConfig, body) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return [];
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    let timeoutHandle;
+    try {
+        const raw = await Promise.race([
+            chatCompletion(llmConfig, [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userPrompt },
+            ], { maxTokens: 768, temperature: 0.1 }),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("memory inference timed out")), LLM_TIMEOUT_MS);
+            }),
+        ]);
+        if (!raw)
+            return [];
+        const parsed = parseJsonResponse(raw);
+        if (!parsed || !Array.isArray(parsed.facts)) {
+            warn("memory inference: invalid JSON response from LLM; skipping memory.");
+            return [];
+        }
+        const facts = parsed.facts
+            .filter((f) => typeof f === "string")
+            .map((f) => f.trim())
+            .filter((f) => f.length > 0)
+            .slice(0, MAX_FACTS_PER_MEMORY);
+        return facts;
+    }
+    catch (err) {
+        warn(`memory inference failed: ${toErrorMessage(err)}`);
+        return [];
+    }
+    finally {
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+    }
+}

package/dist/{output → src/output}/renderers.js

@@ -391,6 +391,64 @@ const wikiMdRenderer = {
         }
     },
 };
+// ── 4c. lesson-md ────────────────────────────────────────────────────────────
+/**
+ * Renderer for the `lesson` asset type (v1 spec §13).
+ *
+ * Lessons are markdown files with required `description` and `when_to_use`
+ * frontmatter. The renderer projects both fields explicitly so consumers can
+ * decide whether to apply a lesson without reading the full body. Lint
+ * (see `src/core/lesson-lint.ts`) is the contract enforcer; the renderer is
+ * intentionally tolerant — a lesson missing required fields will still render
+ * its body so the user has something to work with while they fix the file.
+ */
+const lessonMdRenderer = {
+    name: "lesson-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
+        const description = toStringOrUndefined(parsed.data.description);
+        const whenToUse = toStringOrUndefined(parsed.data.when_to_use);
+        const action = whenToUse
+            ? `Apply this lesson when: ${whenToUse}`
+            : "Apply this lesson when its `when_to_use` trigger matches the current task.";
+        return {
+            type: "lesson",
+            name,
+            path: ctx.absPath,
+            action,
+            description,
+            content: parsed.content,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const parsed = parseFrontmatter(ctx.content());
+            const fm = parsed.data;
+            const desc = toStringOrUndefined(fm.description);
+            if (desc && !entry.description) {
+                entry.description = desc;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+            const whenToUse = toStringOrUndefined(fm.when_to_use);
+            if (whenToUse) {
+                const hints = new Set(entry.searchHints ?? []);
+                hints.add(`when_to_use:${whenToUse}`);
+                entry.searchHints = Array.from(hints).filter(Boolean);
+            }
+            if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+                const fmTags = fm.tags.filter((t) => typeof t === "string" && t.trim().length > 0);
+                if (fmTags.length > 0) {
+                    entry.tags = Array.from(new Set([...(entry.tags ?? []), ...fmTags]));
+                }
+            }
+        }
+        catch {
+            // Non-fatal: skip metadata extraction on parse error
+        }
+    },
+};
 // ── 5. memory-md ─────────────────────────────────────────────────────────────
 const memoryMdRenderer = {
     name: "memory-md",
@@ -560,6 +618,7 @@ const builtinRenderers = [
     agentMdRenderer,
     knowledgeMdRenderer,
     wikiMdRenderer,
+    lessonMdRenderer,
     memoryMdRenderer,
     workflowMdRenderer,
     scriptSourceRenderer,
@@ -575,4 +634,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };