@lumi0/sdk 0.0.2

package/README.md

@@ -0,0 +1,147 @@
+# Lumi0 TypeScript SDK
+
+The official TypeScript SDK for storing, retrieving, and compressing persistent
+AI memory with Lumi0.
+
+## Installation
+
+```bash
+bun add @lumi0/sdk
+```
+
+```bash
+npm install @lumi0/sdk
+```
+
+## Quick start
+
+Create a client with a Lumi0 API key:
+
+```ts
+import { Lumi0 } from "@lumi0/sdk";
+
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+```
+
+Store a memory, then search for relevant context:
+
+```ts
+await client.store({
+	id: "user_123",
+	content: "The user prefers concise TypeScript examples.",
+});
+
+const memories = await client.search({
+	id: "user_123",
+	query: "What coding examples does the user prefer?",
+	limit: 5,
+});
+```
+
+## API
+
+### `store`
+
+Stores one memory for an identifier.
+
+```ts
+await client.store({
+	id: "user_123",
+	content: "The user uses Bun and TypeScript.",
+	dedupeThreshold: 0.9,
+});
+```
+
+### `batch`
+
+Stores multiple memories in one request.
+
+```ts
+await client.batch([
+	{
+		id: "user_123",
+		content: "The user works with Hono.",
+	},
+	{
+		id: "user_123",
+		content: "The user prefers practical implementation details.",
+	},
+]);
+```
+
+### `search`
+
+Searches memories semantically.
+
+```ts
+const memories = await client.search({
+	id: "user_123",
+	query: "Which backend framework does the user use?",
+	limit: 10,
+	minSimilarity: 0.7,
+	memoryType: "semantic",
+});
+```
+
+### `get`
+
+Retrieves a memory by identifier. Pass `version` to retrieve a specific version.
+
+```ts
+const memory = await client.get({
+	id: "memory_123",
+	version: 2,
+});
+```
+
+### `forget`
+
+Deletes a memory for a user.
+
+```ts
+await client.forget({
+	id: "memory_123",
+	userId: "user_123",
+});
+```
+
+### `compress`
+
+Reduces context while retaining information relevant to a query.
+
+```ts
+const result = await client.compress({
+	content: JSON.stringify(memories),
+	query: "What is the user's preferred backend stack?",
+	mode: "adaptive",
+	budgetRatio: 0.5,
+});
+
+console.log(result.data.compressedText);
+console.log(`${result.data.tokensSaved} tokens saved`);
+```
+
+Use `"fixed"` mode with `budgetRatio` to target a specific retained-context
+ratio. Use `"adaptive"` mode to let Lumi0 determine the appropriate amount of
+context to retain for the query.
+
+## Configuration
+
+```ts
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+	baseUrl: "https://api.lumi0.com/api/v1",
+	timeout: 30_000,
+});
+```
+
+`baseUrl` defaults to `https://api.lumi0.com/api/v1` and `timeout` defaults to
+30 seconds.
+
+## Errors
+
+SDK requests reject with an `Error` when Lumi0 returns a non-success status.
+The error message includes the HTTP status and the API-provided error message
+when available.

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+//#region ../../../apps/api/src/shared/utils/types.d.ts
+interface ForgetMemoryInput {
+  userId: string;
+  id: string;
+}
+//#endregion
+//#region src/types.d.ts
+type Lumi0Options = {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+};
+//#endregion
+//#region src/client.d.ts
+declare class Lumi0 {
+  private readonly http;
+  constructor(option: Lumi0Options);
+  store(input: StoreMemoryInput): Promise<unknown>;
+  search(input: SearchMemoryInput): Promise<unknown>;
+  get(input: GetMemoryInput): Promise<unknown>;
+  forget(input: ForgetMemoryInput): Promise<unknown>;
+  batch(input: StoreMemoryInput[]): Promise<unknown>;
+  compress(input: CompressMemoryInput): Promise<CompressMemoryApiResponse>;
+}
+interface StoreMemoryInput {
+  content: string;
+  dedupeThreshold?: number;
+  id: string;
+}
+interface SearchMemoryInput {
+  query: string;
+  limit?: number;
+  minSimilarity?: number;
+  memoryType?: string;
+  id: string;
+}
+interface GetMemoryInput {
+  id: string;
+  version?: number;
+}
+interface CompressMemoryInput {
+  content: string;
+  query?: string;
+  budgetRatio?: number;
+  mode: "fixed" | "adaptive";
+}
+interface CompressMemoryResult {
+  compressedText: string;
+  originalTokens: number;
+  keptTokens: number;
+  tokensSaved: number;
+  tokensSavedPct: number;
+  keepRatio: number;
+  mode: "fixed" | "adaptive";
+  policyName: string;
+  keptLineRatio: number;
+}
+interface CompressMemoryApiResponse {
+  success: boolean;
+  data: CompressMemoryResult;
+}
+//#endregion
+export { CompressMemoryApiResponse, CompressMemoryInput, CompressMemoryResult, GetMemoryInput, Lumi0, SearchMemoryInput, StoreMemoryInput };

