### Run Embellama server via CLI

Source: https://github.com/darjus/embellama/blob/master/ARCHITECTURE.md

Example command to start the server with specific model and network configurations.

```bash
embellama-server --model-path /path/to/model.gguf --model-name my-model --port 8080 --workers 4
```

--------------------------------

### Run Examples

Source: https://github.com/darjus/embellama/blob/master/README.md

Command to run a specific example from the examples directory.

```bash
cargo run --example simple
```

--------------------------------

### Install Just

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Install Just, a command runner, using cargo. This tool is used for various development tasks in the project.

```bash
cargo install just
```

--------------------------------

### Clone Repository and Install Hooks

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Fork and clone the Embellama repository, then install pre-commit hooks. The hooks use uvx or pipx for isolated environments.

```bash
git clone https://github.com/yourusername/embellama.git
cd embellama

# Install the git hooks (uses uvx/pipx automatically)
just install-hooks
```

--------------------------------

### Setup tracing logging

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Imports necessary macros for structured logging.

```rust
use tracing::{debug, error, info, warn, trace};
```

--------------------------------

### Install uv or pipx

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Install uv (preferred) or pipx for isolated Python tools. This helps avoid global package pollution.

```bash
# Install uv (preferred)
curl -LsSf https://astral.sh/uv/install.sh | sh

# OR install pipx
pip install --user pipx
```

--------------------------------

### Install Rust

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Install the Rust programming language and its package manager, Cargo. Ensure you have version 1.70.0 or later.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Basic Configuration Setup

Source: https://github.com/darjus/embellama/blob/master/README.md

Shows the minimal configuration required to set up the ModelConfig and EngineConfig, specifying the model path and name.

```rust
# fn main() -> anyhow::Result<()> {
use embellama::{ModelConfig, EngineConfig};

let model_config = ModelConfig::builder()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("my-model")
    .build()?;

let config = EngineConfig::builder()
    .with_model_config(model_config)
    .build()?;
# Ok(())
# }
```

--------------------------------

### Run OpenAI-Compatible Server

Source: https://context7.com/darjus/embellama/llms.txt

Starts an HTTP server for embeddings using the server feature.

```rust
// Cargo.toml: embellama = { version = "0.10.1", features = ["server"] }

use embellama::server::{ServerConfig, run_server, EngineConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build engine configuration
    let engine_config = EngineConfig::builder()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("my-model")
        .build()?;

    // Configure server
    let config = ServerConfig::builder()
        .engine_config(engine_config)
        .host("0.0.0.0")
        .port(8080)
        .worker_count(4)
        .queue_size(100)
        .request_timeout_secs(30)
        .build()?;

    // Run server (blocks until shutdown)
    run_server(config).await?;

    Ok(())
}
```

--------------------------------

### Install CMake on macOS

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Install CMake using Homebrew on macOS.

```bash
# macOS
brew install cmake

```

--------------------------------

### Quick Start: Build and Use Embedding Engine

Source: https://github.com/darjus/embellama/blob/master/README.md

Demonstrates building model and engine configurations, creating an EmbeddingEngine, and generating single or batch embeddings. Ensure the model path is correct and the engine is initialized.

```rust
# fn main() -> anyhow::Result<()> {
use embellama::{ModelConfig, EngineConfig, EmbeddingEngine, NormalizationMode};

// Build model configuration
let model_config = ModelConfig::builder()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("my-model")
    .with_normalization_mode(NormalizationMode::L2)
    .build()?;

// Build engine configuration
let engine_config = EngineConfig::builder()
    .with_model_config(model_config)
    .build()?;

// Create engine
let engine = EmbeddingEngine::new(engine_config)?;

// Generate single embedding
let text = "Hello, world!";
let embedding = engine.embed(None, text)?;

// Generate batch embeddings
let texts = vec!["Text 1", "Text 2", "Text 3"];
let embeddings = engine.embed_batch(None, &texts)?;
# Ok(())
# }
```

--------------------------------

### Development Workflow and Commands

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Information on the development setup, testing procedures, and command-line tools available for the Embellama project.

