# How Embeddings Are Generated and Utilized for Semantic Search Ranking in GitNexus

> Discover how GitNexus generates 384-dimensional embeddings with snowflake arctic embed xs and utilizes KuzuDB for semantic search ranking. Learn about hybrid ranking combining semantic and BM25 search.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: internals
- Published: 2026-03-08

---

**GitNexus generates 384-dimensional embeddings using the snowflake-arctic-embed-xs transformer model, stores them in a KuzuDB vector index with cosine similarity, and combines semantic results with BM25 keyword search via Reciprocal Rank Fusion for hybrid ranking.**

GitNexus is an open-source semantic code search engine that transforms repository contents into searchable vector representations. Understanding how embeddings are generated and utilized for semantic search ranking in GitNexus reveals a sophisticated pipeline that bridges transformer-based NLP with graph database vector indices.

## Embedding Generation Pipeline

The embedding generation process follows a six-stage pipeline orchestrated by `runEmbeddingPipeline()` in [`src/core/embeddings/embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedding-pipeline.ts). This pipeline converts raw source code into indexed vector representations ready for similarity search.

### Model Initialization and Hardware Acceleration

The `initEmbedder()` function in [`src/core/embeddings/embedder.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedder.ts) (lines 17-85) bootstraps the transformer pipeline as a singleton instance. It automatically probes for hardware acceleration, preferring CUDA on Linux and DirectML on Windows, with automatic fallback to CPU or WASM execution. The system loads the `snowflake-arctic-embed-xs` model, which produces dense 384-dimensional vectors optimized for code similarity tasks.

### Node Discovery and Text Extraction

The `queryEmbeddableNodes()` function (lines 31-73 in [`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts)) traverses the graph database to identify all nodes labeled as embeddable—typically files, functions, classes, and methods. For each node, it extracts the `id`, `name`, `label`, `filePath`, and `content` fields, along with line number boundaries (`startLine` and `endLine`) for precise code element localization.

### Batch Encoding and Vector Storage

Text preparation occurs through `generateBatchEmbeddingTexts()`, which concatenates relevant node metadata into a single textual representation per node. The `embedBatch(texts)` method (lines 36-61 in [`embedder.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedder.ts)) then processes these texts through the transformer pipeline in batches, returning an array of `Float32Array` vectors.

The `batchInsertEmbeddings()` function (lines 90-101 in [`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts)) persists these vectors to the dedicated `CodeEmbedding` table in KuzuDB. This separation of concerns—storing vectors in a lightweight auxiliary table rather than updating original code tables—ensures efficient bulk operations without disrupting the primary graph structure.

### Vector Index Creation with Cosine Similarity

Finally, `createVectorIndex()` (lines 107-113 in [`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts)) issues a KuzuDB command to build a vector index on the `embedding` column using cosine distance metrics. This index enables sub-second nearest-neighbor lookups across the entire code repository during query execution.

## Semantic Search Execution at Query Time

When users submit search queries, GitNexus executes a three-phase retrieval process that transforms natural language into ranked code results.

### Query Encoding and Vector Index Lookup

The `semanticSearch()` function (lines 97-108 in [`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts)) first verifies model readiness via `isEmbedderReady()`, then encodes the user's search string into a 384-dimensional vector using `embedText(query)`. This vector feeds into a KuzuDB vector index query (`CALL QUERY_VECTOR_INDEX …`) that returns the closest node IDs along with their cosine distances.

### Metadata Enrichment and Result Structuring

Each retrieved node ID undergoes metadata resolution (lines 40-66 in [`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts)) to fetch the original table context—whether the node represents a File, Function, Class, or Method. The system enriches the results with `name`, `filePath`, `startLine`, and `endLine` attributes, returning structured `SemanticSearchResult` objects that preserve code location precision.

## Hybrid Ranking with Reciprocal Rank Fusion

GitNexus does not rely solely on semantic similarity. Instead, it implements a hybrid search strategy that combines vector-based semantic search with traditional BM25 keyword matching.

### Combining BM25 and Semantic Results

