@jcode.labs/ragmir 2.0.0

package/examples/library-api-demo/run.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Local library smoke for @jcode.labs/ragmir.
+//
+// This exercises the public TypeScript API (ingest -> search -> ask -> audit) the
+// exact way an external consumer would `import` it, but Node self-referencing
+// resolves "@jcode.labs/ragmir" to THIS repo's local build (packages/ragmir-core/dist),
+// never the npm-published version. That is the point of the demo: while developing
+// core you can validate the library surface end to end against your own changes,
+// without `npx` silently pulling a released package.
+//
+// Run it from the repository root with `pnpm example`.
+
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { ask, audit, ingest, search } from "@jcode.labs/ragmir"
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+// Reuse the committed synthetic corpus so the demo needs no private documents and
+// writes only to the sibling example's gitignored .ragmir/storage.
+const corpus = path.resolve(here, "..", "sovereign-rag-demo")
+
+function heading(title) {
+  console.log(`\n=== ${title} ===`)
+}
+
+async function main() {
+  console.log("Running @jcode.labs/ragmir from the local build against the synthetic corpus.")
+  console.log(`corpus: ${corpus}`)
+
+  heading("ingest")
+  const ingested = await ingest({ cwd: corpus, rebuild: true })
+  console.log(
+    `indexed ${ingested.indexedFiles}/${ingested.supportedFiles} supported files, ` +
+      `${ingested.chunks} chunks, ${ingested.redactions} redactions`,
+  )
+
+  heading('search "offline retrieval approval"')
+  const passages = await search("offline retrieval approval", { cwd: corpus, topK: 3 })
+  for (const passage of passages) {
+    console.log(`- ${passage.relativePath}#${passage.chunkIndex} (distance ${passage.distance ?? "n/a"})`)
+  }
+
+  heading('ask "What evidence supports offline operation?"')
+  const answer = await ask("What evidence supports offline operation?", { cwd: corpus, topK: 3 })
+  console.log(`${answer.sources.length} cited sources`)
+  console.log(answer.answer)
+
+  heading("audit")
+  const report = await audit(corpus)
+  console.log(
+    `${report.supportedFiles.length} supported, ${report.skippedFiles.length} skipped, ` +
+      `${report.totalChunks} chunks indexed`,
+  )
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/examples/sovereign-rag-demo/.ragmir/config.json

@@ -0,0 +1,22 @@
+{
+  "rawDir": "raw",
+  "storageDir": ".ragmir/storage",
+  "sourcesFile": ".ragmir/sources.txt",
+  "accessLogPath": ".ragmir/access.log",
+  "embeddingModelPath": ".ragmir/models",
+  "tableName": "chunks",
+  "embeddingProvider": "local-hash",
+  "embeddingModel": "mixedbread-ai/mxbai-embed-xsmall-v1",
+  "transformersAllowRemoteModels": false,
+  "redaction": {
+    "enabled": true,
+    "builtIn": true,
+    "patterns": []
+  },
+  "accessLog": true,
+  "mcpMaxTopK": 10,
+  "topK": 5,
+  "chunkSize": 900,
+  "chunkOverlap": 120,
+  "includeExtensions": [".evidence"]
+}

package/examples/sovereign-rag-demo/.ragmir/sources.txt

@@ -0,0 +1,2 @@
+# Optional extra source paths, one per line.
+# This demo keeps all indexed files under ./raw.

package/examples/sovereign-rag-demo/README.md

@@ -0,0 +1,95 @@
+# Sovereign RAG Demo
+
+Synthetic test workspace for Ragmir. It is intentionally safe to commit: every document is fictional,
+generic, and designed only to exercise local ingestion, retrieval, redaction, custom extensions, and
+security-audit flows.
+
+This folder must never contain real-world sensitive, regulated, or production documents.
+
+## What It Covers
+
+- Markdown operational briefs.
+- CSV dataset inventories.
+- JSONL incident timelines.
+- YAML policy metadata.
+- A custom `.evidence` text extension enabled through `.ragmir/config.json`.
+- Unsupported/skipped-file reporting with recommendations through `audit --unsupported`.
+
+## Run From This Repository Checkout
+
+Build Ragmir once from the repository root:
+
+```bash
+pnpm build
+```
+
+Then run the CLI from this folder:
+
+```bash
+cd packages/ragmir-core/examples/sovereign-rag-demo
+node ../../dist/cli.js security-audit
+node ../../dist/cli.js ingest
+node ../../dist/cli.js search "offline retrieval approval"
+node ../../dist/cli.js search "dataset residency"
+node ../../dist/cli.js ask "What evidence supports offline operation?"
+node ../../dist/cli.js evaluate --golden golden-queries.json
+node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
+node ../../dist/cli.js audit
+node ../../dist/cli.js audit --unsupported
+node ../../dist/cli.js status
+```
+
+This example uses `embeddingProvider: "local-hash"`, so it does not require a model runtime.
+Retrieval is lexical/hash-based rather than model-semantic.
+
+## Useful Test Queries
+
+- `offline retrieval approval`
+- `dataset residency`
+- `incident containment evidence`
+- `who owns the usage review`
+- `what documents support sovereign deployment`
+
+## Agent Report Prompt
+
+After running `ragmir setup` in a real project, an MCP-compatible agent can use the generated
+`.ragmir/mcp.json`. For this synthetic demo, ask an agent:
+
+```plain text
+Use Ragmir to inspect the local knowledge base, search for "offline retrieval approval", and write a
+cited Markdown report under .ragmir/reports/demo-sovereign-rag.md. Mention any unsupported or stale
+files reported by the audit.
+```
+
+## Switch To Transformers Semantic Mode
+
+To compare no-model retrieval with semantic local retrieval, change `.ragmir/config.json`:
+
+```json
+{
+  "embeddingProvider": "transformers",
+  "embeddingModel": "mixedbread-ai/mxbai-embed-xsmall-v1",
+  "embeddingModelPath": ".ragmir/models",
+  "transformersAllowRemoteModels": false
+}
+```
+
+Preload the model files under `.ragmir/models` for offline work, then rebuild the index:
+
+```bash
+node ../../dist/cli.js ingest
+node ../../dist/cli.js ask "What documents support sovereign deployment?"
+node ../../dist/cli.js evaluate --golden golden-queries.json --json
+node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 0.8 --json
+```
+
+## Generated State
+
+Generated state stays local and ignored:
+
+```plain text
+.ragmir/
+```
+
+Do not replace these synthetic documents with real confidential files inside the Ragmir package
+repository.

package/examples/sovereign-rag-demo/golden-queries.json

@@ -0,0 +1,29 @@
+{
+  "topK": 3,
+  "queries": [
+    {
+      "id": "dataset-rejection",
+      "query": "Which dataset was rejected for confidential tests?",
+      "expectedPaths": ["raw/dataset-inventory.csv"]
+    },
+    {
+      "id": "offline-tts",
+      "query": "What proves offline text-to-speech is required?",
+      "expectedPaths": ["raw/incident-timeline.jsonl", "raw/review-notes.evidence"]
+    },
+    {
+      "id": "usage-review-owner",
+      "query": "Who owns the usage review?",
+      "expectedPaths": [
+        "raw/operations-brief.md",
+        "raw/security-policy.yaml",
+        "raw/review-notes.evidence"
+      ]
+    },
+    {
+      "id": "model-loading-disabled",
+      "query": "Which document says remote model loading is disabled?",
+      "expectedPaths": ["raw/incident-timeline.jsonl", "raw/security-policy.yaml"]
+    }
+  ]
+}

package/examples/sovereign-rag-demo/raw/dataset-inventory.csv

@@ -0,0 +1,5 @@
+dataset,source_type,data_residency,network_access,review_status
+Example Notes,markdown notes,local only,none,approved
+Example Model Card,model metadata,local repository,none,approved
+Example Audio Draft,generated summary,local only,none,approved with offline TTS
+Example Remote Transcript,transcription sample,remote processing,internet,rejected for confidential tests

package/examples/sovereign-rag-demo/raw/facility-scan.heic

@@ -0,0 +1,3 @@
+Synthetic placeholder for an unsupported scanned document format.
+
+Convert scans to OCR text or PDF before expecting Ragmir to index their content.

package/examples/sovereign-rag-demo/raw/incident-timeline.jsonl

@@ -0,0 +1,4 @@
+{"date":"2026-02-12","event":"synthetic dataset imported","owner":"example knowledge team","impact":"none","evidence":"fictional files only"}
+{"date":"2026-02-13","event":"remote model loading disabled","owner":"example review team","impact":"offline policy enforced","evidence":"transformersAllowRemoteModels false"}
+{"date":"2026-02-14","event":"offline retrieval approval completed","owner":"example platform team","impact":"local cited retrieval allowed","evidence":"local-hash provider"}
+{"date":"2026-02-15","event":"audio summary test requested","owner":"example operations role","impact":"offline TTS required","evidence":"ragmir-audio-summary skill"}

package/examples/sovereign-rag-demo/raw/operations-brief.md

@@ -0,0 +1,16 @@
+# Offline Analytics Brief
+
+Example Workspace is a synthetic local knowledge-base deployment used to test Ragmir.
+
+The demo goal is to let a test team summarize fictional operational notes without shipping source
+files to a hosted RAG service. The approved runtime is a local Linux workstation with an encrypted
+disk, local retrieval, and no telemetry.
+
+The initial approval covers three workflows:
+
+- summarize daily operational briefs;
+- compare dataset handling notes against internal policy;
+- prepare audio briefings only with an offline text-to-speech engine.
+
+The usage review is owned by the Example Review Team. Any remote model endpoint requires a written
+exception before use.

package/examples/sovereign-rag-demo/raw/review-notes.evidence

@@ -0,0 +1,11 @@
+Evidence memo for the synthetic usage review.
+
+The Example Review Team approved local-only retrieval because the source documents remain under the
+repository raw folder and the generated vector store remains under .ragmir/storage.
+
+The review rejected remote transcription and online text-to-speech for fictional confidential test
+datasets. The approved audio path is a generated briefing under .ragmir/audio created with an offline
+engine.
+
+The test is considered complete when Ragmir can retrieve the offline retrieval approval, dataset
+residency requirements, and incident containment evidence from separate file formats.

package/examples/sovereign-rag-demo/raw/security-policy.yaml

@@ -0,0 +1,14 @@
+classification: synthetic
+purpose: local-rag-test
+controls:
+  remote_model_loading: disabled
+  storage: encrypted-volume-recommended
+  telemetry: none
+  access_log: metadata-only
+  mcp:
+    destructive_tools: false
+    max_top_k: 10
+review:
+  owner: Example Review Team
+  required_before_remote_model_loading: true
+  required_before_online_tts: true

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@jcode.labs/ragmir",
+  "version": "2.0.0",
+  "description": "Ragmir Core: open-source sovereign local RAG for confidential datasets and AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Jean-Baptiste Thery",
+    "url": "https://github.com/jb-thery"
+  },
+  "keywords": [
+    "jcode",
+    "ragmir",
+    "open-source",
+    "rag",
+    "sovereign-rag",
+    "knowledge-base",
+    "confidential-data",
+    "private-ai",
+    "local-first",
+    "mcp",
+    "transformers",
+    "semantic-search",
+    "lancedb"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jcode-works/jcode-ragmir.git",
+    "directory": "packages/ragmir-core"
+  },
+  "homepage": "https://github.com/jcode-works/jcode-ragmir#readme",
+  "bugs": {
+    "url": "https://github.com/jcode-works/jcode-ragmir/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ragmir": "dist/cli.js",
+    "kb": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "examples",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@lancedb/lancedb": "^0.30.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.2",
+    "fast-glob": "^3.3.3",
+    "fflate": "^0.8.3",
+    "html-to-text": "^9.0.5",
+    "mammoth": "^1.12.0",
+    "picocolors": "^1.1.1",
+    "read-excel-file": "^9.2.0",
+    "unpdf": "^1.4.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.1.13",
+    "@jcode.labs/ragmir-tts": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/html-to-text": "^9.0.4",
+    "@types/node": "^24.10.1",
+    "publint": "^0.3.21",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "mcp:smoke": "pnpm build && node scripts/mcp-smoke.mjs",
+    "package:check": "publint",
+    "test": "vitest run"
+  }
+}