```APIDOC
## Development Workflow

### Quick Development Loop
- `just dev`: Run fix, fmt, clippy, and unit tests.
- `just test`: Run all test suites.
- `just pre-commit`: Full validation before committing.

### Standard Workflow
1. **Planning**: Use zen:thinkdeeper for design decisions.
2. **Research**: Use Fetch/Brave for documentation lookup.
3. **Implementation**: Follow Rust best practices.
4. **Testing**:
   - Run `just test-unit` for quick feedback.
   - Run `just test-integration` for real model testing.
   - Run `just test-concurrency` for thread safety.
5. **Debugging**: Use zen:debug for complex issues.
6. **Review**: Run rust code review agent.
7. **Pre-commit**: Run `just pre-commit`.
8. **Commit**: Update changelog with git-cliff, write clear message.
9. **Document**: Update rustdoc and ARCHITECTURE.md if needed.

### Key Testing Philosophy
- **Test with real models**: No mocks for integration tests.
- **Fail loudly**: Tests should clearly indicate what's wrong.
- **Automated downloads**: Models are cached automatically via justfile.
- **Fast feedback**: Use `just dev` for rapid iteration.
```

--------------------------------

### Clone Embellama Repository

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Clone the Embellama project repository to your local machine. This is the first step to start development.

```bash
git clone https://github.com/embellama/embellama.git
cd embellama
```

--------------------------------

### Performance Profiling

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Commands to install and run flamegraph for performance analysis.

```bash
cargo install flamegraph
cargo flamegraph --bench embeddings
```

--------------------------------

### Install Build Dependencies on Ubuntu/Debian

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Install CMake and essential build tools required for compiling llama-cpp-2 on Ubuntu or Debian-based systems.

```bash
# Ubuntu/Debian
sudo apt-get install cmake build-essential

```

--------------------------------

### Write Benchmarks

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Example of defining a benchmark function using the criterion crate.

```rust
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn benchmark_embedding(c: &mut Criterion) {
    c.bench_function("single_embedding", |b| {
        b.iter(|| {
            // Code to benchmark
            generate_embedding(black_box("test input"))
        });
    });
}

criterion_group!(benches, benchmark_embedding);
criterion_main!(benches);
```

--------------------------------

### GET /v1/models

Source: https://context7.com/darjus/embellama/llms.txt

Lists all available models loaded in the server.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of models currently available on the server.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **data** (array) - List of model objects containing id, created, and context_size.

#### Response Example
{
  "object": "list",
  "data": [{
    "id": "my-model",
    "object": "model",
    "context_size": 2048
  }]
}
```

--------------------------------

### Generate changelog with git-cliff

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Commands for installing and using git-cliff to manage project changelogs.

```bash
# Install git-cliff if not present
cargo install git-cliff

# Generate/update changelog
git-cliff -o CHANGELOG.md

# For specific version/tag range
git-cliff --tag v0.1.0 -o CHANGELOG.md

# Generate unreleased changes only
git-cliff --unreleased -o CHANGELOG.md
```

--------------------------------

### Document Public Items

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Standard documentation format for public functions including arguments, returns, examples, and errors.

```rust
/// Brief description of what this does.
///
/// # Arguments
///
/// * `input` - Description of the input parameter
///
/// # Returns
///
/// Description of the return value
///
/// # Examples
///
/// ```rust
/// let result = function(input);
/// assert_eq!(result, expected);
/// ```
///
/// # Errors
///
/// Returns `Error::InvalidInput` if the input is invalid
pub fn function(input: &str) -> Result<String> {
    // Implementation
}
```

--------------------------------

### Embeddings Endpoint Usage

Source: https://context7.com/darjus/embellama/llms.txt

Examples for generating single, batch, and base64-encoded embeddings.

```bash
# Single text embedding
curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "input": "Hello, world!"
  }'

# Response:
# {
#   "object": "list",
#   "data": [{
#     "index": 0,
#     "object": "embedding",
#     "embedding": [0.123, -0.456, ...]
#   }],
#   "model": "my-model",
#   "usage": {"prompt_tokens": 4, "total_tokens": 4}
# }

# Batch embeddings
curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "input": ["First document", "Second document", "Third document"],
    "encoding_format": "float"
  }'

