Skip to content

Installation

Requirements

  • Python 3.12 or higher
  • PostgreSQL 16+ with Apache AGE extension (for graph features)
  • ClickHouse 23.0+ (for analytics features)

Install from PyPI

pip install imbi-common

Install from Source

For Development

# Clone the repository
git clone https://github.com/AWeber-Imbi/imbi-common.git
cd imbi-common

# Install dependencies and pre-commit hooks
moon run root:setup

For Production

pip install git+https://github.com/AWeber-Imbi/imbi-common.git@main

Verify Installation

# Test basic imports
from imbi.common import settings, models, graph, clickhouse, auth

print("All modules imported successfully")

Optional Dependencies

Server

To use the serve command for running uvicorn:

pip install imbi-common[server]

OpenTelemetry

To install the OpenTelemetry SDK, exporter, and instrumentation packages at versions known to be compatible with each other:

pip install imbi-common[otel]

Use the otel extra to pin the stack

Downstream packages (e.g. imbi-api, imbi-gateway, imbi-mcp) that ship OpenTelemetry support MUST depend on imbi-common[otel] instead of declaring individual opentelemetry-* packages.

Downstream packages SHOULD NOT pin their own versions of opentelemetry-api, opentelemetry-sdk, opentelemetry-distro, opentelemetry-exporter-*, or opentelemetry-instrumentation-* packages. Pinning those separately defeats the purpose of the otel extra and reintroduces the version-skew problems it exists to prevent — the opentelemetry-api/-sdk packages (1.x.y) and the instrumentation/exporter packages (0.x betas) move on a coupled release cadence, and mismatched versions break instrumentation at import time.

Installing through the otel extra ensures that every service in the Imbi ecosystem ends up with a single, consistent set of OpenTelemetry package versions resolved by the consumer's package manager.

The otel extra only installs the packages — it does not configure OpenTelemetry. Library users (i.e. the application or service that depends on imbi-common[otel]) are responsible for:

At a minimum, library users should set OTEL_SERVICE_NAME and include service.version=<version> in OTEL_RESOURCE_ATTRIBUTES so that traces, metrics, and logs can be attributed to a specific service and release:

export OTEL_SERVICE_NAME=imbi-api
export OTEL_RESOURCE_ATTRIBUTES="service.version=2.5.5"

OTEL_RESOURCE_ATTRIBUTES is a comma-separated list of key=value pairs, so additional attributes (e.g. deployment.environment) can be appended:

export OTEL_RESOURCE_ATTRIBUTES="service.version=2.5.5,deployment.environment=production"

The bundled opentelemetry-sdk also ships entry-point-registered resource detectors that can enrich the resource with process, OS, and host attributes without any code changes. Opt in by listing their names (or * for all of them) in OTEL_EXPERIMENTAL_RESOURCE_DETECTORS:

export OTEL_EXPERIMENTAL_RESOURCE_DETECTORS=process,os,host

The otel detector — which reads OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES — is always active and does not need to be listed. Third-party detector packages (cloud-provider, Kubernetes, container, etc.) self-register on install via the opentelemetry_resource_detector entry-point group and only need to be added to OTEL_EXPERIMENTAL_RESOURCE_DETECTORS to take effect.

Documentation

To build documentation locally:

pip install imbi-common[docs]
mkdocs serve

Visit http://localhost:8000 to view the documentation.

Database Setup

PostgreSQL with Apache AGE

imbi-common uses PostgreSQL with the Apache AGE graph extension. The recommended approach for local development is the bundled Docker Compose setup (via moon run root:services), which starts a pre-configured PostgreSQL image with AGE, pgvector, pg_cron, and pgtap already installed.

# Using the project's compose setup
moon run root:services

Or run the custom image manually:

docker run -d \
  --name postgres-age \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  ghcr.io/aweber-imbi/postgres:latest

ClickHouse

# Using Docker
docker run -d \
  --name clickhouse \
  -p 8123:8123 -p 9000:9000 \
  clickhouse/clickhouse-server:latest

Configuration

Create a configuration file:

# config.toml

[postgres]
url = "postgresql://postgres:secret@localhost:5432/imbi"

[clickhouse]
url = "clickhouse+http://localhost:8123"

[auth]
jwt_secret = "your-secret-key-here"

Or use environment variables:

export POSTGRES_URL="postgresql://postgres:secret@localhost:5432/imbi"
export CLICKHOUSE_URL="clickhouse+http://localhost:8123"
export IMBI_AUTH_JWT_SECRET="your-secret-key-here"

Next Steps