@bhooai/nexus-ai-client 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @bhooai/nexus-ai-client
+
+Node client for the Python AI server: streaming (SSE), retries, and timeouts.
+The browser never calls Python directly — the Node backend proxies/re-emits SSE.
+
+## Exports
+
+- **AiClient** — `chat`, `chatStream` (async generator over an SSE stream),
+  `embeddings`, `models`. Retries with backoff, configurable timeout.
+- **parseSseStream** — the SSE parser (buffer → split on `\n\n` → collect `data:`
+  lines → JSON.parse → stop at `[DONE]`).
+- types + errors.
+
+## Usage
+
+```ts
+import { AiClient } from '@bhooai/nexus-ai-client';
+const ai = new AiClient({ serverUrl: 'http://localhost:8000', timeoutMs: 60_000 });
+for await (const chunk of ai.chatStream({ messages: [{ role: 'user', content: 'hi' }] })) {
+  process.stdout.write(chunk.delta ?? '');
+}
+```
+
+The Node→Python contract is defined in `contracts/` (single source of truth).

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@bhooai/nexus-ai-client",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/client.ts

@@ -0,0 +1,159 @@
+import type {
+  AiClientOptions,
+  ChatCompletionRequest,
+  ChatCompletionResponse,
+  ChatCompletionChunk,
+  EmbeddingRequest,
+  EmbeddingResponse,
+  ModelsResponse,
+  ImageGenRequest,
+  ImageGenResponse,
+  ImageGenModelsResponse,
+  AgentImageRequest,
+  AgentImageEvent,
+} from './types.js';
+import { AiError, isRetryable } from './errors.js';
+import { parseSseStream } from './sse.js';
+
+/**
+ * Node client for the BhooAI Nexus AI server (Python FastAPI). OpenAI-compatible.
+ * Supports non-streaming + streaming chat completions, embeddings, and model
+ * listing, with timeout (AbortController) and exponential-backoff retries on
+ * transient failures (network errors, 5xx, 429).
+ */
+export class AiClient {
+  private readonly serverUrl: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly retryDelayMs: number;
+  private readonly authToken?: string;
+
+  constructor(opts: AiClientOptions) {
+    this.serverUrl = opts.serverUrl.replace(/\/+$/, '');
+    this.timeoutMs = opts.timeoutMs ?? 60_000;
+    this.maxRetries = opts.maxRetries ?? 2;
+    this.retryDelayMs = opts.retryDelayMs ?? 500;
+    this.authToken = opts.authToken;
+  }
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json', ...extra };
+    if (this.authToken) h.authorization = `Bearer ${this.authToken}`;
+    return h;
+  }
+
+  private async request<T>(path: string, init: RequestInit, { stream = false } = {}): Promise<T> {
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const res = await fetch(`${this.serverUrl}${path}`, {
+          ...init,
+          signal: controller.signal,
+          headers: this.headers(init.headers as Record<string, string> | undefined),
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+          let message = `AI server ${res.status}`;
+          let code: string | undefined;
+          try {
+            const body = await res.json() as { error?: { message?: string; code?: string } };
+            message = body?.error?.message ?? message;
+            code = body?.error?.code;
+          } catch { /* non-JSON error body */ }
+          const err = new AiError(message, { status: res.status, code });
+          if (isRetryable(err) && attempt < this.maxRetries) {
+            lastErr = err;
+            await this.backoff(attempt);
+            continue;
+          }
+          throw err;
+        }
+        return (stream ? res : await res.json() as T) as T;
+      } catch (e) {
+        clearTimeout(timer);
+        // Abort → timeout; network errors are retryable.
+        const isAbort = e instanceof Error && e.name === 'AbortError';
+        const err = e instanceof AiError ? e : new AiError(isAbort ? 'AI request timed out' : String((e as Error)?.message ?? e));
+        if (isRetryable(err) && attempt < this.maxRetries) {
+          lastErr = err;
+          await this.backoff(attempt);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new AiError('AI request failed');
+  }
+
+  private async backoff(attempt: number): Promise<void> {
+    const delay = this.retryDelayMs * Math.pow(2, attempt);
+    // Tiny jitter without Math.random (deterministic): fold attempt into the delay.
+    await new Promise((r) => setTimeout(r, delay + attempt));
+  }
+
+  /** Non-streaming chat completion. */
+  async chat(req: ChatCompletionRequest): Promise<ChatCompletionResponse> {
+    const body = { ...req, stream: false };
+    return this.request<ChatCompletionResponse>('/chat/completions', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+  }
+
+  /** Streaming chat completion — yields chunks until the stream ends. */
+  async *chatStream(req: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown> {
+    const body = { ...req, stream: true };
+    const res = await this.request<Response>('/chat/completions', {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { accept: 'text/event-stream' },
+    }, { stream: true });
+    if (!res.body) throw new AiError('streaming response has no body');
+    for await (const chunk of parseSseStream(res.body as unknown as ReadableStream<Uint8Array>)) {
+      yield chunk as ChatCompletionChunk;
+    }
+  }
+
+  /** Create embeddings for one or more inputs. */
+  async embeddings(req: EmbeddingRequest): Promise<EmbeddingResponse> {
+    return this.request<EmbeddingResponse>('/embeddings', {
+      method: 'POST',
+      body: JSON.stringify(req),
+    });
+  }
+
+  /** List available models (optionally for a specific provider). */
+  async listModels(provider?: string): Promise<ModelsResponse> {
+    const qs = provider ? `?provider=${encodeURIComponent(provider)}` : '';
+    return this.request<ModelsResponse>(`/models${qs}`, { method: 'GET' });
+  }
+
+  /** Generate images via the local Stable Diffusion HTTP server. */
+  async images(req: ImageGenRequest): Promise<ImageGenResponse> {
+    return this.request<ImageGenResponse>('/images/generations', {
+      method: 'POST',
+      body: JSON.stringify(req),
+    });
+  }
+
+  /** List available image-generation models (SD checkpoints). */
+  async listImageModels(): Promise<ImageGenModelsResponse> {
+    return this.request<ImageGenModelsResponse>('/images/models', { method: 'GET' });
+  }
+
+  /** Agentic image loop — streams reasoning/tool/image/done events.
+   *  Drives the Ollama LLM (reasoning) + local SD server (pixels). */
+  async *agentImageStream(req: AgentImageRequest): AsyncGenerator<AgentImageEvent, void, unknown> {
+    const res = await this.request<Response>('/agent/image', {
+      method: 'POST',
+      body: JSON.stringify(req),
+      headers: { accept: 'text/event-stream' },
+    }, { stream: true });
+    if (!res.body) throw new AiError('agent stream response has no body');
+    for await (const chunk of parseSseStream(res.body as unknown as ReadableStream<Uint8Array>)) {
+      yield chunk as AgentImageEvent;
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+/** AI client errors. */
+
+export class AiError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+  constructor(message: string, opts: { status?: number; code?: string } = {}) {
+    super(message);
+    this.name = 'AiError';
+    this.status = opts.status;
+    this.code = opts.code;
+  }
+}
+
+/** True for transient errors worth retrying: network failures + 5xx + 429. */
+export function isRetryable(err: unknown): boolean {
+  if (err instanceof AiError) {
+    if (err.status === undefined) return true; // network-level failure
+    return err.status >= 500 || err.status === 429;
+  }
+  return true;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './errors.js';
+export { AiClient } from './client.js';
+export { parseSseStream } from './sse.js';

package/src/sse.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal SSE parser for the streaming chat endpoint. Reads a web
+ * ReadableStream<Uint8Array>, buffers bytes, splits events on blank lines, and
+ * yields the parsed `data:` JSON payload of each event. Stops at `[DONE]`.
+ */
+export async function* parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<any, void, unknown> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      // SSE events are separated by a blank line (\n\n). Process complete ones.
+      let idx: number;
+      while ((idx = buffer.indexOf('\n\n')) !== -1) {
+        const rawEvent = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        const payload = extractData(rawEvent);
+        if (payload === undefined) continue;
+        if (payload === '[DONE]') return;
+        try {
+          yield JSON.parse(payload);
+        } catch {
+          /* skip malformed */
+        }
+      }
+    }
+    // Flush any trailing event without a blank-line terminator.
+    if (buffer.trim()) {
+      const payload = extractData(buffer);
+      if (payload && payload !== '[DONE]') {
+        try { yield JSON.parse(payload); } catch { /* skip */ }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function extractData(event: string): string | undefined {
+  // An event may have multiple lines; collect `data:` fields (concatenated).
+  const parts: string[] = [];
+  for (const line of event.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('data:')) {
+      parts.push(trimmed.slice(5).trimStart());
+    }
+  }
+  if (parts.length === 0) return undefined;
+  return parts.join('\n');
+}

package/src/types.ts

@@ -0,0 +1,174 @@
+/** Types mirroring contracts/ai-openapi.yaml — the Node↔Python AI boundary. */
+
+export type Provider = 'openai' | 'ollama' | 'auto';
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface Message {
+  role: Role;
+  content: string;
+  name?: string;
+}
+
+export interface ChatCompletionRequest {
+  model: string;
+  messages: Message[];
+  stream?: boolean;
+  temperature?: number;
+  max_tokens?: number;
+  provider?: Provider;
+}
+
+export interface Choice {
+  index: number;
+  message: Message;
+  finish_reason: string | null;
+}
+
+export interface Usage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
+export interface ChatCompletionResponse {
+  id?: string;
+  model: string;
+  provider?: string;
+  choices: Choice[];
+  usage?: Usage;
+}
+
+export interface Delta {
+  role?: Role;
+  content?: string;
+}
+
+export interface ChunkChoice {
+  index: number;
+  delta: Delta;
+  finish_reason: string | null;
+}
+
+export interface ChatCompletionChunk {
+  id?: string;
+  model: string;
+  provider?: string;
+  choices: ChunkChoice[];
+}
+
+export interface EmbeddingRequest {
+  model: string;
+  input: string | string[];
+  provider?: Provider;
+}
+
+export interface EmbeddingData {
+  index: number;
+  embedding: number[];
+}
+
+export interface EmbeddingResponse {
+  model: string;
+  provider?: string;
+  data: EmbeddingData[];
+  usage?: Usage;
+}
+
+export interface ModelInfo {
+  id: string;
+  owned_by?: string;
+}
+
+export interface ModelsResponse {
+  provider?: string;
+  data: ModelInfo[];
+}
+
+export interface AiClientOptions {
+  /** AI server base URL, e.g. http://localhost:8000. */
+  serverUrl: string;
+  /** Request timeout in ms (default 60000). */
+  timeoutMs?: number;
+  /** Max retry attempts on network/5xx errors (default 2). */
+  maxRetries?: number;
+  /** Base delay for exponential backoff in ms (default 500). */
+  retryDelayMs?: number;
+  /** Optional Bearer token sent to the AI server. */
+  authToken?: string;
+}
+
+// ── Image generation (local Stable Diffusion HTTP server) ──────────────────
+// OpenAI-compatible /images/generations surface, plus the agentic loop.
+
+export interface ImageGenRequest {
+  prompt: string;
+  n?: number;
+  size?: string;
+  model?: string;
+  negative_prompt?: string;
+  steps?: number;
+  sampler?: string;
+  seed?: number;
+}
+
+export interface ImageGenData {
+  b64_json?: string;
+  url?: string;
+}
+
+export interface ImageGenMeta {
+  prompt: string;
+  negative_prompt: string;
+  model: string;
+  steps: number;
+  width: number;
+  height: number;
+  sampler: string;
+  seed: number | null;
+  n: number;
+  api: string;
+}
+
+export interface ImageGenResponse {
+  created: number;
+  data: ImageGenData[];
+  meta?: ImageGenMeta;
+}
+
+export interface ImageGenModelsResponse {
+  api: string;
+  data: Array<{ id: string; title: string }>;
+}
+
+// ── Agentic image loop ─────────────────────────────────────────────────────
+
+export interface AgentImageRequest {
+  /** The user's rough idea, e.g. "a cyberpunk fox in neon rain". */
+  idea: string;
+  /** Max agent iterations (default from server config). */
+  max_iterations?: number;
+}
+
+/** SSE event emitted by POST /agent/image. Discriminated by `type`. */
+export type AgentImageEvent =
+  | { type: 'thinking'; content: string; iteration: number }
+  | { type: 'tool'; name: string; args: Record<string, unknown>; iteration: number }
+  | { type: 'tool_error'; name: string; message: string; iteration: number }
+  | { type: 'image'; b64: string; prompt: string; iteration: number }
+  | { type: 'error'; message: string }
+  | AgentImageDoneEvent;
+
+export interface AgentImageDoneEvent {
+  type: 'done';
+  image_b64: string;
+  prompt: string;
+  negative_prompt: string;
+  style?: string | null;
+  aspect_ratio?: string | null;
+  model: string;
+  steps: number;
+  sampler?: string | null;
+  seed?: number | null;
+  iterations: number;
+  critique_log: Array<{ score?: number; feedback?: string; suggestions?: string[] }>;
+}

package/tests/ai-client.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+import { AiClient, AiError } from '../src/index.js';
+import type { ChatCompletionChunk } from '../src/index.js';
+
+type Handler = (req: IncomingMessage, res: ServerResponse, body: any) => void;
+
+function startServer(handler: Handler): Promise<{ server: Server; url: string }> {
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (c) => chunks.push(c));
+      req.on('end', () => {
+        let body: any = undefined;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { /* */ }
+        handler(req, res, body);
+      });
+    });
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      const url = `http://127.0.0.1:${(addr as { port: number }).port}`;
+      resolve({ server, url });
+    });
+  });
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+let servers: Server[] = [];
+async function withServer(handler: Handler, fn: (url: string) => Promise<void>): Promise<void> {
+  const { server, url } = await startServer(handler);
+  servers.push(server);
+  try { await fn(url); } finally { /* closed in afterEach */ }
+}
+
+afterEach(() => {
+  for (const s of servers) { (s as any).closeAllConnections?.(); s.close(); }
+  servers = [];
+});
+
+describe('AiClient', () => {
+  it('chat (non-stream) parses the response', async () => {
+    await withServer((_req, res, body) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        id: 'c1', model: body.model, provider: 'ollama',
+        choices: [{ index: 0, message: { role: 'assistant', content: 'Hi' }, finish_reason: 'stop' }],
+        usage: { prompt_tokens: 3, completion_tokens: 1, total_tokens: 4 },
+      }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url });
+      const r = await client.chat({ model: 'gpt-test', messages: [{ role: 'user', content: 'hi' }] });
+      expect(r.choices[0].message.content).toBe('Hi');
+      expect(r.provider).toBe('ollama');
+    });
+  });
+
+  it('chatStream yields chunks until [DONE]', async () => {
+    await withServer((_req, res, body) => {
+      res.writeHead(200, { 'content-type': 'text/event-stream' });
+      const chunks: ChatCompletionChunk[] = [
+        { id: 'c1', model: body.model, provider: 'openai', choices: [{ index: 0, delta: { role: 'assistant', content: 'Hel' }, finish_reason: null }] },
+        { id: 'c1', model: body.model, provider: 'openai', choices: [{ index: 0, delta: { content: 'lo' }, finish_reason: null }] },
+        { id: 'c1', model: body.model, provider: 'openai', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+      ];
+      for (const c of chunks) res.write(`data: ${JSON.stringify(c)}\n\n`);
+      res.write('data: [DONE]\n\n');
+      res.end();
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url });
+      const out: string[] = [];
+      for await (const c of client.chatStream({ model: 'gpt-test', messages: [{ role: 'user', content: 'hi' }] })) {
+        out.push(c.choices[0].delta.content ?? '');
+      }
+      expect(out.join('')).toBe('Hello');
+    });
+  });
+
+  it('embeddings (single + batch)', async () => {
+    await withServer((_req, res, body) => {
+      const n = Array.isArray(body.input) ? body.input.length : 1;
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        model: body.model, provider: 'openai',
+        data: Array.from({ length: n }, (_, i) => ({ index: i, embedding: [0.1, 0.2] })),
+        usage: { prompt_tokens: n, total_tokens: n },
+      }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url });
+      const single = await client.embeddings({ model: 'e', input: 'hello' });
+      expect(single.data).toHaveLength(1);
+      const batch = await client.embeddings({ model: 'e', input: ['a', 'b', 'c'] });
+      expect(batch.data).toHaveLength(3);
+    });
+  });
+
+  it('listModels forwards the provider query param', async () => {
+    await withServer((req, res) => {
+      expect(req.url).toBe('/models?provider=ollama');
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ provider: 'ollama', data: [{ id: 'llama3', owned_by: 'ollama' }] }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url });
+      const r = await client.listModels('ollama');
+      expect(r.data[0].id).toBe('llama3');
+    });
+  });
+
+  it('retries on 503 then succeeds', async () => {
+    let calls = 0;
+    await withServer((_req, res) => {
+      calls += 1;
+      if (calls < 3) { res.writeHead(503); res.end(JSON.stringify({ error: { message: 'down' } })); return; }
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ model: 'm', choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }], provider: 'openai' }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url, maxRetries: 3, retryDelayMs: 10 });
+      const r = await client.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }] });
+      expect(r.choices[0].message.content).toBe('ok');
+      expect(calls).toBe(3);
+    });
+  });
+
+  it('throws AiError (non-retryable) on 400', async () => {
+    await withServer((_req, res) => {
+      res.writeHead(400); res.end(JSON.stringify({ error: { message: 'bad', code: 'BAD' } }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url, maxRetries: 2, retryDelayMs: 10 });
+      await expect(client.chat({ model: 'm', messages: [] })).rejects.toThrow(/bad/);
+      await expect(client.chat({ model: 'm', messages: [] })).rejects.toBeInstanceOf(AiError);
+    });
+  });
+
+  it('times out and aborts the request', async () => {
+    await withServer((_req, res) => {
+      // Never respond.
+      setTimeout(() => res.end(), 5000);
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url, timeoutMs: 100, maxRetries: 0 });
+      await expect(client.chat({ model: 'm', messages: [] })).rejects.toThrow(/timed out|aborted/i);
+    });
+  });
+
+  it('sends the auth token header when configured', async () => {
+    await withServer((req, res) => {
+      expect(req.headers['authorization']).toBe('Bearer secret-token');
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ model: 'm', choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }], provider: 'openai' }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url, authToken: 'secret-token' });
+      await client.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }] });
+    });
+  });
+
+  it('forwards the `provider` field to the AI server for routing', async () => {
+    await withServer((_req, res, body) => {
+      expect(body.provider).toBe('auto'); // server routes on this; strips before upstream
+      expect(body.model).toBe('m');
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ model: 'm', choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }], provider: 'openai' }));
+    }, async (url) => {
+      const client = new AiClient({ serverUrl: url });
+      await client.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], provider: 'auto' });
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+    testTimeout: 20_000,
+  },
+});