# Base64 encoding (more compact)
curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "input": "Hello, world!",
    "encoding_format": "base64"
  }'
```

--------------------------------

### Add Rust Components

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Add the `rustfmt` and `clippy` components to your Rust installation. These are used for code formatting and linting.

```bash
rustup component add rustfmt clippy
```

--------------------------------

### EmbeddingEngine::get_or_init - Singleton Pattern

Source: https://context7.com/darjus/embellama/llms.txt

Get or initialize a singleton instance of the embedding engine for shared access across an application.

```APIDOC
## EmbeddingEngine::get_or_init - Singleton Pattern

### Description
Get or initialize a singleton instance of the embedding engine for shared access across an application.

### Method
`POST` (Conceptual - this is a method call, not a REST endpoint)

### Endpoint
N/A (Method call on `EmbeddingEngine` struct)

### Parameters
#### Method Parameters
- **config** (EngineConfig) - Required - The configuration for the embedding engine.

### Request Example
```rust
use embellama::{EmbeddingEngine, EngineConfig};

let config = EngineConfig::builder()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("singleton-model")
    .build()?;

let engine = EmbeddingEngine::get_or_init(config)?;
```

### Response
#### Success Response (200)
- **engine** (Arc<Mutex<EmbeddingEngine>>) - A thread-safe, shared reference to the embedding engine instance.

#### Response Example
```rust
use embellama::EmbeddingEngine;

let engine_clone = EmbeddingEngine::instance().expect("Engine not initialized");
let embedding = {
    let engine_guard = engine_clone.lock().unwrap();
    engine_guard.embed(None, "text")?
};
```
```

--------------------------------

### Singleton Pattern for Shared Engine Access

Source: https://github.com/darjus/embellama/blob/master/README.md

Illustrates how to use the singleton pattern to get or initialize a shared, thread-safe EmbeddingEngine instance. Accessing the engine requires locking a mutex.

```rust
# fn main() -> anyhow::Result<()> {
# use embellama::{ModelConfig, EngineConfig, EmbeddingEngine};
# let model_config = ModelConfig::builder()
#     .with_model_path("/path/to/model.gguf")
#     .with_model_name("my-model")
#     .build()?;
# let config = EngineConfig::builder()
#     .with_model_config(model_config)
#     .build()?;
// Get or initialize singleton instance (returns Arc<Mutex<EmbeddingEngine>>)
let engine = EmbeddingEngine::get_or_init(config)?;

// Access the singleton from anywhere in your application
let engine_clone = EmbeddingEngine::instance()
    .expect("Engine not initialized");

// Use the engine (requires locking the mutex)
let embedding = {
    let engine_guard = engine.lock().unwrap();
    engine_guard.embed(None, "text")?
};
# Ok(())
# }
```

--------------------------------

### Automatic Backend Detection

Source: https://github.com/darjus/embellama/blob/master/README.md

Configure the engine to automatically detect the best available backend and specify model paths and names. This setup is useful for general embedding tasks.

```rust
# fn main() -> anyhow::Result<()> {
use embellama::{ EngineConfig, detect_best_backend, BackendInfo};

// Automatic backend detection
let config = EngineConfig::with_backend_detection()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("my-model")
    .build()?;

// Check which backend was selected
let backend_info = BackendInfo::new();
println!("Using backend: {}", backend_info.backend);
println!("Available features: {:?}", backend_info.available_features);
# Ok(())
# }
```

--------------------------------

### Bash: Checking Prefix Cache Statistics

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Example of checking the statistics of the prefix cache using a cURL command. This helps in monitoring the effectiveness and usage of the caching mechanism.

```bash
# Check prefix cache statistics
curl http://localhost:3000/v1/embeddings/prefix/stats
```

--------------------------------

### Bash: Registering a Common Code Prefix

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Example of registering a common code prefix using a cURL command. This is useful for setting up shared context for embedding generation, particularly for code snippets with repeated imports or boilerplate.

```bash
# Register a common code prefix
curl -X POST http://localhost:3000/v1/embeddings/prefix \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "import numpy as np\nimport pandas as pd\nimport matplotlib.pyplot as plt",
    "model": "my-model"
  }'
