@claude-flow/plugin-hyperbolic-reasoning 3.0.0-alpha.1

package/README.md

@@ -0,0 +1,318 @@
+# @claude-flow/plugin-hyperbolic-reasoning
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/plugin-hyperbolic-reasoning.svg)](https://www.npmjs.com/package/@claude-flow/plugin-hyperbolic-reasoning)
+[![license](https://img.shields.io/npm/l/@claude-flow/plugin-hyperbolic-reasoning.svg)](https://github.com/ruvnet/claude-flow/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@claude-flow/plugin-hyperbolic-reasoning.svg)](https://www.npmjs.com/package/@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
+
+```bash
+npm install @claude-flow/plugin-hyperbolic-reasoning
+```
+
+### CLI
+
+```bash
+npx claude-flow plugins install --name @claude-flow/plugin-hyperbolic-reasoning
+```
+
+## Quick Start
+
+```typescript
+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).
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+// 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](https://www.npmjs.com/package/@claude-flow/plugin-neural-coordination) | Multi-agent coordination | Hierarchical embeddings enable efficient agent organization structures |
+| [@claude-flow/plugin-cognitive-kernel](https://www.npmjs.com/package/@claude-flow/plugin-cognitive-kernel) | Cognitive augmentation | Hyperbolic memory organization for improved episodic retrieval |
+| [@claude-flow/plugin-quantum-optimizer](https://www.npmjs.com/package/@claude-flow/plugin-quantum-optimizer) | Quantum-inspired optimization | Optimizes hierarchical constraint satisfaction and tree operations |
+
+## License
+
+MIT

package/dist/bridges/gnn-bridge.d.ts

@@ -0,0 +1,127 @@
+/**
+ * GNN Bridge - Graph Neural Network Operations
+ *
+ * Bridge to @ruvector/gnn-wasm for graph-based reasoning,
+ * node classification, link prediction, and graph embeddings.
+ */
+import type { Concept, EntailmentGraph } from '../types.js';
+/**
+ * WASM module status
+ */
+export type WasmModuleStatus = 'unloaded' | 'loading' | 'ready' | 'error';
+/**
+ * GNN configuration
+ */
+export interface GnnConfig {
+    /** Input feature dimension */
+    readonly inputDim: number;
+    /** Hidden layer dimension */
+    readonly hiddenDim: number;
+    /** Output dimension */
+    readonly outputDim: number;
+    /** Number of GNN layers */
+    readonly numLayers: number;
+    /** Aggregation method */
+    readonly aggregation: 'mean' | 'sum' | 'max' | 'attention';
+    /** Dropout rate */
+    readonly dropout: number;
+}
+/**
+ * Graph structure for GNN
+ */
+export interface Graph {
+    /** Node features (each node has a feature vector) */
+    readonly nodeFeatures: Float32Array[];
+    /** Edges as [source, target] pairs */
+    readonly edges: Array<[number, number]>;
+    /** Edge weights */
+    readonly edgeWeights?: Float32Array;
+    /** Node labels (for supervised learning) */
+    readonly labels?: Uint32Array;
+}
+/**
+ * GNN inference result
+ */
+export interface GnnResult {
+    /** Node embeddings */
+    readonly nodeEmbeddings: Float32Array[];
+    /** Graph-level embedding */
+    readonly graphEmbedding: Float32Array;
+    /** Node predictions (if applicable) */
+    readonly predictions?: Float32Array[];
+    /** Attention weights (if using attention aggregation) */
+    readonly attentionWeights?: Map<string, Float32Array>;
+}
+/**
+ * Entailment prediction result
+ */
+export interface EntailmentPrediction {
+    /** Premise concept ID */
+    readonly premise: string;
+    /** Hypothesis concept ID */
+    readonly hypothesis: string;
+    /** Probability of entailment */
+    readonly entailmentProb: number;
+    /** Probability of contradiction */
+    readonly contradictionProb: number;
+    /** Probability of neutral */
+    readonly neutralProb: number;
+    /** Final relation type */
+    readonly relation: 'entails' | 'contradicts' | 'neutral';
+}
+/**
+ * Graph Neural Network Bridge
+ */
+export declare class GnnBridge {
+    readonly name = "hyperbolic-gnn-bridge";
+    readonly version = "0.1.0";
+    private _status;
+    private _module;
+    private _config;
+    constructor(config?: Partial<GnnConfig>);
+    get status(): WasmModuleStatus;
+    get initialized(): boolean;
+    /**
+     * Initialize the WASM module
+     */
+    initialize(): Promise<void>;
+    /**
+     * Dispose of resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Forward pass through GNN
+     */
+    forward(graph: Graph, config?: Partial<GnnConfig>): GnnResult;
+    /**
+     * Predict links between nodes
+     */
+    predictLinks(graph: Graph, sourceNodes: number[], targetNodes: number[]): Float32Array;
+    /**
+     * Build entailment graph from concepts using GNN
+     */
+    buildEntailmentGraph(concepts: ReadonlyArray<Concept>, threshold?: number): Promise<EntailmentGraph>;
+    /**
+     * Predict entailment between two concepts
+     */
+    predictEntailment(premiseEmb: Float32Array, hypothesisEmb: Float32Array): EntailmentPrediction;
+    /**
+     * Compute transitive closure of entailment graph
+     */
+    computeTransitiveClosure(graph: EntailmentGraph): EntailmentGraph;
+    /**
+     * Prune entailment graph using transitive reduction
+     */
+    transitiveReduction(graph: EntailmentGraph): EntailmentGraph;
+    private computeEntailmentScore;
+    private computeMaxDepth;
+    /**
+     * Create mock module for development
+     */
+    private createMockModule;
+}
+/**
+ * Create a new GnnBridge instance
+ */
+export declare function createGnnBridge(config?: Partial<GnnConfig>): GnnBridge;
+//# sourceMappingURL=gnn-bridge.d.ts.map

package/dist/bridges/gnn-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnn-bridge.d.ts","sourceRoot":"","sources":["../../src/bridges/gnn-bridge.ts"],"names":[],"mappings":"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"}