ragpack-js 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# RagPack
+
+TypeScript SDK for [RagPack](https://github.com/eozsahin1993/ragpack) — a self-hosted semantic search and RAG engine.
+
+## Installation
+
+```bash
+npm install ragpack
+```
+
+## Quick start
+
+```ts
+import { RagPack } from "ragpack";
+
+const client = new RagPack({
+  baseUrl: "http://localhost:9000",
+  apiKey: "rp_...",
+});
+
+// Create a collection
+const collection = await client.collections.create("my-docs");
+
+// Ingest a file
+await collection.ingest(file);
+
+// Or ingest from a remote URI
+await collection.ingest({ uri: "s3://my-bucket/report.pdf" });
+
+// Wait for ingestion to finish
+const job = await collection.ingest(file);
+await collection.jobs.waitUntilComplete(job.id);
+
+// RAG — retrieve relevant chunks and get an LLM answer
+const { answer, chunks } = await collection.rag({ query: "how does auth work?" });
+console.log(answer);
+
+// Semantic search (without LLM)
+const results = await collection.findSimilar({ query: "how does auth work?", topK: 5 });
+for (const r of results) {
+  console.log(r.similarity, r.chunk_text);
+}
+```
+
+## API
+
+### `new RagPack({ baseUrl, apiKey })`
+
+| Option    | Description                                          |
+|-----------|------------------------------------------------------|
+| `baseUrl` | URL of your RagPack backend (e.g. `http://localhost:9000`) |
+| `apiKey`  | API key printed by the backend on first startup      |
+
+### `client.collections`
+
+| Method                              | Description                              |
+|-------------------------------------|------------------------------------------|
+| `list()`                            | List all collections                     |
+| `create(name, options?)`            | Create a collection, returns a scoped client |
+| `get(slug)`                         | Get collection metadata by slug          |
+| `delete(slug)`                      | Delete a collection and all its documents |
+
+### `client.collection(slug)`
+
+Returns a `CollectionClient` scoped to that collection.
+
+| Method                              | Description                              |
+|-------------------------------------|------------------------------------------|
+| `ingest(file, filename?)`           | Upload a file directly                   |
+| `ingest({ uri, mimeType? })`        | Ingest from a remote URI, MIME type auto-detected if omitted |
+| `rag(options)`                      | Full RAG pipeline — retrieves chunks and returns an LLM answer |
+| `findSimilar({ query, topK? })`     | Semantic search without LLM, returns ranked chunks |
+| `jobs.list()`                       | List ingestion jobs for this collection  |
+| `jobs.get(id)`                      | Get a single job by ID                   |
+| `jobs.waitUntilComplete(id)`        | Poll until job is `complete` or `failed` |
+| `documents.list(options?)`          | List indexed documents                   |
+| `documents.delete(id)`              | Delete a document and its chunks         |
+
+#### `rag(options)`
+
+Runs the full RAG pipeline server-side: embeds the query, retrieves the top-K chunks, fills the prompt template, and calls the configured LLM.
+
+```ts
+const { answer, chunks } = await collection.rag({
+  query: "How do I reset my password?",
+  // All options below are optional
+  promptSlug: "basic_rag",   // defaults to "basic_rag" if omitted
+  topK: 5,                   // number of chunks to retrieve (default: 5)
+  model: "gpt-4o",           // LLM model; falls back to server default
+  minSimilarity: 70,         // drop chunks below this similarity score (0–100)
+});
+
+console.log(answer);
+
+for (const chunk of chunks) {
+  console.log(chunk.similarity, chunk.chunk_text);
+}
+```
+
+#### Prompt templates
+
+Three built-in prompts are always available: `basic_rag`, `rag_with_citations`, and `concise_rag`. List all available prompts (including any you've created in the admin UI) with:
+
+```ts
+const prompts = await client.prompts.list();
+// [{ slug: "basic_rag", name: "Basic RAG", is_system: true, ... }, ...]
+```
+
+## Error handling
+
+All methods throw `RagPackError` on non-2xx responses:
+
+```ts
+import { RagPack, RagPackError } from "ragpack";
+
+try {
+  await collection.findSimilar({ query: "..." });
+} catch (err) {
+  if (err instanceof RagPackError) {
+    console.error(err.status, err.message);
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- A running RagPack backend ([setup guide](https://github.com/eozsahin1993/ragpack))

package/dist/index.cjs

@@ -0,0 +1,330 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RagPack: () => RagPack,
+  RagPackError: () => RagPackError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/requester.ts
+function createRequester(config) {
+  return async function req(path, init) {
+    const isFormData = init?.body instanceof FormData;
+    const res = await fetch(`${config.baseUrl}/api/v1${path}`, {
+      ...init,
+      headers: {
+        ...!isFormData && { "Content-Type": "application/json" },
+        Authorization: `Bearer ${config.apiKey}`,
+        ...init?.headers
+      }
+    });
+    if (res.status === 204) return void 0;
+    const body = await res.json();
+    if (!res.ok) throw new RagPackError(res.status, body.error ?? res.statusText);
+    return body;
+  };
+}
+var RagPackError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "RagPackError";
+  }
+};
+
+// src/resources/jobs.ts
+var JobsResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /** List ingestion jobs for this collection, or all jobs if no collection is scoped. */
+  async list() {
+    const path = this.slug ? `/collections/${this.slug}/jobs` : "/jobs";
+    const r = await this.req(path);
+    return r.jobs;
+  }
+  /**
+   * Get a single ingestion job by ID.
+   * @param id - The job ID.
+   */
+  async get(id) {
+    const r = await this.req(`/collections/${this.slug}/jobs/${id}`);
+    return r.job;
+  }
+  /**
+   * Poll until the job reaches a terminal state (`complete` or `failed`).
+   * Throws {@link RagPackError} if the job fails or the timeout is exceeded.
+   *
+   * @example
+   * ```ts
+   * const job = await collection.ingest(file);
+   * await collection.jobs.waitUntilComplete(job.id);
+   * console.log("ingestion done, ready to search");
+   * ```
+   */
+  async waitUntilComplete(id, options = {}) {
+    const { pollIntervalMs = 1500, timeoutMs = 3e5 } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const job = await this.get(id);
+      if (job.status === "complete") return job;
+      if (job.status === "failed") {
+        throw new RagPackError(422, job.error ?? "ingestion job failed");
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new RagPackError(408, `job ${id} did not complete within ${timeoutMs}ms`);
+  }
+};
+
+// src/resources/documents.ts
+var DocumentsResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /**
+   * List documents in this collection.
+   * @param options.limit - Max number of documents to return. Defaults to 50.
+   * @param options.offset - Pagination offset. Defaults to 0.
+   */
+  async list(options) {
+    const params = new URLSearchParams({
+      limit: String(options?.limit ?? 50),
+      offset: String(options?.offset ?? 0)
+    });
+    const r = await this.req(
+      `/collections/${this.slug}/documents?${params}`
+    );
+    return r.documents;
+  }
+  /**
+   * Delete a document and all its chunks from this collection.
+   * @param id - The document ID.
+   */
+  delete(id) {
+    return this.req(`/collections/${this.slug}/documents/${id}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/query.ts
+var QueryResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /**
+   * Find semantically similar content within this collection.
+   * @returns Ranked results with similarity scores and source chunks.
+   */
+  async findSimilar(options) {
+    const r = await this.req(
+      `/collections/${this.slug}/query`,
+      {
+        method: "POST",
+        body: JSON.stringify({ query: options.query, top_k: options.topK ?? 5 })
+      }
+    );
+    return r.results;
+  }
+};
+
+// src/collection-client.ts
+var CollectionClient = class {
+  constructor(slug, req) {
+    this.slug = slug;
+    this._req = req;
+    this.jobs = new JobsResource(req, slug);
+    this.documents = new DocumentsResource(req, slug);
+    this._query = new QueryResource(req, slug);
+  }
+  ingest(input, filename) {
+    if (input instanceof Blob) {
+      const form = new FormData();
+      form.append("file", input, filename);
+      return this._req(`/collections/${this.slug}/ingest`, {
+        method: "POST",
+        body: form
+      });
+    }
+    return this._req(`/collections/${this.slug}/ingest`, {
+      method: "POST",
+      body: JSON.stringify({ file_uri: input.uri, mime_type: input.mimeType })
+    });
+  }
+  /**
+   * Find semantically similar content in this collection.
+   * @example
+   * ```ts
+   * const results = await collection.findSimilar({ query: "what is RagPack?", topK: 10 });
+   * ```
+   */
+  findSimilar(options) {
+    return this._query.findSimilar(options);
+  }
+  /**
+   * Full RAG pipeline: retrieve relevant chunks, build context, expand the
+   * prompt template, and call the configured LLM — all server-side.
+   *
+   * @example
+   * ```ts
+   * const { answer, chunks } = await collection.rag({
+   *   prompt: "basic-rag",
+   *   query: "How do I reset my password?",
+   * });
+   * ```
+   */
+  rag(options) {
+    return this._req(`/collections/${this.slug}/rag`, {
+      method: "POST",
+      body: JSON.stringify({
+        query: options.query,
+        top_k: options.topK ?? 5,
+        ...options.promptSlug ? { prompt_slug: options.promptSlug } : {},
+        ...options.model ? { model: options.model } : {},
+        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {}
+      })
+    });
+  }
+};
+
+// src/resources/collections.ts
+var CollectionsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all collections. */
+  async list() {
+    const r = await this.req("/collections");
+    return r.collections;
+  }
+  /**
+   * Create a new collection and return a scoped client for it.
+   * @param name - Display name for the collection.
+   * @param options.embedModel - Embedding model to use. Defaults to the server's configured provider.
+   * @param options.chunkConfig - Override chunking behaviour for this collection.
+   *   Omit to use server defaults.
+   *
+   * @example
+   * ```ts
+   * const collection = await client.collections.create("my-docs");
+   * await collection.ingest(file);
+   * ```
+   */
+  async create(name, options) {
+    const col = await this.req("/collections", {
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        embed_model: options?.embedModel,
+        chunk_config: options?.chunkConfig
+      })
+    });
+    return new CollectionClient(col.slug, this.req);
+  }
+  /**
+   * Get a collection by its slug.
+   * @param slug - The collection's URL-safe identifier.
+   */
+  get(slug) {
+    return this.req(`/collections/${slug}`);
+  }
+  /**
+   * Delete a collection and all its documents.
+   * @param slug - The collection's URL-safe identifier.
+   */
+  delete(slug) {
+    return this.req(`/collections/${slug}`, { method: "DELETE" });
+  }
+};
+
+// src/resources/prompts.ts
+var PromptsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all prompt templates (built-in system prompts first, then custom). */
+  async list() {
+    const r = await this.req("/prompts");
+    return [...r.system ?? [], ...r.user ?? []];
+  }
+  /** Fetch a prompt template by slug. */
+  get(slug) {
+    return this.req(`/prompts/${slug}`);
+  }
+};
+
+// src/resources/llms.ts
+var LLMsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all configured LLM models and the server default. */
+  list() {
+    return this.req("/llms");
+  }
+};
+
+// src/resources/embedders.ts
+var EmbeddersResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all configured embedding models and the server default. */
+  list() {
+    return this.req("/embedders");
+  }
+};
+
+// src/index.ts
+var RagPack = class {
+  constructor(config) {
+    this._req = createRequester(config);
+    this.collections = new CollectionsResource(this._req);
+    this.prompts = new PromptsResource(this._req);
+    this.llms = new LLMsResource(this._req);
+    this.embedders = new EmbeddersResource(this._req);
+  }
+  /**
+   * Scope all operations to a specific collection.
+   * @param slug - The collection's URL-safe identifier.
+   *
+   * @example
+   * ```ts
+   * const collection = client.collection("my-docs");
+   * await collection.ingest(file);
+   * await collection.findSimilar({ query: "..." });
+   * await collection.jobs.list();
+   * ```
+   */
+  collection(slug) {
+    return new CollectionClient(slug, this._req);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RagPack,
+  RagPackError
+});