@cilow/sdk 0.2.1 → 0.3.0

package/README.md

@@ -1,535 +1,152 @@
-# @cilow/sdk
+# @cilow/sdk — TypeScript
 
-Complete TypeScript SDK for Cilow - AI Memory Infrastructure with multi-framework support.
+The TypeScript client for **Cilow**, the verifiable context layer for AI agents. Point it at
+a running [`cilow-serve`](../../docs/user_guide/mcp_server.md) and call **four core verbs** —
+`ingest`, `contextPack`, `forget`, `explain` — the same four the MCP core profile advertises.
+The headline feature is **calibrated deferral**: every read tells you when the engine
+*doesn't know* instead of fabricating an answer.
 
-## Installation
+## Install
 
-```bash
-npm install @cilow/sdk
-# or
-yarn add @cilow/sdk
-# or
-pnpm add @cilow/sdk
+```sh
+# From this repo (no registry publish yet):
+cd sdk/typescript && npm install && npm run build
+# In your app, depend on the built package or vendor `dist/`.
 ```
 
-## Quick Start
+Node 18+ (uses the global `fetch`). Zero runtime dependencies.
 
-```typescript
-import { Cilow } from '@cilow/sdk';
+## Point it at a server
 
-const cilow = new Cilow({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-api-key'
-});
-
-// Store a memory
-await cilow.remember("User prefers dark mode", { tags: ["preference", "ui"] });
-
-// Search memories
-const memories = await cilow.recall("user preferences");
-
-// Delete memories
-await cilow.forget({ tags: ["temporary"] });
-```
-
-## Features
-
-- **Simple API**: `remember`, `recall`, `forget` for easy memory management
-- **Full TypeScript Support**: Complete type definitions for all APIs
-- **Framework Integrations**: Vercel AI SDK, OpenAI, LangChain
-- **React Hooks**: `useMemory`, `useRecall`, `useMemoryContext`
-- **WebSocket Support**: Real-time memory updates and graph changes
-- **Multi-tier Memory**: Hot, warm, cold memory tiers for optimal performance
-
-## Core Client
-
-### Basic Operations
-
-```typescript
-import { Cilow } from '@cilow/sdk';
-
-const cilow = new Cilow({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-api-key'
-});
-
-// Store a memory
-const memoryId = await cilow.remember("Important information", {
-  tags: ["important"],
-  userId: "user-123",
-  metadata: { source: "chat" }
-});
-
-// Search memories with semantic similarity
-const results = await cilow.recall("important information", {
-  limit: 10,
-  minRelevance: 0.5,
-  tags: ["important"]
-});
-
-// Delete memories
-await cilow.forget({ memoryId: "mem-123" });
-await cilow.forget({ tags: ["old"], userId: "user-123" });
-```
-
-### Advanced Operations
-
-```typescript
-// Get a specific memory
-const memory = await cilow.getMemory("mem-123");
-
-// Update a memory
-const updated = await cilow.updateMemory("mem-123", {
-  content: "Updated content",
-  tags: ["updated"]
-});
-
-// List memories with pagination
-const list = await cilow.listMemories({
-  limit: 20,
-  offset: 0,
-  userId: "user-123",
-  tags: ["preference"]
-});
-
-// Get context for AI prompts
-const context = await cilow.getContext("recent discussions", {
-  maxTokens: 2000,
-  userId: "user-123"
-});
-
-// Store conversation turns
-await cilow.storeConversation({
-  userMessage: "What's the weather?",
-  assistantResponse: "The weather is sunny today.",
-  userId: "user-123",
-  sessionId: "session-abc"
-});
-
-// Get statistics
-const stats = await cilow.getStats();
-console.log(`Total memories: ${stats.totalMemories}`);
-```
-
-### Graph Operations
-
-```typescript
-// Create graph nodes
-const node = await cilow.createGraphNode("Person", "John Doe", {
-  email: "john@example.com"
-});
-
-// Create relationships
-const edge = await cilow.createGraphEdge(
-  node.id,
-  "other-node-id",
-  "KNOWS",
-  { since: "2024" }
-);
-
-// Traverse the graph
-const subgraph = await cilow.traverseGraph({
-  startNodeId: node.id,
-  maxDepth: 3,
-  relationshipTypes: ["KNOWS", "WORKS_WITH"]
-});
+```sh
+cargo build --profile fast --features serve --bin cilow-serve
+CILOW_DB=/tmp/cilow.log CILOW_TOKENS="demo:1:1" ./target/fast/cilow-serve
+# listening on http://0.0.0.0:8080  ·  bearer token "demo"
 ```
 
