praixis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael E. Ramirez A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Praixis Engine — Node.js Client
+
+A lightweight, **zero-dependency** Node.js client for the Praixis Engine API.
+It is built on the global `fetch` (Node 18+), so an upstream package release
+can never break it.
+
+- Promise-based, async/await API
+- No runtime dependencies
+- Ships hand-authored TypeScript declarations (`index.d.ts`) — no build step
+- Resource-grouped: `client.chat`, `client.rag`
+
+> The companion Python client lives in its own repository.
+
+## Installation
+
+```bash
+npm install praixis
+```
+
+Requires Node.js 18+. The package is ESM (`"type": "module"`).
+
+## Authentication
+
+Every request authenticates with your app API key, sent as the `X-API-Key`
+header. The server's admin panel (`/api/system/*`, HTTP Basic) is intentionally
+not exposed by this client — admin tasks belong in the browser UI, and embedding
+admin credentials in app code is an anti-pattern.
+
+```js
+import { PraixisClient } from "praixis";
+
+const client = new PraixisClient("http://localhost:8080", "your-api-key", {
+  timeoutMs: 30000, // optional, default 30s
+});
+```
+
+## Chat
+
+```js
+// Start a conversation
+const reply = await client.chat.send("Hello, world!");
+console.log(reply.session_id, reply.response);
+
+// Continue it
+await client.chat.send("And again?", { sessionId: reply.session_id });
+
+// JSON-mode response, custom system prompt
+await client.chat.send("List 3 colors", { responseFormat: "json", systemPrompt: "Be terse" });
+
+// Sessions
+await client.chat.listSessions();        // -> [sessionId, ...]
+await client.chat.getHistory(sessionId); // -> { session_id, history: [...] }
+await client.chat.clearHistory(sessionId);
+
+// Summarize an uploaded file ({ filename, content[, contentType] } or a Blob/File)
+await client.chat.summarizeFile({ filename: "notes.txt", content: "raw text here" });
+```
+
+### Streaming
+
+The server streams chat, RAG answers, and file summaries as `text/event-stream`.
+The buffered methods above (`send`, `ask`, `summarizeFile`) collect the whole
+response and return it decoded — the right default for scripts and backends.
+
+For token-by-token output, use the streaming variants, which return an async
+iterator of events. Marker events (`session_id`, `search_query`, `sources`,
+`file`, `progress`, `error`) arrive before the `token` events that carry content:
+
+```js
+for await (const event of client.chat.stream("Tell me a story")) {
+  if (event.type === "token") process.stdout.write(event.value);
+  else if (event.type === "session_id") console.log("session:", event.value);
+}
+
+// RAG: client.rag.askStream(question, { collectionName })
+//   -> session_id, search_query, sources, then token events
+// File summary: client.chat.summarizeFileStream(file)
+//   -> file, [progress...], then token events
+```
+
+## RAG
+
+```js
+// Ingest one or many documents into a collection
+await client.rag.upload({ filename: "manual.txt", content: "..." }, { collectionName: "docs" });
+await client.rag.upload(
+  [
+    { filename: "a.txt", content: "..." },
+    { filename: "b.txt", content: "..." },
+  ],
+  { collectionName: "docs" },
+);
+
+// Ask a question grounded in a collection
+const ans = await client.rag.ask("What does the manual say about setup?", { collectionName: "docs" });
+console.log(ans.answer, ans.sources);
+
+// Embeddings, listing, deletion, compare, summarize
+await client.rag.embed("some text");
+await client.rag.listCollections();
+await client.rag.listFiles("docs");
+await client.rag.deleteFile("docs", "a.txt");
+await client.rag.deleteCollection("docs");
+await client.rag.compare("docs", "a.txt", "b.txt");
+await client.rag.summarizeDocument("docs", "manual.txt");
+```
+
+## Error handling
+
+```js
+import { APIError, AuthenticationError, NotFoundError, RateLimitError, APIConnectionError } from "praixis";
+
+try {
+  await client.chat.send("hi");
+} catch (err) {
+  if (err instanceof AuthenticationError) { /* 401 / 403 */ }
+  else if (err instanceof NotFoundError) { /* 404 */ }
+  else if (err instanceof RateLimitError) { /* 429 */ }
+  else if (err instanceof APIError) { console.log(err.statusCode, err.detail); }
+  else if (err instanceof APIConnectionError) { /* never reached the server */ }
+}
+```
+
+All errors inherit from `PraixisError`.
+
+## Testing
+
+The suite runs against a standard-library mock HTTP server — no network, no
+dependencies:
+
+```bash
+npm test        # node --test
+```
+
+## Privacy note
+
+This client transmits whatever you pass to it (prompts, documents, session IDs)
+to the configured Praixis Engine server. Those payloads may contain personal
+data — handle them according to your own privacy obligations. The client stores
+nothing locally and adds no telemetry.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Type declarations for the Praixis Engine Node.js client.
+ * Hand-authored - the runtime is plain JavaScript with zero dependencies.
+ *
+ * Only confirmed response shapes are typed; loosely-defined server responses
+ * are returned as `Record<string, unknown>` so extra fields are never lost.
+ */
+
+export type ResponseFormat = "text" | "json";
+export type ChunkingStrategy = "semantic" | "character";
+
+/**
+ * An event yielded by the streaming methods (`chat.stream`, `rag.askStream`,
+ * `chat.summarizeFileStream`). Markers arrive before `token` events.
+ */
+export type StreamEvent =
+  | { type: "session_id"; value: string }
+  | { type: "search_query"; value: string }
+  | { type: "sources"; value: string[] }
+  | { type: "file"; value: string }
+  | { type: "progress"; value: string }
+  | { type: "error"; value: string }
+  | { type: "token"; value: string };
+
+export interface ChatMessage {
+  role: string;
+  content: string;
+  [key: string]: unknown;
+}
+
+export interface ChatResponse {
+  /** From the stream's [SESSION_ID:...] marker; null if absent. */
+  session_id: string | null;
+  /** Assembled reply text for "text"; parsed JSON for "json" (raw text if it failed to parse). */
+  response: unknown;
+  response_format: string;
+}
+
+export interface SummaryResponse {
+  /** From the stream's [FILE:...] marker; null if absent. */
+  filename: string | null;
+  /** Assembled summary text. */
+  summary: string;
+  /** Present only if the stream emitted an [ERROR:...] marker. */
+  error?: string;
+}
+
+export interface SessionHistory {
+  session_id: string;
+  history: ChatMessage[];
+}
+
+export interface StatusMessage {
+  status: string;
+  message: string;
+}
+
+/** Returned by clearHistory - the server uses `detail` here, not `message`. */
+export interface SessionDeleted {
+  status: string;
+  detail: string;
+}
+
+/** One per-file outcome from a multi-file upload. */
+export interface UploadResult {
+  filename: string | null;
+  status: "success" | "error";
+  detail?: string;
+}
+
+export interface UploadResponse {
+  collection_name: string;
+  processed: number;
+  succeeded: number;
+  results: UploadResult[];
+}
+
+export interface AskResponse {
+  answer: string;
+  /** Source filenames from the stream's [SOURCES:...] marker. */
+  sources: string[];
+  /** The (possibly reformulated) query from the [SEARCH_QUERY:...] marker. */
+  search_query: string | null;
+  session_id: string | null;
+}
+
+export type FileInput =
+  | { filename: string; content: string | Uint8Array | Blob; contentType?: string }
+  | Blob;
+
+export interface ClientOptions {
+  timeoutMs?: number;
+}
+
+export interface ChatOptions {
+  systemPrompt?: string;
+  sessionId?: string;
+  responseFormat?: ResponseFormat;
+}
+
+export interface SummarizeFileOptions {
+  task?: string;
+  tone?: string;
+}
+
+export interface UploadOptions {
+  collectionName?: string;
+  chunkSize?: number;
+  chunkOverlap?: number;
+  chunkingStrategy?: ChunkingStrategy;
+}
+
+export interface AskOptions {
+  collectionName: string;
+  sessionId?: string;
+  nResults?: number;
+  systemPrompt?: string;
+  metadataFilter?: Record<string, unknown>;
+}
+
+type Dict = Record<string, unknown>;
+
+export class ChatResource {
+  send(prompt: string, opts?: ChatOptions): Promise<ChatResponse>;
+  stream(prompt: string, opts?: ChatOptions): AsyncGenerator<StreamEvent>;
+  summarizeFile(file: FileInput, opts?: SummarizeFileOptions): Promise<SummaryResponse>;
+  summarizeFileStream(file: FileInput, opts?: SummarizeFileOptions): AsyncGenerator<StreamEvent>;
+  listSessions(): Promise<string[]>;
+  getHistory(sessionId: string): Promise<SessionHistory>;
+  clearHistory(sessionId: string): Promise<SessionDeleted>;
+}
+
+export class RagResource {
+  upload(files: FileInput | FileInput[], opts?: UploadOptions): Promise<UploadResponse>;
+  ask(question: string, opts: AskOptions): Promise<AskResponse>;
+  askStream(question: string, opts: AskOptions): AsyncGenerator<StreamEvent>;
+  embed(text: string): Promise<Dict>;
+  listCollections(): Promise<unknown[]>;
+  listFiles(collectionName: string): Promise<Dict>;
+  deleteCollection(collectionName: string): Promise<StatusMessage>;
+  deleteFile(collectionName: string, filename: string): Promise<StatusMessage>;
+  compare(collectionName: string, file1: string, file2: string): Promise<Dict>;
+  summarizeDocument(collectionName: string, filename: string): Promise<Dict>;
+}
+
+export class PraixisClient {
+  constructor(baseURL: string, apiKey?: string, opts?: ClientOptions);
+  readonly baseURL: string;
+  chat: ChatResource;
+  rag: RagResource;
+}
+
+export class PraixisError extends Error {}
+export class APIConnectionError extends PraixisError {
+  cause?: unknown;
+}
+export class APIError extends PraixisError {
+  statusCode: number;
+  body: string;
+  detail: string;
+}
+export class AuthenticationError extends APIError {}
+export class NotFoundError extends APIError {}
+export class RateLimitError extends APIError {}

