ragpack-js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,350 @@
+/**
+ * Controls how ingested documents are split into chunks before embedding.
+ *
+ * - `"auto"` — picks the best strategy based on the file's MIME type (default).
+ * - `"paragraph"` — splits on blank lines; good for prose (plain text, DOCX).
+ * - `"sliding_window"` — fixed-size rolling window with overlap; good for dense text like PDFs.
+ * - `"section"` — splits on headings, preserving section context; good for Markdown and HTML.
+ * - `"unit"` — one chunk per logical unit (e.g. one slide for PPTX); good for structured presentations.
+ * - `"row_group"` — groups rows with a repeated header row per chunk; good for spreadsheets (XLSX).
+ */
+type ChunkStrategy = "auto" | "paragraph" | "sliding_window" | "section" | "unit" | "row_group";
+interface RagPackConfig {
+    /** Base URL of your RagPack backend (e.g. `http://localhost:9000`). */
+    baseUrl: string;
+    /** API key generated on first backend startup. */
+    apiKey: string;
+}
+/** Per-collection chunking overrides. Omitted when all fields use server defaults. */
+interface ChunkConfig {
+    strategy?: ChunkStrategy;
+    /** Max characters per chunk. */
+    size?: number;
+    /** Characters of overlap carried into the next chunk for context continuity. */
+    overlap?: number;
+}
+interface Collection {
+    id: string;
+    name: string;
+    /** URL-safe identifier used in API calls. */
+    slug: string;
+    embed_model: string;
+    vector_dim: number;
+    created_at: string;
+    /** Present only when this collection overrides the server chunking defaults. */
+    chunk_config?: ChunkConfig;
+}
+interface Job {
+    id: string;
+    collection_id: string;
+    file_uri: string;
+    mime_type: string;
+    status: "pending" | "processing" | "complete" | "failed";
+    error?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Document {
+    id: string;
+    collection_id: string;
+    job_id: string;
+    file_uri: string;
+    mime_type: string;
+    chunk_count: number;
+    status: "ingesting" | "complete" | "failed";
+    error?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Prompt {
+    id: string;
+    name: string;
+    slug: string;
+    /** Template content. Use `{{context}}` and `{{question}}` as placeholders. */
+    content: string;
+    is_system: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface RagChunk {
+    source: string;
+    file_uri: string;
+    chunk_index: number;
+    chunk_header: string | null;
+    chunk_text: string | null;
+    similarity: number;
+}
+interface RagResult {
+    formatted_prompt: string;
+    answer: string;
+    chunks: RagChunk[];
+    prompt_slug: string;
+}
+interface QueryResult {
+    source: string;
+    file_uri: string;
+    mime_type: string;
+    chunk_index: number;
+    /** The matched text chunk. */
+    chunk_text: string | null;
+    /** Optional metadata attached at ingest time. */
+    extra_json: string | null;
+    distance: number;
+    /** Cosine similarity score between 0 and 1. Higher is more relevant. */
+    similarity: number;
+}
+
+type Requester = <T>(path: string, init?: RequestInit) => Promise<T>;
+declare class RagPackError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+interface WaitOptions {
+    /** How often to poll for job status, in milliseconds. Defaults to 1500. */
+    pollIntervalMs?: number;
+    /** Maximum time to wait before throwing, in milliseconds. Defaults to 300000 (5 min). */
+    timeoutMs?: number;
+}
+declare class JobsResource {
+    private readonly req;
+    private readonly slug?;
+    constructor(req: Requester, slug?: string | undefined);
+    /** List ingestion jobs for this collection, or all jobs if no collection is scoped. */
+    list(): Promise<Job[]>;
+    /**
+     * Get a single ingestion job by ID.
+     * @param id - The job ID.
+     */
+    get(id: string): Promise<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");
+     * ```
+     */
+    waitUntilComplete(id: string, options?: WaitOptions): Promise<Job>;
+}
+
+declare class DocumentsResource {
+    private readonly req;
+    private readonly slug?;
+    constructor(req: Requester, slug?: string | undefined);
+    /**
+     * 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.
+     */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Document[]>;
+    /**
+     * Delete a document and all its chunks from this collection.
+     * @param id - The document ID.
+     */
+    delete(id: string): Promise<void>;
+}
+
+interface RagOptions {
+    /** Slug of the prompt template to use. Defaults to `"basic_rag"` if omitted. */
+    promptSlug?: string;
+    /** The user's question. Substituted into `{{question}}`. */
+    query: string;
+    /** Number of chunks to retrieve. Defaults to 5. */
+    topK?: number;
+    /** LLM model name to use (e.g. `"gpt-4o"`, `"claude-opus-4-8"`). Falls back to server default. */
+    model?: string;
+    /** Minimum similarity score (0–100) a chunk must meet to be included in context. Omit to include all top_k results. */
+    minSimilarity?: number;
+}
+interface FindSimilarOptions {
+    /** The search query text. */
+    query: string;
+    /** Number of results to return. Defaults to 5. */
+    topK?: number;
+}
+interface IngestUriOptions {
+    /** Remote file URI (e.g. `s3://bucket/file.pdf`). */
+    uri: string;
+    /** MIME type of the file. Detected from the file extension if omitted. */
+    mimeType?: string;
+}
+/**
+ * A collection-scoped client. All operations target the collection
+ * this was created with.
+ *
+ * @example
+ * ```ts
+ * const collection = client.collection("my-docs");
+ *
+ * await collection.ingest(file);
+ * await collection.ingest({ uri: "s3://bucket/file.pdf", mimeType: "application/pdf" });
+ * const results = await collection.findSimilar({ query: "how does auth work?" });
+ * ```
+ */
+declare class CollectionClient {
+    private readonly slug;
+    /** Inspect ingestion jobs for this collection. */
+    readonly jobs: JobsResource;
+    /** Manage indexed documents in this collection. */
+    readonly documents: DocumentsResource;
+    private readonly _req;
+    private readonly _query;
+    constructor(slug: string, req: Requester);
+    /**
+     * Ingest a document into this collection.
+     *
+     * Pass a `File` or `Blob` to upload directly, or an object with `uri` and
+     * `mimeType` to ingest from a remote URI.
+     *
+     * @example
+     * ```ts
+     * // File upload
+     * await collection.ingest(file);
+     *
+     * // Remote URI
+     * await collection.ingest({ uri: "s3://bucket/report.pdf", mimeType: "application/pdf" });
+     * ```
+     */
+    ingest(file: File | Blob, filename?: string): Promise<Job>;
+    ingest(options: IngestUriOptions): Promise<Job>;
+    /**
+     * Find semantically similar content in this collection.
+     * @example
+     * ```ts
+     * const results = await collection.findSimilar({ query: "what is RagPack?", topK: 10 });
+     * ```
+     */
+    findSimilar(options: FindSimilarOptions): Promise<QueryResult[]>;
+    /**
+     * 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: RagOptions): Promise<RagResult>;
+}
+
+declare class CollectionsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all collections. */
+    list(): Promise<Collection[]>;
+    /**
+     * 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);
+     * ```
+     */
+    create(name: string, options?: {
+        embedModel?: string;
+        chunkConfig?: ChunkConfig;
+    }): Promise<CollectionClient>;
+    /**
+     * Get a collection by its slug.
+     * @param slug - The collection's URL-safe identifier.
+     */
+    get(slug: string): Promise<Collection>;
+    /**
+     * Delete a collection and all its documents.
+     * @param slug - The collection's URL-safe identifier.
+     */
+    delete(slug: string): Promise<void>;
+}
+
+declare class PromptsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all prompt templates (built-in system prompts first, then custom). */
+    list(): Promise<Prompt[]>;
+    /** Fetch a prompt template by slug. */
+    get(slug: string): Promise<Prompt>;
+}
+
+interface LLMInfo {
+    models: string[];
+    default: string;
+}
+declare class LLMsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all configured LLM models and the server default. */
+    list(): Promise<LLMInfo>;
+}
+
+interface EmbedderInfo {
+    models: string[];
+    default: string;
+}
+declare class EmbeddersResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all configured embedding models and the server default. */
+    list(): Promise<EmbedderInfo>;
+}
+
+/**
+ * RagPack client for interacting with a self-hosted RagPack RAG engine.
+ *
+ * @example
+ * ```ts
+ * const client = new RagPack({ baseUrl: "http://localhost:9000", apiKey: "rp_..." });
+ *
+ * // Manage collections
+ * const col = await client.collections.create("my-docs");
+ *
+ * // Scope to a collection for all operations
+ * const collection = client.collection(col.slug);
+ * await collection.ingest(file);
+ * const results = await collection.findSimilar({ query: "what is RagPack?" });
+ *
+ * // Discover configured providers
+ * const { models, default: defaultModel } = await client.llms.list();
+ * ```
+ */
+declare class RagPack {
+    /** Create and manage collections. */
+    readonly collections: CollectionsResource;
+    /** Fetch and expand prompt templates. */
+    readonly prompts: PromptsResource;
+    /** List configured LLM models. */
+    readonly llms: LLMsResource;
+    /** List configured embedding models. */
+    readonly embedders: EmbeddersResource;
+    private readonly _req;
+    constructor(config: RagPackConfig);
+    /**
+     * 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: string): CollectionClient;
+}
+
+export { type Collection, type Document, type EmbedderInfo, type FindSimilarOptions, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult };

package/dist/index.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Controls how ingested documents are split into chunks before embedding.
+ *
+ * - `"auto"` — picks the best strategy based on the file's MIME type (default).
+ * - `"paragraph"` — splits on blank lines; good for prose (plain text, DOCX).
+ * - `"sliding_window"` — fixed-size rolling window with overlap; good for dense text like PDFs.
+ * - `"section"` — splits on headings, preserving section context; good for Markdown and HTML.
+ * - `"unit"` — one chunk per logical unit (e.g. one slide for PPTX); good for structured presentations.
+ * - `"row_group"` — groups rows with a repeated header row per chunk; good for spreadsheets (XLSX).
+ */
+type ChunkStrategy = "auto" | "paragraph" | "sliding_window" | "section" | "unit" | "row_group";
+interface RagPackConfig {
+    /** Base URL of your RagPack backend (e.g. `http://localhost:9000`). */
+    baseUrl: string;
+    /** API key generated on first backend startup. */
+    apiKey: string;
+}
+/** Per-collection chunking overrides. Omitted when all fields use server defaults. */
+interface ChunkConfig {
+    strategy?: ChunkStrategy;
+    /** Max characters per chunk. */
+    size?: number;
+    /** Characters of overlap carried into the next chunk for context continuity. */
+    overlap?: number;
+}
+interface Collection {
+    id: string;
+    name: string;
+    /** URL-safe identifier used in API calls. */
+    slug: string;
+    embed_model: string;
+    vector_dim: number;
+    created_at: string;
+    /** Present only when this collection overrides the server chunking defaults. */
+    chunk_config?: ChunkConfig;
+}
+interface Job {
+    id: string;
+    collection_id: string;
+    file_uri: string;
+    mime_type: string;
+    status: "pending" | "processing" | "complete" | "failed";
+    error?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Document {
+    id: string;
+    collection_id: string;
+    job_id: string;
+    file_uri: string;
+    mime_type: string;
+    chunk_count: number;
+    status: "ingesting" | "complete" | "failed";
+    error?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Prompt {
+    id: string;
+    name: string;
+    slug: string;
+    /** Template content. Use `{{context}}` and `{{question}}` as placeholders. */
+    content: string;
+    is_system: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface RagChunk {
+    source: string;
+    file_uri: string;
+    chunk_index: number;
+    chunk_header: string | null;
+    chunk_text: string | null;
+    similarity: number;
+}
+interface RagResult {
+    formatted_prompt: string;
+    answer: string;
+    chunks: RagChunk[];
+    prompt_slug: string;
+}
+interface QueryResult {
+    source: string;
+    file_uri: string;
+    mime_type: string;
+    chunk_index: number;
+    /** The matched text chunk. */
+    chunk_text: string | null;
+    /** Optional metadata attached at ingest time. */
+    extra_json: string | null;
+    distance: number;
+    /** Cosine similarity score between 0 and 1. Higher is more relevant. */
+    similarity: number;
+}
+
+type Requester = <T>(path: string, init?: RequestInit) => Promise<T>;
+declare class RagPackError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+interface WaitOptions {
+    /** How often to poll for job status, in milliseconds. Defaults to 1500. */
+    pollIntervalMs?: number;
+    /** Maximum time to wait before throwing, in milliseconds. Defaults to 300000 (5 min). */
+    timeoutMs?: number;
+}
+declare class JobsResource {
+    private readonly req;
+    private readonly slug?;
+    constructor(req: Requester, slug?: string | undefined);
+    /** List ingestion jobs for this collection, or all jobs if no collection is scoped. */
+    list(): Promise<Job[]>;
+    /**
+     * Get a single ingestion job by ID.
+     * @param id - The job ID.
+     */
+    get(id: string): Promise<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");
+     * ```
+     */
+    waitUntilComplete(id: string, options?: WaitOptions): Promise<Job>;
+}
+
+declare class DocumentsResource {
+    private readonly req;
+    private readonly slug?;
+    constructor(req: Requester, slug?: string | undefined);
+    /**
+     * 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.
+     */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Document[]>;
+    /**
+     * Delete a document and all its chunks from this collection.
+     * @param id - The document ID.
+     */
+    delete(id: string): Promise<void>;
+}
+
+interface RagOptions {
+    /** Slug of the prompt template to use. Defaults to `"basic_rag"` if omitted. */
+    promptSlug?: string;
+    /** The user's question. Substituted into `{{question}}`. */
+    query: string;
+    /** Number of chunks to retrieve. Defaults to 5. */
+    topK?: number;
+    /** LLM model name to use (e.g. `"gpt-4o"`, `"claude-opus-4-8"`). Falls back to server default. */
+    model?: string;
+    /** Minimum similarity score (0–100) a chunk must meet to be included in context. Omit to include all top_k results. */
+    minSimilarity?: number;
+}
+interface FindSimilarOptions {
+    /** The search query text. */
+    query: string;
+    /** Number of results to return. Defaults to 5. */
+    topK?: number;
+}
+interface IngestUriOptions {
+    /** Remote file URI (e.g. `s3://bucket/file.pdf`). */
+    uri: string;
+    /** MIME type of the file. Detected from the file extension if omitted. */
+    mimeType?: string;
+}
+/**
+ * A collection-scoped client. All operations target the collection
+ * this was created with.
+ *
+ * @example
+ * ```ts
+ * const collection = client.collection("my-docs");
+ *
+ * await collection.ingest(file);
+ * await collection.ingest({ uri: "s3://bucket/file.pdf", mimeType: "application/pdf" });
+ * const results = await collection.findSimilar({ query: "how does auth work?" });
+ * ```
+ */
+declare class CollectionClient {
+    private readonly slug;
+    /** Inspect ingestion jobs for this collection. */
+    readonly jobs: JobsResource;
+    /** Manage indexed documents in this collection. */
+    readonly documents: DocumentsResource;
+    private readonly _req;
+    private readonly _query;
+    constructor(slug: string, req: Requester);
+    /**
+     * Ingest a document into this collection.
+     *
+     * Pass a `File` or `Blob` to upload directly, or an object with `uri` and
+     * `mimeType` to ingest from a remote URI.
+     *
+     * @example
+     * ```ts
+     * // File upload
+     * await collection.ingest(file);
+     *
+     * // Remote URI
+     * await collection.ingest({ uri: "s3://bucket/report.pdf", mimeType: "application/pdf" });
+     * ```
+     */
+    ingest(file: File | Blob, filename?: string): Promise<Job>;
+    ingest(options: IngestUriOptions): Promise<Job>;
+    /**
+     * Find semantically similar content in this collection.
+     * @example
+     * ```ts
+     * const results = await collection.findSimilar({ query: "what is RagPack?", topK: 10 });
+     * ```
+     */
+    findSimilar(options: FindSimilarOptions): Promise<QueryResult[]>;
+    /**
+     * 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: RagOptions): Promise<RagResult>;
+}
+
+declare class CollectionsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all collections. */
+    list(): Promise<Collection[]>;
+    /**
+     * 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);
+     * ```
+     */
+    create(name: string, options?: {
+        embedModel?: string;
+        chunkConfig?: ChunkConfig;
+    }): Promise<CollectionClient>;
+    /**
+     * Get a collection by its slug.
+     * @param slug - The collection's URL-safe identifier.
+     */
+    get(slug: string): Promise<Collection>;
+    /**
+     * Delete a collection and all its documents.
+     * @param slug - The collection's URL-safe identifier.
+     */
+    delete(slug: string): Promise<void>;
+}
+
+declare class PromptsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all prompt templates (built-in system prompts first, then custom). */
+    list(): Promise<Prompt[]>;
+    /** Fetch a prompt template by slug. */
+    get(slug: string): Promise<Prompt>;
+}
+
+interface LLMInfo {
+    models: string[];
+    default: string;
+}
+declare class LLMsResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all configured LLM models and the server default. */
+    list(): Promise<LLMInfo>;
+}
+
+interface EmbedderInfo {
+    models: string[];
+    default: string;
+}
+declare class EmbeddersResource {
+    private readonly req;
+    constructor(req: Requester);
+    /** List all configured embedding models and the server default. */
+    list(): Promise<EmbedderInfo>;
+}
+
+/**
+ * RagPack client for interacting with a self-hosted RagPack RAG engine.
+ *
+ * @example
+ * ```ts
+ * const client = new RagPack({ baseUrl: "http://localhost:9000", apiKey: "rp_..." });
+ *
+ * // Manage collections
+ * const col = await client.collections.create("my-docs");
+ *
+ * // Scope to a collection for all operations
+ * const collection = client.collection(col.slug);
+ * await collection.ingest(file);
+ * const results = await collection.findSimilar({ query: "what is RagPack?" });
+ *
+ * // Discover configured providers
+ * const { models, default: defaultModel } = await client.llms.list();
+ * ```
+ */
+declare class RagPack {
+    /** Create and manage collections. */
+    readonly collections: CollectionsResource;
+    /** Fetch and expand prompt templates. */
+    readonly prompts: PromptsResource;
+    /** List configured LLM models. */
+    readonly llms: LLMsResource;
+    /** List configured embedding models. */
+    readonly embedders: EmbeddersResource;
+    private readonly _req;
+    constructor(config: RagPackConfig);
+    /**
+     * 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: string): CollectionClient;
+}
+
+export { type Collection, type Document, type EmbedderInfo, type FindSimilarOptions, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult };