@turbomem/okf 0.2.0

package/dist/index.js

@@ -0,0 +1,248 @@
+import path from 'path';
+import fs2 from 'fs/promises';
+import matter from 'gray-matter';
+import fg from 'fast-glob';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import { z } from 'zod';
+
+// src/parser.ts
+function normalizeRelativePath(relativePath) {
+  return relativePath.split(path.sep).join("/");
+}
+function resolveLinkHref(href, documentPath, bundleRoot) {
+  const withoutFragment = href.split("#")[0] ?? href;
+  if (withoutFragment.startsWith("/")) {
+    return path.join(bundleRoot, withoutFragment.slice(1));
+  }
+  return path.resolve(path.dirname(documentPath), withoutFragment);
+}
+function extractLinks(body, documentPath, bundleRoot, followLinks) {
+  const links = [];
+  const tree = unified().use(remarkParse).parse(body);
+  visit(tree, "link", (node) => {
+    const linkNode = node;
+    const href = linkNode.url;
+    const text = linkNode.children?.[0]?.type === "text" ? linkNode.children[0].value ?? "" : "";
+    if (href.startsWith("http://") || href.startsWith("https://")) {
+      links.push({ text, href });
+      return;
+    }
+    const link = { text, href };
+    if (followLinks) {
+      const resolvedAbsolute = resolveLinkHref(href, documentPath, bundleRoot);
+      link.resolvedPath = normalizeRelativePath(path.relative(bundleRoot, resolvedAbsolute));
+    }
+    links.push(link);
+  });
+  return links;
+}
+function normalizeFrontmatter(data) {
+  const normalized = { ...data };
+  if (normalized.timestamp instanceof Date) {
+    normalized.timestamp = normalized.timestamp.toISOString();
+  }
+  return normalized;
+}
+async function parseDocument(filePath, bundleRoot, options = {}) {
+  const { followLinks = true } = options;
+  const raw = await fs2.readFile(filePath, "utf-8");
+  const { data, content } = matter(raw);
+  const relativePath = normalizeRelativePath(path.relative(bundleRoot, filePath));
+  const links = extractLinks(content, filePath, bundleRoot, followLinks);
+  return {
+    path: filePath,
+    relativePath,
+    frontmatter: normalizeFrontmatter(data),
+    body: content,
+    links
+  };
+}
+async function parseBundle(rootDir, options = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const ignorePatterns = options.ignore ?? [];
+  const filePaths = await fg("**/*.md", {
+    cwd: absoluteRoot,
+    absolute: true,
+    ignore: ignorePatterns
+  });
+  const documents = await Promise.all(
+    filePaths.map((fp) => parseDocument(fp, absoluteRoot, options))
+  );
+  const index = /* @__PURE__ */ new Map();
+  for (const doc of documents) {
+    index.set(doc.relativePath, doc);
+  }
+  return { root: absoluteRoot, documents, index };
+}
+var frontmatterSchema = z.object({
+  type: z.string().min(1, "type field must be a non-empty string"),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  resource: z.string().url("resource must be a valid URL").optional(),
+  tags: z.array(z.string()).optional(),
+  timestamp: z.string().datetime({ offset: true }).optional()
+}).passthrough();
+function validateDocument(doc) {
+  const errors = [];
+  const warnings = [];
+  const result = frontmatterSchema.safeParse(doc.frontmatter);
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      errors.push({
+        path: doc.relativePath,
+        message: issue.message,
+        rule: "frontmatter-schema"
+      });
+    }
+  }
+  if (!doc.body.trim()) {
+    warnings.push({
+      path: doc.relativePath,
+      message: "Document body is empty",
+      rule: "empty-body"
+    });
+  }
+  if (doc.frontmatter.timestamp) {
+    const d = Date.parse(doc.frontmatter.timestamp);
+    if (isNaN(d)) {
+      errors.push({
+        path: doc.relativePath,
+        message: `timestamp "${doc.frontmatter.timestamp}" is not a valid ISO 8601 date`,
+        rule: "timestamp-format"
+      });
+    }
+  }
+  return { errors, warnings };
+}
+function validateBundle(bundle) {
+  const allErrors = [];
+  const allWarnings = [];
+  for (const doc of bundle.documents) {
+    const { errors, warnings } = validateDocument(doc);
+    allErrors.push(...errors);
+    allWarnings.push(...warnings);
+  }
+  for (const doc of bundle.documents) {
+    for (const link of doc.links) {
+      if (link.resolvedPath && !bundle.index.has(link.resolvedPath)) {
+        allWarnings.push({
+          path: doc.relativePath,
+          message: `Cross-link "${link.href}" does not resolve to a known concept in this bundle`,
+          rule: "unresolved-cross-link"
+        });
+      }
+    }
+  }
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+function serializeDocument(frontmatter, body) {
+  return matter.stringify(body, frontmatter);
+}
+async function writeDocument(outputPath, frontmatter, body, options = {}) {
+  const { overwrite = false } = options;
+  let exists = false;
+  try {
+    await fs2.access(outputPath);
+    exists = true;
+  } catch {
+    exists = false;
+  }
+  if (exists && !overwrite) {
+    throw new Error(`File already exists: ${outputPath}. Pass overwrite: true to replace it.`);
+  }
+  await fs2.mkdir(path.dirname(outputPath), { recursive: true });
+  const content = serializeDocument(frontmatter, body);
+  await fs2.writeFile(outputPath, content, "utf-8");
+}
+async function writeIndex(dirPath, title, description, options = {}) {
+  const indexPath = path.join(dirPath, "index.md");
+  await writeDocument(
+    indexPath,
+    { type: "index", title, description },
+    `# ${title}
+
+${description}
+`,
+    options
+  );
+}
+
+// src/graph.ts
+function buildGraph(bundle) {
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = [];
+  for (const doc of bundle.documents) {
+    nodes.set(doc.relativePath, {
+      document: doc,
+      outgoing: [],
+      incoming: []
+    });
+  }
+  for (const doc of bundle.documents) {
+    const fromNode = nodes.get(doc.relativePath);
+    for (const link of doc.links) {
+      if (!link.resolvedPath) continue;
+      const toNode = nodes.get(link.resolvedPath);
+      if (!toNode) continue;
+      const edge = {
+        from: doc,
+        to: toNode.document,
+        linkText: link.text
+      };
+      edges.push(edge);
+      fromNode.outgoing.push(edge);
+      toNode.incoming.push(edge);
+    }
+  }
+  return { nodes, edges };
+}
+function reachableFrom(graph, startRelativePath) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [startRelativePath];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    const node = graph.nodes.get(current);
+    if (!node) continue;
+    for (const edge of node.outgoing) {
+      queue.push(edge.to.relativePath);
+    }
+  }
+  return [...visited];
+}
+
+// src/turbomem.ts
+function documentToFacts(doc) {
+  const facts = [];
+  const fm = doc.frontmatter;
+  const parts = [`[${fm.type}]`];
+  if (fm.title) parts.push(fm.title);
+  if (fm.description) parts.push("\u2014", fm.description);
+  if (fm.resource) parts.push(`(resource: ${fm.resource})`);
+  if (fm.tags?.length) parts.push(`tags: ${fm.tags.join(", ")}`);
+  facts.push(parts.join(" "));
+  const body = doc.body.trim();
+  if (body) {
+    facts.push(`${fm.title ?? doc.relativePath} details: ${body}`);
+  }
+  return facts;
+}
+function bundleToFacts(bundle) {
+  return bundle.documents.flatMap(documentToFacts);
+}
+async function addFromBundle(memory, bundle, scope = {}) {
+  const facts = bundleToFacts(bundle);
+  if (facts.length === 0) return [];
+  return memory.addFacts(facts, scope);
+}
+
+export { addFromBundle, buildGraph, bundleToFacts, documentToFacts, parseBundle, parseDocument, reachableFrom, serializeDocument, validateBundle, validateDocument, writeDocument, writeIndex };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/parser.ts","../src/validator.ts","../src/writer.ts","../src/graph.ts","../src/turbomem.ts"],"names":["fs","matter","path"],"mappings":"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","file":"index.js","sourcesContent":["import path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport matter from \"gray-matter\";\nimport fg from \"fast-glob\";\nimport { unified } from \"unified\";\nimport remarkParse from \"remark-parse\";\nimport { visit } from \"unist-util-visit\";\nimport type { OKFBundle, OKFDocument, OKFLink, OKFFrontmatter, ParseOptions } from \"./types.js\";\n\nfunction normalizeRelativePath(relativePath: string): string {\n  return relativePath.split(path.sep).join(\"/\");\n}\n\nfunction resolveLinkHref(href: string, documentPath: string, bundleRoot: string): string {\n  const withoutFragment = href.split(\"#\")[0] ?? href;\n  if (withoutFragment.startsWith(\"/\")) {\n    return path.join(bundleRoot, withoutFragment.slice(1));\n  }\n  return path.resolve(path.dirname(documentPath), withoutFragment);\n}\n\nfunction extractLinks(\n  body: string,\n  documentPath: string,\n  bundleRoot: string,\n  followLinks: boolean,\n): OKFLink[] {\n  const links: OKFLink[] = [];\n  const tree = unified().use(remarkParse).parse(body);\n\n  visit(tree, \"link\", (node) => {\n    const linkNode = node as { url: string; children?: Array<{ type?: string; value?: string }> };\n    const href = linkNode.url;\n    const text = linkNode.children?.[0]?.type === \"text\" ? (linkNode.children[0].value ?? \"\") : \"\";\n\n    if (href.startsWith(\"http://\") || href.startsWith(\"https://\")) {\n      links.push({ text, href });\n      return;\n    }\n\n    const link: OKFLink = { text, href };\n    if (followLinks) {\n      const resolvedAbsolute = resolveLinkHref(href, documentPath, bundleRoot);\n      link.resolvedPath = normalizeRelativePath(path.relative(bundleRoot, resolvedAbsolute));\n    }\n    links.push(link);\n  });\n\n  return links;\n}\n\nfunction normalizeFrontmatter(data: Record<string, unknown>): OKFFrontmatter {\n  const normalized = { ...data };\n  if (normalized.timestamp instanceof Date) {\n    normalized.timestamp = normalized.timestamp.toISOString();\n  }\n  return normalized as OKFFrontmatter;\n}\n\nexport async function parseDocument(filePath: string, bundleRoot: string, options: ParseOptions = {}): Promise<OKFDocument> {\n  const { followLinks = true } = options;\n  const raw = await fs.readFile(filePath, \"utf-8\");\n  const { data, content } = matter(raw);\n\n  const relativePath = normalizeRelativePath(path.relative(bundleRoot, filePath));\n  const links = extractLinks(content, filePath, bundleRoot, followLinks);\n\n  return {\n    path: filePath,\n    relativePath,\n    frontmatter: normalizeFrontmatter(data as Record<string, unknown>),\n    body: content,\n    links,\n  };\n}\n\nexport async function parseBundle(rootDir: string, options: ParseOptions = {}): Promise<OKFBundle> {\n  const absoluteRoot = path.resolve(rootDir);\n  const ignorePatterns = options.ignore ?? [];\n\n  const filePaths = await fg(\"**/*.md\", {\n    cwd: absoluteRoot,\n    absolute: true,\n    ignore: ignorePatterns,\n  });\n\n  const documents = await Promise.all(\n    filePaths.map((fp) => parseDocument(fp, absoluteRoot, options)),\n  );\n\n  const index = new Map<string, OKFDocument>();\n  for (const doc of documents) {\n    index.set(doc.relativePath, doc);\n  }\n\n  return { root: absoluteRoot, documents, index };\n}\n","import { z } from \"zod\";\nimport type {\n  OKFBundle,\n  OKFDocument,\n  OKFValidationResult,\n  OKFValidationError,\n  OKFValidationWarning,\n} from \"./types.js\";\n\nconst frontmatterSchema = z\n  .object({\n    type: z.string().min(1, \"type field must be a non-empty string\"),\n    title: z.string().optional(),\n    description: z.string().optional(),\n    resource: z.string().url(\"resource must be a valid URL\").optional(),\n    tags: z.array(z.string()).optional(),\n    timestamp: z.string().datetime({ offset: true }).optional(),\n  })\n  .passthrough();\n\nexport function validateDocument(doc: OKFDocument): {\n  errors: OKFValidationError[];\n  warnings: OKFValidationWarning[];\n} {\n  const errors: OKFValidationError[] = [];\n  const warnings: OKFValidationWarning[] = [];\n\n  const result = frontmatterSchema.safeParse(doc.frontmatter);\n  if (!result.success) {\n    for (const issue of result.error.issues) {\n      errors.push({\n        path: doc.relativePath,\n        message: issue.message,\n        rule: \"frontmatter-schema\",\n      });\n    }\n  }\n\n  if (!doc.body.trim()) {\n    warnings.push({\n      path: doc.relativePath,\n      message: \"Document body is empty\",\n      rule: \"empty-body\",\n    });\n  }\n\n  if (doc.frontmatter.timestamp) {\n    const d = Date.parse(doc.frontmatter.timestamp);\n    if (isNaN(d)) {\n      errors.push({\n        path: doc.relativePath,\n        message: `timestamp \"${doc.frontmatter.timestamp}\" is not a valid ISO 8601 date`,\n        rule: \"timestamp-format\",\n      });\n    }\n  }\n\n  return { errors, warnings };\n}\n\nexport function validateBundle(bundle: OKFBundle): OKFValidationResult {\n  const allErrors: OKFValidationError[] = [];\n  const allWarnings: OKFValidationWarning[] = [];\n\n  for (const doc of bundle.documents) {\n    const { errors, warnings } = validateDocument(doc);\n    allErrors.push(...errors);\n    allWarnings.push(...warnings);\n  }\n\n  for (const doc of bundle.documents) {\n    for (const link of doc.links) {\n      if (link.resolvedPath && !bundle.index.has(link.resolvedPath)) {\n        allWarnings.push({\n          path: doc.relativePath,\n          message: `Cross-link \"${link.href}\" does not resolve to a known concept in this bundle`,\n          rule: \"unresolved-cross-link\",\n        });\n      }\n    }\n  }\n\n  return {\n    valid: allErrors.length === 0,\n    errors: allErrors,\n    warnings: allWarnings,\n  };\n}\n","import path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport matter from \"gray-matter\";\nimport type { OKFFrontmatter, WriteOptions } from \"./types.js\";\n\nexport function serializeDocument(frontmatter: OKFFrontmatter, body: string): string {\n  return matter.stringify(body, frontmatter as Record<string, unknown>);\n}\n\nexport async function writeDocument(\n  outputPath: string,\n  frontmatter: OKFFrontmatter,\n  body: string,\n  options: WriteOptions = {},\n): Promise<void> {\n  const { overwrite = false } = options;\n\n  let exists = false;\n  try {\n    await fs.access(outputPath);\n    exists = true;\n  } catch {\n    exists = false;\n  }\n\n  if (exists && !overwrite) {\n    throw new Error(`File already exists: ${outputPath}. Pass overwrite: true to replace it.`);\n  }\n\n  await fs.mkdir(path.dirname(outputPath), { recursive: true });\n  const content = serializeDocument(frontmatter, body);\n  await fs.writeFile(outputPath, content, \"utf-8\");\n}\n\nexport async function writeIndex(\n  dirPath: string,\n  title: string,\n  description: string,\n  options: WriteOptions = {},\n): Promise<void> {\n  const indexPath = path.join(dirPath, \"index.md\");\n  await writeDocument(\n    indexPath,\n    { type: \"index\", title, description },\n    `# ${title}\\n\\n${description}\\n`,\n    options,\n  );\n}\n","import type { OKFBundle, OKFGraph, OKFNode, OKFEdge } from \"./types.js\";\n\nexport function buildGraph(bundle: OKFBundle): OKFGraph {\n  const nodes = new Map<string, OKFNode>();\n  const edges: OKFEdge[] = [];\n\n  for (const doc of bundle.documents) {\n    nodes.set(doc.relativePath, {\n      document: doc,\n      outgoing: [],\n      incoming: [],\n    });\n  }\n\n  for (const doc of bundle.documents) {\n    const fromNode = nodes.get(doc.relativePath)!;\n\n    for (const link of doc.links) {\n      if (!link.resolvedPath) continue;\n      const toNode = nodes.get(link.resolvedPath);\n      if (!toNode) continue;\n\n      const edge: OKFEdge = {\n        from: doc,\n        to: toNode.document,\n        linkText: link.text,\n      };\n\n      edges.push(edge);\n      fromNode.outgoing.push(edge);\n      toNode.incoming.push(edge);\n    }\n  }\n\n  return { nodes, edges };\n}\n\nexport function reachableFrom(graph: OKFGraph, startRelativePath: string): string[] {\n  const visited = new Set<string>();\n  const queue = [startRelativePath];\n\n  while (queue.length > 0) {\n    const current = queue.shift()!;\n    if (visited.has(current)) continue;\n    visited.add(current);\n\n    const node = graph.nodes.get(current);\n    if (!node) continue;\n\n    for (const edge of node.outgoing) {\n      queue.push(edge.to.relativePath);\n    }\n  }\n\n  return [...visited];\n}\n","import type { OKFBundle, OKFDocument } from \"./types.js\";\n\nexport interface OKFMemoryScope {\n  userId?: string;\n  agentId?: string;\n  sessionId?: string;\n}\n\nexport interface OKFMemory {\n  addFacts: (facts: string[], scope: OKFMemoryScope) => Promise<unknown[]>;\n}\n\nexport function documentToFacts(doc: OKFDocument): string[] {\n  const facts: string[] = [];\n  const fm = doc.frontmatter;\n\n  const parts: string[] = [`[${fm.type}]`];\n  if (fm.title) parts.push(fm.title);\n  if (fm.description) parts.push(\"—\", fm.description);\n  if (fm.resource) parts.push(`(resource: ${fm.resource})`);\n  if (fm.tags?.length) parts.push(`tags: ${fm.tags.join(\", \")}`);\n\n  facts.push(parts.join(\" \"));\n\n  const body = doc.body.trim();\n  if (body) {\n    facts.push(`${fm.title ?? doc.relativePath} details: ${body}`);\n  }\n\n  return facts;\n}\n\nexport function bundleToFacts(bundle: OKFBundle): string[] {\n  return bundle.documents.flatMap(documentToFacts);\n}\n\nexport async function addFromBundle(\n  memory: OKFMemory,\n  bundle: OKFBundle,\n  scope: OKFMemoryScope = {},\n): Promise<unknown[]> {\n  const facts = bundleToFacts(bundle);\n  if (facts.length === 0) return [];\n  return memory.addFacts(facts, scope);\n}\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@turbomem/okf",
+  "version": "0.2.0",
+  "description": "Open Knowledge Format (OKF) parser, validator, and writer for Node.js",
+  "homepage": "https://turbomem.dev",
+  "license": "Apache-2.0",
+  "author": "arneesh aima",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/turbomem/turbomem.git",
+    "directory": "packages/okf"
+  },
+  "keywords": [
+    "okf",
+    "open-knowledge-format",
+    "knowledge",
+    "markdown",
+    "agent",
+    "turbomem"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "okf": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "remark": "^15.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.22.0"
+  },
+  "peerDependencies": {
+    "turbomem": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "turbomem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "turbomem": "0.7.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit"
+  },
+  "readme": "# @turbomem/okf\n\n[![npm version](https://img.shields.io/npm/v/@turbomem/okf)](https://www.npmjs.com/package/@turbomem/okf) · [Documentation](https://turbomem.dev/adapters/okf)\n\nOpen Knowledge Format (OKF) v0.1 parser, validator, writer, and concept graph for Node.js. Optionally seed [turbomem](https://www.npmjs.com/package/turbomem) agent memory from OKF bundles.\n\n## Install\n\n```bash\nnpm install @turbomem/okf\n```\n\nFor turbomem integration, also install `turbomem`:\n\n```bash\nnpm install @turbomem/okf turbomem\n```\n\n## Standalone usage\n\n```ts\nimport { parseBundle, validateBundle, buildGraph } from \"@turbomem/okf\";\n\nconst bundle = await parseBundle(\"./knowledge\");\nconst result = validateBundle(bundle);\nconst graph = buildGraph(bundle);\n```\n\n## CLI\n\n```bash\nnpx okf validate ./knowledge\nnpx okf parse ./knowledge\n```\n\n## turbomem integration\n\n```ts\nimport { TurboMemory } from \"turbomem\";\nimport { parseBundle, addFromBundle } from \"@turbomem/okf\";\n\nconst memory = new TurboMemory({\n  embeddings: \"openai\",\n  storage: \"pglite\",\n  extraction: { provider: \"openai\", model: \"gpt-4.1-mini\" },\n  openai: { apiKey: process.env.OPENAI_API_KEY },\n});\n\nawait memory.init();\n\nconst bundle = await parseBundle(\"./knowledge\");\nawait addFromBundle(memory, bundle, { userId: \"agent_1\" });\n\nconst results = await memory.search(\"How do I compute weekly active users?\", {\n  userId: \"agent_1\",\n  limit: 5,\n});\n```\n\n## Documentation\n\n**https://turbomem.dev/adapters/okf**\n\n## License\n\nApache License 2.0\n"
+}