package/index.js

@@ -0,0 +1,22 @@
+/**
+ * Praixis Engine Node.js client.
+ *
+ * A zero-dependency client built on the global `fetch` (Node 18+), so upstream
+ * package releases can never break it.
+ *
+ *   import { PraixisClient } from "praixis";
+ *
+ *   const client = new PraixisClient("http://localhost:8080", "my-api-key");
+ *   const reply = await client.chat.send("Hello");
+ *   console.log(reply.response);
+ */
+
+export { PraixisClient } from "./src/client.js";
+export {
+  PraixisError,
+  APIError,
+  APIConnectionError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+} from "./src/errors.js";

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "praixis",
+  "version": "0.1.0",
+  "description": "Zero-dependency Node.js client for the Praixis Engine API",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["praixis", "llm", "rag", "ai"],
+  "author": "Michael E. Ramirez A.",
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/client.js

@@ -0,0 +1,22 @@
+/** The top-level Praixis Engine client. */
+
+import { Transport } from "./transport.js";
+import { ChatResource } from "./resources/chat.js";
+import { RagResource } from "./resources/rag.js";
+
+export class PraixisClient {
+  /**
+   * @param {string} baseURL  Root URL, e.g. "http://localhost:8080".
+   * @param {string} [apiKey] Sent as the `X-API-Key` header on every request.
+   * @param {{ timeoutMs?: number }} [opts]
+   */
+  constructor(baseURL, apiKey = "", { timeoutMs = 30000 } = {}) {
+    this._transport = new Transport(baseURL, apiKey, { timeoutMs });
+    this.chat = new ChatResource(this._transport);
+    this.rag = new RagResource(this._transport);
+  }
+
+  get baseURL() {
+    return this._transport.baseURL;
+  }
+}