```

--------------------------------

### Build Documentation

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Commands to generate and open project documentation.

```bash
cargo doc --open
```

```bash
cargo doc --open --all-features
```

--------------------------------

### GET /v1/embeddings/prefix/stats

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Retrieves statistics for the prefix cache.

```APIDOC
## GET /v1/embeddings/prefix/stats

### Description
Returns performance and usage statistics for the prefix cache.

### Method
GET

### Endpoint
/v1/embeddings/prefix/stats
```

--------------------------------

### Initialize and Load Models in Embellama

Source: https://github.com/darjus/embellama/blob/master/README.md

Demonstrates initializing the engine and managing model loading states, including lazy loading behavior.

```rust
// First model - loaded immediately
let mut engine = EmbeddingEngine::new(config)?;
assert!(engine.is_model_loaded_in_thread("model1"));

// Additional model - lazy loaded
engine.load_model(config2)?;
assert!(engine.is_model_registered("model2"));
assert!(!engine.is_model_loaded_in_thread("model2"));  // Not yet loaded

// Triggers actual loading in thread
engine.embed(Some("model2"), "text")?;
assert!(engine.is_model_loaded_in_thread("model2"));  // Now loaded
```

--------------------------------

### GET /v1/embeddings/prefix

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Lists all currently cached prefixes.

```APIDOC
## GET /v1/embeddings/prefix

### Description
Retrieves a list of all prefixes currently stored in the cache.

### Method
GET

### Endpoint
/v1/embeddings/prefix
```

--------------------------------

### Download Benchmark Model

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Download the model required for running performance benchmarks.

```bash
just download-bench-model
```

--------------------------------

### Run Full Benchmarks with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute the full suite of performance benchmarks for Embellama using the `just` task runner.

```bash
just bench
```

--------------------------------

### Run Benchmarks

Source: https://github.com/darjus/embellama/blob/master/README.md

Command to execute performance benchmarks with a specified model path.

```bash
EMBELLAMA_BENCH_MODEL=/path/to/model.gguf cargo bench
```

--------------------------------

### Run Benchmarks

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Commands to execute project benchmarks using cargo.

```bash
cargo bench
```

```bash
cargo bench -- benchmark_name
```

--------------------------------

### GET /cache/stats

Source: https://context7.com/darjus/embellama/llms.txt

Retrieves statistics regarding the embedding cache performance and memory usage.

```APIDOC
## GET /cache/stats

### Description
Returns cache hit/miss statistics and current memory usage metrics.

### Method
GET

### Endpoint
/cache/stats

### Response
#### Success Response (200)
- **stats** (object) - Cache hit/miss counts.
- **memory** (object) - Memory usage details.

#### Response Example
{
  "enabled": true,
  "stats": {
    "hits": 1234,
    "misses": 567
  }
}
```

--------------------------------

### Run Quick Benchmark Subset with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute a subset of performance benchmarks for Embellama using the `just` task runner.

```bash
just bench-quick
```

--------------------------------

### Initial Model Loading

Source: https://github.com/darjus/embellama/blob/master/README.md

Demonstrates the initial model loading behavior where the first model specified in `EmbeddingEngine::new()` is loaded immediately into the current thread.

```rust
# fn main() -> anyhow::Result<()> {
# use embellama::{ModelConfig, EngineConfig, EmbeddingEngine};
# let model_config = ModelConfig::builder()
#     .with_model_path("/path/to/model.gguf")
#     .with_model_name("model1")
#     .build()?;
# let config = EngineConfig::builder()
#     .with_model_config(model_config)
#     .build()?;
# let model_config2 = ModelConfig::builder()
#     .with_model_path("/path/to/model2.gguf")
#     .with_model_name("model2")
#     .build()?;
# let config2 = EngineConfig::builder()
#     .with_model_config(model_config2)

