@cilow/sdk 0.2.0 → 0.3.0

package/dist/abstain.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Ergonomic helpers over the abstention contract carried by `recall` / `answer`.
+ *
+ * On abstain the engine returns `abstained: true`, an empty evidence payload, and a machine
+ * `reason_code`. These guards encode the control-flow split so a caller branches on typed state,
+ * not raw strings. Calibration quality is an external, versioned measurement.
+ */
+import type { ExplainReport, ExplainResponse, ReasonCode, TerminalLayer } from "./types.js";
+/** The minimal shape both `RecallResponse` and `AnswerResponse` satisfy. */
+export interface Abstainable {
+    abstained: boolean;
+    reason_code?: ReasonCode;
+    /** Present on `answer` / `context_pack`; `recall` does not carry it. */
+    terminal_layer?: TerminalLayer;
+}
+/**
+ * True iff this is a retryable INFRASTRUCTURE abstain (the embedding provider failed), not a
+ * calibrated "memory does not know". Memory MAY hold the answer — a retry can succeed once the
+ * provider recovers.
+ */
+export declare function isInfrastructureAbstain(r: Abstainable): boolean;
+/**
+ * Which layer stopped the answer (see `TerminalLayer`), or `undefined` when the read answered or
+ * the surface does not carry the field (`recall`).
+ */
+export declare function stoppedAt(r: Abstainable): TerminalLayer | undefined;
+/**
+ * True iff memory abstained because it genuinely lacks grounded context (`below_threshold` /
+ * `no_candidates`). Do NOT fabricate past it; ask the user or search elsewhere.
+ */
+export declare function isCalibratedAbstain(r: Abstainable): boolean;
+/**
+ * Alias for {@link isInfrastructureAbstain} — a retry may succeed once the provider recovers. A
+ * calibrated abstain should NOT be retried verbatim (memory has been asked and does not know).
+ */
+export declare function shouldRetry(r: Abstainable): boolean;
+/**
+ * True iff an `explain` report says the read cleared the gate: found, not abstained, and
+ * `best_nonconformity <= q_hat` (the engine's definition of "grounded"). Accepts the whole
+ * `ExplainResponse` (a not-found lookup is never grounded) or a bare `ExplainReport`.
+ */
+export declare function isGrounded(r: ExplainResponse | ExplainReport): boolean;
+//# sourceMappingURL=abstain.d.ts.map

package/dist/abstain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstain.d.ts","sourceRoot":"","sources":["../src/abstain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5F,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,wEAAwE;IACxE,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAI/D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAEnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAI3D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,eAAe,GAAG,aAAa,GAAG,OAAO,CAKtE"}

package/dist/abstain.js

@@ -0,0 +1,42 @@
+/**
+ * True iff this is a retryable INFRASTRUCTURE abstain (the embedding provider failed), not a
+ * calibrated "memory does not know". Memory MAY hold the answer — a retry can succeed once the
+ * provider recovers.
+ */
+export function isInfrastructureAbstain(r) {
+    return (r.abstained && (r.reason_code === "provider_unavailable" || r.terminal_layer === "provider"));
+}
+/**
+ * Which layer stopped the answer (see `TerminalLayer`), or `undefined` when the read answered or
+ * the surface does not carry the field (`recall`).
+ */
+export function stoppedAt(r) {
+    return r.abstained ? r.terminal_layer : undefined;
+}
+/**
+ * True iff memory abstained because it genuinely lacks grounded context (`below_threshold` /
+ * `no_candidates`). Do NOT fabricate past it; ask the user or search elsewhere.
+ */
+export function isCalibratedAbstain(r) {
+    return (r.abstained && (r.reason_code === "below_threshold" || r.reason_code === "no_candidates"));
+}
+/**
+ * Alias for {@link isInfrastructureAbstain} — a retry may succeed once the provider recovers. A
+ * calibrated abstain should NOT be retried verbatim (memory has been asked and does not know).
+ */
+export function shouldRetry(r) {
+    return isInfrastructureAbstain(r);
+}
+/**
+ * True iff an `explain` report says the read cleared the gate: found, not abstained, and
+ * `best_nonconformity <= q_hat` (the engine's definition of "grounded"). Accepts the whole
+ * `ExplainResponse` (a not-found lookup is never grounded) or a bare `ExplainReport`.
+ */
+export function isGrounded(r) {
+    const report = "found" in r ? (r.found ? r.report : undefined) : r;
+    if (!report || report.abstained)
+        return false;
+    const n = report.best_nonconformity;
+    return typeof n === "number" && n <= report.q_hat;
+}
+//# sourceMappingURL=abstain.js.map