-## Vercel AI SDK Integration
-
-```typescript
-import { createCilowTools, createCilowContext } from '@cilow/sdk/providers/vercel';
-import { streamText } from 'ai';
-import { anthropic } from '@ai-sdk/anthropic';
-
-// Create tools for AI to use
-const tools = createCilowTools({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-key',
-  defaultUserId: 'user-123'
-});
-
-// Use with streamText
-const result = await streamText({
-  model: anthropic('claude-sonnet-4-20250514'),
-  tools,
-  messages: [
-    { role: 'user', content: 'What do you remember about me?' }
-  ]
-});
-
-// Or use context injection
-const getContext = createCilowContext({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-key',
-  maxTokens: 2000
-});
-
-const context = await getContext('previous discussions');
-
-const response = await streamText({
-  model: anthropic('claude-sonnet-4-20250514'),
-  system: `You are a helpful assistant.\n\nContext:\n${context.context}`,
-  prompt: 'Continue our discussion'
-});
-```
-
-### Context Middleware
+The token maps to a tenant scope that the server **stamps** onto every request — a client can
+never read another tenant's memory, and a client-supplied `scope` is ignored over HTTP.
 
-```typescript
-import { createContextMiddleware } from '@cilow/sdk/providers/vercel';
+## Five lines
 
-const withMemory = createContextMiddleware({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-key'
-});
+```ts
+import { CilowClient, isGrounded } from "@cilow/sdk";
 
-// Automatically inject memory context
-const messagesWithContext = await withMemory(originalMessages, {
-  userId: 'user-123',
-  maxTokens: 2000
-});
+const cilow = new CilowClient({ baseUrl: "http://localhost:8080", token: "demo" });
+await cilow.ingest({ facts: [{ subject: "Maya", predicate: "employer", object: "Acme" }] });
+const r = await cilow.contextPack("where does Maya work", { anchor: "Maya", attribute: "employer" });
+console.log(r.abstained ? `don't know: ${r.reason}` : r.pack); // the injectible pack; citations on r.citations
+console.log(isGrounded(await cilow.explain(r.trace_id!)));     // why it surfaced, vs the tenant threshold
 ```
 
-## OpenAI SDK Integration
+## The four core verbs
 
-```typescript
-import OpenAI from 'openai';
-import { createCilowOpenAI } from '@cilow/sdk/providers/openai';
+| Verb | Signature | Returns | What it does |
+|------|-----------|---------|--------------|
+| `ingest` | `ingest({ facts } \| { text } \| { url } \| { contentBase64, mime? }, opts?)` | `IngestResponse` | The **one write door**. Never rejects: known kinds extract, unknown kinds are retained and recallable. A new value for an exclusive attribute *supersedes* the old one (history stays queryable). |
+| `contextPack` | `contextPack(query: string, opts?)` | `ContextPackResponse` | The **product read**: a ready-to-inject `pack`, structured `citations` / `claims` with `is_current`, and the faithfulness fields `abstained` / `reason_code` / `grounding` / `pack_sufficient` / `as_of` / `trace_id`. No free-form synthesis. |
+| `forget` | `forget(entity: string, opts?)` | `ForgetResponse` | **Withdraw**, not erase history: recall stops returning it; as-of-T reads before `at` still see it. `{ erase: true }` (or `erase()`) is the destructive right-to-be-forgotten path. |
+| `explain` | `explain(traceId: number, opts?)` | `ExplainResponse` | **Why** a pack/recall surfaced what it surfaced: the cited claims (labels resolved, inclusion probability each), `best_nonconformity` vs the tenant threshold `q_hat`, and `isGrounded(r)`. `found: false` + `error` is in-band. |
 
-const openai = new OpenAI();
+Plus `health()` (liveness probe, no auth).
 
-const cilowAI = createCilowOpenAI(openai, {
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'cilow-key',
-  autoStore: true // Automatically store conversations
-});
+### Options
 
