@objectstack/knowledge-ragflow 6.4.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type {\n  IKnowledgeAdapter,\n  IKnowledgeService,\n  AdapterContext,\n  AdapterSearchOptions,\n} from '@objectstack/spec/contracts';\nimport type {\n  KnowledgeDocument,\n  KnowledgeHit,\n  KnowledgeSource,\n} from '@objectstack/spec/ai';\nimport { KNOWLEDGE_SERVICE } from '@objectstack/spec/contracts';\n\n/**\n * Subset of `fetch` used by the adapter. Inject in tests; defaults to\n * the global `fetch`.\n */\nexport type FetchLike = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  statusText: string;\n  text(): Promise<string>;\n  json(): Promise<unknown>;\n}>;\n\nexport interface KnowledgeRagflowAdapterOptions {\n  /** RAGFlow endpoint, e.g. `http://localhost:9380`. */\n  endpoint: string;\n  /** RAGFlow API key (Bearer token). */\n  apiKey: string;\n  /** Adapter id. @default 'ragflow' */\n  id?: string;\n  /** Override `fetch` for tests. */\n  fetch?: FetchLike;\n  /** Request timeout in milliseconds. @default 30000 */\n  timeoutMs?: number;\n}\n\ninterface RagflowSourceOptions {\n  datasetId: string;\n  /** Optional rerank model id (overrides dataset default). */\n  rerankModel?: string;\n  /** Optional similarity threshold passed through to RAGFlow. */\n  similarityThreshold?: number;\n  /** Optional vector vs keyword weight in [0,1]. */\n  vectorSimilarityWeight?: number;\n}\n\nfunction extractRagflowOptions(source: KnowledgeSource): RagflowSourceOptions {\n  const opts = ((source as unknown as { options?: Record<string, unknown> }).options ?? {}) as\n    Record<string, unknown>;\n  const datasetId = opts.datasetId;\n  if (typeof datasetId !== 'string' || !datasetId) {\n    throw new Error(\n      `RAGFlow adapter requires source.options.datasetId on source '${source.id}'`,\n    );\n  }\n  return {\n    datasetId,\n    rerankModel: typeof opts.rerankModel === 'string' ? opts.rerankModel : undefined,\n    similarityThreshold:\n      typeof opts.similarityThreshold === 'number' ? opts.similarityThreshold : undefined,\n    vectorSimilarityWeight:\n      typeof opts.vectorSimilarityWeight === 'number'\n        ? opts.vectorSimilarityWeight\n        : undefined,\n  };\n}\n\n/**\n * RAGFlow adapter. Maps {@link KnowledgeDocument} upserts to the\n * dataset's chunk API, delegates retrieval to `/api/v1/retrieval`, and\n * returns {@link KnowledgeHit}s with `sourceRecordId` preserved so the\n * orchestrator can run a permission re-check.\n */\nexport class KnowledgeRagflowAdapter implements IKnowledgeAdapter {\n  readonly id: string;\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: FetchLike;\n  private readonly timeoutMs: number;\n\n  constructor(opts: KnowledgeRagflowAdapterOptions) {\n    if (!opts.endpoint) throw new Error('RAGFlow adapter: endpoint required');\n    if (!opts.apiKey) throw new Error('RAGFlow adapter: apiKey required');\n    this.id = opts.id ?? 'ragflow';\n    this.endpoint = opts.endpoint.replace(/\\/+$/, '');\n    this.apiKey = opts.apiKey;\n    this.fetchImpl = opts.fetch ?? ((globalThis as { fetch?: FetchLike }).fetch as FetchLike);\n    this.timeoutMs = opts.timeoutMs ?? 30000;\n    if (!this.fetchImpl) {\n      throw new Error('RAGFlow adapter: no fetch available; pass options.fetch');\n    }\n  }\n\n  async upsert(docs: KnowledgeDocument[], ctx: AdapterContext): Promise<void> {\n    const { datasetId } = extractRagflowOptions(ctx.source);\n    // RAGFlow models documents in two layers: documents (file-like) and\n    // chunks (text blocks). We treat each KnowledgeDocument as a single\n    // chunk-set: delete existing chunks with the same external id, then\n    // upload as `content` chunks tagged with our document id.\n    for (const doc of docs) {\n      await this.deleteChunksByDocumentId(datasetId, doc.id);\n      await this.request(`/api/v1/datasets/${datasetId}/chunks`, {\n        method: 'POST',\n        body: JSON.stringify({\n          content: doc.content,\n          // RAGFlow accepts arbitrary metadata used for filtering at\n          // retrieval time. We always stamp `objectstack_doc_id` so\n          // delete() can find these chunks again.\n          important_keywords: doc.title ? [doc.title] : undefined,\n          metadata: {\n            ...(doc.metadata ?? {}),\n            objectstack_doc_id: doc.id,\n            objectstack_source_id: doc.sourceId,\n            objectstack_record_id: doc.sourceRecordId,\n            title: doc.title,\n          },\n        }),\n      });\n    }\n  }\n\n  async delete(documentIds: string[], ctx: AdapterContext): Promise<void> {\n    const { datasetId } = extractRagflowOptions(ctx.source);\n    for (const id of documentIds) {\n      await this.deleteChunksByDocumentId(datasetId, id);\n    }\n  }\n\n  async search(query: string, opts: AdapterSearchOptions): Promise<KnowledgeHit[]> {\n    const { datasetId, rerankModel, similarityThreshold, vectorSimilarityWeight } =\n      extractRagflowOptions(opts.source);\n    const body: Record<string, unknown> = {\n      question: query,\n      dataset_ids: [datasetId],\n      top_k: opts.topK,\n      keyword: true,\n    };\n    if (rerankModel) body.rerank_id = rerankModel;\n    if (typeof similarityThreshold === 'number') body.similarity_threshold = similarityThreshold;\n    if (typeof vectorSimilarityWeight === 'number')\n      body.vector_similarity_weight = vectorSimilarityWeight;\n    if (opts.filter) body.metadata_condition = { ...opts.filter };\n\n    const res = await this.request('/api/v1/retrieval', {\n      method: 'POST',\n      body: JSON.stringify(body),\n    });\n    const data = (res?.data ?? {}) as { chunks?: RagflowChunkHit[] };\n    const chunks = data.chunks ?? [];\n    return chunks.slice(0, opts.topK).map<KnowledgeHit>((c) => {\n      const md = (c.metadata ?? {}) as Record<string, unknown>;\n      const docId =\n        (md.objectstack_doc_id as string | undefined) ??\n        c.document_id ??\n        c.doc_id ??\n        c.id;\n      const recordId = md.objectstack_record_id as string | undefined;\n      return {\n        chunkId: c.id ?? `${docId}#${c.position ?? 0}`,\n        documentId: docId ?? c.id ?? 'unknown',\n        sourceId: opts.source.id,\n        sourceRecordId: recordId,\n        score: c.similarity ?? c.score ?? 0,\n        snippet: c.content ?? c.content_with_weight ?? '',\n        title: (md.title as string | undefined) ?? c.document_name,\n        metadata: md,\n      };\n    });\n  }\n\n  async healthCheck(): Promise<{ ok: boolean; message?: string }> {\n    try {\n      await this.request('/api/v1/datasets?page=1&page_size=1', { method: 'GET' });\n      return { ok: true };\n    } catch (err) {\n      return { ok: false, message: err instanceof Error ? err.message : String(err) };\n    }\n  }\n\n  private async deleteChunksByDocumentId(datasetId: string, docId: string): Promise<void> {\n    // Find chunks with our stamped metadata, then delete by chunk id.\n    const found = (await this.request(`/api/v1/retrieval`, {\n      method: 'POST',\n      body: JSON.stringify({\n        question: docId,\n        dataset_ids: [datasetId],\n        top_k: 256,\n        keyword: false,\n        metadata_condition: { objectstack_doc_id: docId },\n      }),\n    })) as { data?: { chunks?: Array<{ id?: string }> } };\n    const ids = (found.data?.chunks ?? [])\n      .map((c) => c.id)\n      .filter((x): x is string => typeof x === 'string');\n    if (ids.length === 0) return;\n    await this.request(`/api/v1/datasets/${datasetId}/chunks`, {\n      method: 'DELETE',\n      body: JSON.stringify({ chunk_ids: ids }),\n    });\n  }\n\n  private async request(\n    path: string,\n    init: { method: string; body?: string },\n  ): Promise<{ data?: unknown; code?: number; message?: string }> {\n    const controller = new AbortController();\n    const t = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      const res = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: init.method,\n        headers: {\n          'content-type': 'application/json',\n          authorization: `Bearer ${this.apiKey}`,\n        },\n        body: init.body,\n        signal: controller.signal,\n      });\n      const raw = await res.text();\n      let parsed: { data?: unknown; code?: number; message?: string } = {};\n      if (raw) {\n        try {\n          parsed = JSON.parse(raw) as typeof parsed;\n        } catch {\n          if (!res.ok) {\n            throw new Error(\n              `RAGFlow ${init.method} ${path} → ${res.status} ${res.statusText}: ${raw.slice(0, 200)}`,\n            );\n          }\n        }\n      }\n      if (!res.ok || (typeof parsed.code === 'number' && parsed.code !== 0 && parsed.code !== 200)) {\n        throw new Error(\n          `RAGFlow ${init.method} ${path} → ${res.status} ${res.statusText}${\n            parsed.message ? ` (${parsed.message})` : ''\n          }`,\n        );\n      }\n      return parsed;\n    } finally {\n      clearTimeout(t);\n    }\n  }\n}\n\ninterface RagflowChunkHit {\n  id?: string;\n  document_id?: string;\n  doc_id?: string;\n  document_name?: string;\n  content?: string;\n  content_with_weight?: string;\n  similarity?: number;\n  score?: number;\n  position?: number;\n  metadata?: Record<string, unknown>;\n}\n\n/* ---------------------------------------------------------------- */\n/* Kernel plugin glue                                               */\n/* ---------------------------------------------------------------- */\n\nexport interface KnowledgeRagflowPluginOptions extends KnowledgeRagflowAdapterOptions {}\n\nexport class KnowledgeRagflowPlugin implements Plugin {\n  name = 'com.objectstack.plugin.knowledge-ragflow';\n  version = '0.1.0';\n  type = 'standard';\n\n  private readonly adapter: KnowledgeRagflowAdapter;\n\n  constructor(opts: KnowledgeRagflowPluginOptions) {\n    this.adapter = new KnowledgeRagflowAdapter(opts);\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // No-op: actual registration happens in start() once service is available.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    let svc: IKnowledgeService | undefined;\n    try {\n      svc = ctx.getService<IKnowledgeService>(KNOWLEDGE_SERVICE);\n    } catch {\n      ctx.logger.warn?.(\n        'KnowledgeRagflowPlugin: IKnowledgeService not registered — install KnowledgeServicePlugin first.',\n      );\n      return;\n    }\n    svc.registerAdapter(this.adapter.id, this.adapter);\n    ctx.logger.info?.(\n      `KnowledgeRagflowPlugin: adapter '${this.adapter.id}' registered (endpoint=${(this.adapter as unknown as { endpoint: string }).endpoint}).`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,187 @@
+// src/index.ts
+import { KNOWLEDGE_SERVICE } from "@objectstack/spec/contracts";
+function extractRagflowOptions(source) {
+  const opts = source.options ?? {};
+  const datasetId = opts.datasetId;
+  if (typeof datasetId !== "string" || !datasetId) {
+    throw new Error(
+      `RAGFlow adapter requires source.options.datasetId on source '${source.id}'`
+    );
+  }
+  return {
+    datasetId,
+    rerankModel: typeof opts.rerankModel === "string" ? opts.rerankModel : void 0,
+    similarityThreshold: typeof opts.similarityThreshold === "number" ? opts.similarityThreshold : void 0,
+    vectorSimilarityWeight: typeof opts.vectorSimilarityWeight === "number" ? opts.vectorSimilarityWeight : void 0
+  };
+}
+var KnowledgeRagflowAdapter = class {
+  constructor(opts) {
+    if (!opts.endpoint) throw new Error("RAGFlow adapter: endpoint required");
+    if (!opts.apiKey) throw new Error("RAGFlow adapter: apiKey required");
+    this.id = opts.id ?? "ragflow";
+    this.endpoint = opts.endpoint.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+    if (!this.fetchImpl) {
+      throw new Error("RAGFlow adapter: no fetch available; pass options.fetch");
+    }
+  }
+  async upsert(docs, ctx) {
+    const { datasetId } = extractRagflowOptions(ctx.source);
+    for (const doc of docs) {
+      await this.deleteChunksByDocumentId(datasetId, doc.id);
+      await this.request(`/api/v1/datasets/${datasetId}/chunks`, {
+        method: "POST",
+        body: JSON.stringify({
+          content: doc.content,
+          // RAGFlow accepts arbitrary metadata used for filtering at
+          // retrieval time. We always stamp `objectstack_doc_id` so
+          // delete() can find these chunks again.
+          important_keywords: doc.title ? [doc.title] : void 0,
+          metadata: {
+            ...doc.metadata ?? {},
+            objectstack_doc_id: doc.id,
+            objectstack_source_id: doc.sourceId,
+            objectstack_record_id: doc.sourceRecordId,
+            title: doc.title
+          }
+        })
+      });
+    }
+  }
+  async delete(documentIds, ctx) {
+    const { datasetId } = extractRagflowOptions(ctx.source);
+    for (const id of documentIds) {
+      await this.deleteChunksByDocumentId(datasetId, id);
+    }
+  }
+  async search(query, opts) {
+    const { datasetId, rerankModel, similarityThreshold, vectorSimilarityWeight } = extractRagflowOptions(opts.source);
+    const body = {
+      question: query,
+      dataset_ids: [datasetId],
+      top_k: opts.topK,
+      keyword: true
+    };
+    if (rerankModel) body.rerank_id = rerankModel;
+    if (typeof similarityThreshold === "number") body.similarity_threshold = similarityThreshold;
+    if (typeof vectorSimilarityWeight === "number")
+      body.vector_similarity_weight = vectorSimilarityWeight;
+    if (opts.filter) body.metadata_condition = { ...opts.filter };
+    const res = await this.request("/api/v1/retrieval", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    const data = res?.data ?? {};
+    const chunks = data.chunks ?? [];
+    return chunks.slice(0, opts.topK).map((c) => {
+      const md = c.metadata ?? {};
+      const docId = md.objectstack_doc_id ?? c.document_id ?? c.doc_id ?? c.id;
+      const recordId = md.objectstack_record_id;
+      return {
+        chunkId: c.id ?? `${docId}#${c.position ?? 0}`,
+        documentId: docId ?? c.id ?? "unknown",
+        sourceId: opts.source.id,
+        sourceRecordId: recordId,
+        score: c.similarity ?? c.score ?? 0,
+        snippet: c.content ?? c.content_with_weight ?? "",
+        title: md.title ?? c.document_name,
+        metadata: md
+      };
+    });
+  }
+  async healthCheck() {
+    try {
+      await this.request("/api/v1/datasets?page=1&page_size=1", { method: "GET" });
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  async deleteChunksByDocumentId(datasetId, docId) {
+    const found = await this.request(`/api/v1/retrieval`, {
+      method: "POST",
+      body: JSON.stringify({
+        question: docId,
+        dataset_ids: [datasetId],
+        top_k: 256,
+        keyword: false,
+        metadata_condition: { objectstack_doc_id: docId }
+      })
+    });
+    const ids = (found.data?.chunks ?? []).map((c) => c.id).filter((x) => typeof x === "string");
+    if (ids.length === 0) return;
+    await this.request(`/api/v1/datasets/${datasetId}/chunks`, {
+      method: "DELETE",
+      body: JSON.stringify({ chunk_ids: ids })
+    });
+  }
+  async request(path, init) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.endpoint}${path}`, {
+        method: init.method,
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`
+        },
+        body: init.body,
+        signal: controller.signal
+      });
+      const raw = await res.text();
+      let parsed = {};
+      if (raw) {
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          if (!res.ok) {
+            throw new Error(
+              `RAGFlow ${init.method} ${path} \u2192 ${res.status} ${res.statusText}: ${raw.slice(0, 200)}`
+            );
+          }
+        }
+      }
+      if (!res.ok || typeof parsed.code === "number" && parsed.code !== 0 && parsed.code !== 200) {
+        throw new Error(
+          `RAGFlow ${init.method} ${path} \u2192 ${res.status} ${res.statusText}${parsed.message ? ` (${parsed.message})` : ""}`
+        );
+      }
+      return parsed;
+    } finally {
+      clearTimeout(t);
+    }
+  }
+};
+var KnowledgeRagflowPlugin = class {
+  constructor(opts) {
+    this.name = "com.objectstack.plugin.knowledge-ragflow";
+    this.version = "0.1.0";
+    this.type = "standard";
+    this.adapter = new KnowledgeRagflowAdapter(opts);
+  }
+  async init(_ctx) {
+  }
+  async start(ctx) {
+    let svc;
+    try {
+      svc = ctx.getService(KNOWLEDGE_SERVICE);
+    } catch {
+      ctx.logger.warn?.(
+        "KnowledgeRagflowPlugin: IKnowledgeService not registered \u2014 install KnowledgeServicePlugin first."
+      );
+      return;
+    }
+    svc.registerAdapter(this.adapter.id, this.adapter);
+    ctx.logger.info?.(
+      `KnowledgeRagflowPlugin: adapter '${this.adapter.id}' registered (endpoint=${this.adapter.endpoint}).`
+    );
+  }
+};
+export {
+  KnowledgeRagflowAdapter,
+  KnowledgeRagflowPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type {\n  IKnowledgeAdapter,\n  IKnowledgeService,\n  AdapterContext,\n  AdapterSearchOptions,\n} from '@objectstack/spec/contracts';\nimport type {\n  KnowledgeDocument,\n  KnowledgeHit,\n  KnowledgeSource,\n} from '@objectstack/spec/ai';\nimport { KNOWLEDGE_SERVICE } from '@objectstack/spec/contracts';\n\n/**\n * Subset of `fetch` used by the adapter. Inject in tests; defaults to\n * the global `fetch`.\n */\nexport type FetchLike = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  statusText: string;\n  text(): Promise<string>;\n  json(): Promise<unknown>;\n}>;\n\nexport interface KnowledgeRagflowAdapterOptions {\n  /** RAGFlow endpoint, e.g. `http://localhost:9380`. */\n  endpoint: string;\n  /** RAGFlow API key (Bearer token). */\n  apiKey: string;\n  /** Adapter id. @default 'ragflow' */\n  id?: string;\n  /** Override `fetch` for tests. */\n  fetch?: FetchLike;\n  /** Request timeout in milliseconds. @default 30000 */\n  timeoutMs?: number;\n}\n\ninterface RagflowSourceOptions {\n  datasetId: string;\n  /** Optional rerank model id (overrides dataset default). */\n  rerankModel?: string;\n  /** Optional similarity threshold passed through to RAGFlow. */\n  similarityThreshold?: number;\n  /** Optional vector vs keyword weight in [0,1]. */\n  vectorSimilarityWeight?: number;\n}\n\nfunction extractRagflowOptions(source: KnowledgeSource): RagflowSourceOptions {\n  const opts = ((source as unknown as { options?: Record<string, unknown> }).options ?? {}) as\n    Record<string, unknown>;\n  const datasetId = opts.datasetId;\n  if (typeof datasetId !== 'string' || !datasetId) {\n    throw new Error(\n      `RAGFlow adapter requires source.options.datasetId on source '${source.id}'`,\n    );\n  }\n  return {\n    datasetId,\n    rerankModel: typeof opts.rerankModel === 'string' ? opts.rerankModel : undefined,\n    similarityThreshold:\n      typeof opts.similarityThreshold === 'number' ? opts.similarityThreshold : undefined,\n    vectorSimilarityWeight:\n      typeof opts.vectorSimilarityWeight === 'number'\n        ? opts.vectorSimilarityWeight\n        : undefined,\n  };\n}\n\n/**\n * RAGFlow adapter. Maps {@link KnowledgeDocument} upserts to the\n * dataset's chunk API, delegates retrieval to `/api/v1/retrieval`, and\n * returns {@link KnowledgeHit}s with `sourceRecordId` preserved so the\n * orchestrator can run a permission re-check.\n */\nexport class KnowledgeRagflowAdapter implements IKnowledgeAdapter {\n  readonly id: string;\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: FetchLike;\n  private readonly timeoutMs: number;\n\n  constructor(opts: KnowledgeRagflowAdapterOptions) {\n    if (!opts.endpoint) throw new Error('RAGFlow adapter: endpoint required');\n    if (!opts.apiKey) throw new Error('RAGFlow adapter: apiKey required');\n    this.id = opts.id ?? 'ragflow';\n    this.endpoint = opts.endpoint.replace(/\\/+$/, '');\n    this.apiKey = opts.apiKey;\n    this.fetchImpl = opts.fetch ?? ((globalThis as { fetch?: FetchLike }).fetch as FetchLike);\n    this.timeoutMs = opts.timeoutMs ?? 30000;\n    if (!this.fetchImpl) {\n      throw new Error('RAGFlow adapter: no fetch available; pass options.fetch');\n    }\n  }\n\n  async upsert(docs: KnowledgeDocument[], ctx: AdapterContext): Promise<void> {\n    const { datasetId } = extractRagflowOptions(ctx.source);\n    // RAGFlow models documents in two layers: documents (file-like) and\n    // chunks (text blocks). We treat each KnowledgeDocument as a single\n    // chunk-set: delete existing chunks with the same external id, then\n    // upload as `content` chunks tagged with our document id.\n    for (const doc of docs) {\n      await this.deleteChunksByDocumentId(datasetId, doc.id);\n      await this.request(`/api/v1/datasets/${datasetId}/chunks`, {\n        method: 'POST',\n        body: JSON.stringify({\n          content: doc.content,\n          // RAGFlow accepts arbitrary metadata used for filtering at\n          // retrieval time. We always stamp `objectstack_doc_id` so\n          // delete() can find these chunks again.\n          important_keywords: doc.title ? [doc.title] : undefined,\n          metadata: {\n            ...(doc.metadata ?? {}),\n            objectstack_doc_id: doc.id,\n            objectstack_source_id: doc.sourceId,\n            objectstack_record_id: doc.sourceRecordId,\n            title: doc.title,\n          },\n        }),\n      });\n    }\n  }\n\n  async delete(documentIds: string[], ctx: AdapterContext): Promise<void> {\n    const { datasetId } = extractRagflowOptions(ctx.source);\n    for (const id of documentIds) {\n      await this.deleteChunksByDocumentId(datasetId, id);\n    }\n  }\n\n  async search(query: string, opts: AdapterSearchOptions): Promise<KnowledgeHit[]> {\n    const { datasetId, rerankModel, similarityThreshold, vectorSimilarityWeight } =\n      extractRagflowOptions(opts.source);\n    const body: Record<string, unknown> = {\n      question: query,\n      dataset_ids: [datasetId],\n      top_k: opts.topK,\n      keyword: true,\n    };\n    if (rerankModel) body.rerank_id = rerankModel;\n    if (typeof similarityThreshold === 'number') body.similarity_threshold = similarityThreshold;\n    if (typeof vectorSimilarityWeight === 'number')\n      body.vector_similarity_weight = vectorSimilarityWeight;\n    if (opts.filter) body.metadata_condition = { ...opts.filter };\n\n    const res = await this.request('/api/v1/retrieval', {\n      method: 'POST',\n      body: JSON.stringify(body),\n    });\n    const data = (res?.data ?? {}) as { chunks?: RagflowChunkHit[] };\n    const chunks = data.chunks ?? [];\n    return chunks.slice(0, opts.topK).map<KnowledgeHit>((c) => {\n      const md = (c.metadata ?? {}) as Record<string, unknown>;\n      const docId =\n        (md.objectstack_doc_id as string | undefined) ??\n        c.document_id ??\n        c.doc_id ??\n        c.id;\n      const recordId = md.objectstack_record_id as string | undefined;\n      return {\n        chunkId: c.id ?? `${docId}#${c.position ?? 0}`,\n        documentId: docId ?? c.id ?? 'unknown',\n        sourceId: opts.source.id,\n        sourceRecordId: recordId,\n        score: c.similarity ?? c.score ?? 0,\n        snippet: c.content ?? c.content_with_weight ?? '',\n        title: (md.title as string | undefined) ?? c.document_name,\n        metadata: md,\n      };\n    });\n  }\n\n  async healthCheck(): Promise<{ ok: boolean; message?: string }> {\n    try {\n      await this.request('/api/v1/datasets?page=1&page_size=1', { method: 'GET' });\n      return { ok: true };\n    } catch (err) {\n      return { ok: false, message: err instanceof Error ? err.message : String(err) };\n    }\n  }\n\n  private async deleteChunksByDocumentId(datasetId: string, docId: string): Promise<void> {\n    // Find chunks with our stamped metadata, then delete by chunk id.\n    const found = (await this.request(`/api/v1/retrieval`, {\n      method: 'POST',\n      body: JSON.stringify({\n        question: docId,\n        dataset_ids: [datasetId],\n        top_k: 256,\n        keyword: false,\n        metadata_condition: { objectstack_doc_id: docId },\n      }),\n    })) as { data?: { chunks?: Array<{ id?: string }> } };\n    const ids = (found.data?.chunks ?? [])\n      .map((c) => c.id)\n      .filter((x): x is string => typeof x === 'string');\n    if (ids.length === 0) return;\n    await this.request(`/api/v1/datasets/${datasetId}/chunks`, {\n      method: 'DELETE',\n      body: JSON.stringify({ chunk_ids: ids }),\n    });\n  }\n\n  private async request(\n    path: string,\n    init: { method: string; body?: string },\n  ): Promise<{ data?: unknown; code?: number; message?: string }> {\n    const controller = new AbortController();\n    const t = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      const res = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: init.method,\n        headers: {\n          'content-type': 'application/json',\n          authorization: `Bearer ${this.apiKey}`,\n        },\n        body: init.body,\n        signal: controller.signal,\n      });\n      const raw = await res.text();\n      let parsed: { data?: unknown; code?: number; message?: string } = {};\n      if (raw) {\n        try {\n          parsed = JSON.parse(raw) as typeof parsed;\n        } catch {\n          if (!res.ok) {\n            throw new Error(\n              `RAGFlow ${init.method} ${path} → ${res.status} ${res.statusText}: ${raw.slice(0, 200)}`,\n            );\n          }\n        }\n      }\n      if (!res.ok || (typeof parsed.code === 'number' && parsed.code !== 0 && parsed.code !== 200)) {\n        throw new Error(\n          `RAGFlow ${init.method} ${path} → ${res.status} ${res.statusText}${\n            parsed.message ? ` (${parsed.message})` : ''\n          }`,\n        );\n      }\n      return parsed;\n    } finally {\n      clearTimeout(t);\n    }\n  }\n}\n\ninterface RagflowChunkHit {\n  id?: string;\n  document_id?: string;\n  doc_id?: string;\n  document_name?: string;\n  content?: string;\n  content_with_weight?: string;\n  similarity?: number;\n  score?: number;\n  position?: number;\n  metadata?: Record<string, unknown>;\n}\n\n/* ---------------------------------------------------------------- */\n/* Kernel plugin glue                                               */\n/* ---------------------------------------------------------------- */\n\nexport interface KnowledgeRagflowPluginOptions extends KnowledgeRagflowAdapterOptions {}\n\nexport class KnowledgeRagflowPlugin implements Plugin {\n  name = 'com.objectstack.plugin.knowledge-ragflow';\n  version = '0.1.0';\n  type = 'standard';\n\n  private readonly adapter: KnowledgeRagflowAdapter;\n\n  constructor(opts: KnowledgeRagflowPluginOptions) {\n    this.adapter = new KnowledgeRagflowAdapter(opts);\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // No-op: actual registration happens in start() once service is available.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    let svc: IKnowledgeService | undefined;\n    try {\n      svc = ctx.getService<IKnowledgeService>(KNOWLEDGE_SERVICE);\n    } catch {\n      ctx.logger.warn?.(\n        'KnowledgeRagflowPlugin: IKnowledgeService not registered — install KnowledgeServicePlugin first.',\n      );\n      return;\n    }\n    svc.registerAdapter(this.adapter.id, this.adapter);\n    ctx.logger.info?.(\n      `KnowledgeRagflowPlugin: adapter '${this.adapter.id}' registered (endpoint=${(this.adapter as unknown as { endpoint: string }).endpoint}).`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@objectstack/knowledge-ragflow",
+  "version": "6.4.0",
+  "license": "Apache-2.0",
+  "description": "RAGFlow knowledge adapter for ObjectStack — production-grade RAG via the Apache 2.0 RAGFlow REST API.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "6.4.0",
+    "@objectstack/service-knowledge": "6.4.0",
+    "@objectstack/spec": "6.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "knowledge",
+    "rag",
+    "ragflow"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "dev": "tsc -w",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/ragflow-adapter.test.ts

@@ -0,0 +1,160 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { KnowledgeRagflowAdapter, type FetchLike } from '../index';
+import type { KnowledgeSource, KnowledgeDocument } from '@objectstack/spec/ai';
+
+const source: KnowledgeSource = {
+  id: 'docs',
+  label: 'Docs',
+  adapter: 'ragflow',
+  source: { kind: 'http', urls: ['https://docs.example.com'] } as KnowledgeSource['source'],
+  options: { datasetId: 'ds_42' },
+};
+
+function fakeFetch(handler: (url: string, init?: any) => unknown): { fetch: FetchLike; calls: Array<{ url: string; init: any }> } {
+  const calls: Array<{ url: string; init: any }> = [];
+  const fetch: FetchLike = async (url, init) => {
+    calls.push({ url, init });
+    const out = await Promise.resolve(handler(url, init));
+    const body = typeof out === 'string' ? out : JSON.stringify(out ?? {});
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () => body,
+      json: async () => JSON.parse(body),
+    };
+  };
+  return { fetch, calls };
+}
+
+describe('KnowledgeRagflowAdapter', () => {
+  it('rejects sources without datasetId', async () => {
+    const { fetch } = fakeFetch(() => ({}));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://x', apiKey: 'k', fetch });
+    const bad: KnowledgeSource = { ...source, options: {} as Record<string, unknown> };
+    await expect(a.search('q', { source: bad, topK: 1 })).rejects.toThrow(/datasetId/);
+  });
+
+  it('upsert deletes-then-creates chunks and stamps objectstack metadata', async () => {
+    const { fetch, calls } = fakeFetch((url) => {
+      if (url.includes('/api/v1/retrieval')) return { code: 0, data: { chunks: [] } };
+      return { code: 0, data: {} };
+    });
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    const doc: KnowledgeDocument = {
+      id: 'd1',
+      sourceId: 'docs',
+      sourceRecordId: 'rec_1',
+      content: 'hello world',
+      title: 'Greeting',
+      metadata: { topic: 'intro' },
+    };
+    await a.upsert([doc], { source });
+    // First call: lookup existing chunks; second: create chunk
+    const createCall = calls.find((c) => c.url.endsWith('/api/v1/datasets/ds_42/chunks') && c.init.method === 'POST');
+    expect(createCall).toBeDefined();
+    const body = JSON.parse(createCall!.init.body);
+    expect(body.content).toBe('hello world');
+    expect(body.metadata.objectstack_doc_id).toBe('d1');
+    expect(body.metadata.objectstack_record_id).toBe('rec_1');
+    expect(body.metadata.objectstack_source_id).toBe('docs');
+    expect(body.metadata.topic).toBe('intro');
+  });
+
+  it('search maps ragflow chunks to KnowledgeHit shape', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      code: 0,
+      data: {
+        chunks: [
+          {
+            id: 'c1',
+            content: 'snippet one',
+            similarity: 0.91,
+            metadata: { objectstack_doc_id: 'd1', objectstack_record_id: 'rec_1', title: 'T1' },
+          },
+          {
+            id: 'c2',
+            content: 'snippet two',
+            similarity: 0.7,
+            metadata: { objectstack_doc_id: 'd2' },
+          },
+        ],
+      },
+    }));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    const hits = await a.search('hello', { source, topK: 5 });
+    expect(hits).toHaveLength(2);
+    expect(hits[0]).toMatchObject({
+      chunkId: 'c1',
+      documentId: 'd1',
+      sourceId: 'docs',
+      sourceRecordId: 'rec_1',
+      score: 0.91,
+      snippet: 'snippet one',
+      title: 'T1',
+    });
+    expect(hits[1].sourceRecordId).toBeUndefined();
+    // Authorization header present
+    const last = calls.at(-1)!;
+    expect(last.init.headers.authorization).toBe('Bearer k');
+  });
+
+  it('search honours rerankModel + similarityThreshold + filter', async () => {
+    const { fetch, calls } = fakeFetch(() => ({ code: 0, data: { chunks: [] } }));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    const s: KnowledgeSource = {
+      ...source,
+      options: { datasetId: 'ds_42', rerankModel: 'bge-reranker', similarityThreshold: 0.6 },
+    };
+    await a.search('q', { source: s, topK: 3, filter: { tag: 'a' } });
+    const body = JSON.parse(calls[0].init.body);
+    expect(body.rerank_id).toBe('bge-reranker');
+    expect(body.similarity_threshold).toBe(0.6);
+    expect(body.metadata_condition).toEqual({ tag: 'a' });
+    expect(body.top_k).toBe(3);
+  });
+
+  it('delete looks up chunks then issues DELETE with chunk_ids', async () => {
+    const { fetch, calls } = fakeFetch((url) => {
+      if (url.includes('/api/v1/retrieval')) {
+        return { code: 0, data: { chunks: [{ id: 'c1' }, { id: 'c2' }] } };
+      }
+      return { code: 0, data: {} };
+    });
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    await a.delete(['d1'], { source });
+    const del = calls.find((c) => c.init.method === 'DELETE');
+    expect(del).toBeDefined();
+    expect(JSON.parse(del!.init.body)).toEqual({ chunk_ids: ['c1', 'c2'] });
+  });
+
+  it('healthCheck pings dataset list', async () => {
+    const { fetch } = fakeFetch(() => ({ code: 0, data: { datasets: [] } }));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    const h = await a.healthCheck();
+    expect(h.ok).toBe(true);
+  });
+
+  it('healthCheck reports failure when request throws', async () => {
+    const fetch: FetchLike = async () => {
+      throw new Error('boom');
+    };
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    const h = await a.healthCheck();
+    expect(h.ok).toBe(false);
+    expect(h.message).toMatch(/boom/);
+  });
+
+  it('throws on non-zero RAGFlow error code', async () => {
+    const { fetch } = fakeFetch(() => ({ code: 102, message: 'bad request' }));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
+    await expect(a.search('q', { source, topK: 1 })).rejects.toThrow(/bad request/);
+  });
+
+  it('constructor validates endpoint and apiKey', () => {
+    expect(() => new KnowledgeRagflowAdapter({ endpoint: '', apiKey: 'k', fetch: (async () => ({}) as any) })).toThrow(/endpoint/);
+    expect(() => new KnowledgeRagflowAdapter({ endpoint: 'http://x', apiKey: '', fetch: (async () => ({}) as any) })).toThrow(/apiKey/);
+  });
+});