Skip to content

Embedding strategy

Crader generates embeddings in a separate step using CodebaseIndexer.embed() and CodeEmbedder. The pipeline is staged and deduplicated to reduce API calls.

Pipeline summary

  1. Staging
  2. Nodes that are missing embeddings are streamed from the database.
  3. Each node is transformed into a prompt and hashed into a vector_hash.

  4. Rows are bulk loaded into the staging_embeddings table.

  5. Deduplication

  6. vector_hash is matched against existing embeddings in node_embeddings.

  7. If a match exists, the vector is copied into staging.

  8. Delta processing

  9. Remaining rows are fetched in batches.

  10. Workers call the embedding provider and write vectors back to the database.

  11. Promotion and cleanup

  12. Staged rows with embeddings are promoted into node_embeddings.
  13. Staging rows are removed.

Prompt template

CodeEmbedder embeds a structured prompt that combines file metadata and code:

[CONTEXT]
File: <file_path>
Language: <language>
Category: <category>
Role: <role tags>
Tags: <other semantic tags>
Defines: <incoming definitions>

[CODE]
<chunk content>

The vector_hash is the SHA-256 hash of this full prompt. Moving a file or changing metadata will change the hash.

Providers

Crader ships with these embedding providers:

  • OpenAIEmbeddingProvider (uses CRADER_OPENAI_API_KEY or OPENAI_API_KEY)
  • FastEmbedProvider (local embeddings via fastembed)
  • DummyEmbeddingProvider (random vectors for tests)

You can implement the EmbeddingProvider interface to integrate another provider.