-// Memory context is automatically injected
-const { completion, memoriesUsed } = await cilowAI.chat.completions.create({
-  model: 'gpt-4',
-  messages: [
-    { role: 'user', content: 'Based on our previous discussions, what should I focus on?' }
-  ]
-});
+- `ingest`: `{ scope?, sourceId?, observedAt?, source?, rawContext?, branch?, subjectHint?, metadata? }` —
+  `source` / `rawContext` / `branch` apply to the facts form; `subjectHint` / `metadata` to text / url / bytes.
+- `contextPack`: `{ scope?, now?, asOf?, anchor?, attribute? }`
+- `forget`: `{ scope?, attribute?, value?, erase?, at? }`
+- `explain`: `{ scope? }`
 
-console.log(`Used ${memoriesUsed} memories for context`);
-console.log(completion.choices[0].message.content);
+`ingest` takes **exactly one** content form. `sourceId` (the idempotency key the wire requires)
+defaults to a **content hash** — `ingestSourceId(content)` — so re-sending the same payload is a
+no-op; the key actually sent is echoed on `source_id`. `kind` tells you which server path ran
+(`"facts"` → the `remember` receipt on `remember`; `"content"` → the raw-durable receipt on
+`content` with `blob_id` / `detected` / `reader_error`).
 
-// Direct memory access
-await cilowAI.remember("Important insight", { tags: ["insight"] });
-const memories = await cilowAI.recall("insights");
-```
+`anchor` (an entity surface form like `"Maya"`) + `attribute` (a predicate like `"employer"`)
+take the exact-key **fast path**. Omit them for free-text semantic reads — same response shape.
 
-## LangChain Integration
+### Full profile / legacy aliases
 
-### Memory Class
+The engine's full tool profile (`CILOW_MCP_PROFILE=full`) also advertises the older verbs, and
+the client keeps them as aliases with their original receipts:
 
-```typescript
-import { CilowMemory } from '@cilow/sdk/providers/langchain';
-import { ConversationChain } from 'langchain/chains';
-import { ChatOpenAI } from '@langchain/openai';
+| Alias | Signature | Returns |
+|-------|-----------|---------|
+| `remember` | `remember(facts: Fact[], { scope?, source?, sourceId?, observedAt?, rawContext?, branch? })` | `RememberResponse` (write receipt) |
+| `recall` | `recall(query: string, { scope?, asOf?, now?, anchor?, attribute?, branch? })` | `RecallResponse` (`abstained`, `claims`, `receipt`) |
+| `answer` | `answer(query: string, { scope?, now?, anchor?, attribute?, branch? })` | `AnswerResponse` (`abstained`, `text`, `citations`) |
+| `timeline` | `timeline(entity: string, { scope?, at?, from?, to? })` | `TimelineEntry[]` (bitemporal history) |
+| `trackEntity` | `trackEntity(name: string, { scope?, at? })` | `TrackEntityResponse` (canonical id + alias class) |
 
-const memory = new CilowMemory({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'cilow-key',
-  userId: 'user-123',
-  sessionId: 'session-abc'
-});
+Also available: `rememberText`, `ingestImage` / `ingestAudio` / `ingestPdf` / `ingestStructured`,
+`save` / `ingestAny`, `feedback`, `consolidate`, `fork` / `branchList`, `blobGet` / `blobMeta` /
+`blobList`, and the `cilow.memories.*` id-based REST surface (also exposed to frameworks via
+`@cilow/sdk/adapters`).
 
-const chain = new ConversationChain({
-  llm: new ChatOpenAI(),
-  memory
-});
-
-const response = await chain.call({
-  input: 'What did we discuss last time?'
-});
-```
+### Time is in microseconds
 
-### Retriever for RAG
+Every time field (`observedAt`, `asOf`, `now`, `at`, `from`, `to`, and the `valid_from` /
+`valid_until` on timeline entries) is **epoch microseconds (µs)**, matching the engine. They all
+default to "now" (`Date.now() * 1000`). Use the exported `nowMicros()` helper if you need it:
 
-```typescript
-import { CilowRetriever } from '@cilow/sdk/providers/langchain';
-import { RetrievalQAChain } from 'langchain/chains';
-
-const retriever = new CilowRetriever({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'cilow-key',
-  topK: 5
-});
-
-const chain = RetrievalQAChain.fromLLM(
-  new ChatOpenAI(),
-  retriever
-);
-
-const answer = await chain.call({
-  query: 'What are the key points from our meetings?'
-});
+```ts
+import { nowMicros } from "@cilow/sdk";
+const t = nowMicros();
+await cilow.remember(facts, { observedAt: t });
+const past = await cilow.recall("...", { asOf: t - 86_400_000_000, now: t }); // a day ago
 ```
 