package/src/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Error types raised by the Praixis client.
+ *
+ * The hierarchy is intentionally small so callers can catch broadly
+ * (`PraixisError`) or narrowly (`AuthenticationError`) without depending on
+ * any third-party error classes.
+ */
+
+export class PraixisError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/** The request never reached the server (DNS, refused, timeout, TLS). */
+export class APIConnectionError extends PraixisError {
+  constructor(message, { cause } = {}) {
+    super(message);
+    if (cause) this.cause = cause;
+  }
+}
+
+/** The server returned a non-2xx response. */
+export class APIError extends PraixisError {
+  constructor(statusCode, body, detail) {
+    super(`API error (status ${statusCode}): ${detail ?? body}`);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.detail = detail ?? body;
+  }
+}
+
+/** A 401 or 403 response - missing or invalid API key. */
+export class AuthenticationError extends APIError {}
+
+/** A 404 response - the requested resource does not exist. */
+export class NotFoundError extends APIError {}
+
+/** A 429 response - the per-route rate limit was exceeded. */
+export class RateLimitError extends APIError {}
+
+/** Return the most specific APIError subclass for a status code. */
+export function errorForStatus(statusCode, body, detail) {
+  if (statusCode === 401 || statusCode === 403) return new AuthenticationError(statusCode, body, detail);
+  if (statusCode === 404) return new NotFoundError(statusCode, body, detail);
+  if (statusCode === 429) return new RateLimitError(statusCode, body, detail);
+  return new APIError(statusCode, body, detail);
+}