package/dist/index.mjs

@@ -0,0 +1,112 @@
+//#region src/http.ts
+var HttpClient = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async request(path, init = {}) {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), this.options.timeout ?? 3e4);
+		try {
+			const response = await fetch(`${this.options.baseUrl}${path}`, {
+				...init,
+				signal: controller.signal,
+				headers: {
+					Authorization: `Bearer ${this.options.apiKey}`,
+					"Content-Type": "application/json",
+					Accept: "application/json",
+					"User-Agent": "lumi0-sdk/0.1.0",
+					...this.options.headers,
+					...init.headers
+				}
+			});
+			if (!response.ok) throw await this.parseError(response);
+			if (response.status === 204) return;
+			return await response.json();
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	get(path) {
+		return this.request(path);
+	}
+	post(path, body) {
+		return this.request(path, {
+			method: "POST",
+			body: body ? JSON.stringify(body) : void 0
+		});
+	}
+	list(path, items) {
+		return this.request(path, {
+			method: "POST",
+			body: JSON.stringify(items)
+		});
+	}
+	put(path, body) {
+		return this.request(path, {
+			method: "PUT",
+			body: body ? JSON.stringify(body) : void 0
+		});
+	}
+	patch(path, body) {
+		return this.request(path, {
+			method: "PATCH",
+			body: body ? JSON.stringify(body) : void 0
+		});
+	}
+	delete(path, query) {
+		const params = new URLSearchParams();
+		if (query) {
+			for (const [key, value] of Object.entries(query)) if (value !== void 0) params.append(key, String(value));
+		}
+		const url = params.toString() ? `${path}?${params}` : path;
+		return this.request(url, { method: "DELETE" });
+	}
+	async parseError(response) {
+		let message = response.statusText;
+		try {
+			const json = await response.json();
+			message = json.message ?? json.error ?? response.statusText;
+		} catch {}
+		return /* @__PURE__ */ new Error(`${response.status} ${message}`);
+	}
+};
+//#endregion
+//#region src/client.ts
+var Lumi0 = class {
+	http;
+	constructor(option) {
+		const apiKey = option.apiKey;
+		this.http = new HttpClient({
+			baseUrl: option.baseUrl ?? "https://api.lumi0.com/api/v1",
+			apiKey,
+			timeout: option.timeout ?? 3e4
+		});
+	}
+	store(input) {
+		return this.http.post("/memory", {
+			...input,
+			externalId: input.id
+		});
+	}
+	search(input) {
+		return this.http.post("/memory/search", {
+			...input,
+			externalId: input.id
+		});
+	}
+	get(input) {
+		return this.http.post("/memory/get", input);
+	}
+	forget(input) {
+		return this.http.delete(`/memory/${input.id}`, { userId: input.userId });
+	}
+	batch(input) {
+		return this.http.post("/memory/batch", input.map((item) => ({ ...item })));
+	}
+	compress(input) {
+		return this.http.post("/compress", input);
+	}
+};
+//#endregion
+export { Lumi0 };

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@lumi0/sdk",
+	"version": "0.0.2",
+	"description": "Official TypeScript SDK for Lumi0",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/lumi0ai/lumi0-ts.git"
+	},
+	"homepage": "https://lumi0.com",
+	"keywords": [
+		"lumi0",
+		"ai",
+		"memory",
+		"ai-memory",
+		"llm",
+		"typescript",
+		"sdk"
+	],
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsdown index.ts",
+		"dev": "bun --watch index.ts",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "bun run typecheck && bun run build"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"tsdown": "^0.22.14",
+		"typescript": "^5"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}