ruvector/npm/packages/ruvector-extensions/docs/EXPORTERS_API.md

Graph Exporters API Reference

Complete API documentation for the ruvector-extensions graph export module.

Table of Contents

• Graph Building
• Export Functions
• Streaming Exporters
• Types and Interfaces
• Utilities

Graph Building

buildGraphFromEntries()

Build a graph from an array of vector entries by computing similarity.

function buildGraphFromEntries(
  entries: VectorEntry[],
  options?: ExportOptions
): Graph

Parameters:

• entries: VectorEntry[] - Array of vector entries with id, vector, and optional metadata
• options?: ExportOptions - Configuration options

Returns: Graph - Graph structure with nodes and edges

Example:

const entries = [
  { id: 'doc1', vector: [0.1, 0.2, 0.3], metadata: { title: 'AI' } },
  { id: 'doc2', vector: [0.15, 0.25, 0.35], metadata: { title: 'ML' } }
];

const graph = buildGraphFromEntries(entries, {
  maxNeighbors: 5,
  threshold: 0.7,
  includeMetadata: true
});

buildGraphFromVectorDB()

Build a graph directly from a VectorDB instance.

function buildGraphFromVectorDB(
  db: VectorDB,
  options?: ExportOptions
): Graph

Note: Currently throws an error as VectorDB doesn't expose a list() method. Use buildGraphFromEntries() instead with pre-fetched entries.

Export Functions

exportGraph()

Universal export function that routes to the appropriate format exporter.

function exportGraph(
  graph: Graph,
  format: ExportFormat,
  options?: ExportOptions
): ExportResult

Parameters:

• graph: Graph - Graph to export
• format: ExportFormat - Target format ('graphml' | 'gexf' | 'neo4j' | 'd3' | 'networkx')
• options?: ExportOptions - Export configuration

Returns: ExportResult - Export result with data and metadata

Example:

const result = exportGraph(graph, 'graphml', {
  graphName: 'My Network',
  includeMetadata: true
});

console.log(result.data); // GraphML XML string
console.log(result.nodeCount); // Number of nodes
console.log(result.edgeCount); // Number of edges

exportToGraphML()

Export graph to GraphML XML format.

function exportToGraphML(
  graph: Graph,
  options?: ExportOptions
): string

Returns: GraphML XML string

Features:

• XML-based format
• Supported by Gephi, yEd, NetworkX, igraph, Cytoscape
• Includes node and edge attributes
• Proper XML escaping

Example:

const graphml = exportToGraphML(graph, {
  graphName: 'Document Network',
  includeVectors: false,
  includeMetadata: true
});

await writeFile('network.graphml', graphml);

exportToGEXF()

Export graph to GEXF XML format (optimized for Gephi).

function exportToGEXF(
  graph: Graph,
  options?: ExportOptions
): string

Returns: GEXF XML string

Features:

• Designed for Gephi
• Rich metadata support
• Includes graph description and creator info
• Timestamp-based versioning

Example:

const gexf = exportToGEXF(graph, {
  graphName: 'Knowledge Graph',
  graphDescription: 'Vector similarity network',
  includeMetadata: true
});

await writeFile('network.gexf', gexf);

exportToNeo4j()

Export graph to Neo4j Cypher queries.

function exportToNeo4j(
  graph: Graph,
  options?: ExportOptions
): string

Returns: Cypher query string

Features:

• CREATE statements for nodes
• MATCH/CREATE for relationships
• Constraints and indexes
• Verification queries
• Proper Cypher escaping

Example:

const cypher = exportToNeo4j(graph, {
  includeVectors: true,
  includeMetadata: true
});

// Execute in Neo4j
await neo4jSession.run(cypher);

exportToNeo4jJSON()

Export graph to Neo4j JSON import format.

function exportToNeo4jJSON(
  graph: Graph,
  options?: ExportOptions
): { nodes: any[]; relationships: any[] }

Returns: Object with nodes and relationships arrays

Example:

const neoData = exportToNeo4jJSON(graph);
await writeFile('neo4j-import.json', JSON.stringify(neoData));

exportToD3()

Export graph to D3.js JSON format.

function exportToD3(
  graph: Graph,
  options?: ExportOptions
): { nodes: any[]; links: any[] }

Returns: Object with nodes and links arrays

Features:

• Compatible with D3.js force simulation
• Node attributes preserved
• Link weights as values
• Ready for web visualization

Example:

const d3Data = exportToD3(graph, {
  includeMetadata: true
});

// Use in D3.js
const simulation = d3.forceSimulation(d3Data.nodes)
  .force("link", d3.forceLink(d3Data.links).id(d => d.id));

exportToD3Hierarchy()

Export graph to D3.js hierarchy format for tree layouts.

function exportToD3Hierarchy(
  graph: Graph,
  rootId: string,
  options?: ExportOptions
): any

Parameters:

• rootId: string - ID of the root node

Returns: Hierarchical JSON object

Example:

const hierarchy = exportToD3Hierarchy(graph, 'root-node', {
  includeMetadata: true
});

// Use with D3 tree layout
const root = d3.hierarchy(hierarchy);
const treeLayout = d3.tree()(root);

exportToNetworkX()

Export graph to NetworkX node-link JSON format.

function exportToNetworkX(
  graph: Graph,
  options?: ExportOptions
): any

Returns: NetworkX-compatible JSON object

Features:

• Node-link format
• Directed graph support
• Full metadata preservation
• Compatible with nx.node_link_graph()

Example:

const nxData = exportToNetworkX(graph);
await writeFile('graph.json', JSON.stringify(nxData));

Python usage:

import networkx as nx
import json

