ruvnet--ruflo/v3/plugins/hyperbolic-reasoning

@claude-flow/plugin-hyperbolic-reasoning

An exotic reasoning plugin implementing hyperbolic neural networks for superior hierarchical understanding. The plugin enables efficient representation of tree structures, taxonomic reasoning, and hierarchical entailment using Poincare ball embeddings with Mobius operations. Applications include improved ontology navigation, hierarchical code understanding, and organizational relationship modeling.

Installation

npm

npm install @claude-flow/plugin-hyperbolic-reasoning

CLI

npx claude-flow plugins install --name @claude-flow/plugin-hyperbolic-reasoning

Quick Start

import { HyperbolicReasoningPlugin } from '@claude-flow/plugin-hyperbolic-reasoning';

// Initialize the plugin
const plugin = new HyperbolicReasoningPlugin();
await plugin.initialize();

// Embed a file system hierarchy in hyperbolic space
const embedding = await plugin.embedHierarchy({
  hierarchy: {
    nodes: [
      { id: 'src', parent: null, features: { type: 'directory' } },
      { id: 'src/components', parent: 'src', features: { type: 'directory' } },
      { id: 'src/components/Button.tsx', parent: 'src/components', features: { type: 'file' } },
      { id: 'src/components/Modal.tsx', parent: 'src/components', features: { type: 'file' } },
      { id: 'src/utils', parent: 'src', features: { type: 'directory' } }
    ]
  },
  model: 'poincare_ball',
  parameters: {
    dimensions: 32,
    curvature: -1.0,
    learnCurvature: true
  }
});

console.log('Hierarchy embedded in hyperbolic space');

Available MCP Tools

1. hyperbolic/embed-hierarchy

Embed hierarchical data in hyperbolic space (Poincare ball).

const result = await mcp.call('hyperbolic/embed-hierarchy', {
  hierarchy: {
    nodes: [
      { id: 'Animal', parent: null, features: {} },
      { id: 'Mammal', parent: 'Animal', features: {} },
      { id: 'Dog', parent: 'Mammal', features: {} },
      { id: 'Cat', parent: 'Mammal', features: {} },
      { id: 'Bird', parent: 'Animal', features: {} }
    ],
    edges: []
  },
  model: 'poincare_ball',
  parameters: {
    dimensions: 32,
    curvature: -1.0,
    learnCurvature: true
  }
});

Models: poincare_ball, lorentz, klein, half_plane

Returns: Hyperbolic embeddings with learned curvature and embedding quality metrics.

2. hyperbolic/taxonomic-reason

Perform taxonomic reasoning using hyperbolic entailment.

const result = await mcp.call('hyperbolic/taxonomic-reason', {
  query: {
    type: 'is_a',
    subject: 'Dog',
    object: 'Mammal'
  },
  taxonomy: 'animal-taxonomy',
  inference: {
    transitive: true,
    fuzzy: false,
    confidence: 0.8
  }
});

Query Types: is_a, subsumption, lowest_common_ancestor, path, similarity

Returns: Reasoning result with confidence score and inference path.

3. hyperbolic/semantic-search

Hierarchically-aware semantic search in hyperbolic space.

const result = await mcp.call('hyperbolic/semantic-search', {
  query: 'authentication middleware',
  index: 'codebase-hierarchy',
  searchMode: 'subtree',
  constraints: {
    maxDepth: 5,
    minDepth: 0,
    subtreeRoot: 'src/middleware'
  },
  topK: 10
});

Search Modes: nearest, subtree, ancestors, siblings, cone

Returns: Ranked results with hierarchical context and similarity scores.

4. hyperbolic/hierarchy-compare

Compare hierarchical structures using hyperbolic alignment.

const result = await mcp.call('hyperbolic/hierarchy-compare', {
  source: sourceHierarchy,
  target: targetHierarchy,
  alignment: 'gromov_wasserstein',
  metrics: ['structural_similarity', 'semantic_similarity', 'coverage']
});

Alignments: wasserstein, gromov_wasserstein, tree_edit, subtree_isomorphism

Returns: Alignment mapping with similarity metrics and structural correspondences.

5. hyperbolic/entailment-graph

Build and query entailment graphs using hyperbolic embeddings.

const result = await mcp.call('hyperbolic/entailment-graph', {
  action: 'build',
  concepts: [
    { id: 'error', text: 'An error occurred', type: 'event' },
    { id: 'network_error', text: 'Network connection failed', type: 'event' },
    { id: 'timeout', text: 'Request timed out', type: 'event' }
  ],
  entailmentThreshold: 0.7,
  transitiveClosure: true,
  pruneStrategy: 'transitive_reduction'
});

Actions: build, query, expand, prune

Returns: Entailment graph with directed edges indicating semantic entailment relationships.

Configuration Options

interface HyperbolicReasoningConfig {
  // Maximum nodes in hierarchy (default: 1000000)
  maxNodes: number;