```

--------------------------------

### Apply Apache 2.0 license header

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Mandatory license header for all source files in the project.

```rust
// Copyright 2024 Embellama Contributors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
```

--------------------------------

### Clean Build Artifacts and Models with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Remove all build artifacts and downloaded models using the `just` task runner.

```bash
just clean-all
```

--------------------------------

### Run Integration and Concurrency Tests

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Commands to execute integration and concurrency test suites using just.

```bash
just test-integration
```

```bash
just test-concurrency
```

--------------------------------

### Create and Configure Pre-commit Hook

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Manually set up the `pre-commit` hook script in the `.git/hooks` directory. This script runs formatting, linting, and tests before each commit.

```bash
#!/bin/sh
set -e

# Format code
cargo fmt -- --check

# Run clippy
cargo clippy --all-features -- -D warnings

# Run tests
cargo test --quiet

echo "Pre-commit checks passed!"
```

--------------------------------

### Handle Embellama Errors

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Example of how to match and handle different types of errors returned by the `embed` function, including specific errors and retryable conditions.

```rust
use embellama::Error;

match engine.embed(None, text) {
    Ok(embedding) => process_embedding(embedding),
    Err(Error::ModelNotFound { name }) => {
        println!("Model {} not found", name);
    }
    Err(Error::InvalidInput { message }) => {
        println!("Invalid input: {}", message);
    }
    Err(e) if e.is_retryable() => {
        // Retry logic for transient errors
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

```

--------------------------------

### Enable Logging Levels

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Environment variable configurations to control logging output.

```bash
RUST_LOG=debug cargo run
```

```bash
RUST_LOG=embellama::engine=trace cargo run
```

--------------------------------

### Run Embellama Benchmarks

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Execute performance benchmarks for Embellama. Includes full and quick benchmark subsets.

```bash
# Run benchmarks
just bench

# Quick benchmark subset
just bench-quick
```

--------------------------------

### Redis Backend Implementation (Rust)

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Optional Redis backend for distributed caching. Requires the 'redis-cache' feature flag. Implements get and set operations with TTL.

```rust
// src/cache/redis_backend.rs (optional feature)
#[cfg(feature = "redis-cache")]
pub struct RedisBackend {
    client: redis::Client,
    ttl: usize,
}

#[cfg(feature = "redis-cache")]
impl RedisBackend {
    pub async fn get(&self, key: &str) -> Option<Vec<f32>> {
        // Implement Redis get with deserialization
    }

    pub async fn set(&self, key: &str, value: &[f32]) {
        // Implement Redis set with serialization and TTL
    }
}
```

--------------------------------

### Configure and use EmbeddingEngine

Source: https://github.com/darjus/embellama/blob/master/ARCHITECTURE.md

Demonstrates the builder pattern for engine configuration and methods for generating single or batch embeddings.

```rust
use embellama::{ModelConfig, EngineConfig, EmbeddingEngine};

// 1. Build model configuration
let model_config = ModelConfig::builder()
    .with_model_path("path/to/your/model.gguf")
    .with_model_name("my-embedding-model")
    .build()?;

// 2. Build engine configuration
let engine_config = EngineConfig::builder()
    .with_model_config(model_config)
    .build()?;

// 3. Create the engine
let engine = EmbeddingEngine::new(engine_config)?;

// 4. Generate a single embedding
let embedding = engine.embed("my-embedding-model", "Hello, world!")?;

// 5. Generate embeddings in a batch
let texts = vec!["First text", "Second text"];
let embeddings = engine.embed_batch("my-embedding-model", texts)?;

// 6. Unload the model when no longer needed
engine.unload_model("my-embedding-model")?;
```

--------------------------------

### List Available `just` Commands

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Display all available automation tasks defined in the `justfile`. This command helps in understanding the project's workflow.

```bash
just
```

--------------------------------

### Advanced Configuration Options

Source: https://github.com/darjus/embellama/blob/master/README.md

Demonstrates advanced configuration for ModelConfig and EngineConfig, including context size, threads, GPU layers, normalization mode, pooling strategy, GPU usage, and batch size.

```rust
# fn main() -> anyhow::Result<()> {
use embellama::{ModelConfig, EngineConfig, PoolingStrategy, NormalizationMode};

let model_config = ModelConfig::builder()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("my-model")
    .with_context_size(2048)
    .with_n_threads(8)
    .with_n_gpu_layers(32)
    .with_normalization_mode(NormalizationMode::L2)
    .with_pooling_strategy(PoolingStrategy::Mean)
    .build()?;

let config = EngineConfig::builder()
    .with_model_config(model_config)
    .with_use_gpu(true)
    .with_batch_size(64)
    .build()?;
# Ok(())
# }
```

--------------------------------

### Bash: Generating Embeddings with Cached Prefix

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Example of generating embeddings using a cURL command, where the input text includes a previously registered prefix. This demonstrates how the system utilizes the cache for faster processing.

```bash
# Generate embeddings that will use the cached prefix
curl -X POST http://localhost:3000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": "import numpy as np\nimport pandas as pd\nimport matplotlib.pyplot as plt\n\nclass MyModel: pass",
    "model": "my-model"
  }'
```

--------------------------------

### Run Development Workflow with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute a common development workflow including formatting, linting, and unit tests using the `just` task runner.

```bash
just dev
```

--------------------------------

### Run Pre-commit Checks with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute all pre-commit checks, including formatting, linting, and tests, using the `just` task runner.

```bash
just pre-commit
```

--------------------------------

### EngineConfig::with_backend_detection - Auto-Detect Hardware Backend

Source: https://context7.com/darjus/embellama/llms.txt

Creates an engine configuration with automatic detection of the best available hardware backend (Metal, CUDA, ROCm, Vulkan, or CPU).

```APIDOC
## EngineConfig::with_backend_detection - Auto-Detect Hardware Backend

### Description
Creates an engine configuration with automatic detection of the best available hardware backend (Metal, CUDA, ROCm, Vulkan, or CPU).

### Method
POST (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
This function does not take direct parameters but configures the `EngineConfig` builder.

### Request Example
```rust
let config = EngineConfig::with_backend_detection()
    .with_model_path("/path/to/model.gguf")
    .with_model_name("auto-model")
    .build()?;
```

### Response
#### Success Response (200)
- **backend** (String) - The detected hardware backend (e.g., "Metal", "CUDA", "CPU").
- **platform** (String) - The operating system and architecture (e.g., "macos aarch64").
- **available_features** (Array<String>) - A list of available hardware features.

#### Response Example
```json
{
  "backend": "Metal",
  "platform": "macos aarch64",
  "available_features": ["metal"]
}
```
```

--------------------------------

### Configure Token Truncation

Source: https://context7.com/darjus/embellama/llms.txt

Demonstrates how to set up automatic token truncation strategies using EngineConfig.

```rust
use embellama::{EmbeddingEngine, EngineConfig, EmbeddingConfig, TruncateTokens};

fn main() -> anyhow::Result<()> {
    // Option 1: Automatic truncation to model's max tokens
    let config = EngineConfig::builder()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("truncate-model")
        .with_truncate_tokens(TruncateTokens::Yes)
        .build()?;

    // Option 2: Truncate to specific limit
    let config_limited = EngineConfig::builder()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("limited-model")
        .with_truncate_limit(256)  // Max 256 tokens
        .build()?;

    // Option 3: No truncation (default) - errors if input exceeds limit
    let config_no_truncate = EngineConfig::builder()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("no-truncate-model")
        .with_truncate_tokens(TruncateTokens::No)
        .build()?;

    let engine = EmbeddingEngine::new(config)?;

    // Long text will be automatically truncated
    let long_text = "word ".repeat(10000);
    let embedding = engine.embed(None, &long_text)?;
    println!("Embedding generated successfully");

    Ok(())
}
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Manually run pre-commit hooks. Use 'just pre-commit' for staged files or 'just pre-commit-all' for all files.

```bash
# On staged files only
just pre-commit

# On all files
just pre-commit-all
```

--------------------------------

### Test Multiple Configurations

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Demonstrates reusing a single engine instance for multiple model configurations to avoid backend initialization conflicts.

```rust
#[test]
#[serial]  // Required for all integration tests
fn test_multiple_configurations() {
    let mut engine = EmbeddingEngine::new(initial_config)?;

    // Load additional models instead of creating new engines
    engine.load_model(config2)?;
    engine.load_model(config3)?;
}
```

--------------------------------

### Run All Embellama Tests with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute all unit, integration, and concurrency tests for Embellama using the `just` task runner.

```bash
just test
```

--------------------------------

### Implement Cache Mitigation Strategies in Rust

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Demonstrates feature flags, version-aware cache keys, and admission control logic for embedding caches.

```rust
// Feature flag support
#[cfg(feature = "caching")]
let cache = if config.cache.enabled {
    Some(EmbeddingCache::new(&config.cache))
} else {
    None
};

// Version-aware cache keys
let cache_key = format!("{}-{}-v{}", text_hash, model_hash, MODEL_VERSION);

// Admission control
if request_frequency > MIN_CACHE_FREQUENCY {
    cache.insert(key, value);
}
```

--------------------------------

### Build Embellama Project

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Compile the Embellama project using Cargo. This command builds the entire project.

```bash
cargo build
```

--------------------------------

### Configure Project Dependencies

Source: https://github.com/darjus/embellama/blob/master/ARCHITECTURE.md

Cargo.toml configuration defining core library dependencies and feature-gated server components.

```toml
[package]
name = "embellama"
version = "0.1.0"
edition = "2021"

[dependencies]
# Core library dependencies
llama-cpp-2 = "0.1.117"
thiserror = "1.0"
anyhow = "1.0"
tracing = "0.1"
serde = { version = "1.0", features = ["derive"] }
rayon = "1.8"  # For library batch processing only

# Server-only dependencies
axum = { version = "0.8", optional = true }
tokio = { version = "1.35", features = ["full"], optional = true }
clap = { version = "4.4", features = ["derive"], optional = true }
tower = { version = "0.4", optional = true }
tower-http = { version = "0.6", features = ["cors", "trace"], optional = true }

[features]
default = []
server = ["dep:axum", "dep:tokio", "dep:clap", "dep:tower", "dep:tower-http"]

[[bin]]
name = "embellama-server"
required-features = ["server"]
path = "src/bin/server.rs"
```

--------------------------------

### Create Git Tag

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Create an annotated git tag for a specific release version.

```bash
git tag -a v0.9.0 -m "Release v0.9.0"

```

--------------------------------

### Run Integration Tests with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute integration tests for Embellama, which involve real model interactions, using the `just` task runner.

```bash
just test-integration
```

--------------------------------

### Run Embellama Tests

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Execute tests for the Embellama project. Includes unit, integration, and all tests.

```bash
# Unit tests (fast, no model required)
just test-unit

# Integration tests (requires test model)
just test-integration

# All tests
just test
```

--------------------------------

### Execute development workflow commands

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Commonly used commands for the development loop, including linting, formatting, and testing.

```bash
just dev        # Run fix, fmt, clippy, and unit tests
just test       # Run all test suites
just pre-commit # Full validation before committing
```

--------------------------------

### Run Tests in Release Mode

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute all tests in release mode, which enables optimizations. This provides a more accurate performance measurement for tests.

```bash
cargo test --release
```

--------------------------------

### Implement library and application error handling

Source: https://github.com/darjus/embellama/blob/master/AGENTS.md

Demonstrates returning Result types from library functions and handling them in application code.

```rust
// Library code with specific errors
pub fn load_model(path: &str) -> Result<Model, EmbellamaError> {
    // Implementation
}

// Application code can use anyhow
use anyhow::Result;
fn main() -> Result<()> {
    let model = embellama::load_model("model.gguf")?;
    Ok(())
}
```

--------------------------------

### Debug with rust-gdb

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Command line instructions for debugging using rust-gdb.

```bash
cargo build
rust-gdb target/debug/embellama-server
```

--------------------------------

### Run Unit Tests with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute only the unit tests for Embellama using the `just` task runner.

```bash
just test-unit
```

--------------------------------

### Create Embedding Engine with Configuration

Source: https://context7.com/darjus/embellama/llms.txt

Instantiate an EmbeddingEngine using EngineConfig, which includes model details and normalization settings. The model is loaded immediately upon engine creation.

```rust
use embellama::{EmbeddingEngine, EngineConfig, ModelConfig, NormalizationMode};

fn main() -> anyhow::Result<()> {
    // Build model configuration
    let model_config = ModelConfig::builder()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("my-model")
        .with_normalization_mode(NormalizationMode::L2)
        .build()?;

    // Build engine configuration
    let engine_config = EngineConfig::builder()
        .with_model_config(model_config)
        .build()?;

    // Create engine - model is loaded immediately
    let engine = EmbeddingEngine::new(engine_config)?;

    // Verify model is loaded
    assert!(engine.is_model_loaded_in_thread("my-model"));

    Ok(())
}

```

--------------------------------

### Model Management and Health Check

Source: https://context7.com/darjus/embellama/llms.txt

Lists available models and checks server health status.

```bash
# List models
curl http://localhost:8080/v1/models

# Response:
# {
#   "object": "list",
#   "data": [{
#     "id": "my-model",
#     "object": "model",
#     "created": 1700000000,
#     "owned_by": "embellama",
#     "context_size": 2048
#   }]
# }

# Health check
curl http://localhost:8080/health

# Response:
# {
#   "status": "healthy",
#   "model": "my-model",
#   "version": "0.10.1"
# }
```

--------------------------------

### Execute k6 Load Test

Source: https://github.com/darjus/embellama/blob/master/caching_implementation_plan.md

Command to run the defined load test script.

```bash
k6 run cache_load_test.js
```

--------------------------------

### Lint Code with `cargo clippy`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Run `clippy` with all features enabled to perform advanced linting and check for common mistakes. Warnings are treated as errors.

```bash
cargo clippy --all-features -- -D warnings
```

--------------------------------

### VS Code Debug Configuration

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Launch configuration for debugging unit tests using CodeLLDB.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug unit tests",
            "cargo": {
                "args": ["test", "--no-run"],
                "filter": {
                    "name": "embellama",
                    "kind": "lib"
                }
            },
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}
```

--------------------------------

### Generate Changelogs

Source: https://github.com/darjus/embellama/blob/master/README.md

Commands to regenerate or preview the project changelog using git-cliff.

```bash
just changelog              # Regenerate CHANGELOG.md
just changelog-unreleased   # Preview unreleased changes
```

--------------------------------

### Download Test Models

Source: https://github.com/darjus/embellama/blob/master/CONTRIBUTING.md

Download test models required for running all tests in the Embellama project.

```bash
just download-test-model
```

--------------------------------

### Write Unit Tests

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Standard structure for writing unit tests in Rust.

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_something() {
        // Arrange
        let input = "test";

        // Act
        let result = function_under_test(input);

        // Assert
        assert_eq!(result, expected);
    }
}
```

--------------------------------

### Run Concurrency Tests with `just`

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Execute concurrency tests for Embellama using the `just` task runner.

```bash
just test-concurrency
```

--------------------------------

### Automated Release Command

Source: https://github.com/darjus/embellama/blob/master/DEVELOPMENT.md

Use the provided justfile command to automate the release process, including version bumping, changelog generation, tagging, and pushing.

```bash
just release 0.9.0

```

--------------------------------

### Auto-detect hardware backend

Source: https://context7.com/darjus/embellama/llms.txt

Configures the engine to automatically select the best available hardware backend such as Metal, CUDA, or ROCm. Use BackendInfo to verify the selected platform and features.

```rust
use embellama::{EmbeddingEngine, EngineConfig, BackendInfo, detect_best_backend};

fn main() -> anyhow::Result<()> {
    // Auto-detect and configure the best backend
    let config = EngineConfig::with_backend_detection()
        .with_model_path("/path/to/model.gguf")
        .with_model_name("auto-model")
        .build()?;

    let engine = EmbeddingEngine::new(config)?;

    // Check which backend was selected
    let backend_info = BackendInfo::new();
    println!("Using backend: {}", backend_info.backend);
    println!("Platform: {}", backend_info.platform);
    println!("Available features: {:?}", backend_info.available_features);

    // Output on macOS with Metal:
    // Using backend: Metal
    // Platform: macos aarch64
    // Available features: ["metal"]

    Ok(())
}
```