-### Vector Store
-
-```typescript
-import { CilowVectorStore } from '@cilow/sdk/providers/langchain';
+## The deferral contract
 
-const vectorStore = new CilowVectorStore({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'cilow-key'
-});
+`contextPack` (and the `recall` / `answer` aliases) **never throw** for a deferral — they return
+a normal response with a boolean flag. When `abstained` is `true`, the pack / claims / citations
+are empty and `reason_code` says why: `below_threshold` / `no_candidates` are a *calibrated*
+abstain (memory genuinely lacks grounded context — do not fabricate past it), while
+`provider_unavailable` is an *infrastructure* abstain (retry when the provider recovers). Branch
+with `isCalibratedAbstain(r)` / `isInfrastructureAbstain(r)` rather than matching strings.
 
-// Add documents
-await vectorStore.addDocuments([
-  { pageContent: 'Meeting notes from Monday', metadata: { topic: 'standup' } },
-  { pageContent: 'Product requirements document', metadata: { topic: 'product' } }
-]);
+On `answer` / `contextPack` an abstain also names **which layer stopped it** — `r.terminal_layer`
+(`structural` | `gate` | `provider` | `reader` | `verifier`; `stoppedAt(r)` is the same thing gated on
+`abstained`). Only `provider` is retryable. Both surfaces also carry `r.evidence`: the claim, span,
+and verbatim lanes collapsed into one list ordered by fused cross-lane rank (`Evidence.origins`
+says which lanes agreed; `Evidence.structure` is present when a typed claim backs the unit). It is
+present on abstains too — the raw lanes have no standing at the gate, but you may still read them.
 
-// Similarity search
-const results = await vectorStore.similaritySearch('standup notes', 5);
-
-// With scores
-const resultsWithScores = await vectorStore.similaritySearchWithScore('standup notes');
-```
-
-## React Hooks
-
-```tsx
-import {
-  CilowProvider,
-  useMemory,
-  useRecall,
-  useMemoryContext,
-  useMemorySubscription,
-  useDebouncedSearch
-} from '@cilow/sdk/react';
-
-// Wrap your app with the provider
-function App() {
-  return (
-    <CilowProvider
-      apiUrl="https://api.cilow.ai"
-      apiKey="your-key"
-      userId="user-123"
-      enableWebSocket={true}
-    >
-      <YourApp />
-    </CilowProvider>
-  );
-}
-
-// Use memory operations
-function MemoryManager() {
-  const { remember, forget, isLoading, error } = useMemory();
-
-  const handleSave = async () => {
-    await remember("Important note", { tags: ["note"] });
-  };
-
-  return (
-    <button onClick={handleSave} disabled={isLoading}>
-      Save Memory
-    </button>
-  );
-}
-
-// Search memories
-function SearchComponent() {
-  const { data, search, isLoading } = useRecall();
-
-  const handleSearch = () => {
-    search("user preferences", { limit: 10 });
-  };
-
-  return (
-    <div>
-      <button onClick={handleSearch}>Search</button>
-      {data.map(result => (
-        <div key={result.memory.id}>
-          <p>{result.memory.content}</p>
-          <span>Score: {(result.score * 100).toFixed(0)}%</span>
-        </div>
-      ))}
-    </div>
-  );
-}
-
-// Debounced search
-function LiveSearch() {
-  const { query, setQuery, results, isLoading } = useDebouncedSearch({
-    delay: 300,
-    minLength: 2
-  });
-
-  return (
-    <div>
-      <input
-        value={query}
-        onChange={e => setQuery(e.target.value)}
-        placeholder="Search memories..."
-      />
-      {isLoading && <p>Searching...</p>}
-      {results.map(r => (
-        <div key={r.memory.id}>{r.memory.content}</div>
-      ))}
-    </div>
-  );
-}
-
-// Get context for AI
-function ChatWithContext() {
-  const { getContext, isLoading } = useMemoryContext();
-
-  const sendMessage = async (message: string) => {
-    const { context, memoriesUsed } = await getContext(message);
-
-    // Use context with your AI provider
-    const response = await callAI({
-      system: `Context:\n${context}`,
-      message
-    });
-  };
-
-  return <ChatUI onSend={sendMessage} />;
-}
-
-// Real-time updates
-function LiveMemoryFeed() {
-  const { latestEvent, events, isConnected } = useMemorySubscription({
-    userId: 'user-123',
-    eventTypes: ['memory.created', 'memory.updated']
-  });
-
-  useEffect(() => {
-    if (latestEvent?.type === 'memory.created') {
-      console.log('New memory:', latestEvent.memory);
-    }
-  }, [latestEvent]);
-
-  return (
-    <div>
-      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
-      <p>Events: {events.length}</p>
-    </div>
-  );
+```ts
+const r = await cilow.contextPack("what is Maya's salary", { anchor: "Maya", attribute: "salary" });
+if (r.abstained) {
+  // r.pack is empty; r.reason explains the configured gate decision.
+  return `I don't have that in memory (${r.reason}).`;
 }
