flexorch-sdk 0.1.0 → 0.2.0

package/README.md

@@ -167,7 +167,7 @@ await client.connectors.get(id);
 await client.connectors.delete(id);
 ```
 
-Supported connector types: `"s3"`, `"gcs"`, `"azure_blob"`.
+Supported connector types: `"s3"`. (`"gcs"` and `"azure_blob"` coming in a future release.)
 
 ---
 

package/dist/{chunk-7JBTDKMH.js → chunk-35RGZSFP.js}

@@ -7,7 +7,8 @@ var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
   "md",
   "xml",
   "xlsx",
-  "rag"
+  "rag",
+  "hf"
 ]);
 var Dataset = class _Dataset {
   id;
@@ -62,6 +63,27 @@ var Dataset = class _Dataset {
       sizeBytes: Number(data["size_bytes"] ?? 0)
     };
   }
+  async chunks(opts = {}) {
+    const params = {};
+    if (opts.page !== void 0) params["page"] = String(opts.page);
+    if (opts.pageSize !== void 0) params["page_size"] = String(opts.pageSize);
+    if (opts.qualityGrade !== void 0) params["quality_grade"] = opts.qualityGrade;
+    if (opts.piiMasked !== void 0) params["pii_masked"] = String(opts.piiMasked);
+    const data = await this._transport.get(`/datasets/${this.id}/chunks`, params) ?? {};
+    const raw = data["items"] ?? [];
+    return {
+      items: raw.map((item) => ({
+        chunkId: String(item["chunk_id"] ?? ""),
+        chunkIndex: Number(item["chunk_index"] ?? 0),
+        text: String(item["text"] ?? ""),
+        tokenCount: Number(item["token_count"] ?? 0),
+        metadata: item["metadata"] ?? {}
+      })),
+      total: Number(data["total"] ?? 0),
+      page: Number(data["page"] ?? 1),
+      pageSize: Number(data["page_size"] ?? 20)
+    };
+  }
   async index() {
     const data = await this._transport.post(`/datasets/${this.id}/index`) ?? {};
     return {

package/dist/{dataset-IS63EK2G.js → dataset-PP755LIW.js}

@@ -1,6 +1,6 @@
 import {
   Dataset
-} from "./chunk-7JBTDKMH.js";
+} from "./chunk-35RGZSFP.js";
 export {
   Dataset
 };

package/dist/index.cjs

@@ -47,7 +47,8 @@ var init_dataset = __esm({
       "md",
       "xml",
       "xlsx",
-      "rag"
+      "rag",
+      "hf"
     ]);
     Dataset = class _Dataset {
       id;
@@ -102,6 +103,27 @@ var init_dataset = __esm({
           sizeBytes: Number(data["size_bytes"] ?? 0)
         };
       }
+      async chunks(opts = {}) {
+        const params = {};
+        if (opts.page !== void 0) params["page"] = String(opts.page);
+        if (opts.pageSize !== void 0) params["page_size"] = String(opts.pageSize);
+        if (opts.qualityGrade !== void 0) params["quality_grade"] = opts.qualityGrade;
+        if (opts.piiMasked !== void 0) params["pii_masked"] = String(opts.piiMasked);
+        const data = await this._transport.get(`/datasets/${this.id}/chunks`, params) ?? {};
+        const raw = data["items"] ?? [];
+        return {
+          items: raw.map((item) => ({
+            chunkId: String(item["chunk_id"] ?? ""),
+            chunkIndex: Number(item["chunk_index"] ?? 0),
+            text: String(item["text"] ?? ""),
+            tokenCount: Number(item["token_count"] ?? 0),
+            metadata: item["metadata"] ?? {}
+          })),
+          total: Number(data["total"] ?? 0),
+          page: Number(data["page"] ?? 1),
+          pageSize: Number(data["page_size"] ?? 20)
+        };
+      }
       async index() {
         const data = await this._transport.post(`/datasets/${this.id}/index`) ?? {};
         return {
@@ -132,11 +154,14 @@ __export(index_exports, {
   Dataset: () => Dataset,
   FlexOrchClient: () => FlexOrchClient,
   FlexOrchError: () => FlexOrchError,
+  FlexOrchReader: () => FlexOrchReader,
+  FlexOrchRetriever: () => FlexOrchRetriever,
   Job: () => Job,
   JobFailedError: () => JobFailedError,
   JobTimeoutError: () => JobTimeoutError,
   NotFoundError: () => NotFoundError,
   QuotaError: () => QuotaError,
+  RAGDocument: () => RAGDocument,
   RateLimitError: () => RateLimitError,
   SearchResult: () => SearchResult,
   ServerError: () => ServerError,
@@ -679,7 +704,8 @@ var FlexOrchClient = class {
   async search(query, opts = {}) {
     const body = {
       query,
-      top_k: opts.topK ?? 10
+      top_k: opts.topK ?? 10,
+      mode: opts.mode ?? "auto"
     };
     if (opts.filters) {
       const f = opts.filters;
@@ -701,7 +727,184 @@ var FlexOrchClient = class {
 
 // src/index.ts
 init_dataset();
-var version = "0.1.0";
+
+// src/rag.ts
+var GRADE_ORDER = { A: 0, B: 1, C: 2, D: 3 };
+function gradeAndAbove(threshold) {
+  const t = GRADE_ORDER[threshold.toUpperCase()] ?? 3;
+  return Object.entries(GRADE_ORDER).filter(([, rank]) => rank <= t).map(([g]) => g);
+}
+var RAGDocument = class {
+  /** Chunk text — LangChain-style attribute name. */
+  pageContent;
+  metadata;
+  constructor(pageContent, metadata = {}) {
+    this.pageContent = pageContent;
+    this.metadata = metadata;
+  }
+  /** LlamaIndex-style alias for pageContent. */
+  get text() {
+    return this.pageContent;
+  }
+  toString() {
+    const snippet = this.pageContent.slice(0, 60).replace(/\n/g, " ");
+    return `RAGDocument(text="${snippet}", metadata=${JSON.stringify(this.metadata)})`;
+  }
+};
+var FlexOrchRetriever = class {
+  _client;
+  _qualityThreshold;
+  _piiMasked;
+  _topK;
+  _documentType;
+  _language;
+  _mode;
+  /**
+   * LangChain-compatible retriever backed by FlexOrch's /v1/search endpoint.
+   *
+   * Works without LangChain installed — invoke() returns RAGDocument objects
+   * that are duck-type compatible with langchain_core.documents.Document.
+   *
+   * @example
+   * ```ts
+   * const client = new FlexOrchClient("dfx_xxx");
+   * const retriever = new FlexOrchRetriever(client, { qualityThreshold: "B", piiMasked: true });
+   *
+   * // standalone
+   * const docs = await retriever.invoke("payment terms");
+   *
+   * // LangChain chain (TypeScript)
+   * import { RetrievalQAChain } from "langchain/chains";
+   * const chain = RetrievalQAChain.fromLLM(llm, retriever);
+   * ```
+   */
+  constructor(client, opts = {}) {
+    const threshold = (opts.qualityThreshold ?? "B").toUpperCase();
+    if (!(threshold in GRADE_ORDER)) {
+      throw new Error(`qualityThreshold must be A, B, C, or D \u2014 got "${opts.qualityThreshold}"`);
+    }
+    this._client = client;
+    this._qualityThreshold = threshold;
+    this._piiMasked = opts.piiMasked;
+    this._topK = opts.topK ?? 5;
+    this._documentType = opts.documentType;
+    this._language = opts.language;
+    this._mode = opts.mode ?? "auto";
+  }
+  /**
+   * Retrieve the most relevant chunks for a query.
+   *
+   * Requests 2× topK results from the API then filters client-side by quality
+   * threshold, returning at most topK final documents.
+   */
+  async invoke(query) {
+    const filters = {};
+    if (this._piiMasked !== void 0) filters.piiMasked = this._piiMasked;
+    if (this._documentType) filters.documentType = this._documentType;
+    if (this._language) filters.language = this._language;
+    const raw = await this._client.search(query, {
+      topK: Math.min(this._topK * 2, 50),
+      mode: this._mode,
+      filters: Object.keys(filters).length > 0 ? filters : void 0
+    });
+    const allowedGrades = new Set(gradeAndAbove(this._qualityThreshold));
+    const docs = [];
+    for (const r of raw) {
+      const grade = String(r.metadata["quality_grade"] ?? "D");
+      if (!allowedGrades.has(grade)) continue;
+      docs.push(
+        new RAGDocument(r.text, {
+          chunkId: r.chunkId,
+          datasetId: r.datasetId,
+          score: r.score,
+          qualityGrade: grade,
+          piiMasked: r.metadata["pii_masked"],
+          docType: r.metadata["doc_type"],
+          language: r.metadata["language"]
+        })
+      );
+      if (docs.length >= this._topK) break;
+    }
+    return docs;
+  }
+  /** LangChain BaseRetriever compatibility shim. */
+  async getRelevantDocuments(query) {
+    return this.invoke(query);
+  }
+  toString() {
+    return `FlexOrchRetriever(qualityThreshold="${this._qualityThreshold}", topK=${this._topK}, mode="${this._mode}")`;
+  }
+};
+var FlexOrchReader = class {
+  _client;
+  /**
+   * LlamaIndex-compatible reader backed by FlexOrch's chunk API.
+   *
+   * Paginates through all RAG chunks of a processed, indexed dataset.
+   * Returns RAGDocument objects duck-type compatible with llama_index Document.
+   *
+   * @example
+   * ```ts
+   * const reader = new FlexOrchReader(new FlexOrchClient("dfx_xxx"));
+   * const docs = await reader.loadData("42", { minQuality: "B" });
+   * ```
+   */
+  constructor(client) {
+    this._client = client;
+  }
+  /**
+   * Load all qualifying chunks from a dataset, paginating automatically.
+   *
+   * @param datasetId  ID of the indexed dataset.
+   * @param opts       Filtering and pagination options.
+   */
+  async loadData(datasetId, opts = {}) {
+    const minQuality = (opts.minQuality ?? "B").toUpperCase();
+    if (!(minQuality in GRADE_ORDER)) {
+      throw new Error(`minQuality must be A, B, C, or D \u2014 got "${opts.minQuality}"`);
+    }
+    const gradeFilter = gradeAndAbove(minQuality).join(",");
+    const pageSize = opts.pageSize ?? 100;
+    const allDocs = [];
+    let page = 1;
+    while (true) {
+      const params = {
+        page: String(page),
+        page_size: String(pageSize),
+        quality_grade: gradeFilter
+      };
+      if (opts.piiMaskedOnly) params["pii_masked"] = "true";
+      const data = await this._client._transport.get(`/datasets/${datasetId}/chunks`, params) ?? {};
+      const items = data["items"] ?? [];
+      const total = Number(data["total"] ?? 0);
+      for (const item of items) {
+        const meta = item["metadata"] ?? {};
+        allDocs.push(
+          new RAGDocument(String(item["text"] ?? ""), {
+            chunkId: item["chunk_id"],
+            chunkIndex: item["chunk_index"],
+            datasetId: String(datasetId),
+            docType: meta["doc_type"],
+            language: meta["language"],
+            qualityGrade: meta["quality_grade"],
+            qualityScore: meta["quality_score"],
+            piiMasked: meta["pii_masked"],
+            source: meta["source_filename"]
+          })
+        );
+      }
+      if (allDocs.length >= total || items.length < pageSize) break;
+      page++;
+    }
+    return allDocs;
+  }
+  toString() {
+    return "FlexOrchReader()";
+  }
+};
+
+// src/index.ts
+var version = "0.2.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
@@ -709,11 +912,14 @@ var version = "0.1.0";
   Dataset,
   FlexOrchClient,
   FlexOrchError,
+  FlexOrchReader,
+  FlexOrchRetriever,
   Job,
   JobFailedError,
   JobTimeoutError,
   NotFoundError,
   QuotaError,
+  RAGDocument,
   RateLimitError,
   SearchResult,
   ServerError,

package/dist/index.d.cts

@@ -15,7 +15,7 @@ declare class Transport {
     delete(path: string): Promise<unknown>;
 }
 
-type ExportFormat = "json" | "jsonl" | "csv" | "parquet" | "md" | "xml" | "xlsx" | "rag";
+type ExportFormat = "json" | "jsonl" | "csv" | "parquet" | "md" | "xml" | "xlsx" | "rag" | "hf";
 declare class Dataset {
     readonly id: string;
     readonly name: string;
@@ -41,6 +41,23 @@ declare class Dataset {
         s3Key: string;
         sizeBytes: number;
     }>;
+    chunks(opts?: {
+        page?: number;
+        pageSize?: number;
+        qualityGrade?: string;
+        piiMasked?: boolean;
+    }): Promise<{
+        items: Array<{
+            chunkId: string;
+            chunkIndex: number;
+            text: string;
+            tokenCount: number;
+            metadata: Record<string, unknown>;
+        }>;
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
     index(): Promise<{
         status: string;
         message: string;
@@ -232,6 +249,7 @@ declare class FlexOrchClient {
     }): Promise<Job[]>;
     search(query: string, opts?: {
         topK?: number;
+        mode?: string;
         filters?: SearchFilters;
     }): Promise<SearchResult[]>;
     toString(): string;
@@ -274,6 +292,113 @@ declare class JobTimeoutError extends FlexOrchError {
     constructor(jobId: string, timeout: number);
 }
 
-declare const version = "0.1.0";
+/**
+ * RAG helpers for the FlexOrch SDK.
+ *
+ * FlexOrchRetriever  — LangChain-compatible retriever backed by /v1/search.
+ * FlexOrchReader     — LlamaIndex-compatible reader backed by /v1/datasets/{id}/chunks.
+ *
+ * Both classes work without LangChain or LlamaIndex installed.
+ * RAGDocument is duck-type compatible with:
+ *   - langchain_core.documents.Document  (pageContent + metadata)
+ *   - llama_index.core.schema.Document   (.text + metadata)
+ */
+
+declare class RAGDocument {
+    /** Chunk text — LangChain-style attribute name. */
+    readonly pageContent: string;
+    readonly metadata: Record<string, unknown>;
+    constructor(pageContent: string, metadata?: Record<string, unknown>);
+    /** LlamaIndex-style alias for pageContent. */
+    get text(): string;
+    toString(): string;
+}
+interface RetrieverOptions {
+    /** Minimum quality grade to return (A/B/C/D). Default: "B". */
+    qualityThreshold?: string;
+    /** When set, only include chunks where PII was (true) or wasn't (false) masked. */
+    piiMasked?: boolean;
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    /** Filter by document type (e.g. "invoice"). */
+    documentType?: string;
+    /** Filter by language code (e.g. "en", "tr"). */
+    language?: string;
+    /** Search mode: "auto" | "semantic" | "hybrid" | "structured". Default: "auto". */
+    mode?: string;
+}
+declare class FlexOrchRetriever {
+    private readonly _client;
+    private readonly _qualityThreshold;
+    private readonly _piiMasked;
+    private readonly _topK;
+    private readonly _documentType;
+    private readonly _language;
+    private readonly _mode;
+    /**
+     * LangChain-compatible retriever backed by FlexOrch's /v1/search endpoint.
+     *
+     * Works without LangChain installed — invoke() returns RAGDocument objects
+     * that are duck-type compatible with langchain_core.documents.Document.
+     *
+     * @example
+     * ```ts
+     * const client = new FlexOrchClient("dfx_xxx");
+     * const retriever = new FlexOrchRetriever(client, { qualityThreshold: "B", piiMasked: true });
+     *
+     * // standalone
+     * const docs = await retriever.invoke("payment terms");
+     *
+     * // LangChain chain (TypeScript)
+     * import { RetrievalQAChain } from "langchain/chains";
+     * const chain = RetrievalQAChain.fromLLM(llm, retriever);
+     * ```
+     */
+    constructor(client: FlexOrchClient, opts?: RetrieverOptions);
+    /**
+     * Retrieve the most relevant chunks for a query.
+     *
+     * Requests 2× topK results from the API then filters client-side by quality
+     * threshold, returning at most topK final documents.
+     */
+    invoke(query: string): Promise<RAGDocument[]>;
+    /** LangChain BaseRetriever compatibility shim. */
+    getRelevantDocuments(query: string): Promise<RAGDocument[]>;
+    toString(): string;
+}
+interface ReaderLoadOptions {
+    /** Minimum quality grade to include (A/B/C/D). Default: "B". */
+    minQuality?: string;
+    /** When true, include only chunks where PII was masked. Default: false. */
+    piiMaskedOnly?: boolean;
+    /** Chunks per page (max 100). Default: 100. */
+    pageSize?: number;
+}
+declare class FlexOrchReader {
+    private readonly _client;
+    /**
+     * LlamaIndex-compatible reader backed by FlexOrch's chunk API.
+     *
+     * Paginates through all RAG chunks of a processed, indexed dataset.
+     * Returns RAGDocument objects duck-type compatible with llama_index Document.
+     *
+     * @example
+     * ```ts
+     * const reader = new FlexOrchReader(new FlexOrchClient("dfx_xxx"));
+     * const docs = await reader.loadData("42", { minQuality: "B" });
+     * ```
+     */
+    constructor(client: FlexOrchClient);
+    /**
+     * Load all qualifying chunks from a dataset, paginating automatically.
+     *
+     * @param datasetId  ID of the indexed dataset.
+     * @param opts       Filtering and pagination options.
+     */
+    loadData(datasetId: string | number, opts?: ReaderLoadOptions): Promise<RAGDocument[]>;
+    toString(): string;
+}
+
+declare const version = "0.2.0";
 
-export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RateLimitError, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };
+export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RAGDocument, RateLimitError, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };

package/dist/index.d.ts

@@ -15,7 +15,7 @@ declare class Transport {
     delete(path: string): Promise<unknown>;
 }
 
-type ExportFormat = "json" | "jsonl" | "csv" | "parquet" | "md" | "xml" | "xlsx" | "rag";
+type ExportFormat = "json" | "jsonl" | "csv" | "parquet" | "md" | "xml" | "xlsx" | "rag" | "hf";
 declare class Dataset {
     readonly id: string;
     readonly name: string;
@@ -41,6 +41,23 @@ declare class Dataset {
         s3Key: string;
         sizeBytes: number;
     }>;
+    chunks(opts?: {
+        page?: number;
+        pageSize?: number;
+        qualityGrade?: string;
+        piiMasked?: boolean;
+    }): Promise<{
+        items: Array<{
+            chunkId: string;
+            chunkIndex: number;
+            text: string;
+            tokenCount: number;
+            metadata: Record<string, unknown>;
+        }>;
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
     index(): Promise<{
         status: string;
         message: string;
@@ -232,6 +249,7 @@ declare class FlexOrchClient {
     }): Promise<Job[]>;
     search(query: string, opts?: {
         topK?: number;
+        mode?: string;
         filters?: SearchFilters;
     }): Promise<SearchResult[]>;
     toString(): string;
@@ -274,6 +292,113 @@ declare class JobTimeoutError extends FlexOrchError {
     constructor(jobId: string, timeout: number);
 }
 
-declare const version = "0.1.0";
+/**
+ * RAG helpers for the FlexOrch SDK.
+ *
+ * FlexOrchRetriever  — LangChain-compatible retriever backed by /v1/search.
+ * FlexOrchReader     — LlamaIndex-compatible reader backed by /v1/datasets/{id}/chunks.
+ *
+ * Both classes work without LangChain or LlamaIndex installed.
+ * RAGDocument is duck-type compatible with:
+ *   - langchain_core.documents.Document  (pageContent + metadata)
+ *   - llama_index.core.schema.Document   (.text + metadata)
+ */
+
+declare class RAGDocument {
+    /** Chunk text — LangChain-style attribute name. */
+    readonly pageContent: string;
+    readonly metadata: Record<string, unknown>;
+    constructor(pageContent: string, metadata?: Record<string, unknown>);
+    /** LlamaIndex-style alias for pageContent. */
+    get text(): string;
+    toString(): string;
+}
+interface RetrieverOptions {
+    /** Minimum quality grade to return (A/B/C/D). Default: "B". */
+    qualityThreshold?: string;
+    /** When set, only include chunks where PII was (true) or wasn't (false) masked. */
+    piiMasked?: boolean;
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    /** Filter by document type (e.g. "invoice"). */
+    documentType?: string;
+    /** Filter by language code (e.g. "en", "tr"). */
+    language?: string;
+    /** Search mode: "auto" | "semantic" | "hybrid" | "structured". Default: "auto". */
+    mode?: string;
+}
+declare class FlexOrchRetriever {
+    private readonly _client;
+    private readonly _qualityThreshold;
+    private readonly _piiMasked;
+    private readonly _topK;
+    private readonly _documentType;
+    private readonly _language;
+    private readonly _mode;
+    /**
+     * LangChain-compatible retriever backed by FlexOrch's /v1/search endpoint.
+     *
+     * Works without LangChain installed — invoke() returns RAGDocument objects
+     * that are duck-type compatible with langchain_core.documents.Document.
+     *
+     * @example
+     * ```ts
+     * const client = new FlexOrchClient("dfx_xxx");
+     * const retriever = new FlexOrchRetriever(client, { qualityThreshold: "B", piiMasked: true });
+     *
+     * // standalone
+     * const docs = await retriever.invoke("payment terms");
+     *
+     * // LangChain chain (TypeScript)
+     * import { RetrievalQAChain } from "langchain/chains";
+     * const chain = RetrievalQAChain.fromLLM(llm, retriever);
+     * ```
+     */
+    constructor(client: FlexOrchClient, opts?: RetrieverOptions);
+    /**
+     * Retrieve the most relevant chunks for a query.
+     *
+     * Requests 2× topK results from the API then filters client-side by quality
+     * threshold, returning at most topK final documents.
+     */
+    invoke(query: string): Promise<RAGDocument[]>;
+    /** LangChain BaseRetriever compatibility shim. */
+    getRelevantDocuments(query: string): Promise<RAGDocument[]>;
+    toString(): string;
+}
+interface ReaderLoadOptions {
+    /** Minimum quality grade to include (A/B/C/D). Default: "B". */
+    minQuality?: string;
+    /** When true, include only chunks where PII was masked. Default: false. */
+    piiMaskedOnly?: boolean;
+    /** Chunks per page (max 100). Default: 100. */
+    pageSize?: number;
+}
+declare class FlexOrchReader {
+    private readonly _client;
+    /**
+     * LlamaIndex-compatible reader backed by FlexOrch's chunk API.
+     *
+     * Paginates through all RAG chunks of a processed, indexed dataset.
+     * Returns RAGDocument objects duck-type compatible with llama_index Document.
+     *
+     * @example
+     * ```ts
+     * const reader = new FlexOrchReader(new FlexOrchClient("dfx_xxx"));
+     * const docs = await reader.loadData("42", { minQuality: "B" });
+     * ```
+     */
+    constructor(client: FlexOrchClient);
+    /**
+     * Load all qualifying chunks from a dataset, paginating automatically.
+     *
+     * @param datasetId  ID of the indexed dataset.
+     * @param opts       Filtering and pagination options.
+     */
+    loadData(datasetId: string | number, opts?: ReaderLoadOptions): Promise<RAGDocument[]>;
+    toString(): string;
+}
+
+declare const version = "0.2.0";
 
-export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RateLimitError, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };
+export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RAGDocument, RateLimitError, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   Dataset
-} from "./chunk-7JBTDKMH.js";
+} from "./chunk-35RGZSFP.js";
 
 // src/errors.ts
 var FlexOrchError = class extends Error {
@@ -251,7 +251,7 @@ var Job = class _Job {
     });
     const items = data["items"] ?? [];
     if (items.length === 0) return null;
-    const { Dataset: Dataset2 } = await import("./dataset-IS63EK2G.js");
+    const { Dataset: Dataset2 } = await import("./dataset-PP755LIW.js");
     return Dataset2.fromDict(items[0], this._transport);
   }
   toString() {
@@ -535,7 +535,8 @@ var FlexOrchClient = class {
   async search(query, opts = {}) {
     const body = {
       query,
-      top_k: opts.topK ?? 10
+      top_k: opts.topK ?? 10,
+      mode: opts.mode ?? "auto"
     };
     if (opts.filters) {
       const f = opts.filters;
@@ -555,19 +556,197 @@ var FlexOrchClient = class {
   }
 };
 
+// src/rag.ts
+var GRADE_ORDER = { A: 0, B: 1, C: 2, D: 3 };
+function gradeAndAbove(threshold) {
+  const t = GRADE_ORDER[threshold.toUpperCase()] ?? 3;
+  return Object.entries(GRADE_ORDER).filter(([, rank]) => rank <= t).map(([g]) => g);
+}
+var RAGDocument = class {
+  /** Chunk text — LangChain-style attribute name. */
+  pageContent;
+  metadata;
+  constructor(pageContent, metadata = {}) {
+    this.pageContent = pageContent;
+    this.metadata = metadata;
+  }
+  /** LlamaIndex-style alias for pageContent. */
+  get text() {
+    return this.pageContent;
+  }
+  toString() {
+    const snippet = this.pageContent.slice(0, 60).replace(/\n/g, " ");
+    return `RAGDocument(text="${snippet}", metadata=${JSON.stringify(this.metadata)})`;
+  }
+};
+var FlexOrchRetriever = class {
+  _client;
+  _qualityThreshold;
+  _piiMasked;
+  _topK;
+  _documentType;
+  _language;
+  _mode;
+  /**
+   * LangChain-compatible retriever backed by FlexOrch's /v1/search endpoint.
+   *
+   * Works without LangChain installed — invoke() returns RAGDocument objects
+   * that are duck-type compatible with langchain_core.documents.Document.
+   *
+   * @example
+   * ```ts
+   * const client = new FlexOrchClient("dfx_xxx");
+   * const retriever = new FlexOrchRetriever(client, { qualityThreshold: "B", piiMasked: true });
+   *
+   * // standalone
+   * const docs = await retriever.invoke("payment terms");
+   *
+   * // LangChain chain (TypeScript)
+   * import { RetrievalQAChain } from "langchain/chains";
+   * const chain = RetrievalQAChain.fromLLM(llm, retriever);
+   * ```
+   */
+  constructor(client, opts = {}) {
+    const threshold = (opts.qualityThreshold ?? "B").toUpperCase();
+    if (!(threshold in GRADE_ORDER)) {
+      throw new Error(`qualityThreshold must be A, B, C, or D \u2014 got "${opts.qualityThreshold}"`);
+    }
+    this._client = client;
+    this._qualityThreshold = threshold;
+    this._piiMasked = opts.piiMasked;
+    this._topK = opts.topK ?? 5;
+    this._documentType = opts.documentType;
+    this._language = opts.language;
+    this._mode = opts.mode ?? "auto";
+  }
+  /**
+   * Retrieve the most relevant chunks for a query.
+   *
+   * Requests 2× topK results from the API then filters client-side by quality
+   * threshold, returning at most topK final documents.
+   */
+  async invoke(query) {
+    const filters = {};
+    if (this._piiMasked !== void 0) filters.piiMasked = this._piiMasked;
+    if (this._documentType) filters.documentType = this._documentType;
+    if (this._language) filters.language = this._language;
+    const raw = await this._client.search(query, {
+      topK: Math.min(this._topK * 2, 50),
+      mode: this._mode,
+      filters: Object.keys(filters).length > 0 ? filters : void 0
+    });
+    const allowedGrades = new Set(gradeAndAbove(this._qualityThreshold));
+    const docs = [];
+    for (const r of raw) {
+      const grade = String(r.metadata["quality_grade"] ?? "D");
+      if (!allowedGrades.has(grade)) continue;
+      docs.push(
+        new RAGDocument(r.text, {
+          chunkId: r.chunkId,
+          datasetId: r.datasetId,
+          score: r.score,
+          qualityGrade: grade,
+          piiMasked: r.metadata["pii_masked"],
+          docType: r.metadata["doc_type"],
+          language: r.metadata["language"]
+        })
+      );
+      if (docs.length >= this._topK) break;
+    }
+    return docs;
+  }
+  /** LangChain BaseRetriever compatibility shim. */
+  async getRelevantDocuments(query) {
+    return this.invoke(query);
+  }
+  toString() {
+    return `FlexOrchRetriever(qualityThreshold="${this._qualityThreshold}", topK=${this._topK}, mode="${this._mode}")`;
+  }
+};
+var FlexOrchReader = class {
+  _client;
+  /**
+   * LlamaIndex-compatible reader backed by FlexOrch's chunk API.
+   *
+   * Paginates through all RAG chunks of a processed, indexed dataset.
+   * Returns RAGDocument objects duck-type compatible with llama_index Document.
+   *
+   * @example
+   * ```ts
+   * const reader = new FlexOrchReader(new FlexOrchClient("dfx_xxx"));
+   * const docs = await reader.loadData("42", { minQuality: "B" });
+   * ```
+   */
+  constructor(client) {
+    this._client = client;
+  }
+  /**
+   * Load all qualifying chunks from a dataset, paginating automatically.
+   *
+   * @param datasetId  ID of the indexed dataset.
+   * @param opts       Filtering and pagination options.
+   */
+  async loadData(datasetId, opts = {}) {
+    const minQuality = (opts.minQuality ?? "B").toUpperCase();
+    if (!(minQuality in GRADE_ORDER)) {
+      throw new Error(`minQuality must be A, B, C, or D \u2014 got "${opts.minQuality}"`);
+    }
+    const gradeFilter = gradeAndAbove(minQuality).join(",");
+    const pageSize = opts.pageSize ?? 100;
+    const allDocs = [];
+    let page = 1;
+    while (true) {
+      const params = {
+        page: String(page),
+        page_size: String(pageSize),
+        quality_grade: gradeFilter
+      };
+      if (opts.piiMaskedOnly) params["pii_masked"] = "true";
+      const data = await this._client._transport.get(`/datasets/${datasetId}/chunks`, params) ?? {};
+      const items = data["items"] ?? [];
+      const total = Number(data["total"] ?? 0);
+      for (const item of items) {
+        const meta = item["metadata"] ?? {};
+        allDocs.push(
+          new RAGDocument(String(item["text"] ?? ""), {
+            chunkId: item["chunk_id"],
+            chunkIndex: item["chunk_index"],
+            datasetId: String(datasetId),
+            docType: meta["doc_type"],
+            language: meta["language"],
+            qualityGrade: meta["quality_grade"],
+            qualityScore: meta["quality_score"],
+            piiMasked: meta["pii_masked"],
+            source: meta["source_filename"]
+          })
+        );
+      }
+      if (allDocs.length >= total || items.length < pageSize) break;
+      page++;
+    }
+    return allDocs;
+  }
+  toString() {
+    return "FlexOrchReader()";
+  }
+};
+
 // src/index.ts
-var version = "0.1.0";
+var version = "0.2.0";
 export {
   AuthError,
   Connector,
   Dataset,
   FlexOrchClient,
   FlexOrchError,
+  FlexOrchReader,
+  FlexOrchRetriever,
   Job,
   JobFailedError,
   JobTimeoutError,
   NotFoundError,
   QuotaError,
+  RAGDocument,
   RateLimitError,
   SearchResult,
   ServerError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexorch-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript/JavaScript SDK for the FlexOrch API — process documents, build LLM-ready datasets",
   "type": "module",
   "main": "./dist/index.cjs",