package/src/files.js

@@ -0,0 +1,30 @@
+/** Helpers for turning caller-supplied files into multipart parts. */
+
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+
+/**
+ * Normalize one file input into a part for the given field.
+ * Accepts:
+ *   - { filename, content, contentType? }
+ *   - a Blob/File (its own name is used unless `filename` is on it)
+ */
+export function toPart(item, field) {
+  if (item && typeof item === "object" && "content" in item) {
+    return {
+      field,
+      filename: item.filename,
+      content: item.content,
+      contentType: item.contentType ?? DEFAULT_CONTENT_TYPE,
+    };
+  }
+  if (item instanceof Blob) {
+    return { field, filename: item.name ?? "file", content: item, contentType: item.type || DEFAULT_CONTENT_TYPE };
+  }
+  throw new TypeError("file must be { filename, content, contentType? } or a Blob/File");
+}
+
+/** Normalize one file or an array of files into parts under `field`. */
+export function toParts(items, field) {
+  const list = Array.isArray(items) ? items : [items];
+  return list.map((it) => toPart(it, field));
+}

package/src/resources/chat.js

@@ -0,0 +1,97 @@
+/** Core AI endpoints - prefix /general-requests. */
+
+import { toPart } from "../files.js";
+import { streamEvents, collectStream } from "../stream.js";
+
+const PREFIX = "/general-requests";
+const DEFAULT_TASK = "Summarize the key points of this document.";
+const DEFAULT_TONE = "Professional and objective";
+
+export class ChatResource {
+  constructor(transport) {
+    this._t = transport;
+  }
+
+  _chatBody(prompt, { systemPrompt, sessionId, responseFormat = "text" } = {}) {
+    const body = { prompt, response_format: responseFormat };
+    if (systemPrompt !== undefined) body.system_prompt = systemPrompt;
+    if (sessionId !== undefined) body.session_id = sessionId;
+    return body;
+  }
+
+  _summaryArgs(file, { task = DEFAULT_TASK, tone = DEFAULT_TONE } = {}) {
+    return {
+      files: [toPart(file, "file")],
+      fields: [
+        { name: "task", value: task },
+        { name: "tone", value: tone },
+      ],
+    };
+  }
+
+  /**
+   * POST /general-requests/chat - send a prompt and get the full reply.
+   * Omit `sessionId` to start a new conversation. The server streams the reply;
+   * this buffers it and returns { session_id, response, response_format }.
+   */
+  async send(prompt, opts = {}) {
+    const { markers, body } = await collectStream(
+      this._t.requestStream("POST", `${PREFIX}/chat`, { body: this._chatBody(prompt, opts) }),
+    );
+    const responseFormat = opts.responseFormat ?? "text";
+    let response = body;
+    if (responseFormat === "json") {
+      try {
+        response = JSON.parse(body);
+      } catch {
+        // server didn't return valid JSON; hand back the raw text
+      }
+    }
+    return { session_id: markers.session_id ?? null, response, response_format: responseFormat };
+  }
+
+  /**
+   * POST /general-requests/chat - stream the reply incrementally, yielding
+   * `{ type: "session_id" | "token", value }` events as they arrive.
+   */
+  stream(prompt, opts = {}) {
+    return streamEvents(this._t.requestStream("POST", `${PREFIX}/chat`, { body: this._chatBody(prompt, opts) }));
+  }
+
+  /**
+   * POST /general-requests/file_summary - summarize one uploaded file.
+   * `file` is { filename, content, contentType? } or a Blob/File.
+   */
+  async summarizeFile(file, opts = {}) {
+    const { markers, body } = await collectStream(
+      this._t.uploadStream(`${PREFIX}/file_summary`, this._summaryArgs(file, opts)),
+    );
+    const result = { filename: markers.file ?? null, summary: body };
+    if (markers.error !== undefined) result.error = markers.error;
+    return result;
+  }
+
+  /**
+   * POST /general-requests/file_summary - stream the summary incrementally,
+   * yielding `{ type: "file" | "progress" | "error" | "token", value }` events.
+   */
+  summarizeFileStream(file, opts = {}) {
+    return streamEvents(this._t.uploadStream(`${PREFIX}/file_summary`, this._summaryArgs(file, opts)));
+  }
+
+  /** GET /general-requests/chat/sessions/active - active session IDs. */
+  async listSessions() {
+    const data = await this._t.requestJSON("GET", `${PREFIX}/chat/sessions/active`);
+    return data?.active_sessions ?? [];
+  }
+
+  /** GET /general-requests/chat/{sessionId} - a session's message history. */
+  async getHistory(sessionId) {
+    return this._t.requestJSON("GET", `${PREFIX}/chat/${encodeURIComponent(sessionId)}`);
+  }
+
+  /** DELETE /general-requests/chat/{sessionId} - clear a session. */
+  async clearHistory(sessionId) {
+    return this._t.requestJSON("DELETE", `${PREFIX}/chat/${encodeURIComponent(sessionId)}`);
+  }
+}