  // Maximum edges (default: 10000000)
  maxEdges: number;

  // Embedding dimensions (default: 32)
  dimensions: number;

  // Default curvature (default: -1.0)
  curvature: number;

  // Memory limit in bytes (default: 2GB)
  memoryLimit: number;

  // CPU time limit for embedding (default: 300s)
  embeddingTimeout: number;

  // Numerical stability epsilon (default: 1e-10)
  boundaryEpsilon: number;
}

Hyperbolic Geometry Benefits

Property	Euclidean	Hyperbolic
Tree capacity	O(n^d)	O(exp(d))
Hierarchy distortion	High	Low
Dimensions needed	Many	Few
Parent-child relationship	No natural representation	Radial distance
Sibling relationship	No natural representation	Angular distance

Dimension Efficiency: 32-dim hyperbolic embeddings match the quality of 512-dim Euclidean embeddings for hierarchical data (16x memory reduction).

Performance Targets

Metric	Target	Improvement vs Euclidean
Embedding (10K nodes)	<10s	3x faster
Hyperbolic search (1M embeddings)	<5ms	10x faster
Taxonomic query	<10ms	10x faster than graph traversal
Hierarchy comparison (10K nodes)	<1s	30x faster than tree edit distance
Entailment graph (100K concepts)	<30s	20x faster than pairwise
Memory efficiency	32-dim	16x less than 512-dim Euclidean

Security Considerations

• Numerical Stability: Vectors are clipped to stay within Poincare ball boundary (1 - epsilon)
• Input Validation: All inputs validated with Zod schemas; hierarchies validated for cycles, excessive depth (max 100), and excessive branching
• Output Validation: All hyperbolic outputs validated for numerical sanity (finite values, within ball)
• DoS Prevention: Limits on node count (1M), edge count (10M), and embedding timeout (300s)
• Curvature Bounds: Curvature restricted to range [-10, -0.01] to prevent numerical issues
• Cycle Detection: DAG validation prevents infinite loops in hierarchy traversal

WASM Security Constraints

Constraint	Value	Rationale
Memory Limit	2GB max	Handle large hierarchies
CPU Time Limit	300 seconds	Allow complex embedding operations
No Network Access	Enforced	Prevent data exfiltration
Numerical Epsilon	1e-10	Prevent boundary violations
Output Validation	All vectors checked	Ensure numerical stability

Input Limits

Constraint	Limit
Max nodes	1,000,000
Max edges	10,000,000
Max dimensions	512
Max hierarchy depth	100
Max branching factor	10,000
CPU time for embedding	300 seconds
Memory limit	2GB

Rate Limits

Tool	Requests/Minute	Max Concurrent
embed-hierarchy	5	1
taxonomic-reason	60	5
semantic-search	60	5
hierarchy-compare	10	2
entailment-graph	10	2

Dependencies

• ruvector-hyperbolic-hnsw-wasm - Hyperbolic nearest neighbor search
• ruvector-attention-wasm - Hyperbolic attention mechanisms
• ruvector-gnn-wasm - Hyperbolic graph neural networks
• micro-hnsw-wasm - Tangent space approximation search
• sona - Adaptive curvature learning

Mobius Operations

The plugin implements core Mobius operations for the Poincare ball:

// Mobius addition: x + y in hyperbolic space
mobius_add(x: Vector, y: Vector, c: number): Vector

// Mobius scalar multiplication
mobius_scalar(r: number, x: Vector, c: number): Vector

// Exponential map: tangent space -> hyperbolic
exp_map(v: Vector, c: number): Vector

// Logarithmic map: hyperbolic -> tangent space
log_map(x: Vector, c: number): Vector

// Hyperbolic distance
hyperbolic_distance(x: Vector, y: Vector, c: number): number

Curvature Learning

The plugin supports learning optimal curvature per hierarchy:

Hierarchy Type	Typical Curvature
Flat hierarchy (organization chart)	Low curvature (-0.1)
Deep hierarchy (taxonomy)	High curvature (-2.0)
Mixed hierarchy	Adaptive via SONA

Use Cases

1. Ontology Navigation: Efficiently traverse and query large knowledge graphs
2. Code Hierarchy Understanding: Model inheritance, module structure, and dependencies
3. Organizational Analysis: Understand reporting structures and influence networks
4. Taxonomic Classification: Improved classification with hierarchical awareness
5. Concept Entailment: Determine semantic relationships between concepts

Related Plugins

Plugin	Description	Synergy
@claude-flow/plugin-neural-coordination	Multi-agent coordination	Hierarchical embeddings enable efficient agent organization structures
@claude-flow/plugin-cognitive-kernel	Cognitive augmentation	Hyperbolic memory organization for improved episodic retrieval
@claude-flow/plugin-quantum-optimizer	Quantum-inspired optimization	Optimizes hierarchical constraint satisfaction and tree operations

License

MIT