Laurus : Lexical Augmented Unified Retrieval Using Semantics

Laurus is a search platform written in Rust — built for Lexical Augmented Unified Retrieval Using Semantics. Built on a core library covering lexical search, vector search, and hybrid search, it provides multiple ready-to-use interfaces:

• Core Library — Modular search engine embeddable into any application
• CLI & REPL — Command-line tool for interactive search experiences
• gRPC Server & HTTP Gateway — Seamless integration with microservices and existing systems
• MCP Server — Direct integration with AI assistants such as Claude
• Python Bindings — Native Python package for use in data science and AI workflows
• Node.js Bindings — Native Node.js addon for server-side JavaScript applications
• WebAssembly — Browser and edge runtime support via wasm-bindgen
• Ruby Bindings — Native Ruby gem for Rails and Ruby applications
• PHP Bindings — Native PHP extension for web applications and CLI tools

Whether embedded as a library, deployed as a standalone server, called from Python / Node.js / Ruby / PHP, run in the browser via WASM, or woven into AI workflows, Laurus is a composable search foundation.

Live Demo

Try Laurus directly in your browser — every sample runs entirely client-side via WebAssembly:

https://mosuka.github.io/laurus/demo/

Sample	What it shows
basic	Japanese full-text, vector, and hybrid search with the unified query DSL
geo	Tokyo points-of-interest on a Leaflet map with bounding-box + text + vector queries
geo3d	Live aircraft on a CesiumJS 3D globe using geo3d_bbox / geo3d_nearest (true ECEF 3D, including altitude)

Documentation

Comprehensive documentation is available online:

• English: https://mosuka.github.io/laurus/
• Japanese (日本語): https://mosuka.github.io/laurus/ja/

Contents

• Getting Started
  • Installation
  • Quick Start
  • Examples
• Core Concepts
  • Schema & Fields
  • Text Analysis
  • Embeddings
  • Storage
  • Indexing (Lexical / Vector)
  • Search (Lexical / Vector / Hybrid)
  • Query DSL
• Crate Guides
  • laurus (Library) — Engine, Scoring, Faceting, Highlighting, Spelling Correction, Persistence & WAL
  • laurus-cli — Command-line interface, REPL, Schema Format
  • laurus-server — gRPC server, HTTP Gateway, Configuration
  • laurus-mcp — MCP server for AI assistants (Claude, etc.)
  • laurus-python — Python bindings (PyPI package)
  • laurus-nodejs — Node.js bindings (npm package)
  • laurus-wasm — WebAssembly bindings (npm package)
  • laurus-ruby — Ruby bindings (RubyGems package)
  • laurus-php — PHP bindings (PHP extension)
• Development
  • Build & Test
  • Feature Flags
  • Project Structure
• API Reference (docs.rs)

Features

• Pure Rust Implementation: Memory-safe and fast performance with zero-cost abstractions.
• Hybrid Search: Seamlessly combine BM25 lexical search with HNSW vector search using configurable fusion strategies.
• Multimodal Capabilities: Native support for text-to-image and image-to-image search via CLIP embeddings.
• Rich Query DSL: Term, phrase, boolean, fuzzy, wildcard, range, 2D / 3D geographic (sphere, bounding box, k-NN), and span queries.
• Flexible Analysis: Configurable pipelines for tokenization, normalization, and stemming (including CJK support via Lindera).
• Pluggable Storage: Interfaces for in-memory, file-system, and memory-mapped storage backends.
• Dynamic Schema: Optional schema-on-write — undeclared fields are inferred from the value, with Strict / Dynamic / Ignore policies for fine-grained control.
• Multi-valued Numeric Fields: Integer and Float fields can hold multiple values per document; range queries match if any value satisfies the predicate (Lucene-style "any match" semantics).
• Scoring & Ranking: BM25 scoring with customizable fusion strategies for hybrid results.
• Faceting & Highlighting: Built-in support for faceted navigation and search result highlighting.
• Spelling Correction: Suggest corrections for misspelled query terms.

Workspace Structure

Laurus is organized as a Cargo workspace with 9 crates:

Crate	Description
laurus	Core search library — schema, analysis, indexing, search, and storage
laurus-cli	Command-line interface with REPL for interactive search
laurus-server	gRPC server with HTTP gateway for deploying Laurus as a service
laurus-mcp	MCP server for AI assistants (Claude, etc.) via stdio transport
laurus-python	Python bindings (PyPI package) built with PyO3 and Maturin
laurus-nodejs	Node.js bindings (npm package) built with NAPI-RS
laurus-wasm	WebAssembly bindings (npm package) built with wasm-bindgen
laurus-ruby	Ruby bindings (RubyGems package) built with magnus and rb-sys
laurus-php	PHP bindings (PHP extension) built with ext-php-rs

Feature Flags

The laurus crate provides optional feature flags for embedding support:

Feature	Description
embeddings-candle	Local BERT embeddings via Candle
embeddings-openai	Cloud-based embeddings via the OpenAI API
embeddings-multimodal	CLIP-based multimodal (text + image) embeddings
embeddings-all	Enable all embedding backends

Quick Start

use laurus::lexical::{TermQuery,TextOption};use laurus::storage::memory::MemoryStorageConfig;use laurus::storage::{StorageConfig,StorageFactory};use laurus::{Document,Engine,LexicalSearchRequest,Schema,SearchRequestBuilder};#[tokio::main]asyncfnmain() -> laurus::Result<()>{// 1. Create storagelet storage = StorageFactory::create(StorageConfig::Memory(MemoryStorageConfig::default()))?;// 2. Define schemalet schema = Schema::builder().add_text_field("title",TextOption::default()).add_text_field("body",TextOption::default()).build();// 3. Create enginelet engine = Engine::new(storage, schema).await?;// 4. Index documents
engine
.add_document("doc1",Document::builder().add_text("title","Introduction to Rust").add_text("body","Rust is a systems programming language focused on safety and performance.",).build(),).await?;
engine
.add_document("doc2",Document::builder().add_text("title","Python for Data Science").add_text("body","Python is a versatile language widely used in data science and machine learning.",).build(),).await?;
engine.commit().await?;// 5. Searchlet results = engine
.search(SearchRequestBuilder::new().lexical_search_request(LexicalSearchRequest::new(Box::new(TermQuery::new("body","rust",)))).limit(5).build(),).await?;for hit in&results {println!("score={:.4}", hit.score);}Ok(())}

Examples

You can find usage examples in the laurus/examples/ directory:

Example	Description	Feature Flag
quickstart	Basic full-text search	—
lexical_search	All query types (Term, Phrase, Boolean, Fuzzy, Wildcard, Range, Geo, Span)	—
vector_search	Semantic similarity search with embeddings	—
hybrid_search	Combining lexical and vector search with fusion	—
geo3d_search	3D ECEF geographic search (sphere, bounding box, k-NN)	—
synonym_graph_filter	Synonym expansion in analysis pipeline	—
search_with_candle	Local BERT embeddings via Candle	embeddings-candle
search_with_openai	Cloud-based embeddings via OpenAI	embeddings-openai
multimodal_search	Text-to-image and image-to-image search	embeddings-multimodal

Contributing

We welcome contributions!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.