package/dist/abstain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstain.js","sourceRoot":"","sources":["../src/abstain.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAc;IACpD,OAAO,CACL,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,WAAW,KAAK,sBAAsB,IAAI,CAAC,CAAC,cAAc,KAAK,UAAU,CAAC,CAC7F,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,CAAc;IACtC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAc;IAChD,OAAO,CACL,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,WAAW,KAAK,iBAAiB,IAAI,CAAC,CAAC,WAAW,KAAK,eAAe,CAAC,CAC1F,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,CAAc;IACxC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,CAAkC;IAC3D,MAAM,MAAM,GAA8B,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,kBAAkB,CAAC;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC;AACpD,CAAC"}

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Anthropic SDK binding over {@link CilowMemory}, no `@anthropic-ai/sdk` dependency required.
+ *
+ * Anthropic has no OpenAI-compatible endpoint, so the base_url swap does NOT apply here (R2.2 of the
+ * design doc). This binding uses the explicit Messages tool-use path: register {@link cilowRecallTool}
+ * (Anthropic tool schema), execute calls with {@link runRecallTool} into a `tool_result` block, and/or
+ * pre-inject grounded context with {@link injectMemory}. Both surface the abstained/grounded branch.
+ */
+import type { CilowMemory, RecallResult } from "./memory.js";
+/** Structural shape of an Anthropic tool (Messages API `tools:[...]`). */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+/** Minimal Anthropic message shape (structural — no SDK import). */
+export interface AnthropicMessage {
+    role: "user" | "assistant";
+    content: string | unknown[];
+}
+/** The Anthropic-format memory-recall tool. Register it in `tools:[cilowRecallTool]`. */
+export declare const cilowRecallTool: AnthropicTool;
+export interface RecallToolInput {
+    query: string;
+    anchor?: string;
+    attribute?: string;
+}
+/** A `tool_result` content block to append to the next `user` message. */
+export interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+/**
+ * Execute one `cilow_recall` tool_use. Returns the `tool_result` block (branch-aware content) plus the
+ * raw {@link RecallResult}. An INFRASTRUCTURE abstain is marked `is_error: true` (retryable); a
+ * calibrated abstain is a normal result whose content instructs the model not to fabricate.
+ */
+export declare function runRecallTool(memory: CilowMemory, toolUseId: string, input: RecallToolInput): Promise<{
+    toolResult: AnthropicToolResult;
+    result: RecallResult;
+}>;
+/**
+ * Pre-inject grounded memory ahead of a `messages.create` call: recall, and if grounded return a
+ * `system` string block to prepend plus the branch signal. On an abstain `system` is empty and
+ * `grounded` is false — the caller decides whether to proceed on the model's own knowledge or stop.
+ */
+export declare function injectMemory(memory: CilowMemory, query: string, opts?: {
+    anchor?: string;
+    attribute?: string;
+}): Promise<{
+    system: string;
+    grounded: boolean;
+    result: RecallResult;
+}>;
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/adapters/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;CAC7B;AAED,yFAAyF;AACzF,eAAO,MAAM,eAAe,EAAE,aAc7B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC;IAAE,UAAU,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CAmBpE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CAStE"}

package/dist/adapters/anthropic.js