+return r.pack;
 ```
 
-## WebSocket Support
-
-```typescript
-import { CilowWebSocket } from '@cilow/sdk/websocket';
-
-const ws = new CilowWebSocket({
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-key',
-  reconnectAttempts: 5,
-  heartbeatInterval: 30000
-});
-
-// Connect
-await ws.connect();
-
-// Subscribe to events
-ws.subscribe({ userId: 'user-123' });
-
-// Listen for memory events
-ws.onMemoryCreated((event) => {
-  console.log('New memory:', event.memory);
-});
-
-ws.onMemoryUpdated((event) => {
-  console.log('Updated memory:', event.memory);
-});
-
-ws.onMemoryDeleted((event) => {
-  console.log('Deleted memory ID:', event.memoryId);
-});
+Every read carries a `trace_id`. Hand it to `explain` for the audit trail — the cited claims,
+the tenant's conformal threshold `q_hat`, the best candidate's `best_nonconformity` (grounded iff
+`n ≤ q̂`, see `isGrounded`) — or to `feedback` so memory learns from the outcome. This is the
+difference between "I don't know" and a confident wrong answer.
 
-// Listen for graph events
-ws.onGraphNodeCreated((event) => {
-  console.log('New node:', event.node);
-});
+## Errors
 
-// Connection status
-ws.onConnectionStatus((event) => {
-  console.log('Connection:', event.status, event.reason);
-});
-
-// Wait for specific event
-const event = await ws.once('memory.created', 5000);
-
-// Disconnect
-ws.disconnect();
-```
-
-## TypeScript Types
-
-The SDK exports comprehensive TypeScript types:
-
-```typescript
-import type {
-  // Core types
-  Memory,
-  MemorySummary,
-  MemoryTier,
-  SearchResult,
-
-  // Graph types
-  GraphNode,
-  GraphEdge,
-  GraphSubgraph,
-
-  // Event types
-  CilowEvent,
-  MemoryCreatedEvent,
-  MemoryUpdatedEvent,
-
-  // Configuration
-  CilowConfig,
-  WebSocketConfig,
-
-  // API types
-  PaginatedResponse,
-  ContextResult,
-} from '@cilow/sdk';
-```
-
-## Error Handling
-
-```typescript
-import { CilowApiError, isApiError } from '@cilow/sdk';
+`CilowError` is thrown for genuine failures — auth (`401` / JSON-RPC `-32001`), bad params,
+transport errors, malformed responses. A deferral is not an error.
 
+```ts
+import { CilowError } from "@cilow/sdk";
 try {
-  await cilow.getMemory('invalid-id');
-} catch (error) {
-  if (error instanceof CilowApiError) {
-    console.log('API Error:', error.message);
-    console.log('Code:', error.code);
-    console.log('Status:', error.statusCode);
-    console.log('Details:', error.details);
-  }
+  await cilow.recall("...");
+} catch (e) {
+  if (e instanceof CilowError && e.isUnauthorized) { /* bad/expired token */ }
 }
 ```
 
-## Configuration Options
-
-```typescript
-const cilow = new Cilow({
-  // Required
-  apiUrl: 'https://api.cilow.ai',
-  apiKey: 'your-api-key',
-
-  // Optional
-  timeout: 30000,        // Request timeout (ms)
-  retries: 3,            // Retry attempts
-  debug: false,          // Enable debug logging
-  headers: {             // Custom headers
-    'X-Custom-Header': 'value'
-  }
-});
-```
-
-## License
+## Develop
 
-MIT
+```sh
+npm install
+npm run build     # tsc → dist/
+npm test          # node:test — client + adapters suites, mocks the HTTP layer (no server needed)
+npm run example   # runs examples/quickstart.ts against a live server
+```

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