ahnlich

• ahnlich-ai: AI proxy to communicate with ahnlich-db, receiving raw input, transforming into embeddings, and storing within the DB. It extends the capabilities by then allowing developers/engineers to issue queries to the same store using raw input such as images/text. It features multiple off-the-shelf models that can be selected for store index and query.

CREATESTORE my_store QUERYMODEL all-minilm-l6-v2 INDEXMODEL all-minilm-l6-v2

// example query
create_store(
    store="my_store",
    index_model="all-minilm-l6-v2",
    query_model="all-minilm-l6-v2",
)

• ahnlich-client-rs: Rust client for ahnlich-db and ahnlich-ai.

• ahnlich-client-py: Python client for ahnlich-db and ahnlich-ai.

• ahnlich-client-go: Go client for ahnlich-db and ahnlich-ai.

• ahnlich-client-node: Node.js/TypeScript client for ahnlich-db and ahnlich-ai.

• ahnlich-cli: CLI for querying ahnlich-db and ahnlich-ai

Architecture

flowchart TD
  subgraph ai [ahnlich‑ai]
    direction TB
    AIClient["AI Client"]
    StoreHandlerAI["Store Handler"]
    StoreA_AI["Store A"]
    ModelNode["Index Model → Model B<br/>Query Model → Model A<br/>Preprocess Method"]
    PersistenceAI[(Persistence)]
    
    AIClient --> |"original + metadata"| StoreHandlerAI
    StoreHandlerAI --> StoreA_AI
    StoreA_AI --> ModelNode
    ModelNode -.-> PersistenceAI
    class PersistenceAI optionalNode
  end

  subgraph db [ahnlich‑db]
    direction TB
    DBClient["DB Client"]
    StoreHandlerDB["Store Handler"]
    StoreA_DB["Store A"]
    PersistenceDB[(Persistence)]
    
    DBClient --> |"DB query"| StoreHandlerDB
    StoreHandlerDB --> StoreA_DB
    StoreA_DB -.-> PersistenceDB
    class PersistenceDB optionalNode
  end

  %% Interactions between services
  StoreHandlerAI -.-> |"Set: vector + metadata"| StoreHandlerDB
  StoreHandlerAI -.-> |"GetSimN: vector"| StoreHandlerDB
  StoreHandlerDB -.-> |"TopN results"| StoreHandlerAI

  classDef optionalNode stroke-dasharray: 5 5, color: gray, stroke: gray;
  class PersistenceAI,PersistenceDB optionalNode

Usage

ahnlich-db, ahnlich-ai and ahnlich-cli are packaged and released as binaries for multiple platforms alongside docker images

The DB can be used without the AI proxy for more fine grained control of the generated vector embeddings as all clients support both

Docker Images.

Note:

1. Arguments and commands must be passed in quotes. E.G: docker run <image_name> "ahnlich-db run --enable-tracing --port 8000"

2. The CLI comes packaged into the docker images.

Installation

Download Binaries

You can download the Ahnlich binaries for ai and db from GitHub Releases.

• wget:

  wget https://github.com/deven96/ahnlich/releases/download/bin%2Fdb%2F0.0.0/aarch64-darwin-ahnlich-db.tar.gz  
  

• Extract the file:

  tar -xvzf aarch64-darwin-ahnlich-db.tar.gz  
  

• Run the binary:

  ./ahnlich-db  
  

Replace aarch64-darwin-ahnlich-db.tar.gz with the appropriate file name for your architecture. For ai, download the corresponding ai binary, extract it, and run it using ./ahnlich-ai.

Using Docker

You can pull the prebuilt Docker images for Ahnlich:

• Ahnlich AI:

  docker pull ghcr.io/deven96/ahnlich-ai:latest  
  

• Ahnlich DB:

  docker pull ghcr.io/deven96/ahnlich-db:latest  
  

Example Docker Compose

Below is an example docker-compose.yaml configuration to run both ahnlich-db and ahnlich-ai with tracing:

