Skip to content

CLAUDE.md

Latest commit

 

History

History
86 lines (55 loc) · 5.02 KB

CLAUDE.md

File metadata and controls

86 lines (55 loc) · 5.02 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Open Data Hub OGX Distribution — a containerized distribution of OGX (the opendatahub-io fork of Llama Stack) for AI/ML workflows. The project generates and maintains multi-arch (amd64/arm64) container images with pre-configured providers for inference, vector storage, file processing, and other ML APIs.

The container image is published to quay.io/opendatahub/odh-ogx-core.

Common Commands

# Regenerate all auto-generated files + run linting
pre-commit run --all-files

# Build container image locally
podman build -t ogx-core .

# Run container (requires PostgreSQL and at least one inference endpoint)
podman run -p 8321:8321 -e VLLM_URL=http://host:8000/v1 ogx-core

# Run smoke tests (requires running container, vLLM, and PostgreSQL)
./tests/smoke.sh

# Run integration tests (clones upstream OGX repo, runs pytest against live server)
./tests/run_integration_tests.sh

Linting is handled entirely via pre-commit: Ruff (Python), Shellcheck (shell), Actionlint (GitHub Actions workflows).

Architecture

Build Pipeline

pre-commit run --all-files triggers two local hooks that regenerate distribution artifacts:

  1. build/build.py (hook: pkg-gen, always runs) — creates a temp venv, installs OGX, runs ogx stack list-deps against build/build.yaml to discover Python dependencies, then generates:

    • distribution/config.yaml — stripped runtime config (dependency-only providers like inline::sentence-transformers, inline::milvus, inline::faiss are removed)
    • distribution/requirements.txt — full pip requirements including OpenTelemetry instrumentation packages
    • Containerfile — generated from Containerfile.in, embeds config.yaml as base64-encoded OCI labels

  2. build/gen_distro_docs.py (hook: doc-gen, runs when build/build.yaml, build/build.env, or distribution/config.yaml change) — generates distribution/README.md with an API/provider table.

Auto-Generated Files (do not edit manually)

  • Containerfile — generated from Containerfile.in by build/build.py
  • distribution/config.yaml — generated from build/build.yaml by build/build.py
  • distribution/requirements.txt — generated by build/build.py
  • distribution/README.md — generated by build/gen_distro_docs.py

Key Files

  • build/build.yaml — the source of truth for all providers. Contains provider definitions with ${env.VAR:=default} / ${env.VAR:+value} templating for runtime env-var configuration. When adding or removing a provider, edit this file and run pre-commit run --all-files.
  • build/build.env — sets OGX_VERSION and OGX_INSTALL_FROM_SOURCE. The OGX_VERSION env var can also be overridden at build time.
  • Containerfile.in — the container build template (hand-edited, at repo root). Contains a {config_labels} placeholder that build/build.py substitutes with OCI labels embedding the config.yaml as base64.
  • distribution/entrypoint.sh — container entrypoint; runs ogx run <config> with optional OpenTelemetry instrumentation when OTEL_SERVICE_NAME is set.
  • distribution/constraints.txt — pip constraints for known-broken dependency versions.

Provider Activation Pattern

Providers in build/build.yaml use conditional provider_id syntax: ${env.SOME_VAR:+provider-name}. When the env var is unset, the provider is skipped at OGX server startup. This means the same config.yaml works for all deployment scenarios — providers activate based on which env vars are present.

Version Management

The OGX version is set in build/build.env (OGX_VERSION). The build script (build/build.py) reads this and constructs the appropriate pip specifier (source install from git or published package, controlled by OGX_INSTALL_FROM_SOURCE).

CI/CD

  • redhat-distro-container.yml — main workflow: builds multi-arch images, runs smoke + integration tests against vLLM (local CPU or MaaS) and PostgreSQL, publishes to Quay.io on push to main/rhoai-v*/release-*. Nightly scheduled builds test against OGX main.
  • responses-weekly.yml — weekly Responses API test suite across OpenAI, Vertex AI, and vLLM MaaS providers; publishes results to GitHub Pages.
  • Tekton (.tekton/) — Konflux/RHOAI downstream build pipelines.
  • create-or-update-release-branch.yml — creates/updates release-* release branches.

PR Title Format

PR titles must use Conventional Commits format (<type>(<optional scope>): <description>), enforced by semantic-pr.yml.

Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.

Important Notes

  • Python version: 3.12
  • Package manager: uv
  • Uses the opendatahub-io/ogx fork, not upstream llamastack/llama-stack
  • The vllm/ directory contains a separate vLLM CPU container image used for CI testing