with open('graph.json') as f:
    data = json.load(f)

G = nx.node_link_graph(data)

exportToNetworkXEdgeList()

Export graph to NetworkX edge list format.

function exportToNetworkXEdgeList(graph: Graph): string

Returns: Edge list string (one edge per line)

Format: source target weight

Example:

const edgeList = exportToNetworkXEdgeList(graph);
await writeFile('edges.txt', edgeList);

exportToNetworkXAdjacencyList()

Export graph to NetworkX adjacency list format.

function exportToNetworkXAdjacencyList(graph: Graph): string

Returns: Adjacency list string

Format: source target1:weight1 target2:weight2 ...

Example:

const adjList = exportToNetworkXAdjacencyList(graph);
await writeFile('adjacency.txt', adjList);

Streaming Exporters

For large graphs that don't fit in memory, use streaming exporters.

GraphMLStreamExporter

Stream large graphs to GraphML format.

class GraphMLStreamExporter extends StreamingExporter {
  constructor(stream: Writable, options?: ExportOptions)

  async start(): Promise<void>
  async addNode(node: GraphNode): Promise<void>
  async addEdge(edge: GraphEdge): Promise<void>
  async end(): Promise<void>
}

Example:

import { createWriteStream } from 'fs';

const stream = createWriteStream('large-graph.graphml');
const exporter = new GraphMLStreamExporter(stream, {
  graphName: 'Large Network'
});

await exporter.start();

// Add nodes
for (const node of nodes) {
  await exporter.addNode(node);
}

// Add edges
for (const edge of edges) {
  await exporter.addEdge(edge);
}

await exporter.end();
stream.close();

D3StreamExporter

Stream large graphs to D3.js JSON format.

class D3StreamExporter extends StreamingExporter {
  constructor(stream: Writable, options?: ExportOptions)

  async start(): Promise<void>
  async addNode(node: GraphNode): Promise<void>
  async addEdge(edge: GraphEdge): Promise<void>
  async end(): Promise<void>
}

Example:

const stream = createWriteStream('large-d3-graph.json');
const exporter = new D3StreamExporter(stream);

await exporter.start();

for (const node of nodeGenerator()) {
  await exporter.addNode(node);
}

for (const edge of edgeGenerator()) {
  await exporter.addEdge(edge);
}

await exporter.end();

streamToGraphML()

Helper function for streaming GraphML export.

async function streamToGraphML(
  graph: Graph,
  stream: Writable,
  options?: ExportOptions
): Promise<void>

Types and Interfaces

Graph

Complete graph structure.

interface Graph {
  nodes: GraphNode[];
  edges: GraphEdge[];
  metadata?: Record<string, any>;
}

GraphNode

Graph node representing a vector entry.

interface GraphNode {
  id: string;
  label?: string;
  vector?: number[];
  attributes?: Record<string, any>;
}

GraphEdge

Graph edge representing similarity between nodes.

interface GraphEdge {
  source: string;
  target: string;
  weight: number;
  type?: string;
  attributes?: Record<string, any>;
}

ExportOptions

Configuration options for exports.

interface ExportOptions {
  includeVectors?: boolean;        // Include embeddings (default: false)
  includeMetadata?: boolean;       // Include attributes (default: true)
  maxNeighbors?: number;           // Max edges per node (default: 10)
  threshold?: number;              // Min similarity (default: 0.0)
  graphName?: string;              // Graph title
  graphDescription?: string;       // Graph description
  streaming?: boolean;             // Enable streaming
  attributeMapping?: Record<string, string>; // Custom mappings
}

ExportFormat

Supported export format types.

type ExportFormat = 'graphml' | 'gexf' | 'neo4j' | 'd3' | 'networkx';

ExportResult

Export result containing output and metadata.

interface ExportResult {
  format: ExportFormat;
  data: string | object;
  nodeCount: number;
  edgeCount: number;
  metadata?: Record<string, any>;
}

Utilities

validateGraph()

Validate graph structure and throw errors if invalid.

function validateGraph(graph: Graph): void

Checks:

• Nodes array exists
• Edges array exists
• All nodes have IDs
• All edges reference existing nodes
• All edges have numeric weights

Example:

try {
  validateGraph(graph);
  console.log('Graph is valid');
} catch (error) {
  console.error('Invalid graph:', error.message);
}

cosineSimilarity()

Compute cosine similarity between two vectors.

function cosineSimilarity(a: number[], b: number[]): number

Returns: Similarity score (0-1, higher is better)

Example:

const sim = cosineSimilarity([1, 0, 0], [0.9, 0.1, 0]);
console.log(sim); // ~0.995

Error Handling

All functions may throw errors:

try {
  const graph = buildGraphFromEntries(entries);
  const result = exportGraph(graph, 'graphml');
} catch (error) {
  if (error.message.includes('dimension')) {
    console.error('Vector dimension mismatch');
  } else if (error.message.includes('format')) {
    console.error('Unsupported export format');
  } else {
    console.error('Export failed:', error);
  }
}

Performance Notes

• Memory: Streaming exporters use constant memory
• Speed: Binary formats faster than XML
• Threshold: Higher thresholds = fewer edges = faster exports
• maxNeighbors: Limiting neighbors reduces graph size
• Batch Processing: Process large datasets in chunks

Browser Support

The module is designed for Node.js. For browser use:

1. Use bundlers (webpack, Rollup)
2. Polyfill Node.js streams
3. Use web-friendly formats (D3.js JSON)

Version Compatibility

• Node.js ≥ 18.0.0
• TypeScript ≥ 5.0
• ruvector ≥ 0.1.0

License

MIT - See LICENSE file for details