services:
  ahnlich_db:
    image: ghcr.io/deven96/ahnlich-db:latest
    command: >
      "ahnlich-db run --host 0.0.0.0 \
      --enable-tracing \
      --otel-endpoint http://jaeger:4317"
    ports:
      - "1369:1369"

  ahnlich_ai:
    image: ghcr.io/deven96/ahnlich-ai:latest
    command: >
      "ahnlich-ai run --db-host ahnlich_db --host 0.0.0.0 \
      --supported-models all-minilm-l6-v2,resnet-50 \
      --enable-tracing \
      --otel-endpoint http://jaeger:4317"
    ports:
      - "1370:1370"

  # optional jaeger service whenever --enable-tracing and
  # --otel-endpoint is used
  jaeger:
    image: jaegertracing/all-in-one:${JAEGER_VERSION:-latest}
    ports:
      - "16686:16686"
      - "1888:1888" # pprof extension
      - "8888:8888" # Prometheus metrics exposed by the collector
      - "8889:8889" # Prometheus exporter metrics
      - "4317:4317" # otlp grpc
      - "4318:4318" # otlp http

Below is an example docker-compose.yaml configuration with persistence:

services:
  ahnlich_db:
    image: ghcr.io/deven96/ahnlich-db:latest
    command: >
      "ahnlich-db run --host 0.0.0.0 \
      --enable-persistence --persist-location /root/.ahnlich/data/db.dat \
      --persistence-interval 300"
    ports:
      - "1369:1369"
    volumes:
      - "./data/:/root/.ahnlich/data" # Persistence Location

  ahnlich_ai:
    image: ghcr.io/deven96/ahnlich-ai:latest
    command: >
      "ahnlich-ai run --db-host ahnlich_db --host 0.0.0.0 \
      --supported-models all-minilm-l6-v2,resnet-50 \
      --enable-persistence --persist-location /root/.ahnlich/data/ai.dat \
      --persistence-interval 300"
    ports:
      - "1370:1370"
    volumes:
      - "./ahnlich_ai_model_cache:/root/.ahnlich/models" # Model cache storage
      - "./data/:/root/.ahnlich/data" # Persistence Location

Below is an example docker-compose.yaml configuration with health checks using the CLI in non-interactive mode:

services:
  ahnlich_db:
    image: ghcr.io/deven96/ahnlich-db:latest
    command: >
      "ahnlich-db run --host 0.0.0.0"
    ports:
      - "1369:1369"
    healthcheck:
      test: ["CMD-SHELL", "echo 'PING' | ahnlich-cli ahnlich --agent db --host 127.0.0.1 --port 1369 --no-interactive"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

  ahnlich_ai:
    image: ghcr.io/deven96/ahnlich-ai:latest
    command: >
      "ahnlich-ai run --db-host ahnlich_db --host 0.0.0.0 \
      --supported-models all-minilm-l6-v2"
    ports:
      - "1370:1370"
    depends_on:
      ahnlich_db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "echo 'PING' | ahnlich-cli ahnlich --agent ai --host 127.0.0.1 --port 1370 --no-interactive"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s

The --no-interactive flag allows the CLI to accept commands via stdin and exit immediately after processing, making it ideal for Docker health checks, CI/CD pipelines, and automated scripts.

Execution Providers (Ahnlich AI)

• CUDA: Only supports >= CUDAv12 and might need to sudo apt install libcudnn9-dev-cuda-12
• CoreML (Apple): Not advised for NLP models due to often large dimensionality.
• MIGraphX (AMD GPUs, Linux): AMD's recommended execution provider (upstream ONNX Runtime removed the older ROCm provider in release 1.23). Requires the migraphx runtime to be installed (ships in AMD's ROCm apt repository). Supported AMD Instinct accelerators are listed in the ROCm compatibility matrix; select Radeon cards are also supported. When unsupported, ORT falls back to CPU.

Contributing

View contribution guide