@claude-flow/embeddings/dist/hyperbolic-attention.d.ts

V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking

/**
 * ADR-121 Phase 3b — `@ruvector/attention`-backed Poincaré ball ops.
 *
 * Our existing `src/hyperbolic.ts` ships hand-rolled Euclidean ⇄
 * Poincaré conversions, Mobius operations, and hyperbolic distance.
 * `@ruvector/attention@2.2.2` ships the same surface as Rust-native
 * NAPI bindings — faster, more accurate (uses double precision
 * internally), and gives us free access to the attention-mechanism
 * family above (Flash Attention, Mixed Curvature, etc.) for future
 * embedding-aware retrieval layers.
 *
 * This module is the thin adapter:
 *   - When `@ruvector/attention` is installed and the native bindings
 *     load cleanly: route through the high-performance backend
 *   - When it isn't: fall back to the hand-rolled `hyperbolic.ts`
 *     functions so callers see identical semantics
 *
 * The fallback is the back-compat story for callers that don't want
 * the optional peer dep. The acceptance gate (CI smoke) asserts both
 * paths agree to within numerical tolerance on a fixed corpus.
 *
 * Discovered NAPI arg shapes (probed against @ruvector/attention@2.2.2):
 *   projectToPoincareBall(vec: Float32Array, curvature: number) → Float32Array
 *   poincareDistance(a: Float32Array, b: Float32Array, curvature: number) → number
 *   expMap(point: Float32Array, tangent: Float32Array, curvature: number) → Float32Array
 *   logMap(p1: Float32Array, p2: Float32Array, curvature: number) → Float32Array
 *   mobiusAddition(a: Float32Array, b: Float32Array, curvature: number) → Float32Array
 *
 * The curvature arg is REQUIRED — passing undefined or null throws
 * "Failed to convert napi value into rust type f64". Defaulted to 1.0
 * here (standard Poincaré ball curvature) to match the hand-rolled
 * `hyperbolic.ts` convention.
 */
import { type HyperbolicConfig } from './hyperbolic.js';
/**
 * Test seam — flush the cached module so tests can re-probe.
 * Don't call this in production code.
 */
export declare function __resetHyperbolicAttentionCache(): void;
export interface HyperbolicAttentionOptions extends HyperbolicConfig {
    /**
     * Curvature of the Poincaré ball (default 1.0). Negative values
     * model spherical geometry; positive values are hyperbolic. The
     * standard convention in hyperbolic embedding literature is c=1.
     */
    readonly curvature?: number;
}
/**
 * Project a Euclidean vector into the Poincaré ball. Uses
 * `@ruvector/attention`'s native NAPI binding when available; falls
 * back to the hand-rolled `euclideanToPoincare`.
 */
export declare function projectToPoincareBall(vec: Float32Array | number[], options?: HyperbolicAttentionOptions): Promise<Float32Array>;
/**
 * Hyperbolic distance between two points in the Poincaré ball.
 */
export declare function poincareDistance(a: Float32Array | number[], b: Float32Array | number[], options?: HyperbolicAttentionOptions): Promise<number>;
/**
 * Exponential map at `point` in the direction of `tangent`. Moves
 * along the Poincaré geodesic.
 */
export declare function expMap(point: Float32Array | number[], tangent: Float32Array | number[], options?: HyperbolicAttentionOptions): Promise<Float32Array>;
/**
 * Logarithmic map — inverse of expMap. Returns the tangent vector
 * at `p1` pointing toward `p2`.
 */
export declare function logMap(p1: Float32Array | number[], p2: Float32Array | number[], options?: HyperbolicAttentionOptions): Promise<Float32Array>;
/**
 * Mobius addition in the Poincaré ball.
 */
export declare function mobiusAddition(a: Float32Array | number[], b: Float32Array | number[], options?: HyperbolicAttentionOptions): Promise<Float32Array>;
/**
 * Detect whether the @ruvector/attention native backend is reachable.
 * Useful for ruflo doctor / observability reporting.
 */
export declare function hyperbolicAttentionAvailable(): Promise<boolean>;
//# sourceMappingURL=hyperbolic-attention.d.ts.map