@cilow/sdk 0.2.0 → 0.3.0

package/dist/adapters/openai.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenAI SDK binding — two thin surfaces over {@link CilowMemory}, no `openai` dependency required
+ * (the framework's shapes are structural interfaces, so this typechecks offline).
+ *
+ * 1. `base_url` swap — point the OpenAI client at the Cilow proxy; recall→inject→forward is automatic
+ *    and every response carries `x-cilow-memory-grounded`. Read it with {@link groundedFromHeaders}.
+ * 2. memory tool-use — hand `cilowRecallTool` to `tools:[...]` and execute calls with
+ *    {@link runRecallTool}; the tool result carries the abstained/grounded branch so the model never
+ *    fabricates past a calibrated abstain.
+ */
+import type { CilowMemory, RecallResult } from "./memory.js";
+/** The `x-cilow-memory-grounded` response header — grounded-in-memory vs the model's own output. */
+export declare const GROUNDED_HEADER = "x-cilow-memory-grounded";
+/** Structural shape of an OpenAI function tool (no `openai` import needed). */
+export interface OpenAiTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/**
+ * Config to spread into `new OpenAI({ ...cilowProxyConfig(...) })`. The base URL is the Cilow proxy's
+ * OpenAI-compatible `/v1`; the bearer becomes the OpenAI `apiKey`.
+ */
+export declare function cilowProxyConfig(memory: CilowMemory, token: string): {
+    baseURL: string;
+    apiKey: string;
+};
+/**
+ * Read the grounded signal off an OpenAI raw response's headers (from `client…​.withResponse()`),
+ * a `Headers`, or a plain header record. Returns `undefined` when the header is absent (non-proxy).
+ */
+export declare function groundedFromHeaders(headers: Headers | Record<string, string | undefined> | {
+    get(name: string): string | null;
+}): boolean | undefined;
+/** The OpenAI-format memory-recall tool. Register it in `tools:[cilowRecallTool]`. */
+export declare const cilowRecallTool: OpenAiTool;
+/** The parsed shape of a `cilow_recall` tool call's `arguments` JSON. */
+export interface RecallToolArgs {
+    query: string;
+    anchor?: string;
+    attribute?: string;
+}
+/**
+ * Execute one `cilow_recall` tool call. Returns the `content` string to feed back as the tool result
+ * plus the raw {@link RecallResult} so the caller can branch (`result.grounded` /
+ * `result.abstained` / `result.reason_code`). On an abstain the content is an explicit
+ * "memory does not know" so the model is instructed not to fabricate.
+ */
+export declare function runRecallTool(memory: CilowMemory, rawArgs: string | RecallToolArgs): Promise<{
+    content: string;
+    result: RecallResult;
+}>;
+//# sourceMappingURL=openai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,oGAAoG;AACpG,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAExG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAC3F,OAAO,GAAG,SAAS,CAUrB;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,UAiB7B,CAAC;AAEF,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GAAG,cAAc,GAC/B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CAYpD"}

package/dist/adapters/openai.js

@@ -0,0 +1,64 @@
+/** The `x-cilow-memory-grounded` response header — grounded-in-memory vs the model's own output. */
+export const GROUNDED_HEADER = "x-cilow-memory-grounded";
+/**
+ * Config to spread into `new OpenAI({ ...cilowProxyConfig(...) })`. The base URL is the Cilow proxy's
+ * OpenAI-compatible `/v1`; the bearer becomes the OpenAI `apiKey`.
+ */
+export function cilowProxyConfig(memory, token) {
+    return { baseURL: memory.proxyBaseUrl(), apiKey: token };
+}
+/**
+ * Read the grounded signal off an OpenAI raw response's headers (from `client…​.withResponse()`),
+ * a `Headers`, or a plain header record. Returns `undefined` when the header is absent (non-proxy).
+ */
+export function groundedFromHeaders(headers) {
+    let raw;
+    if (typeof headers.get === "function") {
+        raw = headers.get(GROUNDED_HEADER);
+    }
+    else {
+        const rec = headers;
+        raw = rec[GROUNDED_HEADER] ?? rec[GROUNDED_HEADER.toUpperCase()];
+    }
+    if (raw == null)
+        return undefined;
+    return raw.trim().toLowerCase() === "true";
+}
+/** The OpenAI-format memory-recall tool. Register it in `tools:[cilowRecallTool]`. */
+export const cilowRecallTool = {
+    type: "function",
+    function: {
+        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.",
+        parameters: {
+            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 call. Returns the `content` string to feed back as the tool result
+ * plus the raw {@link RecallResult} so the caller can branch (`result.grounded` /
+ * `result.abstained` / `result.reason_code`). On an abstain the content is an explicit
+ * "memory does not know" so the model is instructed not to fabricate.
+ */
+export async function runRecallTool(memory, rawArgs) {
+    const args = typeof rawArgs === "string" ? JSON.parse(rawArgs) : rawArgs;
+    const result = await memory.recall(args.query, { anchor: args.anchor, attribute: args.attribute });
+    if (result.abstained || !result.grounded) {
+        const kind = result.reason_code === "provider_unavailable" ? "temporarily unavailable" : "no grounded facts";
+        return {
+            content: `MEMORY ABSTAINED (${kind}): ${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 { content: `MEMORY-GROUNDED FACTS:\n${lines}`, result };
+}
+//# sourceMappingURL=openai.js.map

package/dist/adapters/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAYA,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,yBAAyB,CAAC;AAQzD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB,EAAE,KAAa;IACjE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA4F;IAE5F,IAAI,GAA8B,CAAC;IACnC,IAAI,OAAQ,OAA6B,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAC7D,GAAG,GAAI,OAAgD,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC/E,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,GAAG,OAA6C,CAAC;QAC1D,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAClC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;AAC7C,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAe;IACzC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,gGAAgG;YAChG,0FAA0F;QAC5F,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;gBACpE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mDAAmD,EAAE;gBAC5F,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iDAAiD,EAAE;aAC9F;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;CACF,CAAC;AASF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAmB,EACnB,OAAgC;IAEhC,MAAM,IAAI,GAAmB,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACzF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACnG,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,KAAK,sBAAsB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,mBAAmB,CAAC;QAC7G,OAAO;YACL,OAAO,EAAE,qBAAqB,IAAI,MAAM,MAAM,CAAC,MAAM,IAAI,sBAAsB,yDAAyD;YACxI,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,EAAE,OAAO,EAAE,2BAA2B,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC;AACjE,CAAC"}

package/dist/adapters/remaining.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The remaining six framework bindings — same {@link CilowMemory} contract, same ≤150-line-shim
+ * pattern as `openai.ts` / `anthropic.ts` / `langchain.ts`. Each entry documents the framework's
+ * integration point and the exact mapping onto the five contract verbs. Where the framework interface
+ * is a plain function/protocol we ship a working stub; where it requires extending a framework base
+ * class we leave a typed TODO so the shim lands the moment the dep is added.
+ *
+ * THE INVARIANT (all nine): map the framework's memory/retriever/tool onto
+ * `ingest` / `recall` / `answer` / `reset` / `health` (+ `proxyBaseUrl()` for base_url swaps) and
+ * re-expose `abstained` + `reason_code` + `grounded` unchanged. An abstain is ALWAYS surfaced, never
+ * fabricated past.
+ */
+import type { CilowMemory } from "./memory.js";
+/** One row of the remaining-adapter plan (mirrors the design doc §2.2 table). */
+export interface AdapterPlan {
+    framework: string;
+    integrationPoint: string;
+    mapping: string;
+    status: "stub" | "todo";
+}
+export declare const REMAINING_ADAPTERS: readonly AdapterPlan[];
+/**
+ * LlamaIndex stub — a retriever whose `retrieve` returns NodeWithScore-shaped hits (abstain ⇒ []).
+ * When `llamaindex` is added, extend `BaseRetriever` and delegate to this.
+ */
+export interface LlamaNodeWithScore {
+    node: {
+        text: string;
+        metadata: Record<string, unknown>;
+    };
+    score: number;
+}
+export declare function makeLlamaIndexRetriever(memory: CilowMemory, opts?: {
+    k?: number;
+    anchor?: string;
+}): {
+    retrieve(query: string): Promise<LlamaNodeWithScore[]>;
+};
+/**
+ * AutoGen stub — the `Memory` protocol surface (`add` / `query`). `query` returns grounded content
+ * strings; an abstain yields an empty list (never a fabricated memory).
+ */
+export declare function makeAutoGenMemory(memory: CilowMemory, opts?: {
+    subjectHint?: string;
+}): {
+    add(content: string): Promise<void>;
+    query(query: string): Promise<{
+        results: string[];
+        grounded: boolean;
+    }>;
+};
+//# sourceMappingURL=remaining.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remaining.d.ts","sourceRoot":"","sources":["../../src/adapters/remaining.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAqC3C,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AACD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO;oBAE7E,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;EAS/D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO;iBAEnE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;iBAGtB,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;EAKhF"}

package/dist/adapters/remaining.js

@@ -0,0 +1,67 @@
+export const REMAINING_ADAPTERS = [
+    {
+        framework: "LlamaIndex",
+        integrationPoint: "BaseRetriever.retrieve(QueryBundle) -> NodeWithScore[]",
+        mapping: "recall → NodeWithScore[]; abstain ⇒ []. Near-identical to CilowRetriever (langchain.ts).",
+        status: "stub",
+    },
+    {
+        framework: "Vercel AI SDK",
+        integrationPoint: "wrapLanguageModel middleware",
+        mapping: "proxyBaseUrl() as the provider base URL; surface `grounded` in stream metadata (R2.1: streaming tool-call capture pending).",
+        status: "todo",
+    },
+    {
+        framework: "CrewAI",
+        integrationPoint: "Storage / memory_backend",
+        mapping: "save→ingest, search→recall; branch on abstained before use.",
+        status: "todo",
+    },
+    {
+        framework: "AutoGen",
+        integrationPoint: "Memory protocol (add / query)",
+        mapping: "add→ingest, query→recall; abstain ⇒ empty MemoryQueryResult.",
+        status: "stub",
+    },
+    {
+        framework: "Composio",
+        integrationPoint: "connector / tool bundle",
+        mapping: "the five CilowMemory verbs as Composio actions (recall/remember/answer/reset).",
+        status: "todo",
+    },
+    {
+        framework: "MCP",
+        integrationPoint: "native /mcp recall/answer/remember (already shipped)",
+        mapping: "no shim needed — add cilow-mcp to .mcp.json.",
+        status: "stub",
+    },
+];
+export function makeLlamaIndexRetriever(memory, opts = {}) {
+    return {
+        async retrieve(query) {
+            const r = await memory.recall(query, { k: opts.k, anchor: opts.anchor });
+            if (!r.grounded)
+                return [];
+            return r.results.map((h) => ({
+                node: { text: h.text, metadata: { id: h.id, entity: h.entity, grounded: true } },
+                score: h.score,
+            }));
+        },
+    };
+}
+/**
+ * AutoGen stub — the `Memory` protocol surface (`add` / `query`). `query` returns grounded content
+ * strings; an abstain yields an empty list (never a fabricated memory).
+ */
+export function makeAutoGenMemory(memory, opts = {}) {
+    return {
+        async add(content) {
+            await memory.ingest(content, { subjectHint: opts.subjectHint });
+        },
+        async query(query) {
+            const r = await memory.recall(query);
+            return { results: r.grounded ? r.results.map((h) => h.text) : [], grounded: r.grounded };
+        },
+    };
+}
+//# sourceMappingURL=remaining.js.map

package/dist/adapters/remaining.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remaining.js","sourceRoot":"","sources":["../../src/adapters/remaining.ts"],"names":[],"mappings":"AAsBA,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD;QACE,SAAS,EAAE,YAAY;QACvB,gBAAgB,EAAE,wDAAwD;QAC1E,OAAO,EAAE,0FAA0F;QACnG,MAAM,EAAE,MAAM;KACf;IACD;QACE,SAAS,EAAE,eAAe;QAC1B,gBAAgB,EAAE,8BAA8B;QAChD,OAAO,EAAE,6HAA6H;QACtI,MAAM,EAAE,MAAM;KACf;IACD;QACE,SAAS,EAAE,QAAQ;QACnB,gBAAgB,EAAE,0BAA0B;QAC5C,OAAO,EAAE,6DAA6D;QACtE,MAAM,EAAE,MAAM;KACf;IACD;QACE,SAAS,EAAE,SAAS;QACpB,gBAAgB,EAAE,+BAA+B;QACjD,OAAO,EAAE,8DAA8D;QACvE,MAAM,EAAE,MAAM;KACf;IACD;QACE,SAAS,EAAE,UAAU;QACrB,gBAAgB,EAAE,yBAAyB;QAC3C,OAAO,EAAE,gFAAgF;QACzF,MAAM,EAAE,MAAM;KACf;IACD;QACE,SAAS,EAAE,KAAK;QAChB,gBAAgB,EAAE,sDAAsD;QACxE,OAAO,EAAE,8CAA8C;QACvD,MAAM,EAAE,MAAM;KACf;CACO,CAAC;AAUX,MAAM,UAAU,uBAAuB,CAAC,MAAmB,EAAE,OAAwC,EAAE;IACrG,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,KAAa;YAC1B,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACzE,IAAI,CAAC,CAAC,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAC;YAC3B,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;gBAChF,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB,EAAE,OAAiC,EAAE;IACxF,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,OAAe;YACvB,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,KAAa;YACvB,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC3F,CAAC;KACF,CAAC;AACJ,CAAC"}