@jcode.labs/ragmir 6.5.2 → 6.7.0

package/README.md

@@ -67,16 +67,24 @@ covers pnpm and guided setup.
 
 ## Connect your agent
 
-`rgr setup --agents claude,codex` prepares a project MCP server and a retrieval skill. The server
-exposes four read-only tools: `ragmir_search` (one question or up to five related ones sharing a
-budget, with named scopes), `ragmir_expand`, `ragmir_status`, and `ragmir_audit`. Passages
-already returned in a session come back as one-line stubs. Its instructions name the base it
-serves, and it warns or refuses agents working in unrelated projects. See
-[agent integration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md)
-for connection steps and local or self-hosted model examples. Python agents built with the MCP
-SDK, LangChain, or LlamaIndex use the same server
-([Python guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/python.md)), and
-`ghcr.io/jcode-works/ragmir` runs it without Node.js.
+[![Claude Code](https://img.shields.io/badge/Claude_Code-D97757?style=flat-square&logo=claude&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents) [![OpenAI Codex](https://img.shields.io/badge/OpenAI_Codex-111111?style=flat-square)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents) [![Cursor](https://img.shields.io/badge/Cursor-111111?style=flat-square&logo=cursor&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents) [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-8E75B2?style=flat-square&logo=googlegemini&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents) [![Qwen Code](https://img.shields.io/badge/Qwen_Code-6950EF?style=flat-square&logo=qwen&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents) [![LangChain.js](https://img.shields.io/badge/LangChain.js-1C3C3C?style=flat-square&logo=langchain&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md#langchainjs-retriever) [![LangChain](https://img.shields.io/badge/LangChain-1C3C3C?style=flat-square&logo=langchain&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/python.md#langchain) [![LlamaIndex](https://img.shields.io/badge/LlamaIndex-6D28D9?style=flat-square)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/python.md#llamaindex) [![MCP](https://img.shields.io/badge/MCP-111111?style=flat-square&logo=modelcontextprotocol&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#connect-an-agent-through-mcp) [![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/python.md) [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md) [![Ollama](https://img.shields.io/badge/Ollama-111111?style=flat-square&logo=ollama&logoColor=white)](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#confidential-chat-local-model-example)
+
+Install Ragmir as a plugin for Claude Code (`/plugin install ragmir --marketplace
+jcode-works/jcode-ragmir`), OpenAI Codex, or Cursor, or as an extension for Gemini CLI and Qwen
+Code; the [plugin
+guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md#plugins-and-extensions-for-coding-agents)
+lists every install command. Without a plugin, `rgr setup --agents claude,codex` prepares a project
+MCP server and a retrieval skill. The server exposes four read-only tools: `ragmir_search` (one
+question or up to five related ones sharing a budget, with named scopes), `ragmir_expand`,
+`ragmir_status`, and `ragmir_audit`. Passages already returned in a session come back as one-line
+stubs. Its instructions name the base it serves, and it warns or refuses agents working in unrelated
+projects. See [agent
+integration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md) for
+connection steps and local or self-hosted model examples. Python agents built with the MCP SDK,
+LangChain, or LlamaIndex use the same server ([Python
+guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/python.md)), and
+`ghcr.io/jcode-works/ragmir` runs it without Node.js. LangChain.js chains use `RagmirRetriever` from
+`@jcode.labs/ragmir/langchain` with the optional peer `@langchain/core`.
 
 ## TypeScript API
 

package/dist/langchain.d.ts

@@ -0,0 +1,60 @@
+import { Document } from "@langchain/core/documents";
+import { BaseRetriever, type BaseRetrieverInput } from "@langchain/core/retrievers";
+import { RagmirClient } from "./client.js";
+import type { SearchOptions, SearchResult, SourceStatus } from "./types.js";
+/** Search settings the retriever forwards to `RagmirClient.search` on every query. */
+export type RagmirRetrieverSearchOptions = Omit<SearchOptions, "cwd" | "explain" | "signal">;
+export interface RagmirRetrieverInput extends BaseRetrieverInput, RagmirRetrieverSearchOptions {
+    /**
+     * Client to query. The retriever never closes a client it did not open, so one client can serve
+     * several retrievers and the rest of the application.
+     */
+    client?: RagmirClient;
+    /**
+     * Project root, or a directory inside it, used to open a client on the first query when `client`
+     * is not given. Defaults to the current working directory. Call `close()` during shutdown.
+     */
+    projectRoot?: string;
+}
+/** Citation fields attached to every LangChain document the retriever returns. */
+export interface RagmirDocumentMetadata extends Record<string, unknown> {
+    /** Project-relative path of the cited file. */
+    source: string;
+    /** Exact citation, such as `docs/runbook.md:L12-L18` or a PDF page, slide, or cell range. */
+    citation: string;
+    chunkIndex: number;
+    /** Heading or structural path of the passage inside its file. */
+    contextPath: string;
+    lineStart: number | null;
+    lineEnd: number | null;
+    pageStart: number | null;
+    pageEnd: number | null;
+    /** Vector distance when a semantic model scored the passage, otherwise null. */
+    distance: number | null;
+    /** The passage holds few of the question's distinctive words: verify it before relying on it. */
+    weakEvidence: boolean;
+    /** Set when the cited file changed or disappeared since it was indexed. */
+    sourceStatus?: SourceStatus;
+    knowledgeBaseId?: string;
+}
+/**
+ * LangChain.js retriever backed by a local Ragmir base. Each document carries its citation in
+ * `metadata`, and a query the indexed sources cannot answer returns an empty list instead of the
+ * least unrelated passages.
+ */
+export declare class RagmirRetriever extends BaseRetriever<RagmirDocumentMetadata> {
+    static lc_name(): string;
+    lc_namespace: string[];
+    private readonly sharedClient;
+    private readonly projectRoot;
+    private readonly searchOptions;
+    private ownedClient;
+    constructor(input?: RagmirRetrieverInput);
+    _getRelevantDocuments(query: string): Promise<Document<RagmirDocumentMetadata>[]>;
+    /** Closes the client this retriever opened. A client passed in `client` stays open. */
+    close(): Promise<void>;
+    private client;
+}
+/** Converts one Ragmir search result into a LangChain document that keeps its citation. */
+export declare function ragmirResultToDocument(result: SearchResult): Document<RagmirDocumentMetadata>;
+//# sourceMappingURL=langchain.d.ts.map

package/dist/langchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../src/langchain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3E,sFAAsF;AACtF,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAA;AAE5F,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB,EAAE,4BAA4B;IAC5F;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,sBAAuB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iGAAiG;IACjG,YAAY,EAAE,OAAO,CAAA;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,aAAa,CAAC,sBAAsB,CAAC;IACxE,MAAM,CAAC,OAAO,IAAI,MAAM,CAEvB;IAED,YAAY,WAA2B;IAEvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,WAAW,CAAmC;IAEtD,YAAY,KAAK,GAAE,oBAAyB,EAW3C;IAEK,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAItF;IAED,uFAAuF;IACjF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3B;IAED,OAAO,CAAC,MAAM;CAiBf;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,QAAQ,CAAC,sBAAsB,CAAC,CAwB7F"}

package/dist/langchain.js

@@ -0,0 +1,86 @@
+import { Document } from "@langchain/core/documents";
+import { BaseRetriever } from "@langchain/core/retrievers";
+import { RagmirClient } from "./client.js";
+/**
+ * LangChain.js retriever backed by a local Ragmir base. Each document carries its citation in
+ * `metadata`, and a query the indexed sources cannot answer returns an empty list instead of the
+ * least unrelated passages.
+ */
+export class RagmirRetriever extends BaseRetriever {
+    static lc_name() {
+        return "RagmirRetriever";
+    }
+    lc_namespace = ["ragmir", "retrievers"];
+    sharedClient;
+    projectRoot;
+    searchOptions;
+    ownedClient;
+    constructor(input = {}) {
+        const { client, projectRoot, callbacks, tags, metadata, verbose, ...searchOptions } = input;
+        super({
+            ...(callbacks === undefined ? {} : { callbacks }),
+            ...(tags === undefined ? {} : { tags }),
+            ...(metadata === undefined ? {} : { metadata }),
+            ...(verbose === undefined ? {} : { verbose }),
+        });
+        this.sharedClient = client;
+        this.projectRoot = projectRoot;
+        this.searchOptions = searchOptions;
+    }
+    async _getRelevantDocuments(query) {
+        const client = await this.client();
+        const results = await client.search(query, this.searchOptions);
+        return results.map(ragmirResultToDocument);
+    }
+    /** Closes the client this retriever opened. A client passed in `client` stays open. */
+    async close() {
+        const owned = this.ownedClient;
+        if (!owned) {
+            return;
+        }
+        const client = await owned.catch(() => undefined);
+        await client?.close();
+    }
+    client() {
+        if (this.sharedClient) {
+            return Promise.resolve(this.sharedClient);
+        }
+        if (!this.ownedClient) {
+            const opening = RagmirClient.create(this.projectRoot === undefined ? {} : { cwd: this.projectRoot });
+            this.ownedClient = opening;
+            opening.catch(() => {
+                if (this.ownedClient === opening) {
+                    this.ownedClient = undefined;
+                }
+            });
+        }
+        return this.ownedClient;
+    }
+}
+/** Converts one Ragmir search result into a LangChain document that keeps its citation. */
+export function ragmirResultToDocument(result) {
+    const metadata = {
+        source: result.relativePath,
+        citation: result.citation,
+        chunkIndex: result.chunkIndex,
+        contextPath: result.contextPath,
+        lineStart: result.lineStart,
+        lineEnd: result.lineEnd,
+        pageStart: result.pageStart,
+        pageEnd: result.pageEnd,
+        distance: result.distance,
+        weakEvidence: result.weakEvidence === true,
+    };
+    if (result.sourceStatus) {
+        metadata.sourceStatus = result.sourceStatus;
+    }
+    if (result.evidence?.knowledgeBaseId) {
+        metadata.knowledgeBaseId = result.evidence.knowledgeBaseId;
+    }
+    return new Document({
+        pageContent: result.text,
+        metadata,
+        id: result.evidence?.id ?? result.citation,
+    });
+}
+//# sourceMappingURL=langchain.js.map

package/dist/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../src/langchain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,EAAE,aAAa,EAA2B,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAyC1C;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAqC;IACxE,MAAM,CAAC,OAAO;QACZ,OAAO,iBAAiB,CAAA;IAC1B,CAAC;IAED,YAAY,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAEtB,YAAY,CAA0B;IACtC,WAAW,CAAoB;IAC/B,aAAa,CAA8B;IACpD,WAAW,CAAmC;IAEtD,YAAY,KAAK,GAAyB,EAAE;QAC1C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,KAAK,CAAA;QAC3F,KAAK,CAAC;YACJ,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;YACjD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACvC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;YAC/C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;SAC9C,CAAC,CAAA;QACF,IAAI,CAAC,YAAY,GAAG,MAAM,CAAA;QAC1B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,KAAa;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;QAClC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;QAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;IAC5C,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,KAAK;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAA;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAM;QACR,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACjD,MAAM,MAAM,EAAE,KAAK,EAAE,CAAA;IACvB,CAAC;IAEO,MAAM;QACZ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;QAC3C,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CACjC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,CAChE,CAAA;YACD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAA;YAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;gBACjB,IAAI,IAAI,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;oBACjC,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;gBAC9B,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CACF;AAED,2FAA2F;AAC3F,MAAM,UAAU,sBAAsB,CAAC,MAAoB;IACzD,MAAM,QAAQ,GAA2B;QACvC,MAAM,EAAE,MAAM,CAAC,YAAY;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY,KAAK,IAAI;KAC3C,CAAA;IACD,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,QAAQ,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;IAC7C,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;QACrC,QAAQ,CAAC,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAA;IAC5D,CAAC;IACD,OAAO,IAAI,QAAQ,CAAyB;QAC1C,WAAW,EAAE,MAAM,CAAC,IAAI;QACxB,QAAQ;QACR,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,MAAM,CAAC,QAAQ;KAC3C,CAAC,CAAA;AACJ,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "6.5.2";
+export declare const VERSION = "6.7.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "6.5.2";
+export const VERSION = "6.7.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jcode.labs/ragmir",
   "mcpName": "io.github.jcode-works/ragmir",
-  "version": "6.5.2",
+  "version": "6.7.0",
   "description": "Open-source retrieval for agentic RAG: document search with exact citations on your laptop or servers, with OCR, CLI, MCP, and TypeScript.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -49,6 +49,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
     }
   },
   "bin": {
@@ -82,11 +86,15 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@huggingface/transformers": "^4.3.0"
+    "@huggingface/transformers": "^4.3.0",
+    "@langchain/core": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@huggingface/transformers": {
       "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
     }
   },
   "devDependencies": {