package/src/resources/rag.js

@@ -0,0 +1,105 @@
+/** Vector / RAG endpoints - prefix /rag-db. */
+
+import { toParts } from "../files.js";
+import { streamEvents, collectStream } from "../stream.js";
+
+const PREFIX = "/rag-db";
+
+export class RagResource {
+  constructor(transport) {
+    this._t = transport;
+  }
+
+  /**
+   * POST /rag-db/upload - ingest one or more documents into a collection.
+   * Each file is { filename, content, contentType? } or a Blob/File.
+   */
+  async upload(files, { collectionName = "main", chunkSize = 2000, chunkOverlap = 150, chunkingStrategy = "semantic" } = {}) {
+    return this._t.upload(`${PREFIX}/upload`, {
+      files: toParts(files, "files"),
+      fields: [
+        { name: "collection_name", value: collectionName },
+        { name: "chunk_size", value: String(chunkSize) },
+        { name: "chunk_overlap", value: String(chunkOverlap) },
+        { name: "chunking_strategy", value: chunkingStrategy },
+      ],
+    });
+  }
+
+  _askBody(question, { collectionName, sessionId, nResults = 5, systemPrompt, metadataFilter } = {}) {
+    const body = { collection_name: collectionName, question, n_results: nResults };
+    if (sessionId !== undefined) body.session_id = sessionId;
+    if (systemPrompt !== undefined) body.system_prompt = systemPrompt;
+    if (metadataFilter !== undefined) body.metadata_filter = metadataFilter;
+    return body;
+  }
+
+  /**
+   * POST /rag-db/ask - answer a question grounded in a collection. The server
+   * streams the answer; this buffers it and returns
+   * { answer, sources, search_query, session_id }.
+   */
+  async ask(question, opts = {}) {
+    const { markers, body: answer } = await collectStream(
+      this._t.requestStream("POST", `${PREFIX}/ask`, { body: this._askBody(question, opts) }),
+    );
+    return {
+      answer,
+      sources: markers.sources ?? [],
+      search_query: markers.search_query ?? null,
+      session_id: markers.session_id ?? null,
+    };
+  }
+
+  /**
+   * POST /rag-db/ask - stream the grounded answer incrementally, yielding
+   * `{ type: "session_id" | "search_query" | "sources" | "token", value }` events.
+   */
+  askStream(question, opts = {}) {
+    return streamEvents(this._t.requestStream("POST", `${PREFIX}/ask`, { body: this._askBody(question, opts) }));
+  }
+
+  /** POST /rag-db/embed - return the embedding vector for `text`. */
+  async embed(text) {
+    return this._t.requestJSON("POST", `${PREFIX}/embed`, { body: { text } });
+  }
+
+  /** GET /rag-db/list - collections owned by the calling app. */
+  async listCollections() {
+    const data = await this._t.requestJSON("GET", `${PREFIX}/list`);
+    return data?.active_collections ?? [];
+  }
+
+  /** GET /rag-db/{collectionName}/files - files in a collection. */
+  async listFiles(collectionName) {
+    return this._t.requestJSON("GET", `${PREFIX}/${encodeURIComponent(collectionName)}/files`);
+  }
+
+  /** DELETE /rag-db/delete/{collectionName} - remove an entire collection. */
+  async deleteCollection(collectionName) {
+    return this._t.requestJSON("DELETE", `${PREFIX}/delete/${encodeURIComponent(collectionName)}`);
+  }
+
+  /** DELETE /rag-db/{collectionName}/files/{filename} - remove one file. */
+  async deleteFile(collectionName, filename) {
+    return this._t.requestJSON(
+      "DELETE",
+      `${PREFIX}/${encodeURIComponent(collectionName)}/files/${encodeURIComponent(filename)}`,
+    );
+  }
+
+  /** POST /rag-db/knowledge_base/compare - compare two stored documents. */
+  async compare(collectionName, file1, file2) {
+    return this._t.requestJSON("POST", `${PREFIX}/knowledge_base/compare`, {
+      body: { collection_name: collectionName, file_1: file1, file_2: file2 },
+    });
+  }
+
+  /** GET /rag-db/knowledge_base/{collectionName}/files/{filename}/summary. */
+  async summarizeDocument(collectionName, filename) {
+    return this._t.requestJSON(
+      "GET",
+      `${PREFIX}/knowledge_base/${encodeURIComponent(collectionName)}/files/${encodeURIComponent(filename)}/summary`,
+    );
+  }
+}

