@crowkis/client 0.5.0

package/README.md

@@ -0,0 +1,156 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/crowkis/crowkis-sdk/main/assets/banner.png" alt="Crowkis — the intelligent cache & memory for LLM apps, built in Rust" width="100%" />
+
+<p>
+<a href="https://www.npmjs.com/package/@crowkis/client"><img src="https://img.shields.io/npm/v/@crowkis/client?color=d62221&label=npm&logo=npm&logoColor=white" alt="npm" /></a>
+<img src="https://img.shields.io/badge/TypeScript-included-d62221?logo=typescript&logoColor=white" alt="TypeScript" />
+<a href="https://hub.docker.com/r/crowkis/crowkis"><img src="https://img.shields.io/docker/pulls/crowkis/crowkis?color=d62221&label=Docker&logo=docker&logoColor=white" alt="Docker" /></a>
+<img src="https://img.shields.io/badge/License-Apache_2.0-d62221" alt="Apache 2.0" />
+</p>
+
+<p>
+<a href="https://www.crowkis.com"><b>Website</b></a> &nbsp;·&nbsp;
+<a href="https://www.crowkis.com/docs/sdk-node"><b>Documentation</b></a> &nbsp;·&nbsp;
+<a href="https://hub.docker.com/r/crowkis/crowkis"><b>Docker Hub</b></a>
+</p>
+
+</div>
+
+## About Crowkis
+
+Every LLM app quietly pays the same bill twice. Users ask the same questions worded a
+hundred different ways, and each rewording is billed at full price. **Crowkis is an
+intelligent, Redis-compatible cache and memory layer that sits between your app and your
+model** — it recognises when a new question *means* the same as one it has already
+answered, and serves that answer instantly, for free.
+
+It is **model-agnostic**: you wrap the call you already make — to OpenAI, Anthropic, a
+local model, or whatever comes next — and Crowkis handles the rest. It also gives your
+agents **durable, semantic memory** that survives restarts and stays strictly isolated
+per tenant. The engine is written in Rust and ships as a single small container.
+
+This is the official **Node / TypeScript SDK**, with typings included.
+
+## Install
+
+```bash
+npm install @crowkis/client
+```
+
+## Run a Crowkis server
+
+```bash
+docker run -d -p 6383:6383 -v "$(pwd)/.crow:/data/.crow" \
+  crowkis/crowkis:latest server --data /data/.crow
+```
+
+The server listens on `6383` (cache/RESP), `6384` (dashboard/HTTP), and `6385` (gRPC).
+Image → [hub.docker.com/r/crowkis/crowkis](https://hub.docker.com/r/crowkis/crowkis).
+
+## Cache any model — the wrapper
+
+Wrap any async function whose first argument is the prompt. It matches on **meaning**, so
+rephrased prompts hit too. The body can call *any* provider.
+
+```ts
+import { Crowkis } from "@crowkis/client";
+
+const cache = new Crowkis({ tenant: "my-app" });
+
+const answer = cache.cached(async (prompt: string) => myModel(prompt), { ttl: 3600 });
+
+await answer("How do refunds work?");         // miss → your model runs, result cached
+await answer("What's the refund process?");   // semantic HIT → no model call, instant
+```
+
+Prefer an inline call?
+
+```ts
+const text = await cache.ask("How do refunds work?", async (p) => myModel(p), { ttl: 3600 });
+```
+
+## Read & write directly
+
+```ts
+const hit = await cache.lookup("what's the refund timeline?");
+if (hit) {
+  console.log(hit.text, hit.similarity, hit.confidence);
+} else {
+  await cache.store("what's the refund timeline?", "5–7 business days.", { ttl: 3600 });
+}
+```
+
+## Streaming
+
+```ts
+for await (const chunk of cache.stream("Explain vector caches", async (p) => myStream(p), { ttl: 3600 })) {
+  process.stdout.write(typeof chunk === "string" ? chunk : chunk.toString());
+}
+```
+
+## LangChain.js
+
+```ts
+import { CrowkisCache } from "@crowkis/client/langchain";
+import { OpenAI } from "@langchain/openai";
+
+const llm = new OpenAI({ cache: new CrowkisCache({ tenant: "my-app", ttl: 3600 }) });
+```
+
+## Agent memory (LangGraph.js or any loop)
+
+Durable, semantic, per-user memory. Every recall is scoped to its agent and user.
+
+```ts
+import { CrowkisMemory } from "@crowkis/client/memory";
+
+const mem = new CrowkisMemory("support-bot", { user: "alice" });
+await mem.remember("Alice prefers email over phone");
+await mem.recall("how should I contact Alice?");   // semantic recall
+```
+
+## Authentication
+
+If your server sets an auth token (`CROWKIS_AUTH_TOKEN`), pass it from your environment —
+never hard-code it. Keep it in a gitignored `.env`.
+
+```ts
+const cache = new Crowkis({
+  host: process.env.CROWKIS_HOST ?? "127.0.0.1",
+  port: Number(process.env.CROWKIS_PORT ?? 6383),
+  tenant: "my-app",
+  authToken: process.env.CROWKIS_TOKEN,   // from .env, not the code
+});
+```
+
+## Method reference
+
+| Group | Methods |
+|-------|---------|
+| **Caching** | `cached()` · `ask()` · `stream()` · `lookup()` · `store()` · `similar()` · `embed()` · `flush()` |
+| **Agent memory** | `cmemset` · `cmemget` · `cmemextract` · `cmemhistory` · `cmemforget` · `cmemlink` · `cmemgraph` |
+| **Sessions / docs / pins / tools** | `csession*` · `cdoc*` · `cpin*` · `ctool*` |
+| **Safety / cost / compliance** | `cguard` · `coutcheck` · `cbudget*` · `ckeylimit*` · `cpii*` |
+| **Evals / prompts / freshness / ops** | `ceval` · `cprompt*` · `csource*` · `cscan` · `csave` · `compact` |
+
+Full reference and guides at **[www.crowkis.com/docs/sdk-node](https://www.crowkis.com/docs/sdk-node)**.
+
+## Contributing
+
+Issues and pull requests are welcome at
+[github.com/crowkis/crowkis-sdk](https://github.com/crowkis/crowkis-sdk). The client is
+Apache-2.0 licensed and safe to fork, embed, and ship.
+
+<br/>
+
+<table>
+<tr>
+<td width="96"><img src="https://raw.githubusercontent.com/crowkis/crowkis-sdk/main/assets/founder.jpg" width="84" alt="Mohit Rohilla" /></td>
+<td>
+Built with care by <b><a href="https://github.com/itsmohitrohilla">Mohit Rohilla</a></b>, founder & creator of Crowkis — engineering the intelligent cache & memory layer for the agentic era, in Rust. 🦀
+</td>
+</tr>
+</table>
+
+<sub>© 2026 Crowkis · Licensed under Apache-2.0 · <a href="https://www.crowkis.com">crowkis.com</a></sub>

package/crowkis.proto

@@ -0,0 +1,76 @@
+syntax = "proto3";
+
+package crowkis.v1;
+
+service CrowkisCache {
+  rpc Get(GetRequest) returns (GetResponse);
+  rpc Set(SetRequest) returns (SetResponse);
+  rpc GetStream(GetRequest) returns (stream StreamChunk);
+  rpc Stats(Empty) returns (StatsResponse);
+  rpc Invalidate(InvalidateRequest) returns (InvalidateResponse);
+}
+
+message Empty {}
+
+message GetRequest {
+  bytes query = 1;
+  string tenant = 2;
+  string model = 3;
+  float threshold = 4;
+  uint32 chunk_tokens = 5;
+  uint32 delay_ms = 6;
+  string format = 7;
+  bytes image = 8;
+}
+
+message GetResponse {
+  bool hit = 1;
+  bytes response = 2;
+  float similarity = 3;
+  int64 ttl_remaining = 4;
+  bytes matched_key = 5;
+  float confidence = 6;
+  string hit_type = 7;
+}
+
+message SetRequest {
+  bytes query = 1;
+  bytes response = 2;
+  uint64 ttl_secs = 3;
+  string tenant = 4;
+  string model = 5;
+  bytes image = 6;
+}
+
+message SetResponse {
+  bool ok = 1;
+  string error = 2;
+}
+
+message StreamChunk {
+  bytes delta = 1;
+  bool is_final = 2;
+  string format = 3;
+}
+
+message StatsResponse {
+  uint64 total_requests = 1;
+  uint64 total_hits = 2;
+  uint64 total_misses = 3;
+  double hit_rate_pct = 4;
+  uint64 tokens_saved = 5;
+  double avg_confidence = 6;
+  double avg_latency_ms = 7;
+  uint64 vector_index_entries = 8;
+  uint64 memtable_bytes = 9;
+  uint64 memtable_keys = 10;
+}
+
+message InvalidateRequest {
+  string tenant = 1;
+}
+
+message InvalidateResponse {
+  bool ok = 1;
+  uint64 removed = 2;
+}

package/grpc.js

@@ -0,0 +1,121 @@
+"use strict";
+
+const path = require("node:path");
+
+function loadCrowkisGrpc(options = {}) {
+  let grpc;
+  let protoLoader;
+  try {
+    grpc = require("@grpc/grpc-js");
+    protoLoader = require("@grpc/proto-loader");
+  } catch (error) {
+    throw new Error("Crowkis gRPC support requires npm packages @grpc/grpc-js and @grpc/proto-loader");
+  }
+
+  const protoPath = options.protoPath || path.join(__dirname, "crowkis.proto");
+  const definition = protoLoader.loadSync(protoPath, {
+    defaults: true,
+    enums: String,
+    keepCase: false,
+    longs: Number,
+    oneofs: true,
+  });
+  return grpc.loadPackageDefinition(definition).crowkis.v1;
+}
+
+class CrowkisGrpcClient {
+  constructor(options = {}) {
+    const target = options.target || "127.0.0.1:6381";
+    const api = loadCrowkisGrpc(options);
+    let credentials;
+    if (options.credentials) {
+      credentials = options.credentials;
+    } else {
+      const grpc = require("@grpc/grpc-js");
+      credentials = grpc.credentials.createInsecure();
+    }
+    this.client = new api.CrowkisCache(target, credentials);
+    this.authToken = options.authToken;
+  }
+
+  metadata() {
+    if (!this.authToken) return undefined;
+    const grpc = require("@grpc/grpc-js");
+    const metadata = new grpc.Metadata();
+    metadata.set("x-crowkis-auth-token", this.authToken);
+    return metadata;
+  }
+
+  get(query, options = {}) {
+    return unary(this.client, "Get", request(query, options), this.metadata());
+  }
+
+  set(query, response, options = {}) {
+    return unary(
+      this.client,
+      "Set",
+      {
+        query: toBuffer(query),
+        response: toBuffer(response),
+        ttlSecs: Number(options.ttlSecs || options.ttl || 0),
+        tenant: options.tenant || "",
+        model: options.model || "",
+        image: options.image ? toBuffer(options.image) : Buffer.alloc(0),
+      },
+      this.metadata(),
+    );
+  }
+
+  getStream(query, options = {}) {
+    return this.client.GetStream(request(query, options), this.metadata());
+  }
+
+  stats() {
+    return unary(this.client, "Stats", {}, this.metadata());
+  }
+
+  invalidate(options = {}) {
+    return unary(this.client, "Invalidate", { tenant: options.tenant || "" }, this.metadata());
+  }
+
+  close() {
+    this.client.close();
+  }
+}
+
+function unary(client, method, payload, metadata) {
+  return new Promise((resolve, reject) => {
+    const callback = (error, response) => (error ? reject(error) : resolve(response));
+    if (metadata) client[method](payload, metadata, callback);
+    else client[method](payload, callback);
+  });
+}
+
+function request(query, options = {}) {
+  const payload = {
+    query: toBuffer(query),
+    tenant: options.tenant || "",
+    model: options.model || "",
+    format: options.format || "",
+  };
+  if (options.threshold !== undefined) payload.threshold = Number(options.threshold);
+  if (options.chunkTokens !== undefined || options.chunk_tokens !== undefined) {
+    payload.chunkTokens = Number(options.chunkTokens ?? options.chunk_tokens);
+  }
+  if (options.delayMs !== undefined || options.delay_ms !== undefined) {
+    payload.delayMs = Number(options.delayMs ?? options.delay_ms);
+  }
+  if (options.image) payload.image = toBuffer(options.image);
+  return payload;
+}
+
+function toBuffer(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  return Buffer.from(String(value));
+}
+
+module.exports = {
+  CrowkisGrpcClient,
+  loadCrowkisGrpc,
+};

package/index.d.ts

@@ -0,0 +1,142 @@
+export interface CrowkisClientOptions {
+  host?: string;
+  port?: number;
+  tenant?: string;
+  model?: string;
+  authToken?: string;
+  auth_token?: string;
+  timeoutMs?: number;
+}
+
+export interface CacheSetOptions {
+  ttl?: number;
+  tenant?: string;
+  model?: string;
+  modelVersion?: string;
+  model_version?: string;
+  image?: string | Buffer | Uint8Array;
+}
+
+export interface CacheGetOptions {
+  threshold?: number;
+  tenant?: string;
+  model?: string;
+  modelVersion?: string;
+  model_version?: string;
+  migrationMode?: "miss" | "refresh" | "recompute" | "force_miss" | "force-miss" | string;
+  migration_mode?: "miss" | "refresh" | "recompute" | "force_miss" | "force-miss" | string;
+  image?: string | Buffer | Uint8Array;
+}
+
+export interface StreamCacheOptions extends CacheGetOptions, CacheSetOptions {
+  chunkTokens?: number;
+  delayMs?: number;
+}
+
+export interface CacheHit {
+  response: Buffer;
+  text: string;
+  similarity: number;
+  ttlRemaining: number;
+  matchedKey: Buffer;
+  confidence: number;
+  hitType: string;
+  migrationPending: boolean;
+  migrationFromModelVersion: string | null;
+  migrationTargetModelVersion: string | null;
+  migrationCanaryId: string | null;
+  migrationPlannedAt: number | null;
+}
+
+export interface SimResult {
+  key: Buffer;
+  similarity: number;
+}
+
+export class CrowkisClient {
+  constructor(options?: CrowkisClientOptions);
+  connect(): Promise<void>;
+  close(): void;
+  execute(...args: Array<string | Buffer | Uint8Array>): Promise<unknown>;
+  ping(): Promise<boolean>;
+  get(key: string | Buffer | Uint8Array): Promise<Buffer | null>;
+  set(key: string | Buffer | Uint8Array, value: string | Buffer | Uint8Array, options?: { ttl?: number }): Promise<void>;
+  cset(query: string | Buffer | Uint8Array, response: string | Buffer | Uint8Array, options?: CacheSetOptions): Promise<void>;
+  cget(query: string | Buffer | Uint8Array, options?: CacheGetOptions): Promise<Buffer | null>;
+  cgetHit(query: string | Buffer | Uint8Array, options?: CacheGetOptions): Promise<CacheHit | null>;
+  cimgget(image: string | Buffer | Uint8Array, options?: CacheGetOptions): Promise<Buffer | null>;
+  csim(query: string | Buffer | Uint8Array, options?: { k?: number; tenant?: string }): Promise<SimResult[]>;
+  cflush(options?: { tenant?: string }): Promise<number>;
+  cvecCount(): Promise<number>;
+  getOrCompute(
+    query: string,
+    fn: (query: string) => Promise<string | Buffer | Uint8Array> | string | Buffer | Uint8Array,
+    options?: CacheGetOptions & CacheSetOptions,
+  ): Promise<string>;
+  streamGetOrCompute(
+    query: string,
+    fn: (
+      query: string,
+    ) =>
+      | AsyncIterable<string | Buffer | Uint8Array>
+      | Iterable<string | Buffer | Uint8Array>
+      | Promise<AsyncIterable<string | Buffer | Uint8Array> | Iterable<string | Buffer | Uint8Array>>
+      | string
+      | Buffer
+      | Uint8Array,
+    options?: StreamCacheOptions,
+  ): AsyncIterable<string | Buffer | Uint8Array>;
+}
+
+export interface CrowkisAdminOptions {
+  baseUrl?: string;
+  adminKey?: string;
+  timeoutMs?: number;
+}
+
+export class CrowkisAdmin {
+  constructor(options?: CrowkisAdminOptions);
+  health(): Promise<Record<string, unknown>>;
+  getStats(): Promise<Record<string, unknown>>;
+  updateThreshold(config: Record<string, unknown>): Promise<Record<string, unknown>>;
+  registerWebhook(webhook: Record<string, unknown>): Promise<Record<string, unknown>>;
+  invalidateSource(sourceId: string, extra?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  flushTenant(tenantId: string): Promise<Record<string, unknown>>;
+  cacheEntries(options?: { tenant?: string; limit?: number }): Promise<Record<string, unknown>>;
+  migrationProgress(options?: {
+    tenant?: string;
+    canaryId?: string;
+    canary_id?: string;
+    fromModelVersion?: string;
+    from_model_version?: string;
+    targetModelVersion?: string;
+    target_model_version?: string;
+    limit?: number;
+  }): Promise<Record<string, unknown>>;
+  canaryMigrationProgress(id: string, options?: { tenant?: string; limit?: number }): Promise<Record<string, unknown>>;
+  leaseMigrationWork(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  leaseCanaryMigrationWork(id: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  completeMigrationWork(item: Record<string, unknown>): Promise<Record<string, unknown>>;
+  failMigrationWork(item: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+export class CrowkisError extends Error {}
+
+export interface CrowkisGrpcClientOptions {
+  target?: string;
+  authToken?: string;
+  protoPath?: string;
+  credentials?: unknown;
+}
+
+export class CrowkisGrpcClient {
+  constructor(options?: CrowkisGrpcClientOptions);
+  get(query: string | Buffer | Uint8Array, options?: CacheGetOptions & StreamCacheOptions): Promise<Record<string, unknown>>;
+  set(query: string | Buffer | Uint8Array, response: string | Buffer | Uint8Array, options?: CacheSetOptions & { ttlSecs?: number }): Promise<Record<string, unknown>>;
+  getStream(query: string | Buffer | Uint8Array, options?: StreamCacheOptions): AsyncIterable<Record<string, unknown>>;
+  stats(): Promise<Record<string, unknown>>;
+  invalidate(options?: { tenant?: string }): Promise<Record<string, unknown>>;
+  close(): void;
+}
+
+export function loadCrowkisGrpc(options?: { protoPath?: string }): unknown;