Installation

Prerequisites

• Python 3.12 (pinned exactly — ==3.12.*)
• uv package manager
• Redis (for session state when using the runtime)

Note

Python 3.12 is required exactly. The requires-python = "==3.12.*" constraint is intentional — do not use 3.11 or 3.13.

Distribution

Caution

alquimia-core is a private package and is not published to PyPI. It must be installed from a local tarball or directly from the private GitHub repository. Contact the Alquimia team for access.

alquimia-runtime is distributed as a Docker image. For local development, clone the repository and run with Docker Compose (see Docker Compose guide).

Install alquimia-core

From tarball

# Install from a distributed tarball
uv pip install ./alquimia_core-0.2.0.tar.gz

From source

# Requires access to the private repository
git clone https://github.com/Alquimia-ai/alquimia-core
cd alquimia-core
uv pip install -e .

Optional extras

Install only what you need:

# AWS S3 blob storage
uv pip install "alquimia-core[aws]"

# Python module tool schema extraction (requires numpydoc)
uv pip install "alquimia-core[tools]"

# On-premise ML inference (HuggingFace, OpenVINO, Triton)
uv pip install "alquimia-core[leviathan]"

# All extras
uv pip install "alquimia-core[aws,tools,leviathan]"

Environment variables

Set these before running any agent:

# Required for OCI registry operations
export ALQUIMIA_OCI_REGISTRY_DEFAULT=ghcr.io

# Secret resolver: 'env' (default for local) or 'vault' (for production)
export ALQUIMIA_REGISTRY_SECRET_RESOLVER=env

# Registry storage directory (default: /tmp/.alquimia)
export ALQUIMIA_REGISTRY_DIR=/var/lib/alquimia

For Vault-backed secrets:

export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=<your-scoped-token>
export VAULT_MOUNT_POINT=secret

For OpenTelemetry:

export OTEL_COLLECTOR_ENDPOINT=http://otel-collector:4318
export OTEL_ALQUIMIA_SERVICE_NAME=my-agent-service

Verify the installation

python -c "from alquimia.core import evaluate; print('alquimia-core OK')"
alquimia --help

Expected output:

alquimia-core OK
Usage: alquimia [OPTIONS] COMMAND [ARGS]...
  Alquimia CLI
Options:
  --help  Show this message and exit.
Commands:
  embeddings  Embeddings management
  local       Local assistant operations
  registry    Registry management

Next steps

• Run your first agent with the Quickstart guide
• Deploy the full runtime stack with Docker Compose
• Deploy to Kubernetes or OpenShift

Source

• Alquimia-ai/alquimia-core — SDK source, pyproject.toml, extras
• Alquimia-ai/alquimia-runtime — runtime service, Docker Compose, Kubernetes manifests