package/src/stream.js

@@ -0,0 +1,108 @@
+/**
+ * Parser for the Praixis Engine's streamed responses.
+ *
+ * Chat, RAG `ask`, and file-summary endpoints are served as `text/event-stream`
+ * bodies that are NOT JSON. They begin with zero or more single-line markers and
+ * are followed by the raw generated content:
+ *
+ *   [SESSION_ID:<id>]\n
+ *   [SEARCH_QUERY:<query>]\n     (RAG ask only)
+ *   [SOURCES:<a.txt,b.txt>]\n    (RAG ask only)
+ *   [FILE:<filename>]\n          (file summary only)
+ *   [PROGRESS:<message>]\n       (file summary, large docs; may repeat)
+ *   [ERROR:<message>]\n          (in-stream failure; always before content)
+ *   ...content tokens...
+ *
+ * Markers are emitted on their own `\n`-terminated lines before any content, so
+ * we peel complete marker lines off the head of the stream and treat everything
+ * from the first non-marker byte onward as content.
+ */
+
+const MARKER_KEYS = ["SESSION_ID", "SEARCH_QUERY", "SOURCES", "FILE", "PROGRESS", "ERROR"];
+
+/** A complete leading marker line: `[KEY:value]\n`. */
+const MARKER_RE = new RegExp(`^\\[(${MARKER_KEYS.join("|")}):([^\\n]*)\\]\\n`);
+
+/** A buffer that is still a possible (incomplete) marker line: no `\n` yet. */
+const PARTIAL_MARKER_RE = /^\[[A-Z_]*(:[^\n]*)?$/;
+
+/** Server marker key -> public event type. */
+const EVENT_TYPE = {
+  SESSION_ID: "session_id",
+  SEARCH_QUERY: "search_query",
+  SOURCES: "sources",
+  FILE: "file",
+  PROGRESS: "progress",
+  ERROR: "error",
+};
+
+function markerEvent(key, value) {
+  if (key === "SOURCES") return { type: "sources", value: value ? value.split(",") : [] };
+  return { type: EVENT_TYPE[key], value };
+}
+
+/**
+ * Turn an async iterable of decoded text chunks into an async iterable of events:
+ *
+ *   { type: "session_id" | "search_query" | "file" | "progress" | "error", value: string }
+ *   { type: "sources", value: string[] }
+ *   { type: "token", value: string }   // a piece of the generated content
+ *
+ * @param {AsyncIterable<string>} chunks
+ * @returns {AsyncGenerator<{ type: string, value: string | string[] }>}
+ */
+export async function* streamEvents(chunks) {
+  let buffer = "";
+  let inContent = false;
+
+  const drainMarkers = function* () {
+    let m;
+    while ((m = MARKER_RE.exec(buffer))) {
+      yield markerEvent(m[1], m[2]);
+      buffer = buffer.slice(m[0].length);
+    }
+  };
+
+  for await (const chunk of chunks) {
+    if (inContent) {
+      if (chunk) yield { type: "token", value: chunk };
+      continue;
+    }
+    buffer += chunk;
+    yield* drainMarkers();
+    // The buffer no longer starts with a complete marker. If it can't still grow
+    // into one either, the marker section is over: the rest is content.
+    if (buffer && !PARTIAL_MARKER_RE.test(buffer)) {
+      yield { type: "token", value: buffer };
+      buffer = "";
+      inContent = true;
+    }
+  }
+
+  // End of stream: peel any trailing complete markers, emit the remainder.
+  yield* drainMarkers();
+  if (buffer) yield { type: "token", value: buffer };
+}
+
+/**
+ * Drain a {@link streamEvents} iterable into the buffered shape used by the
+ * non-streaming methods: `{ markers, body }`, where `markers` maps event type ->
+ * value (`progress` collects into an array) and `body` is the joined content.
+ *
+ * @param {AsyncIterable<string>} chunks
+ * @returns {Promise<{ markers: Record<string, string | string[]>, body: string }>}
+ */
+export async function collectStream(chunks) {
+  const markers = {};
+  let body = "";
+  for await (const ev of streamEvents(chunks)) {
+    if (ev.type === "token") {
+      body += ev.value;
+    } else if (ev.type === "progress") {
+      (markers.progress ??= []).push(ev.value);
+    } else {
+      markers[ev.type] = ev.value;
+    }
+  }
+  return { markers, body };
+}

package/src/transport.js

@@ -0,0 +1,137 @@
+/**
+ * Low-level HTTP transport built on the global `fetch` (Node 18+).
+ *
+ * Depends on nothing outside the Node runtime, so the client cannot be broken by
+ * an upstream package release. Every request authenticates with the app-level
+ * `X-API-Key` header; admin (`/api/system`) endpoints are intentionally not
+ * exposed by this SDK.
+ */
+
+import { APIConnectionError, errorForStatus } from "./errors.js";
+
+export class Transport {
+  constructor(baseURL, apiKey = "", { timeoutMs = 30000 } = {}) {
+    this.baseURL = baseURL.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+  }
+
+  _url(path, params) {
+    const url = new URL(this.baseURL + path);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+
+  _authHeader() {
+    return this.apiKey ? { "X-API-Key": this.apiKey } : {};
+  }
+
+  async _raise(resp) {
+    const body = await resp.text().catch(() => "");
+    let detail;
+    try {
+      const parsed = JSON.parse(body);
+      if (parsed && typeof parsed === "object" && "detail" in parsed) {
+        // FastAPI validation errors surface `detail` as a list/object; keep it
+        // readable instead of stringifying to "[object Object]".
+        detail = typeof parsed.detail === "string" ? parsed.detail : JSON.stringify(parsed.detail);
+      }
+    } catch {
+      // not JSON; leave detail undefined
+    }
+    return errorForStatus(resp.status, body, detail);
+  }
+
+  /** Perform the fetch with a timeout and raise on a non-2xx status. */
+  async _fetch(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await fetch(url, { ...init, signal: controller.signal });
+    } catch (err) {
+      const reason = err?.name === "AbortError" ? "request timed out" : err?.message;
+      throw new APIConnectionError(`failed to reach ${this.baseURL}: ${reason}`, { cause: err });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!resp.ok) throw await this._raise(resp);
+    return resp;
+  }
+
+  /** Build the fetch init for a (possibly JSON-bodied) request. */
+  _jsonInit(method, body) {
+    const headers = this._authHeader();
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    return { method, headers, body: payload };
+  }
+
+  /** Build the fetch init for a multipart/form-data POST (fetch sets the boundary). */
+  _formInit(files, fields) {
+    const form = new FormData();
+    for (const { name, value } of fields) form.append(name, value);
+    for (const { field, filename, content, contentType } of files) {
+      const blob = content instanceof Blob ? content : new Blob([content], { type: contentType });
+      form.append(field, blob, filename);
+    }
+    return { method: "POST", headers: this._authHeader(), body: form };
+  }
+
+  /** Read a response body as JSON (or null for an empty body). */
+  async _readJSON(resp) {
+    const text = await resp.text();
+    return text ? JSON.parse(text) : null;
+  }
+
+  /** Read a response body as an async iterable of decoded text chunks. */
+  async *_streamChunks(url, init) {
+    const resp = await this._fetch(url, init);
+    if (!resp.body) return;
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of resp.body) {
+        const piece = decoder.decode(chunk, { stream: true });
+        if (piece) yield piece;
+      }
+    } catch (err) {
+      throw new APIConnectionError(`stream from ${this.baseURL} interrupted: ${err?.message}`, { cause: err });
+    }
+    const tail = decoder.decode();
+    if (tail) yield tail;
+  }
+
+  /** Send a JSON request and return the decoded JSON response (or null). */
+  async requestJSON(method, path, { body, params } = {}) {
+    return this._readJSON(await this._fetch(this._url(path, params), this._jsonInit(method, body)));
+  }
+
+  /**
+   * Stream a request body as decoded text chunks, for the server's streamed
+   * (`text/event-stream`) endpoints which are not JSON.
+   */
+  requestStream(method, path, { body, params } = {}) {
+    return this._streamChunks(this._url(path, params), this._jsonInit(method, body));
+  }
+
+  /**
+   * Send a multipart/form-data POST and return the decoded JSON response.
+   * `files` is an array of { field, filename, content, contentType }; `fields`
+   * an array of { name, value }.
+   */
+  async upload(path, { files = [], fields = [], params } = {}) {
+    return this._readJSON(await this._fetch(this._url(path, params), this._formInit(files, fields)));
+  }
+
+  /** Like {@link upload} but streams the response as decoded text chunks. */
+  uploadStream(path, { files = [], fields = [], params } = {}) {
+    return this._streamChunks(this._url(path, params), this._formInit(files, fields));
+  }
+}