@asklumora/sdk 0.1.0

package/README.md

@@ -0,0 +1,1162 @@
+
+# Lumora TypeScript SDK
+
+![enter image description here](https://olive-chemical-haddock-701.mypinata.cloud/ipfs/bafkreiejroy5o6reqsby3ds4mozzxu37tnirjiso2u47bb45evhijz3imy)
+  
+
+TypeScript SDK for building Lumora-powered AI chat, custom domain assistants, and game AI systems.
+
+  
+
+The package is designed for Node.js applications that want one consistent interface over multiple model providers. OpenAI is the default provider, with optional xAI and Gemini support available per request.
+
+
+  
+
+```bash
+
+npm  i  @asklumora/sdk
+
+```
+
+<div align="center">
+
+
+
+### Multi-Provider AI SDK for Chat, Assistants, Training, and Game AI
+
+<p>
+  <img src="https://img.shields.io/npm/v/lumora-sdk?style=for-the-badge" />
+  <img src="https://img.shields.io/npm/dm/lumora-sdk?style=for-the-badge" />
+  <img src="https://img.shields.io/github/license/your-org/lumora?style=for-the-badge" />
+  <img src="https://img.shields.io/github/stars/your-org/lumora?style=for-the-badge" />
+</p>
+
+## Tech Stack
+
+<p>
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
+  <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=node.js&logoColor=white" />
+  <img src="https://img.shields.io/badge/OpenAI-412991?style=for-the-badge&logo=openai&logoColor=white" />
+  <img src="https://img.shields.io/badge/Gemini-4285F4?style=for-the-badge&logo=google&logoColor=white" />
+  <img src="https://img.shields.io/badge/xAI-000000?style=for-the-badge&logo=x&logoColor=white" />
+</p>
+
+<p>
+  <img src="https://img.shields.io/badge/AI_SDK-Multi_Provider-blue?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Streaming-Supported-success?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Game_AI-Ready-orange?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Assistants-Customizable-purple?style=for-the-badge" />
+</p>
+
+</div>
+
+  
+
+## Core Capabilities
+
+  
+
+- Train custom AI assistants with your own documents, websites, datasets, or raw text
+
+- Build streaming conversational experiences with provider-independent request types
+
+- Use OpenAI by default, then switch to xAI or Gemini when a request needs it
+
+- Inject long-term memory into chat calls
+
+- Define function/tool schemas for tool-aware providers
+
+- Generate NPC dialogue, companion behavior, quests, lore, and contextual game interactions
+
+- Keep API keys out of source code with `dotenv`
+
+  
+
+## Runtime Requirements
+
+  
+
+- Node.js `>=18`
+
+- TypeScript `>=5`
+
+- ESM project support
+
+- Provider API keys loaded from `.env`
+
+  
+
+Node 18 or newer is required because the SDK uses the native `fetch`, `ReadableStream`, and Web API primitives available in modern Node runtimes.
+
+## Folder Structure
+```
+
+LUMORA/
+├── examples/
+│   ├── chat.ts
+│   ├── custom-assistant.ts
+│   ├── game-ai.ts
+│   ├── providers.ts
+│   └── streaming.ts
+│
+├── src/
+│   ├── providers/
+│   │   ├── base.ts
+│   │   ├── gemini.ts
+│   │   ├── openai.ts
+│   │   └── xai.ts
+│   │
+│   ├── types/
+│   │   ├── chat.ts
+│   │   ├── game.ts
+│   │   └── training.ts
+│   │
+│   ├── clients.ts
+│   ├── env.ts
+│   └── index.ts
+│
+├── .env
+├── .env.example
+├── .gitignore
+├── package.json
+├── package-lock.json
+├── README.md
+└── tsconfig.json
+
+```
+
+
+
+  
+
+## Environment Configuration
+
+  
+
+Lumora always loads environment variables through `dotenv`. Create a `.env` file in your app root:
+
+  
+
+```bash
+
+OPENAI_API_KEY=sk-your-openai-key
+
+XAI_API_KEY=xai-your-xai-key
+
+GEMINI_API_KEY=your-gemini-key
+
+  
+
+LUMORA_DEFAULT_PROVIDER=openai
+
+LUMORA_DEFAULT_MODEL=gpt-4o-mini
+
+```
+
+  
+
+Environment variables:
+
+  
+
+| Variable | Required | Description |
+
+| --- | --- | --- |
+
+| `OPENAI_API_KEY` | Required for OpenAI | Used by the default OpenAI provider. |
+
+| `XAI_API_KEY` | Required for xAI | Used when `provider: "xai"` is selected. |
+
+| `GEMINI_API_KEY` | Required for Gemini | Used when `provider: "gemini"` is selected. |
+
+| `LUMORA_DEFAULT_PROVIDER` | Optional | One of `openai`, `xai`, or `gemini`. Defaults to `openai`. |
+
+| `LUMORA_DEFAULT_MODEL` | Optional | Model used for the default provider when no request model is supplied. |
+
+  
+
+Provider-specific defaults are preserved. For example, if `LUMORA_DEFAULT_MODEL=gpt-4o-mini` and a request explicitly uses `provider: "gemini"`, the SDK uses Gemini's default model unless you pass a Gemini model manually.
+
+  
+
+## Quick Start
+
+  
+
+```ts
+
+import  "dotenv/config";
+
+import  { createLumoraClient }  from  "@asklumora/sdk";
+
+  
+
+const  lumora = createLumoraClient();
+
+  
+
+const  response = await  lumora.chat({
+
+messages: [
+
+{
+
+role:  "system",
+
+content:  "You are Lumora, a precise and helpful assistant."
+
+},
+
+{
+
+role:  "user",
+
+content:  "Create a launch tagline for an AI game studio."
+
+}
+
+]
+
+});
+
+  
+
+console.log(response.text);
+
+```
+
+  
+
+## Client Initialization
+
+  
+
+The simplest client uses `.env`:
+
+  
+
+```ts
+
+const  lumora = createLumoraClient();
+
+```
+
+  
+
+You can also override defaults in code:
+
+  
+
+```ts
+
+const  lumora = createLumoraClient({
+
+defaultProvider:  "openai",
+
+defaultModel:  "gpt-4o-mini"
+
+});
+
+```
+
+  
+
+API keys can be injected programmatically, although `.env` is recommended for normal application use:
+
+  
+
+```ts
+
+const  lumora = createLumoraClient({
+
+apiKeys: {
+
+openai: process.env.OPENAI_API_KEY,
+
+xai: process.env.XAI_API_KEY,
+
+gemini: process.env.GEMINI_API_KEY
+
+}
+
+});
+
+```
+
+  
+
+## Chat API
+
+  
+
+`chat()` accepts a provider-independent request and returns normalized text output plus the raw provider response.
+
+  
+
+```ts
+
+const  result = await  lumora.chat({
+
+provider:  "openai",
+
+model:  "gpt-4o-mini",
+
+temperature:  0.4,
+
+maxTokens:  600,
+
+messages: [
+
+{ role:  "system", content:  "Answer as a senior product engineer." },
+
+{ role:  "user", content:  "Design an AI support workflow for a SaaS app." }
+
+],
+
+metadata: {
+
+requestId:  "support-workflow-001"
+
+}
+
+});
+
+  
+
+console.log(result.provider);
+
+console.log(result.model);
+
+console.log(result.text);
+
+```
+
+  
+
+Request shape:
+
+  
+
+```ts
+
+interface  LumoraChatRequest {
+
+messages: LumoraMessage[];
+
+model?: string;
+
+provider?: "openai" | "xai" | "gemini";
+
+temperature?: number;
+
+maxTokens?: number;
+
+tools?: LumoraTool[];
+
+memory?: LumoraMemoryEntry[];
+
+metadata?: Record<string, unknown>;
+
+}
+
+```
+
+  
+
+Response shape:
+
+  
+
+```ts
+
+interface  LumoraChatResponse {
+
+provider: "openai" | "xai" | "gemini";
+
+model: string;
+
+text: string;
+
+toolCalls?: LumoraToolCall[];
+
+raw?: unknown;
+
+}
+
+```
+
+  
+
+## Streaming API
+
+  
+
+`streamChat()` returns an async iterable. Each yielded chunk contains normalized text and provider metadata.
+
+  
+
+```ts
+
+for  await (const  chunk  of  lumora.streamChat({
+
+messages: [
+
+{ role:  "user", content:  "Brainstorm five game mechanics using AI companions." }
+
+]
+
+})) {
+
+process.stdout.write(chunk.text);
+
+}
+
+```
+
+  
+
+Chunk shape:
+
+  
+
+```ts
+
+interface  LumoraStreamChunk {
+
+provider: "openai" | "xai" | "gemini";
+
+model: string;
+
+text: string;
+
+done: boolean;
+
+raw?: unknown;
+
+}
+
+```
+
+  
+
+## Provider Selection
+
+  
+
+OpenAI is the default:
+
+  
+
+```ts
+
+await  lumora.chat({
+
+messages: [{ role:  "user", content:  "Use the default provider." }]
+
+});
+
+```
+
+  
+
+Select a provider per request:
+
+  
+
+```ts
+
+await  lumora.chat({
+
+provider:  "xai",
+
+messages: [{ role:  "user", content:  "Use xAI for this request." }]
+
+});
+
+  
+
+await  lumora.chat({
+
+provider:  "gemini",
+
+model:  "gemini-1.5-flash",
+
+messages: [{ role:  "user", content:  "Use Gemini for this request." }]
+
+});
+
+```
+
+  
+
+Built-in provider defaults:
+
+  
+
+| Provider | Default Model | API Base |
+
+| --- | --- | --- |
+
+| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` |
+
+| xAI | `grok-2-latest` | `https://api.x.ai/v1` |
+
+| Gemini | `gemini-1.5-flash` | `https://generativelanguage.googleapis.com/v1beta` |
+
+  
+
+## Custom Provider Injection
+
+  
+
+You can register your own provider implementation if you want to proxy requests, add telemetry, or support another model API.
+
+  
+
+```ts
+
+import  type  {
+
+LumoraProvider,
+
+LumoraChatRequest,
+
+LumoraChatResponse,
+
+LumoraStreamChunk
+
+}  from  "@asklumora/sdk";
+
+  
+
+const  customProvider: LumoraProvider = {
+
+name:  "openai",
+
+defaultModel:  "my-proxied-model",
+
+async  chat(request: LumoraChatRequest): Promise<LumoraChatResponse> {
+
+return {
+
+provider:  "openai",
+
+model: request.model ??  "my-proxied-model",
+
+text:  "Response from my custom provider."
+
+};
+
+},
+
+async  *streamChat(): AsyncIterable<LumoraStreamChunk> {
+
+yield {
+
+provider:  "openai",
+
+model:  "my-proxied-model",
+
+text:  "Streaming response from my custom provider.",
+
+done:  false
+
+};
+
+yield {
+
+provider:  "openai",
+
+model:  "my-proxied-model",
+
+text:  "",
+
+done:  true
+
+};
+
+}
+
+};
+
+  
+
+const  lumora = createLumoraClient({
+
+providers: {
+
+openai: customProvider
+
+}
+
+});
+
+```
+
+  
+
+## Long-Term Memory
+
+  
+
+Memory entries are injected into the system context before each chat request.
+
+  
+
+```ts
+
+lumora.remember({
+
+content:  "The user prefers concise technical explanations.",
+
+importance:  0.8,
+
+metadata: {
+
+source:  "profile"
+
+}
+
+});
+
+  
+
+const  answer = await  lumora.chat({
+
+messages: [
+
+{ role:  "user", content:  "Explain embeddings in one paragraph." }
+
+]
+
+});
+
+```
+
+  
+
+Per-request memory is also supported:
+
+  
+
+```ts
+
+await  lumora.chat({
+
+memory: [
+
+{
+
+content:  "The current project is a fantasy RPG with persistent NPC relationships."
+
+}
+
+],
+
+messages: [
+
+{ role:  "user", content:  "Generate a companion greeting." }
+
+]
+
+});
+
+```
+
+  
+
+## Tool Calling Types
+
+  
+
+The SDK exposes provider-independent tool definitions. OpenAI-compatible tools are sent as function tools.
+
+  
+
+```ts
+
+const  response = await  lumora.chat({
+
+provider:  "openai",
+
+tools: [
+
+{
+
+name:  "search_inventory",
+
+description:  "Search product inventory by SKU or keyword.",
+
+parameters: {
+
+type:  "object",
+
+properties: {
+
+query: {
+
+type:  "string"
+
+}
+
+},
+
+required: ["query"]
+
+}
+
+}
+
+],
+
+messages: [
+
+{ role:  "user", content:  "Find waterproof boots under $150." }
+
+]
+
+});
+
+  
+
+console.log(response.toolCalls);
+
+```
+
+  
+
+## Custom AI Assistants
+
+  
+
+Lumora includes a typed assistant layer for domain-specific behavior. This is useful when you want an application-level assistant object that carries instructions, knowledge references, tools, and provider settings.
+
+  
+
+```ts
+
+const  assistant = lumora.createAssistant({
+
+name:  "Retail Support Assistant",
+
+instructions:  "Answer using the provided business knowledge. Be accurate and concise.",
+
+provider:  "openai",
+
+knowledge: [
+
+{
+
+type:  "document",
+
+name:  "Support Handbook",
+
+content:  "Unused items can be returned within 30 days with proof of purchase."
+
+},
+
+{
+
+type:  "website",
+
+name:  "Help Center",
+
+url:  "https://example.com/help"
+
+},
+
+{
+
+type:  "dataset",
+
+name:  "Product Catalog",
+
+content:  "SKU-1001: Waterproof hiking boot. SKU-1002: Lightweight trail shoe."
+
+}
+
+],
+
+tools: ["search_inventory", "create_return_label"],
+
+metadata: {
+
+tenantId:  "tenant_123"
+
+}
+
+});
+
+  
+
+const  answer = await  lumora.chatWithAssistant(
+
+assistant,
+
+"Can I return hiking boots after two weeks?"
+
+);
+
+```
+
+  
+
+Knowledge source types:
+
+  
+
+| Type | Use Case |
+
+| --- | --- |
+
+| `document` | Uploaded manuals, PDFs, handbooks, support docs. |
+
+| `website` | Public docs, help centers, knowledge base URLs. |
+
+| `dataset` | Structured business data, catalogs, CSV-derived content. |
+
+| `text` | Direct inline context. |
+
+  
+
+## AI for Games
+
+  
+
+Lumora has game-specific helpers for NPC dialogue and quest generation.
+
+  
+
+### NPC Dialogue
+
+  
+
+```ts
+
+const  dialogue = await  lumora.npcDialogue({
+
+character: {
+
+id:  "blacksmith-mira",
+
+name:  "Mira",
+
+description:  "A village blacksmith who remembers every blade she has forged.",
+
+personality:  "Warm, direct, and protective of the town.",
+
+memory: [
+
+{
+
+content:  "The player saved Mira's apprentice from the old mine."
+
+}
+
+]
+
+},
+
+context: {
+
+world:  "A coastal fantasy kingdom where storms reveal ancient ruins.",
+
+scene:  "The player enters Mira's forge at midnight.",
+
+lore: [
+
+"The lighthouse bell rings when sea spirits are near."
+
+]
+
+},
+
+playerMessage:  "I need a weapon before the tide rises."
+
+});
+
+  
+
+console.log(dialogue.text);
+
+```
+
+  
+
+### Dynamic Quest Generation
+
+  
+
+```ts
+
+const  quest = await  lumora.generateQuest({
+
+context: {
+
+world:  "A post-collapse city where factions control old transit tunnels.",
+
+player:  "Level 12 engineer with stealth upgrades.",
+
+questState: {
+
+factionTrust:  "neutral",
+
+discoveredTunnelMap:  true
+
+}
+
+},
+
+objective:  "Create a morally ambiguous rescue mission."
+
+});
+
+  
+
+console.log(quest.text);
+
+```
+
+  
+
+## Error Handling
+
+  
+
+Provider failures throw `LumoraProviderError`.
+
+  
+
+```ts
+
+import  { LumoraProviderError }  from  "@asklumora/sdk";
+
+  
+
+try  {
+
+await lumora.chat({
+
+provider:  "gemini",
+
+messages: [{ role:  "user", content:  "Hello." }]
+
+});
+
+}  catch (error) {
+
+if (error instanceof  LumoraProviderError) {
+
+console.error(error.provider);
+
+console.error(error.status);
+
+console.error(error.details);
+
+}
+
+  
+
+throw error;
+
+}
+
+```
+
+  
+
+Common causes:
+
+  
+
+- Missing provider API key in `.env`
+
+- Invalid model name for the selected provider
+
+- Provider-side rate limit or quota error
+
+- Network failure between your runtime and the provider API
+
+- Passing an OpenAI model while explicitly selecting Gemini or xAI
+
+  
+
+## Running Examples
+
+  
+
+Install dependencies and build:
+
+  
+
+```bash
+
+npm  install
+
+npm  run  build
+
+```
+
+  
+
+Run examples from a Unix-like shell:
+
+  
+
+```bash
+
+node  ./dist/examples/chat.js
+
+node  ./dist/examples/streaming.js
+
+node  ./dist/examples/providers.js
+
+node  ./dist/examples/game-ai.js
+
+node  ./dist/examples/custom-assistant.js
+
+```
+
+  
+
+Run examples from PowerShell:
+
+  
+
+```powershell
+
+node .\dist\examples\chat.js
+
+node .\dist\examples\streaming.js
+
+node .\dist\examples\providers.js
+
+node .\dist\examples\game-ai.js
+
+node .\dist\examples\custom-assistant.js
+
+```
+
+  
+
+## Project Structure
+
+  
+
+```text
+
+src/
+
+client.ts Main LumoraSDK client and high-level workflows
+
+env.ts dotenv loading and environment validation helpers
+
+index.ts Public package exports
+
+providers/
+
+base.ts Provider contract and provider error type
+
+gemini.ts Gemini REST adapter
+
+openai.ts OpenAI chat and streaming adapter
+
+xai.ts xAI chat and streaming adapter
+
+types/
+
+chat.ts Chat, streaming, memory, and tool types
+
+game.ts NPC and quest generation types
+
+training.ts Assistant and knowledge source types
+
+examples/
+
+chat.ts Basic chat example
+
+custom-assistant.ts Domain assistant example
+
+game-ai.ts NPC dialogue example
+
+providers.ts Multi-provider example
+
+streaming.ts Streaming response example
+
+```
+
+  
+
+## Build and Typecheck
+
+  
+
+```bash
+
+npm  run  typecheck
+
+npm  run  build
+
+```
+
+  
+
+The package emits ESM JavaScript and TypeScript declarations into `dist/`.
+
+  
+
+```text
+
+dist/
+├── src/
+├── examples/
+│   └── chat.js
+├── index.js
+└── index.d.ts
+
+```
+
+  
+
+## Publishing Checklist
+
+  
+
+Before publishing `@asklumora/sdk`:
+
+  
+
+1. Confirm `package.json` version is correct.
+
+2. Run `npm run typecheck`.
+
+3. Run `npm run build`.
+
+4. Inspect package contents with `npm pack --dry-run`.
+
+5. Publish with `npm publish --access public`.
+
+  
+
+## Security Notes
+
+  
+
+- Never commit `.env` files.
+
+- Use separate API keys for development, staging, and production.
+
+- Route browser or mobile requests through your own backend if you need to protect provider keys.
+
+- Treat uploaded documents, website content, datasets, and tool outputs as untrusted application data.
+
+- Log provider errors carefully so raw responses do not leak user content or credentials.
+
+  
+
+## Current Scope
+
+  
+
+This SDK provides a typed provider abstraction and high-level Lumora workflows. It does not currently persist assistants, upload files to provider-specific fine-tuning APIs, manage vector indexes, or store long-term memory outside the current client instance. Those features can be layered behind the existing assistant, knowledge source, and provider interfaces.