pi-harness-runtime 1.1.0 → 1.1.2

package/packages/knowledge-graph/src/graph-extractor.ts

@@ -0,0 +1,338 @@
+/**
+ * Knowledge Graph - RFC-0106
+ *
+ * Extract nodes and edges from SKILL.md files.
+ */
+
+import type { KnowledgeNode, KnowledgeEdge, KnowledgeGraph, ProvenanceData } from './types.js';
+
+// Parse frontmatter manually (simplified - full OKF parser in okf-indexer)
+interface OKFDocument {
+  title?: string;
+  sections: { title?: string; content: string }[];
+}
+
+interface SKILLSection {
+  title?: string;
+  content: string;
+}
+
+function parseSKILL(content: string): OKFDocument {
+  const sections: OKFDocument['sections'] = [];
+  const lines = content.split('\n');
+  let currentSection: SKILLSection = { content: '' };
+  let inFrontmatter = false;
+
+  for (const line of lines) {
+    if (line.trim() === '---') {
+      inFrontmatter = !inFrontmatter;
+      continue;
+    }
+    if (inFrontmatter) continue;
+
+    if (line.startsWith('## ')) {
+      if (currentSection.content) {
+        sections.push(currentSection);
+      }
+      currentSection = { title: line.slice(3), content: '' };
+    } else {
+      currentSection.content += (currentSection.content ? '\n' : '') + line;
+    }
+  }
+  if (currentSection.content) {
+    sections.push(currentSection);
+  }
+
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  return { title: titleMatch?.[1], sections };
+}
+
+/**
+ * Extract RFC references from content
+ */
+function extractRFCRefs(content: string): string[] {
+  const rfcPattern = /RFC[- ]?(\d{4})/gi;
+  const matches = content.match(rfcPattern) || [];
+  return [...new Set(matches.map(m => {
+    const num = m.replace(/[^0-9]/g, '');
+    return `RFC-${num.padStart(4, '0')}`;
+  }))];
+}
+
+/**
+ * Extract wiki links from content (e.g., [[skill:xxx]])
+ */
+function extractWikiLinks(content: string): string[] {
+  const linkPattern = /\[\[([^\]]+)\]\]/g;
+  const matches = content.match(linkPattern) || [];
+  return matches.map(m => m.slice(2, -2).trim());
+}
+
+/**
+ * Extract skill ID from file path
+ */
+function extractSkillId(filePath: string): string {
+  // Path: .../skills/{skill-id}/SKILL.md
+  const match = filePath.match(/skills\/([^/]+)\/SKILL\.md$/i);
+  return match ? match[1] : filePath.split('/').pop()?.replace('.md', '') || 'unknown';
+}
+
+/**
+ * Parse provenance from frontmatter
+ */
+function parseProvenance(frontmatter: Record<string, unknown>): ProvenanceData {
+  return {
+    implements: frontmatter.provenance as string || undefined,
+    related_implementation: frontmatter.related_implementation as string || undefined,
+    author: frontmatter.author as string || undefined,
+    version: frontmatter.version as string || undefined,
+  };
+}
+
+/**
+ * Extract a knowledge node from a SKILL.md file
+ */
+export function extractSkillNode(
+  filePath: string,
+  content: string,
+  frontmatter: Record<string, unknown>
+): KnowledgeNode {
+  const skillId = extractSkillId(filePath);
+  const provenance = parseProvenance(frontmatter);
+  const okf = parseSKILL(content);
+
+  return {
+    id: `skill:${skillId}`,
+    type: 'skill',
+    data: {
+      title: frontmatter.title as string || okf.title || skillId,
+      description: okf.sections[0]?.content.slice(0, 200) || undefined,
+      tags: frontmatter.tags as string[] || [],
+      source: filePath,
+    },
+  };
+}
+
+/**
+ * Extract edges from a SKILL.md file
+ */
+export function extractSkillEdges(
+  filePath: string,
+  content: string,
+  frontmatter: Record<string, unknown>
+): KnowledgeEdge[] {
+  const skillId = extractSkillId(filePath);
+  const provenance = parseProvenance(frontmatter);
+  const edges: KnowledgeEdge[] = [];
+
+  // Provenance: implements RFC
+  if (provenance.implements) {
+    const rfcNum = provenance.implements.replace(/RFC[- ]?/i, '').padStart(4, '0');
+    edges.push({
+      from: `skill:${skillId}`,
+      to: `rfc:RFC-${rfcNum}`,
+      type: 'implements',
+      metadata: { source: 'frontmatter:provenance.implements' },
+    });
+  }
+
+  // Provenance: documents implementation
+  if (provenance.related_implementation) {
+    edges.push({
+      from: `skill:${skillId}`,
+      to: `implementation:${provenance.related_implementation}`,
+      type: 'documents',
+      metadata: { source: 'frontmatter:related_implementation' },
+    });
+  }
+
+  // Content: RFC references
+  const rfcRefs = extractRFCRefs(content);
+  for (const rfc of rfcRefs) {
+    if (rfc !== provenance.implements) { // Don't duplicate
+      edges.push({
+        from: `skill:${skillId}`,
+        to: rfc,
+        type: 'references',
+        metadata: { source: 'content:regex' },
+      });
+    }
+  }
+
+  // Content: wiki links
+  const wikiLinks = extractWikiLinks(content);
+  for (const link of wikiLinks) {
+    if (link.startsWith('skill:')) {
+      edges.push({
+        from: `skill:${skillId}`,
+        to: link,
+        type: 'related_to',
+        metadata: { source: 'content:wiki-link' },
+      });
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Extract RFC nodes from RFC markdown files
+ */
+export function extractRFCNode(
+  filePath: string,
+  content: string,
+  title: string
+): KnowledgeNode {
+  // Extract RFC number from filename: RFC-0106_KNOWLEDGE_GRAPH_PROVENANCE.md
+  const match = filePath.match(/RFC[- ]?(\d{4})/i);
+  const rfcNum = match ? match[1].padStart(4, '0') : '0000';
+
+  // Extract summary from first paragraph
+  const summaryMatch = content.match(/## Summary\n+([^\n]+)/i);
+  const summary = summaryMatch ? summaryMatch[1].slice(0, 200) : undefined;
+
+  // Extract tags from content
+  const tagMatches = content.match(/tag[s]?:?\s*\[([^\]]+)\]/i);
+  const tags = tagMatches
+    ? tagMatches[1].split(',').map(t => t.trim().toLowerCase())
+    : [];
+
+  return {
+    id: `rfc:RFC-${rfcNum}`,
+    type: 'rfc',
+    data: {
+      title,
+      description: summary,
+      tags,
+      source: filePath,
+      url: `https://github.com/ManotLuijiu/pi-harness-runtime/blob/main/${filePath}`,
+    },
+  };
+}
+
+/**
+ * Extract edges between RFCs
+ */
+export function extractRFCEdges(
+  filePath: string,
+  content: string
+): KnowledgeEdge[] {
+  const edges: KnowledgeEdge[] = [];
+
+  // RFC references other RFCs
+  const rfcRefs = extractRFCRefs(content);
+  const match = filePath.match(/RFC[- ]?(\d{4})/i);
+  const rfcNum = match ? `RFC-${match[1].padStart(4, '0')}` : 'rfc:unknown';
+
+  for (const ref of rfcRefs) {
+    edges.push({
+      from: rfcNum,
+      to: ref,
+      type: 'references',
+      metadata: { source: 'content:regex' },
+    });
+  }
+
+  // Supersedes (e.g., "Supersedes RFC-0008")
+  const supersedesMatch = content.match(/supersedes\s+RFC[- ]?(\d{4})/gi);
+  if (supersedesMatch) {
+    for (const match of supersedesMatch) {
+      const numMatch = match.match(/\d{4}/);
+      if (numMatch) {
+        const superseded = `RFC-${numMatch[0].padStart(4, '0')}`;
+        edges.push({
+          from: rfcNum,
+          to: superseded,
+          type: 'supersedes',
+          metadata: { source: 'content:supersedes' },
+        });
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Build complete knowledge graph from directory
+ */
+export async function extractKnowledgeGraph(
+  skillsPath: string,
+  rfcPath: string
+): Promise<KnowledgeGraph> {
+  const { readdir, readFile } = await import('fs/promises');
+  const { join } = await import('path');
+
+  const nodes: KnowledgeNode[] = [];
+  const edges: KnowledgeEdge[] = [];
+
+  // Extract skill nodes and edges
+  try {
+    const skillDirs = await readdir(skillsPath, { withFileTypes: true });
+
+    for (const dir of skillDirs) {
+      if (!dir.isDirectory()) continue;
+
+      const skillPath = join(skillsPath, dir.name, 'SKILL.md');
+      try {
+        const content = await readFile(skillPath, 'utf-8');
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        const frontmatter: Record<string, unknown> = {};
+
+        if (frontmatterMatch) {
+          for (const line of frontmatterMatch[1].split('\n')) {
+            const [key, ...valueParts] = line.split(':');
+            if (key && valueParts.length) {
+              const value = valueParts.join(':').trim();
+              // Handle arrays
+              if (value.startsWith('[')) {
+                frontmatter[key.trim()] = value
+                  .slice(1, -1)
+                  .split(',')
+                  .map(v => v.trim().replace(/['"]/g, ''));
+              } else {
+                frontmatter[key.trim()] = value.replace(/['"]/g, '');
+              }
+            }
+          }
+        }
+
+        const node = extractSkillNode(skillPath, content, frontmatter);
+        nodes.push(node);
+
+        const skillEdges = extractSkillEdges(skillPath, content, frontmatter);
+        edges.push(...skillEdges);
+      } catch {
+        // Skip files that can't be read
+      }
+    }
+  } catch {
+    // Skills directory might not exist
+  }
+
+  // Extract RFC nodes and edges
+  try {
+    const rfcFiles = await readdir(rfcPath);
+
+    for (const file of rfcFiles) {
+      if (!file.match(/^RFC[- ]?\d{4}_.*\.md$/i)) continue;
+
+      const filePath = join(rfcPath, file);
+      const content = await readFile(filePath, 'utf-8');
+
+      // Extract title from first # heading
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1].replace(/^RFC[-\d]+\s*[-–]\s*/, '') : file;
+
+      const node = extractRFCNode(filePath, content, title);
+      nodes.push(node);
+
+      const rfcEdges = extractRFCEdges(filePath, content);
+      edges.push(...rfcEdges);
+    }
+  } catch {
+    // RFC directory might not exist
+  }
+
+  return { nodes, edges };
+}

package/packages/knowledge-graph/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Knowledge Graph - RFC-0106
+ *
+ * Knowledge Graph extraction and provenance linking for SKILL.md files.
+ *
+ * @example
+ * ```typescript
+ * import { extractKnowledgeGraph, completeGraph, syncGraphToKnowledgeService } from '@pi-harness/knowledge-graph';
+ *
+ * // Extract graph from skills directory
+ * const graph = await extractKnowledgeGraph(
+ *   'frappe-bench/.claude-plugins/moocoding-skills/skills',
+ *   'pi-harness-runtime/RFC'
+ * );
+ *
+ * // Complete with provenance edges
+ * const fullGraph = completeGraph(graph);
+ *
+ * // Sync to TencentDB Knowledge Service
+ * await syncGraphToKnowledgeService(fullGraph, config);
+ * ```
+ */
+
+export * from './types.js';
+export * from './graph-extractor.js';
+export * from './provenance-linker.js';
+export * from './mcp-client.js';

package/packages/knowledge-graph/src/mcp-client.ts

@@ -0,0 +1,237 @@
+/**
+ * Knowledge Graph - RFC-0106
+ *
+ * MCP tools for knowledge graph queries.
+ */
+
+import type {
+  KnowledgeNode,
+  KnowledgeEdge,
+  KnowledgeGraph,
+  SearchOptions,
+  SearchResult,
+  TencentDBConfig,
+} from './types.js';
+
+/**
+ * Sync graph to TencentDB Knowledge Service
+ */
+export async function syncGraphToKnowledgeService(
+  graph: KnowledgeGraph,
+  config: TencentDBConfig
+): Promise<{ synced: number; errors: string[] }> {
+  const response = await fetch(`${config.knowledgeUrl}/v3/knowledge/graph/sync`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-tdai-user-key': config.userKey,
+      'x-tdai-service-id': config.serviceId,
+    },
+    body: JSON.stringify({
+      nodes: graph.nodes.map(n => ({
+        id: n.id,
+        type: n.type,
+        ...n.data,
+      })),
+      edges: graph.edges.map(e => ({
+        from: e.from,
+        to: e.to,
+        type: e.type,
+      })),
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    return { synced: 0, errors: [error] };
+  }
+
+  return { synced: graph.nodes.length, errors: [] };
+}
+
+/**
+ * Search knowledge graph
+ */
+export async function searchGraph(
+  query: string,
+  config: TencentDBConfig,
+  options: SearchOptions = {}
+): Promise<SearchResult[]> {
+  const limit = options.limit ?? 10;
+
+  const response = await fetch(`${config.knowledgeUrl}/v3/knowledge/graph/search`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-tdai-user-key': config.userKey,
+      'x-tdai-service-id': config.serviceId,
+    },
+    body: JSON.stringify({
+      query,
+      limit,
+      type: options.type,
+      tags: options.tags,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Search failed: ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    results: Array<{
+      id: string;
+      type: string;
+      title: string;
+      description?: string;
+      tags: string[];
+      score: number;
+    }>;
+  };
+
+  return data.results.map(r => ({
+    node: {
+      id: r.id,
+      type: r.type as KnowledgeNode['type'],
+      data: {
+        title: r.title,
+        description: r.description,
+        tags: r.tags,
+      },
+    },
+    score: r.score,
+  }));
+}
+
+/**
+ * Query graph by relationship type
+ */
+export async function queryRelationships(
+  config: TencentDBConfig,
+  options: {
+    type?: KnowledgeEdge['type'];
+    from?: string;
+    to?: string;
+  }
+): Promise<KnowledgeEdge[]> {
+  const response = await fetch(`${config.knowledgeUrl}/v3/knowledge/graph/query`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-tdai-user-key': config.userKey,
+      'x-tdai-service-id': config.serviceId,
+    },
+    body: JSON.stringify(options),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Query failed: ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    edges: Array<{
+      from: string;
+      to: string;
+      type: string;
+    }>;
+  };
+
+  return data.edges.map(e => ({
+    from: e.from,
+    to: e.to,
+    type: e.type as KnowledgeEdge['type'],
+  }));
+}
+
+/**
+ * Get a specific node by ID
+ */
+export async function getNode(
+  nodeId: string,
+  config: TencentDBConfig
+): Promise<KnowledgeNode | null> {
+  const response = await fetch(
+    `${config.knowledgeUrl}/v3/knowledge/graph/node/${encodeURIComponent(nodeId)}`,
+    {
+      headers: {
+        'x-tdai-user-key': config.userKey,
+        'x-tdai-service-id': config.serviceId,
+      },
+    }
+  );
+
+  if (response.status === 404) {
+    return null;
+  }
+
+  if (!response.ok) {
+    throw new Error(`Get node failed: ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    id: string;
+    type: string;
+    title: string;
+    description?: string;
+    tags: string[];
+    source?: string;
+  };
+
+  return {
+    id: data.id,
+    type: data.type as KnowledgeNode['type'],
+    data: {
+      title: data.title,
+      description: data.description,
+      tags: data.tags,
+      source: data.source,
+    },
+  };
+}
+
+/**
+ * Find skills that implement a specific RFC
+ */
+export async function findByRFC(
+  rfcId: string,
+  config: TencentDBConfig
+): Promise<KnowledgeNode[]> {
+  const edges = await queryRelationships(config, {
+    type: 'implements',
+    to: rfcId.startsWith('rfc:') ? rfcId : `rfc:${rfcId}`,
+  });
+
+  const nodes: KnowledgeNode[] = [];
+  for (const edge of edges) {
+    const node = await getNode(edge.from, config);
+    if (node) {
+      nodes.push(node);
+    }
+  }
+
+  return nodes;
+}
+
+/**
+ * Find related skills
+ */
+export async function findRelated(
+  skillId: string,
+  config: TencentDBConfig,
+  maxResults = 5
+): Promise<KnowledgeNode[]> {
+  const edges = await queryRelationships(config, {
+    type: 'related_to',
+    from: skillId.startsWith('skill:') ? skillId : `skill:${skillId}`,
+  });
+
+  const nodes: KnowledgeNode[] = [];
+  for (const edge of edges.slice(0, maxResults)) {
+    const node = await getNode(edge.to, config);
+    if (node) {
+      nodes.push(node);
+    }
+  }
+
+  return nodes;
+}

package/packages/knowledge-graph/src/provenance-linker.ts

@@ -0,0 +1,101 @@
+/**
+ * Knowledge Graph - RFC-0106
+ *
+ * Provenance linking between skills, RFCs, and implementations.
+ */
+
+import type { KnowledgeNode, KnowledgeEdge, KnowledgeGraph } from './types.js';
+
+/**
+ * Build provenance edges based on metadata
+ */
+export function buildProvenanceEdges(graph: KnowledgeGraph): KnowledgeEdge[] {
+  const edges: KnowledgeEdge[] = [];
+  const nodeMap = new Map(graph.nodes.map(n => [n.id, n]));
+
+  for (const node of graph.nodes) {
+    if (node.type === 'skill' && node.data.tags.includes('implements')) {
+      // Link to RFCs found in tags
+      const rfcTag = node.data.tags.find(t => t.startsWith('rfc-'));
+      if (rfcTag) {
+        edges.push({
+          from: node.id,
+          to: `rfc:${rfcTag.toUpperCase()}`,
+          type: 'implements',
+          metadata: { source: 'tag:implements' },
+        });
+      }
+    }
+
+    // Implementation -> documents -> RFC
+    if (node.type === 'implementation') {
+      const rfcMatch = node.id.match(/implementation:RFC-(\d+)/i);
+      if (rfcMatch) {
+        edges.push({
+          from: node.id,
+          to: `rfc:RFC-${rfcMatch[1].padStart(4, '0')}`,
+          type: 'documents',
+          metadata: { source: 'id:parsing' },
+        });
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Infer additional edges from content analysis
+ */
+export function inferRelationships(graph: KnowledgeGraph): KnowledgeEdge[] {
+  const edges: KnowledgeEdge[] = [];
+
+  // Group skills by shared tags
+  const tagGroups = new Map<string, KnowledgeNode[]>();
+  for (const node of graph.nodes) {
+    if (node.type !== 'skill') continue;
+    for (const tag of node.data.tags) {
+      if (!tagGroups.has(tag)) {
+        tagGroups.set(tag, []);
+      }
+      tagGroups.get(tag)!.push(node);
+    }
+  }
+
+  // Skills sharing 3+ tags are related
+  for (const [, nodes] of tagGroups) {
+    if (nodes.length < 2) continue;
+
+    for (let i = 0; i < nodes.length; i++) {
+      for (let j = i + 1; j < nodes.length; j++) {
+        const sharedTags = nodes[i].data.tags.filter(t => nodes[j].data.tags.includes(t));
+        if (sharedTags.length >= 3) {
+          edges.push({
+            from: nodes[i].id,
+            to: nodes[j].id,
+            type: 'related_to',
+            metadata: {
+              source: 'inferred:shared-tags',
+              confidence: sharedTags.length / Math.max(nodes[i].data.tags.length, nodes[j].data.tags.length),
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Complete graph with all provenance links
+ */
+export function completeGraph(graph: KnowledgeGraph): KnowledgeGraph {
+  const provenanceEdges = buildProvenanceEdges(graph);
+  const inferredEdges = inferRelationships(graph);
+
+  return {
+    nodes: graph.nodes,
+    edges: [...graph.edges, ...provenanceEdges, ...inferredEdges],
+  };
+}