v0.1.0-alpha Pre-release

sphereQL v0.1.0-alpha

First public alpha release — project high-dimensional embeddings onto a 3D sphere for semantic search, category enrichment, and visualization.

Highlights

Spherical Math & Spatial Indexing

• Full 3D spherical coordinate system with geodesic distance, interpolation, and bounding regions
• Spatial index with nearest-neighbor and range queries over sphere surfaces
• Cap, wedge, and corridor region types for flexible geographic-style filtering

Embedding Projection

• Project arbitrary-dimension vectors onto the unit sphere via PCA and Kernel PCA (Gaussian RBF)
• Configurable SphereQLPipeline that chains embedding → projection → indexing → query in one call
• CSV and JSON export for projected results

Category Enrichment Layer (new)

• Automatic category detection with inter-category graph and bridge item identification
• Inner spheres: drill into large categories with their own local coordinate system (linear PCA or kernel PCA, chosen automatically)
• Concept path queries: find shortest semantic path between categories
• Neighbor and drill-down queries for exploring category structure

Multi-Platform Bindings

• Python (PyO3): pip install sphereql — full pipeline access including category queries
• WASM (wasm-bindgen): browser-ready JS/TS package with JSON-serialized outputs
• GraphQL (async-graphql): query server for spatial lookups over SpatialIndex

Vector Database Integration

• Pluggable VectorStore trait with Pinecone and Qdrant backends
• VectorBridge syncs pipeline results to your vector DB with category metadata

Crate Architecture

Crate	Purpose
sphereql-core	Spherical math primitives
sphereql-index	Spatial indexing and queries
sphereql-layout	Force-directed and grid layouts
sphereql-embed	PCA/Kernel PCA projection + Category Enrichment
sphereql-graphql	GraphQL query server
sphereql-vectordb	Pinecone & Qdrant connectors
sphereql	Umbrella crate with feature flags

Installation

Rust

[dependencies]
sphereql = { version = "0.1.0-alpha", features = ["embed"] }

Python

pip install sphereql

WASM

npm install sphereql-wasm  # (coming soon)

Known Limitations

• Search precision at k > 1: nearest-neighbor results beyond the first hit may include false positives on very dense datasets. Accuracy improves with sparser distributions.
• GraphQL category gap: the GraphQL crate operates on SpatialIndex directly, not the full SphereQLPipeline. Category enrichment queries are not yet exposed via GraphQL.
• Inner sphere threshold: categories need ≥ 8 items to generate an inner sphere. This threshold is not yet configurable.

Stats

• 403 tests passing across all crates
• 10 crates in the workspace
• CI: cargo fmt, cargo clippy -Dwarnings, cargo test, cargo doc — all green

What's Next

• Configurable inner sphere thresholds
• GraphQL category query support
• Streaming projection for large datasets
• Additional vector DB backends

---

Full commit history and contributor details available on GitHub.