The `hybridSearch()` function in [`src/core/search/hybrid-search.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/search/hybrid-search.ts) (lines 14-78) orchestrates the fusion process. It concurrently executes two retrieval paths: `searchFTSFromKuzu` for BM25 full-text search against the KuzuDB FTS index, and `semanticSearch` for vector similarity. Both result sets are normalized to a common format containing file identifiers and relevance scores.

### RRF Score Calculation and Final Ranking

The `mergeWithRRF()` function applies Reciprocal Rank Fusion to combine the disparate scoring systems. For each result, it calculates an RRF score using the formula `1 / (k + rank)`, where **k = 60** (the standard RRF constant). If a file appears in both the BM25 and semantic result sets, its RRF scores are summed, boosting its final position. The system sorts by the aggregated RRF score and returns the top-N results, ensuring that files matching both keyword patterns and semantic meaning surface first.

## Implementation Examples

### Initialize the Embedder

```typescript
import { initEmbedder } from '@/core/embeddings/embedder';

// Load the model (uses GPU if available)
await initEmbedder();

```

*Source*: [[`embedder.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedder.ts#L81-L89)](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedder.ts#L81-L89)

### Run the Full Embedding Pipeline

```typescript
import { runEmbeddingPipeline } from '@/core/embeddings/embedding-pipeline';
import { executeQuery, executeWithReusedStatement } from '@/storage/kuzu';

await runEmbeddingPipeline(
  executeQuery,
  executeWithReusedStatement,
  progress => console.log('Embedding progress', progress)
);

```

*Source*: [[`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts#L33-L86)](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts#L33-L86)

### Perform Pure Semantic Search

```typescript
import { semanticSearch } from '@/core/embeddings/embedding-pipeline';

const results = await semanticSearch(
  executeQuery,
  'read a file from repository',
  10,          // top-k
  0.4          // max distance threshold
);
console.log(results);

```

*Source*: [[`embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/embedding-pipeline.ts#L97-L108)](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts#L97-L108)

### Execute Hybrid Search

```typescript
import { hybridSearch } from '@/core/search/hybrid-search';
import { semanticSearch } from '@/core/embeddings/embedding-pipeline';

const results = await hybridSearch(
  'parse JSON payload',
  10,
  async cypher => await executeQuery(cypher),
  semanticSearch
);
console.log(results);

```

*Source*: [[`hybrid-search.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/hybrid-search.ts#L52-L62)](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/hybrid-search.ts#L52-L62)

## Summary

- **GitNexus** generates embeddings using the `snowflake-arctic-embed-xs` transformer model, producing 384-dimensional vectors optimized for code semantics.
- The **embedding pipeline** in [`src/core/embeddings/embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedding-pipeline.ts) orchestrates node discovery, batch encoding, and vector storage in a dedicated `CodeEmbedding` table.
- **KuzuDB** stores vectors and maintains a cosine-metric vector index for sub-second nearest-neighbor lookups during query execution.
- **Semantic search** encodes user queries on-the-fly and retrieves relevant code elements with precise file path and line number metadata.
- **Hybrid ranking** combines semantic and BM25 results using Reciprocal Rank Fusion (RRF) with k=60, ensuring files matching both keyword patterns and semantic meaning rank highest.

## Frequently Asked Questions

### What embedding model does GitNexus use?

GitNexus uses the **snowflake-arctic-embed-xs** transformer model, which generates 384-dimensional dense vectors specifically optimized for semantic similarity tasks. The model is loaded via the `@huggingface/transformers` library in [`src/core/embeddings/embedder.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedder.ts) and supports automatic hardware acceleration through CUDA on Linux or DirectML on Windows.

### How does GitNexus handle hardware acceleration for embedding generation?

The `initEmbedder()` function in [`src/core/embeddings/embedder.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedder.ts) implements a cascading hardware detection strategy. It first attempts to use CUDA for GPU acceleration on Linux systems, then falls back to DirectML for Windows environments. If neither GPU backend is available, the system automatically falls back to CPU execution or WebAssembly (WASM) runtimes, ensuring consistent embedding generation across diverse deployment environments.

### What is the difference between pure semantic search and hybrid search in GitNexus?

**Pure semantic search** uses only vector similarity to find code elements that are semantically related to the query, regardless of exact keyword matches. This is implemented in the `semanticSearch()` function in [`src/core/embeddings/embedding-pipeline.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/embeddings/embedding-pipeline.ts). **Hybrid search**, implemented in [`src/core/search/hybrid-search.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/search/hybrid-search.ts), combines these semantic results with traditional BM25 keyword search results using Reciprocal Rank Fusion (RRF). The hybrid approach ensures that files matching both the semantic intent and specific keywords receive higher rankings, providing more robust search results across different query styles.

### How does Reciprocal Rank Fusion improve search results in GitNexus?

Reciprocal Rank Fusion (RRF) addresses the fundamental incompatibility between semantic similarity scores (cosine distance) and keyword relevance scores (BM25). The `mergeWithRRF()` function in [`src/core/search/hybrid-search.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/search/hybrid-search.ts) assigns each result an RRF score calculated as `1 / (k + rank)`, where k is set to 60. When a file appears in both the semantic and keyword result sets, its RRF scores are summed, effectively boosting files that demonstrate both semantic relevance and keyword match quality. This fusion method eliminates the need to normalize disparate scoring scales while ensuring robust ranking across heterogeneous search signals.