@kontourai/flow-agents 0.2.0 → 0.4.0

package/kits/knowledge/adapters/flow-runner/telemetry.js

@@ -0,0 +1,174 @@
+/**
+ * Knowledge Kit — Telemetry Helper
+ *
+ * Emits canonical Flow Agents telemetry events (schema v0.3.0) to a JSONL
+ * sink file. Matches the event shape produced by telemetry.sh and the Python
+ * TelemetrySink in integrations/strands/flow_agents_strands/telemetry.py.
+ *
+ * Zero runtime dependencies beyond Node.js built-ins.
+ * Fails open: telemetry errors never block kit operations.
+ *
+ * Sink path: <workspace>/.telemetry/full.jsonl
+ * The workspace is resolved from FLOW_AGENTS_WORKSPACE env var, falling back
+ * to process.cwd().
+ *
+ * @module adapters/flow-runner/telemetry
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Schema constants
+// ---------------------------------------------------------------------------
+
+const SCHEMA_VERSION = "0.3.0";
+
+// Canonical event name → schema event_type  (mirrors telemetry.sh schema_event_type())
+const CANONICAL_TO_SCHEMA = {
+  agentSpawn:        "session.start",
+  userPromptSubmit:  "turn.user",
+  preToolUse:        "tool.invoke",
+  permissionRequest: "tool.permission_request",
+  postToolUse:       "tool.result",
+  stop:              "session.end",
+  subagentStart:     "agent.delegate",
+  subagentStop:      "agent.delegate",
+};
+
+function schemaEventType(canonical) {
+  return CANONICAL_TO_SCHEMA[canonical] || "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Sink resolution
+// ---------------------------------------------------------------------------
+
+function resolveSinkPath(workspace) {
+  const ws = workspace || process.env.FLOW_AGENTS_WORKSPACE || process.cwd();
+  return path.join(ws, ".telemetry", "full.jsonl");
+}
+
+// ---------------------------------------------------------------------------
+// KnowledgeTelemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Thin telemetry sink for the Knowledge Kit flow runner.
+ *
+ * Usage:
+ *   const tel = new KnowledgeTelemetry({ workspace: "/path/to/workspace" });
+ *   tel.emitGate("knowledge.ingest", "classify-gate", { category: "research", record_id: id });
+ */
+export class KnowledgeTelemetry {
+  /**
+   * @param {{ workspace?: string, agentName?: string, sessionId?: string }} options
+   */
+  constructor({ workspace, agentName, sessionId } = {}) {
+    this._sinkPath = resolveSinkPath(workspace);
+    this._agentName = agentName || "knowledge-kit";
+    this._sessionId = sessionId || crypto.randomUUID();
+
+    // Ensure the sink directory exists; fail open on error
+    try {
+      fs.mkdirSync(path.dirname(this._sinkPath), { recursive: true });
+    } catch {
+      // fail open
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Core emit
+  // -------------------------------------------------------------------------
+
+  /**
+   * Build and append a canonical telemetry event to the JSONL sink.
+   * Returns the emitted event object (useful for tests).
+   * Fails open: never throws.
+   *
+   * @param {string} canonicalEvent  - canonical event name (e.g. "preToolUse")
+   * @param {object} [extra]         - additional fields merged into the event
+   * @returns {object} the emitted event
+   */
+  emit(canonicalEvent, extra) {
+    const schemaType = schemaEventType(canonicalEvent);
+    const event = {
+      schema_version: SCHEMA_VERSION,
+      timestamp: String(Date.now()),
+      session_id: this._sessionId,
+      event_id: crypto.randomUUID(),
+      event_type: schemaType,
+      agent: {
+        name: this._agentName,
+        runtime: "knowledge-kit",
+        version: "unknown",
+      },
+      hook: {
+        event_name: canonicalEvent,
+        runtime_session_id: "",
+        turn_id: "",
+        transcript_path: "",
+        model: "",
+        source: "knowledge-kit",
+        stop_hook_active: null,
+        last_assistant_message: "",
+        raw_input: null,
+      },
+    };
+
+    if (extra && typeof extra === "object") {
+      Object.assign(event, extra);
+    }
+
+    try {
+      fs.appendFileSync(this._sinkPath, JSON.stringify(event) + "\n", "utf8");
+    } catch {
+      // fail open — telemetry must never block kit operations
+    }
+
+    return event;
+  }
+
+  // -------------------------------------------------------------------------
+  // Semantic helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Emit a gate event. Used at each flow gate point in the runner.
+   *
+   * @param {string} flowId    - e.g. "knowledge.ingest"
+   * @param {string} gateId    - e.g. "classify-gate"
+   * @param {object} [context] - gate-specific context payload
+   * @returns {object} the emitted event
+   */
+  emitGate(flowId, gateId, context) {
+    return this.emit("preToolUse", {
+      tool: {
+        name: `${flowId}.${gateId}`,
+        normalized_name: "flow.gate",
+        input: context || null,
+      },
+    });
+  }
+
+  /**
+   * Emit a gate-result event.
+   *
+   * @param {string} flowId    - e.g. "knowledge.ingest"
+   * @param {string} gateId    - e.g. "classify-gate"
+   * @param {object} [result]  - gate result payload
+   * @returns {object} the emitted event
+   */
+  emitGateResult(flowId, gateId, result) {
+    return this.emit("postToolUse", {
+      tool: {
+        name: `${flowId}.${gateId}`,
+        normalized_name: "flow.gate",
+        output: result || null,
+      },
+    });
+  }
+}
+
+export default KnowledgeTelemetry;

package/kits/knowledge/adapters/similarity-vector/index.js

@@ -0,0 +1,284 @@
+/**
+ * Knowledge Kit — Vector Similarity Adapter
+ *
+ * Provides a drop-in SimilarityDetector implementation backed by dense vector
+ * embeddings (cosine similarity) instead of the default category-prefix /
+ * link-overlap heuristic.
+ *
+ * SimilarityDetector interface (from adapters/flow-runner/index.js):
+ *   async (concept: Record, candidates: Record[], store: KnowledgeStoreAdapter) => string[]
+ *
+ * Usage:
+ *   import { createVectorSimilarityDetector } from './adapters/similarity-vector/index.js';
+ *
+ *   // Ollama (default):
+ *   const detector = createVectorSimilarityDetector();
+ *
+ *   // Ollama with non-default model/host:
+ *   const detector = createVectorSimilarityDetector({
+ *     host: 'http://localhost:11434',
+ *     model: 'nomic-embed-text',
+ *     threshold: 0.60,
+ *   });
+ *
+ *   // Injectable embed fn (for tests / custom providers):
+ *   const detector = createVectorSimilarityDetector({
+ *     embed: async (texts) => texts.map(() => [0.1, 0.9, 0.0]),
+ *     threshold: 0.60,
+ *   });
+ *
+ *   // Pass to synthesize:
+ *   await runner.synthesize(conceptId, {
+ *     proposedBody: '...',
+ *     rationale: '...',
+ *     similarityDetector: detector,
+ *   });
+ *
+ * Zero npm dependencies — uses Node.js built-in fetch (Node >= 18).
+ *
+ * Fail-closed policy:
+ *   If the embedding call fails (network error, non-200, malformed response),
+ *   the detector throws an Error with code="EMBED_FAILURE". This is intentional:
+ *   silently returning [] would look identical to "no similar records found" and
+ *   mask infrastructure failures as legitimate empty clusters, blocking synthesis
+ *   with a misleading MISSING_EVIDENCE rather than a clear infrastructure error.
+ *
+ * @module adapters/similarity-vector
+ */
+
+// ---------------------------------------------------------------------------
+// Pure cosine similarity (exported for tests)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the cosine similarity between two equal-length numeric vectors.
+ *
+ * Returns a value in [-1, 1]:
+ *   1.0  — identical direction
+ *   0.0  — orthogonal
+ *  -1.0  — opposite direction
+ *
+ * Edge cases:
+ *   - Zero-magnitude vector(s): returns 0 (no similarity signal).
+ *   - Empty or unequal-length vectors: returns 0.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+export function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return 0;
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  if (denom === 0) return 0;
+  return dot / denom;
+}
+
+// ---------------------------------------------------------------------------
+// Ollama embed call
+// ---------------------------------------------------------------------------
+
+/**
+ * Call ollama's /api/embed endpoint.
+ *
+ * Throws an Error with code="EMBED_FAILURE" on any failure.
+ *
+ * @param {string} host
+ * @param {string} model
+ * @param {string[]} texts
+ * @returns {Promise<number[][]>}
+ */
+async function ollamaEmbed(host, model, texts) {
+  const url = `${host}/api/embed`;
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model, input: texts }),
+    });
+  } catch (cause) {
+    const err = new Error(
+      `EMBED_FAILURE: embedding call to ${url} failed — ${cause.message}`
+    );
+    err.code = "EMBED_FAILURE";
+    err.cause = cause;
+    throw err;
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "(unreadable)");
+    const err = new Error(
+      `EMBED_FAILURE: embedding call to ${url} returned HTTP ${response.status}: ${body}`
+    );
+    err.code = "EMBED_FAILURE";
+    throw err;
+  }
+
+  let data;
+  try {
+    data = await response.json();
+  } catch (cause) {
+    const err = new Error(
+      `EMBED_FAILURE: embedding response from ${url} was not valid JSON — ${cause.message}`
+    );
+    err.code = "EMBED_FAILURE";
+    err.cause = cause;
+    throw err;
+  }
+
+  // ollama /api/embed returns { embeddings: number[][] }
+  if (!data.embeddings || !Array.isArray(data.embeddings)) {
+    const err = new Error(
+      `EMBED_FAILURE: embedding response missing .embeddings array (got: ${JSON.stringify(Object.keys(data || {}))})`
+    );
+    err.code = "EMBED_FAILURE";
+    throw err;
+  }
+
+  if (data.embeddings.length !== texts.length) {
+    const err = new Error(
+      `EMBED_FAILURE: expected ${texts.length} embedding(s), got ${data.embeddings.length}`
+    );
+    err.code = "EMBED_FAILURE";
+    throw err;
+  }
+
+  return data.embeddings;
+}
+
+// ---------------------------------------------------------------------------
+// createVectorSimilarityDetector
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a SimilarityDetector backed by dense vector embeddings.
+ *
+ * The returned detector satisfies the SimilarityDetector interface:
+ *   async (concept, candidates, store) => string[]
+ *
+ * @param {object} [options]
+ * @param {((texts: string[]) => Promise<number[][]>)} [options.embed]
+ *   Injectable embedding function. When provided, `host` and `model` are
+ *   ignored. Signature: async (texts: string[]) => number[][]
+ *   Must return one vector per input text.
+ * @param {string} [options.host="http://localhost:11434"]
+ *   Ollama server base URL. Used when `embed` is not provided.
+ * @param {string} [options.model="nomic-embed-text"]
+ *   Embedding model name passed to ollama. Used when `embed` is not provided.
+ * @param {number} [options.threshold=0.60]
+ *   Minimum cosine similarity score for a candidate to be included.
+ *   Range: [-1, 1]. Default 0.60 is calibrated for nomic-embed-text where
+ *   semantically related texts from the same domain typically score ≥ 0.70
+ *   and unrelated texts score < 0.50.
+ * @param {((record: object) => string)} [options.text]
+ *   Extractor that converts a store record to the text to embed.
+ *   Default: `record.title + "\n" + record.body`.
+ * @returns {(concept: object, candidates: object[], store: object) => Promise<string[]>}
+ */
+export function createVectorSimilarityDetector(options = {}) {
+  const {
+    embed: injectEmbed = null,
+    host = "http://localhost:11434",
+    model = "nomic-embed-text",
+    threshold = 0.60,
+    text: extractText = defaultTextExtractor,
+  } = options;
+
+  // Resolve the actual embed function once (avoid re-resolving on each call)
+  const embedFn = injectEmbed
+    ? injectEmbed
+    : (texts) => ollamaEmbed(host, model, texts);
+
+  /**
+   * SimilarityDetector: returns candidate IDs whose cosine similarity to the
+   * concept embedding meets or exceeds `threshold`.
+   *
+   * Fail-closed: any embedding failure throws EMBED_FAILURE rather than
+   * silently returning [].
+   *
+   * @param {object} concept
+   * @param {object[]} candidates
+   * @param {object} _store  (not used by vector detector; kept for interface compat)
+   * @returns {Promise<string[]>}
+   */
+  async function vectorSimilarityDetector(concept, candidates, _store) {
+    if (!candidates || candidates.length === 0) {
+      return [];
+    }
+
+    // Exclude retired records from the working set (Addendum B — R3)
+    const activeCandidates = candidates.filter(
+      (c) => (c.status || "active") !== "retired"
+    );
+
+    if (activeCandidates.length === 0) {
+      return [];
+    }
+
+    const conceptText = extractText(concept);
+
+    // Build the batch: concept first, then all active candidates.
+    // One round-trip minimises latency and keeps the batch API simple.
+    const allTexts = [conceptText, ...activeCandidates.map(extractText)];
+
+    // Embedding call — throws EMBED_FAILURE on any infrastructure error.
+    const embeddings = await embedFn(allTexts);
+
+    // Validate count: the embed fn must return one vector per input text.
+    // A count mismatch would produce silent wrong results (undefined vectors
+    // scoring 0 and being excluded) — throw EMBED_FAILURE instead.
+    if (!Array.isArray(embeddings) || embeddings.length !== allTexts.length) {
+      const err = new Error(
+        `EMBED_FAILURE: embed function returned ${Array.isArray(embeddings) ? embeddings.length : typeof embeddings} vector(s) but expected ${allTexts.length} (1 concept + ${activeCandidates.length} active candidates)`
+      );
+      err.code = 'EMBED_FAILURE';
+      throw err;
+    }
+
+    const conceptVec = embeddings[0];
+    const similar = [];
+
+    for (let i = 0; i < activeCandidates.length; i++) {
+      const candidateVec = embeddings[i + 1];
+      const score = cosineSimilarity(conceptVec, candidateVec);
+      if (score >= threshold) {
+        similar.push(activeCandidates[i].id);
+      }
+    }
+
+    return similar;
+  }
+
+  return vectorSimilarityDetector;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Default text extractor: title + newline + body.
+ * Gracefully handles missing fields.
+ *
+ * @param {object} record
+ * @returns {string}
+ */
+function defaultTextExtractor(record) {
+  const title = record?.title || "";
+  const body = record?.body || "";
+  return `${title}\n${body}`;
+}
+
+export default createVectorSimilarityDetector;