luki-sdk-js

---

License

This project is licensed under the [Apache 2.0 License with ReMeLife custom clauses]

---

Official JavaScript/TypeScript SDK for the LUKi AI & ReMeLife APIs

---

1. What is this?

@remelife/luki-sdk is the easiest way to call:

• LUKi Core Agent (chat, streaming, tool calls)
• ELR / Memory endpoints (ingest, search)
• Activity & wellbeing services (recommendations, reports)
• Token / consent endpoints (optional)

Works in Node.js (>=18) and modern browsers (ESM). Includes full TypeScript types, an async streaming API, and small helper utilities.

---

2. Features

• Promise & async iterator streaming APIs
• Automatic retries / backoff
• Built‑in types and Zod schemas
• File & chunk upload helpers for ELR ingestion
• Tree‑shakeable ESM build
• Optional CLI (npx luki) for quick calls

---

3. Install

npm install @remelife/luki-sdk
# or
yarn add @remelife/luki-sdk
# or
pnpm add @remelife/luki-sdk

---

4. Quick Start (Node.js)

import { LukiClient } from "@remelife/luki-sdk";

const client = new LukiClient({
  baseUrl: "https://api.luki.ai",
  apiKey: process.env.LUKI_API_KEY!,
});

// 1) Simple chat
const resp = await client.chat.send({
  message: "I feel a bit low, any suggestions?",
});
console.log(resp.text);

// 2) Recommend activities
const acts = await client.activities.recommend({
  userId: "user_123",
  k: 3,
});
acts.forEach(a => console.log(a.title, "-", a.description));

// 3) Upload ELR chunk
await client.elr.uploadText({
  userId: "user_123",
  text: "Alice loves gardening and jazz. Wedding in 1975 in Madrid.",
  tags: ["interests", "life_event"],
});

---

5. Browser Usage

Use only from trusted front-ends. Never expose privileged API keys; use short-lived tokens.

<script type="module">
  import { LukiClient } from "https://cdn.skypack.dev/@remelife/luki-sdk";

  const client = new LukiClient({
    baseUrl: "https://api.luki.ai",
    apiKey: window.localStorage.getItem("lukikey"), // or token from your backend
  });

  const res = await client.chat.send({ message: "Hello from the browser!" });
  document.querySelector("#out").textContent = res.text;
</script>
<div id="out"></div>

---

6. Streaming (Async Iterator)

for await (const chunk of client.chat.stream({ message: "Tell me a story..." })) {
  process.stdout.write(chunk.delta);
}

---

7. API Surface (selected)

Chat

client.chat.send({
  message: string;
  userId?: string;
  context?: Record<string, any>;
  stream?: false;
}): Promise<{ text: string; toolCalls?: any[]; meta?: any }>

Memory / ELR

client.elr.uploadText({
  userId: string;
  text: string;
  tags?: string[];
  sensitivity?: "normal" | "sensitive";
}): Promise<{ id: string }>

client.elr.uploadFile({
  userId: string;
  file: Blob | Buffer | File;
  tags?: string[];
}): Promise<{ id: string }>

client.elr.search({
  userId: string;
  query: string;
  k?: number;
  filters?: Record<string, any>;
}): Promise<Array<{ id: string; text: string; score: number }>>

Activities

client.activities.recommend({ userId: string; k?: number; mood?: string })
client.activities.feedback({ activityId: string; rating: number; comment?: string })

Reports

client.reports.generate({ userId: string; windowDays?: number })
client.reports.get({ reportId: string })

Endpoints are under /v1/...; versioning is handled by the gateway. The SDK keeps compatibility with minor changes.

---

8. Configuration

Option	Env Var	Default	Description
baseUrl	LUKI_BASE_URL	https://api.luki.ai	API root
apiKey	LUKI_API_KEY	–	Auth token
timeoutMs	LUKI_TIMEOUT	30000	Request timeout
maxRetries	LUKI_RETRIES	3	HTTP retries
logLevel	LUKI_LOG	"info"	sdk logging level

You can also pass a custom fetch implementation or agent.

---

9. CLI (optional)

npx luki chat "Suggest a calming music activity"
npx luki elr upload --user user_123 --file story.txt
npx luki activities recommend --user user_123 -k 3

---

10. Error Handling

All API errors throw LukiHTTPError containing status and body.

import { LukiHTTPError } from "@remelife/luki-sdk";

try {
  await client.elr.uploadText({ userId: "x", text: "" });
} catch (e) {
  if (e instanceof LukiHTTPError) {
    console.error(e.status, e.body);
  }
}

---

11. Development

git clone [email protected]:REMELife/luki-sdk-js.git
cd luki-sdk-js
pnpm install   # or yarn / npm
pnpm test
pnpm build

We use eslint, prettier, vitest, tsup.

---

12. Contributing

SDK contributions welcome. For core agent internals, see private repos.
Read CONTRIBUTING.md and sign the CLA.

---

13. Versioning

Semantic versioning (MAJOR.MINOR.PATCH).
Breaking changes → MAJOR bump.

---

14. Security

Email [email protected] for vulnerabilities.
Do not post raw ELR data in issues—use synthetic examples.

---

15. License

Apache-2.0 © 2025 Singularities Ltd / ReMeLife.

---

16. Roadmap

• Browser-native streaming (ReadableStream) helper
• React hooks package (@remelife/luki-react)
• Upload resume & offline queue
• WebSocket transport (fallback to SSE/HTTP)

---

Care to Earn. Data to Own. AI to Empower.