@@ -0,0 +1,57 @@
+/** The Anthropic-format memory-recall tool. Register it in `tools:[cilowRecallTool]`. */
+export const cilowRecallTool = {
+    name: "cilow_recall",
+    description: "Recall grounded facts from verifiable long-term memory. Returns memory-grounded results, or a " +
+        "calibrated abstain when memory genuinely does not know — in which case DO NOT fabricate.",
+    input_schema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "What to look up in memory." },
+            anchor: { type: "string", description: "Optional exact entity hint, e.g. a person's name." },
+            attribute: { type: "string", description: "Optional exact predicate hint, e.g. 'employer'." },
+        },
+        required: ["query"],
+    },
+};
+/**
+ * Execute one `cilow_recall` tool_use. Returns the `tool_result` block (branch-aware content) plus the
+ * raw {@link RecallResult}. An INFRASTRUCTURE abstain is marked `is_error: true` (retryable); a
+ * calibrated abstain is a normal result whose content instructs the model not to fabricate.
+ */
+export async function runRecallTool(memory, toolUseId, input) {
+    const result = await memory.recall(input.query, { anchor: input.anchor, attribute: input.attribute });
+    if (result.reason_code === "provider_unavailable") {
+        return {
+            toolResult: { type: "tool_result", tool_use_id: toolUseId, is_error: true, content: `MEMORY TEMPORARILY UNAVAILABLE: ${result.reason ?? "provider error"} — retry.` },
+            result,
+        };
+    }
+    if (result.abstained || !result.grounded) {
+        return {
+            toolResult: { type: "tool_result", tool_use_id: toolUseId, content: `MEMORY ABSTAINED: ${result.reason ?? "memory does not know"}. Do not fabricate; ask the user or say you don't know.` },
+            result,
+        };
+    }
+    const lines = result.results.map((h) => `- ${h.text}`).join("\n");
+    return {
+        toolResult: { type: "tool_result", tool_use_id: toolUseId, content: `MEMORY-GROUNDED FACTS:\n${lines}` },
+        result,
+    };
+}
+/**
+ * Pre-inject grounded memory ahead of a `messages.create` call: recall, and if grounded return a
+ * `system` string block to prepend plus the branch signal. On an abstain `system` is empty and
+ * `grounded` is false — the caller decides whether to proceed on the model's own knowledge or stop.
+ */
+export async function injectMemory(memory, query, opts = {}) {
+    const result = await memory.recall(query, opts);
+    if (!result.grounded)
+        return { system: "", grounded: false, result };
+    const lines = result.results.map((h) => `- ${h.text}`).join("\n");
+    return {
+        system: `Answer using ONLY these memory-grounded facts. If they are insufficient, say so.\n${lines}`,
+        grounded: true,
+        result,
+    };
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/adapters/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAuBA,yFAAyF;AACzF,MAAM,CAAC,MAAM,eAAe,GAAkB;IAC5C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,gGAAgG;QAChG,0FAA0F;IAC5F,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;YACpE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mDAAmD,EAAE;YAC5F,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iDAAiD,EAAE;SAC9F;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB;CACF,CAAC;AAgBF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAmB,EACnB,SAAiB,EACjB,KAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACtG,IAAI,MAAM,CAAC,WAAW,KAAK,sBAAsB,EAAE,CAAC;QAClD,OAAO;YACL,UAAU,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,mCAAmC,MAAM,CAAC,MAAM,IAAI,gBAAgB,WAAW,EAAE;YACrK,MAAM;SACP,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACzC,OAAO;YACL,UAAU,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,MAAM,CAAC,MAAM,IAAI,sBAAsB,yDAAyD,EAAE;YAC3L,MAAM;SACP,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO;QACL,UAAU,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,2BAA2B,KAAK,EAAE,EAAE;QACxG,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAmB,EACnB,KAAa,EACb,OAAgD,EAAE;IAElD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO;QACL,MAAM,EAAE,qFAAqF,KAAK,EAAE;QACpG,QAAQ,EAAE,IAAI;QACd,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@cilow/sdk/adapters` — framework bindings over the ONE {@link CilowMemory} contract.
+ *
+ * Every binding is a thin shim that maps a framework's memory/retriever/tool interface onto the five
+ * contract verbs (`ingest` / `recall` / `answer` / `reset` / `health`) and re-exposes the
+ * differentiator unchanged: `abstained` + `reason_code` + the `grounded` signal.
+ *
+ * Reuse the abstain guards from the root export (`isCalibratedAbstain` / `isInfrastructureAbstain`) to
+ * branch on an adapter's `RecallResult` / `AnswerResult`.
+ */
+export { CilowMemoryClient, grounded, type CilowMemory, type MemoryHit, type RecallResult, type AnswerResult, type IngestResult, type IngestOptions, type RecallOptions, } from "./memory.js";
+export * as openai from "./openai.js";
+export * as anthropic from "./anthropic.js";
+export * as langchain from "./langchain.js";
+export { REMAINING_ADAPTERS, makeLlamaIndexRetriever, makeAutoGenMemory, type AdapterPlan } from "./remaining.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@cilow/sdk/adapters` — framework bindings over the ONE {@link CilowMemory} contract.
+ *
+ * Every binding is a thin shim that maps a framework's memory/retriever/tool interface onto the five
+ * contract verbs (`ingest` / `recall` / `answer` / `reset` / `health`) and re-exposes the
+ * differentiator unchanged: `abstained` + `reason_code` + the `grounded` signal.
+ *
+ * Reuse the abstain guards from the root export (`isCalibratedAbstain` / `isInfrastructureAbstain`) to
+ * branch on an adapter's `RecallResult` / `AnswerResult`.
+ */
+export { CilowMemoryClient, grounded, } from "./memory.js";
+export * as openai from "./openai.js";
+export * as anthropic from "./anthropic.js";
+export * as langchain from "./langchain.js";
+export { REMAINING_ADAPTERS, makeLlamaIndexRetriever, makeAutoGenMemory } from "./remaining.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,iBAAiB,EACjB,QAAQ,GAQT,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAoB,MAAM,gBAAgB,CAAC"}

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LangChain binding over {@link CilowMemory}, no `langchain` dependency required.
+ *
+ * Two duck-typed classes that satisfy LangChain's structural contracts so they drop into any chain:
+ *  - {@link CilowRetriever} mirrors `BaseRetriever` (`getRelevantDocuments(query) → Document[]`).
+ *  - {@link CilowChatMemory} mirrors `BaseMemory` (`memoryKeys` / `loadMemoryVariables` / `saveContext`
+ *    / `clear`).
+ * The abstention contract is preserved: an abstain yields ZERO documents (never a fabricated one), and
+ * the grounded/abstain branch is readable via {@link CilowRetriever.recallWithSignal} or the metadata
+ * on each returned document.
+ */
+import type { CilowMemory, RecallResult } from "./memory.js";
+/** Structural `Document` (LangChain `@langchain/core/documents`). */
+export interface LcDocument {
+    pageContent: string;
+    metadata: Record<string, unknown>;
+}
+export interface CilowRetrieverOptions {
+    k?: number;
+    anchor?: string;
+    attribute?: string;
+}
+/** A LangChain-compatible retriever backed by Cilow recall. */
+export declare class CilowRetriever {
+    private readonly memory;
+    private readonly opts;
+    lc_namespace: string[];
+    constructor(memory: CilowMemory, opts?: CilowRetrieverOptions);
+    /** BaseRetriever entry point. Returns memory-grounded docs, or `[]` on an abstain (no fabrication). */
+    getRelevantDocuments(query: string): Promise<LcDocument[]>;
+    /** LangChain 0.2+ internal hook — delegates to {@link getRelevantDocuments}. */
+    _getRelevantDocuments(query: string): Promise<LcDocument[]>;
+    /** Escape hatch: the full {@link RecallResult} so a caller can branch on `abstained`/`reason_code`. */
+    recallWithSignal(query: string): Promise<RecallResult>;
+}
+export interface CilowChatMemoryOptions {
+    /** The variable name loaded into the prompt (default `"history"`). */
+    memoryKey?: string;
+    /** Which input key to recall against (default: the sole input). */
+    inputKey?: string;
+    /** Which output key to persist (default: the sole output). */
+    outputKey?: string;
+    /** Default subject for saved turns. */
+    subjectHint?: string;
+    anchor?: string;
+    attribute?: string;
+}
+/** A LangChain-compatible `BaseMemory`: recall on load, persist turns on save. */
+export declare class CilowChatMemory {
+    private readonly memory;
+    private readonly opts;
+    private readonly memoryKey;
+    constructor(memory: CilowMemory, opts?: CilowChatMemoryOptions);
+    get memoryKeys(): string[];
+    /** Load grounded history for the prompt. On an abstain the variable is an empty string (honest). */
+    loadMemoryVariables(values: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Persist the turn into memory so future recalls can ground on it. */
+    saveContext(inputs: Record<string, unknown>, outputs: Record<string, unknown>): Promise<void>;
+    clear(): Promise<void>;
+    private pick;
+}
+//# sourceMappingURL=langchain.d.ts.map

package/dist/adapters/langchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../src/adapters/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,YAAY,WAA2B;gBAGpB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,qBAA0B;IAGnD,uGAAuG;IACjG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAShE,gFAAgF;IAChF,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAI3D,uGAAuG;IACvG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAGvD;AAED,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,sBAA2B;IAKpD,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,oGAAoG;IAC9F,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAO5F,uEAAuE;IACjE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,CAAC,IAAI;CAKb"}

package/dist/adapters/langchain.js

@@ -0,0 +1,68 @@
+/** A LangChain-compatible retriever backed by Cilow recall. */
+export class CilowRetriever {
+    memory;
+    opts;
+    lc_namespace = ["cilow", "retrievers"];
+    constructor(memory, opts = {}) {
+        this.memory = memory;
+        this.opts = opts;
+    }
+    /** BaseRetriever entry point. Returns memory-grounded docs, or `[]` on an abstain (no fabrication). */
+    async getRelevantDocuments(query) {
+        const r = await this.memory.recall(query, this.opts);
+        if (!r.grounded)
+            return [];
+        return r.results.map((h) => ({
+            pageContent: h.text,
+            metadata: { id: h.id, entity: h.entity, score: h.score, grounded: true },
+        }));
+    }
+    /** LangChain 0.2+ internal hook — delegates to {@link getRelevantDocuments}. */
+    _getRelevantDocuments(query) {
+        return this.getRelevantDocuments(query);
+    }
+    /** Escape hatch: the full {@link RecallResult} so a caller can branch on `abstained`/`reason_code`. */
+    recallWithSignal(query) {
+        return this.memory.recall(query, this.opts);
+    }
+}
+/** A LangChain-compatible `BaseMemory`: recall on load, persist turns on save. */
+export class CilowChatMemory {
+    memory;
+    opts;
+    memoryKey;
+    constructor(memory, opts = {}) {
+        this.memory = memory;
+        this.opts = opts;
+        this.memoryKey = opts.memoryKey ?? "history";
+    }
+    get memoryKeys() {
+        return [this.memoryKey];
+    }
+    /** Load grounded history for the prompt. On an abstain the variable is an empty string (honest). */
+    async loadMemoryVariables(values) {
+        const query = this.pick(values, this.opts.inputKey);
+        if (!query)
+            return { [this.memoryKey]: "" };
+        const r = await this.memory.recall(query, { anchor: this.opts.anchor, attribute: this.opts.attribute });
+        return { [this.memoryKey]: r.grounded ? r.results.map((h) => h.text).join("\n") : "" };
+    }
+    /** Persist the turn into memory so future recalls can ground on it. */
+    async saveContext(inputs, outputs) {
+        const input = this.pick(inputs, this.opts.inputKey);
+        const output = this.pick(outputs, this.opts.outputKey);
+        const text = [input, output].filter(Boolean).join("\n");
+        if (text)
+            await this.memory.ingest(text, { subjectHint: this.opts.subjectHint });
+    }
+    async clear() {
+        await this.memory.reset();
+    }
+    pick(bag, key) {
+        if (key)
+            return String(bag[key] ?? "");
+        const vals = Object.values(bag);
+        return vals.length ? String(vals[0]) : "";
+    }
+}
+//# sourceMappingURL=langchain.js.map

package/dist/adapters/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../src/adapters/langchain.ts"],"names":[],"mappings":"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"}

package/dist/adapters/memory.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `CilowMemory` — the ONE adapter contract every framework binding maps onto.
+ *
+ * It is a tiny, framework-neutral interface over the shipped REST surface (`/v1/memories/*` +
+ * the `/v1/chat/completions` proxy). Each framework adapter (OpenAI, Anthropic, LangChain, …) is a
+ * ≤150-line shim that maps the framework's memory/retriever/tool interface onto these five calls and
+ * re-exposes the differentiator unchanged: `abstained` + `reason_code` + the `grounded` signal.
+ *
+ * Transport is the existing {@link CilowClient} — the bindings call the SDK, never raw HTTP.
+ */
+import { CilowClient, type CilowClientOptions } from "../client.js";
+import type { ReasonCode } from "../types.js";
+import type { Abstainable } from "../abstain.js";
+/** One recalled memory line — `text` is ready to inject; structured fields are kept alongside. */
+export interface MemoryHit {
+    id: string;
+    text: string;
+    entity: string;
+    value: string;
+    score: number;
+}
+/**
+ * The result of {@link CilowMemory.recall}. Carries the abstention contract verbatim so a caller
+ * branches on INTENT (`isCalibratedAbstain` / `isInfrastructureAbstain` from `../abstain.js`).
+ * `grounded` is the universal drop-in signal: true ⇒ these hits are memory-grounded; false ⇒ the
+ * caller must fall back to the model's own parametric knowledge (or abstain).
+ */
+export interface RecallResult extends Abstainable {
+    results: MemoryHit[];
+    grounded: boolean;
+    reason?: string;
+    reason_code?: ReasonCode;
+    margin?: number;
+    packedTokens?: number;
+}
+/** The result of {@link CilowMemory.answer} — a synthesized answer + the same grounded/abstain signal. */
+export interface AnswerResult extends Abstainable {
+    text: string;
+    grounded: boolean;
+    reason?: string;
+    reason_code?: ReasonCode;
+}
+/** The receipt of an {@link CilowMemory.ingest}. */
+export interface IngestResult {
+    count: number;
+    ids: string[];
+}
+export interface IngestOptions {
+    /** Default subject when the text names none (e.g. a user/session id). */
+    subjectHint?: string;
+    /** Dedup / idempotency key (single-item ingest). */
+    customId?: string;
+}
+export interface RecallOptions {
+    /** Max hits to surface (advisory; the packer decides the minimal sufficient set). */
+    k?: number;
+    /** Fast-path entity hint, e.g. `"Maya"`. */
+    anchor?: string;
+    /** Fast-path predicate hint, e.g. `"employer"`. */
+    attribute?: string;
+}
+/**
+ * The single contract. Five verbs; every framework binding targets exactly these.
+ *  - `ingest`  → `/v1/memories/add` (or `/batch`)
+ *  - `recall`  → `/v1/memories/search`
+ *  - `answer`  → `/v1/memories/search` (mode `"answer"`)
+ *  - `reset`   → `/v1/memories/list` + `/delete`
+ *  - `health`  → `GET /health`
+ * plus `proxyBaseUrl()` — the drop-in OpenAI-compatible base URL that emits the grounded header.
+ */
+export interface CilowMemory {
+    ingest(items: string | string[], opts?: IngestOptions): Promise<IngestResult>;
+    recall(query: string, opts?: RecallOptions): Promise<RecallResult>;
+    answer(query: string, opts?: RecallOptions): Promise<AnswerResult>;
+    reset(): Promise<{
+        deleted: number;
+    }>;
+    health(): Promise<boolean>;
+    /** The OpenAI-compatible proxy base URL (`…/v1`) to hand a framework's base_url swap. */
+    proxyBaseUrl(): string;
+}
+/** Compute the universal grounded signal from an abstention-carrying response + hit count. */
+export declare function grounded(r: {
+    abstained: boolean;
+}, hitCount: number): boolean;
+/**
+ * The concrete {@link CilowMemory} over a {@link CilowClient}. Construct from client options, or wrap
+ * an existing client with {@link CilowMemoryClient.fromClient}.
+ */
+export declare class CilowMemoryClient implements CilowMemory {
+    private readonly client;
+    private readonly baseUrl;
+    constructor(client: CilowClient, baseUrl: string);
+    static create(opts: CilowClientOptions): CilowMemoryClient;
+    static fromClient(client: CilowClient, baseUrl: string): CilowMemoryClient;
+    ingest(items: string | string[], opts?: IngestOptions): Promise<IngestResult>;
+    recall(query: string, opts?: RecallOptions): Promise<RecallResult>;
+    answer(query: string, opts?: RecallOptions): Promise<AnswerResult>;
+    reset(): Promise<{
+        deleted: number;
+    }>;
+    health(): Promise<boolean>;
+    proxyBaseUrl(): string;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"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"}

package/dist/adapters/memory.js

@@ -0,0 +1,105 @@
+/**
+ * `CilowMemory` — the ONE adapter contract every framework binding maps onto.
+ *
+ * It is a tiny, framework-neutral interface over the shipped REST surface (`/v1/memories/*` +
+ * the `/v1/chat/completions` proxy). Each framework adapter (OpenAI, Anthropic, LangChain, …) is a
+ * ≤150-line shim that maps the framework's memory/retriever/tool interface onto these five calls and
+ * re-exposes the differentiator unchanged: `abstained` + `reason_code` + the `grounded` signal.
+ *
+ * Transport is the existing {@link CilowClient} — the bindings call the SDK, never raw HTTP.
+ */
+import { CilowClient } from "../client.js";
+/** Compute the universal grounded signal from an abstention-carrying response + hit count. */
+export function grounded(r, hitCount) {
+    return !r.abstained && hitCount > 0;
+}
+/**
+ * The concrete {@link CilowMemory} over a {@link CilowClient}. Construct from client options, or wrap
+ * an existing client with {@link CilowMemoryClient.fromClient}.
+ */
+export class CilowMemoryClient {
+    client;
+    baseUrl;
+    constructor(client, baseUrl) {
+        this.client = client;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    static create(opts) {
+        return new CilowMemoryClient(new CilowClient(opts), opts.baseUrl);
+    }
+    static fromClient(client, baseUrl) {
+        return new CilowMemoryClient(client, baseUrl);
+    }
+    async ingest(items, opts = {}) {
+        const list = Array.isArray(items) ? items : [items];
+        if (list.length === 1) {
+            const r = await this.client.memories.add(list[0], {
+                subjectHint: opts.subjectHint,
+                customId: opts.customId,
+            });
+            return { count: r.count, ids: r.memories.map((m) => m.id) };
+        }
+        const r = await this.client.memories.batchAdd(list.map((content) => ({ content, subjectHint: opts.subjectHint })));
+        const ids = r.results.flatMap((res) => res.memories.map((m) => m.id));
+        return { count: ids.length, ids };
+    }
+    async recall(query, opts = {}) {
+        const r = await this.client.memories.search(query, {
+            anchor: opts.anchor,
+            attribute: opts.attribute,
+        });
+        const results = (r.results ?? []).slice(0, opts.k ?? r.results?.length ?? 0).map((h) => ({
+            id: h.id,
+            text: h.text,
+            entity: h.entity ?? "",
+            value: h.value ?? h.text,
+            score: h.score ?? 0,
+        }));
+        return {
+            results,
+            abstained: r.abstained,
+            grounded: grounded(r, results.length),
+            reason: r.reason,
+            reason_code: r.reason_code,
+            margin: r.margin,
+            packedTokens: r.packed_tokens,
+        };
+    }
+    async answer(query, opts = {}) {
+        const r = await this.client.memories.search(query, {
+            anchor: opts.anchor,
+            attribute: opts.attribute,
+            mode: "answer",
+        });
+        return {
+            text: r.context_text ?? "",
+            abstained: r.abstained,
+            grounded: !r.abstained && !!r.context_text,
+            reason: r.reason,
+            reason_code: r.reason_code,
+        };
+    }
+    async reset() {
+        let deleted = 0;
+        // Page through active memories and retire each (there is no bulk-reset REST verb).
+        for (;;) {
+            const page = await this.client.memories.list({ activeOnly: true, limit: 200 });
+            if (!page.memories.length)
+                break;
+            for (const m of page.memories) {
+                const res = await this.client.memories.delete(m.id);
+                deleted += res.deleted ?? 0;
+            }
+            if (page.memories.length < 200)
+                break;
+        }
+        return { deleted };
+    }
+    health() {
+        return this.client.health();
+    }
+    proxyBaseUrl() {
+        return `${this.baseUrl}/v1`;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"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"}