ibm-granite/granite.build

ibm-granite/granite.build

Description: Build orchestration for LLM pipelines

Language: Python

License: Apache-2.0

Stars: 34

Forks: 7

Open issues: 8

Created: 2026-04-27T18:39:04Z

Pushed: 2026-06-10T19:03:38Z

Default branch: main

Fork: no

Archived: no

README:

Granite.Build

Build orchestration for LLM pipelines. Define multi-step model workflows in YAML — download, fine-tune, evaluate, and deploy — and run them locally or on cloud infrastructure.

_This repository is currently in alpha. The code and documentation are under active development and may change frequently as we work to improve usability and reliability. Contributions and feedback are welcome, but please be aware that breaking changes may occur._

Contents

• [What is Granite.Build?](#what-is-granitebuild)
• [Quick start](#quick-start)
• [Example build.yaml](#example-buildyaml)
• [Repository layout](#repository-layout)
• [Features](#features)
• [Supported environments](#supported-environments)
• [CLI](#cli)
• [REST API](#rest-api)
• [Documentation](#documentation)
• [Try the demos](#try-the-demos)
• [Contributing](#contributing)
• [License](#license)

What is Granite.Build?

Granite.Build orchestrates LLM build pipelines. You describe your workflow in a build.yaml file — which models to download, how to fine-tune them, what evaluations to run — and Granite.Build executes each step in the environment you choose: a local Docker container, a Kubernetes cluster, a cloud GPU instance, or a plain bash process on your laptop.

The system has three main components:

• gbserver — the orchestration server. It provides a REST API (/api/v1) for build management and a build watcher that polls for pending builds and dispatches them to execution environments. It stores build metadata in SQLite (standalone) or PostgreSQL (production).

• gb (gbcli) — the command-line client. It talks to the server's REST API to submit builds, list status, manage artifacts, and more.

• build.yaml — the pipeline definition. Each file declares a set of named targets (logical stages like "download", "fine-tune", "evaluate"). Each target specifies an execution environment, input/output artifacts, and one or more steps to run. Targets can depend on each other through artifact bindings — when an upstream target produces an output, downstream targets that reference it are automatically dispatched.

How the pieces fit together

flowchart LR
BY@{ shape: doc, label: "build.yaml" } -->|"gb build start"| API["gbserver REST API"]
API --> BW["BuildWatcher"]
BW --> BR["BuildRunner"]
BR --> Docker
BR --> Kubernetes
BR --> Bash
BR --> RunPod
BR --> SkyPilot
Docker & Kubernetes & Bash & RunPod & SkyPilot --> AS["Artifact stores(HuggingFace, file://, git://)"]

classDef white fill:#fff,color:#000,stroke:#999
class BY white

The BuildWatcher polls storage for pending builds and creates a BuildRunner for each one. The build runs in an associated Space providing environments, credentials, artifact stores and step implementations.

The buildrunner walks the target graph, resolving dependencies and launching steps through the configured Environment (Docker, Kubernetes, Bash, RunPod, or SkyPilot). Each step can pull inputs from and push outputs to artifact stores selected by URI scheme (hf://, file://, git://, cos://).

Granite.build can be configured to run in the cloud or on the local machine. A cloud-based configuration can be seen [here](docs/images/architecture-cloud.jpg). Most of what follows utilizes the standalone configuration, shown below.

Quick start (standalone)

Five commands to a running build, using the bundled standalone-quickstart sample.

In a new terminal, run the following:

# 1. Clone and enter the repo
git clone git@github.com:ibm-granite/granite.build.git
cd granite.build

# 2. Create the venv and install (no Artifactory or cloud creds needed)
make standalone-venv PYTHON=python3.13
source .venv/bin/activate

# 3. Start the standalone server, pointed at the in-repo local space
gbserver standalone --space-dir configurations/spaces/local

In a second terminal, run the build using the servers started above:

# 4. Activate the venv and submit the sample build
cd granite.build
source .venv/bin/activate
export GB_ENVIRONMENT=STANDALONE
gb build start -f samples/standalone/standalone-quickstart/build.yaml

# 5. Watch progress
gb build status
gb build log

The sample runs a single step in a local bash process — no Docker required. To switch backends, edit the environment_uri line in [samples/standalone/standalone-quickstart/build.yaml](samples/standalone/standalone-quickstart/build.yaml); the file has bash, docker, runpod, and skypilot options pre-commented.

> Auth note (skip for localhost): when the client and server are both on the same host, gbserver allows unauthenticated access from 127.0.0.1 / ::1 and the quickstart above just works. If you're running gbserver on a remote box (or hitting auth errors), set a shared secret in both terminals before running steps 3 and 4: > > ``bash > export GBSERVER_API_KEY="my-secret-key" # same value in both terminals >

For a longer walkthrough of the same path, see [docs/getting-started.md](docs/getting-started.md).

Example build.yaml

A minimal pipeline that runs a single step in a Docker container:

llm.build: # alias: granite.build (both keys are accepted)
name: my-build
targets:
download:
environment_uri: space://environments/docker
inputs:
model:
uri: hf://huggingface.co/ibm-granite/granite-3.3-2b-instruct
outputs:
model:
uri: file:workspace/model
steps:
- step_uri: space://steps/somestep

A multi-target pipeline chains stages through bindings:

llm.build:
name: tune-and-eval
targets:
download:
environment_uri: space://environments/docker
outputs:
model: { uri: file:workspace/model }
steps:
- step_uri: space://steps/somestep
fine-tune:
environment_uri: space://environments/docker
inputs:
model: { binding: download.model }
outputs:
checkpoint: { uri: file:workspace/checkpoint }
steps:
- step_uri: space://steps/sft
evaluate:
environment_uri: space://environments/docker
inputs:
model: { binding: fine-tune.checkpoint }
steps:
- step_uri: space://steps/eval

For the full schema, see [docs/users/build-yaml-reference.md](docs/users/build-yaml-reference.md).

Repository layout

| Path | Description | |------|-------------| |…