Tributo

Ray-native machine learning SDK for distributed data, training, model bundles, and inference.

What Tributo provides

Tributo adds machine learning control-plane contracts on top of Ray. Ray owns distributed execution. Tributo validates requests, selects registered implementations, records credential-free provenance, and publishes verified model bundles.

• Submit and manage workloads through Ray Jobs.
• Read bounded data through explicit Ray Data or Daft bindings.
• Run distributed XGBoost, DNN, positive-unlabeled learning, and the formal algorithm execution contract through separately installed official algorithm Wheels.
• Publish validated, multi-format model bundles to local storage or S3.
• Run bundle-backed batch inference and Ray Serve HTTP or gRPC endpoints.
• Build, search, optimize, or compact Lance vector indexes as separate workflows.
• Produce batch explainability reports through registered adapters.

Tributo is an SDK, not a multi-tenant platform or Kubernetes control plane. See the documentation and support matrix for verified paths and explicit boundaries.

Quick start

Tributo 1.1.0 is a source-only GitHub Release; no PyPI distribution is published for this version.

Development checkouts on master declare 1.2.0.dev0. This development version does not determine the next published patch or minor version. Use a release tag for a fixed source snapshot and that snapshot's documentation.

git clone --branch tributo-1.1.0 --depth 1 https://github.com/jiangxt2/Tributo.git
cd Tributo
uv sync --locked --no-dev

Run Python and CLI commands through uv run --locked --no-sync so they use the release's locked environment.

from tributo import TributoClient

client = TributoClient("http://127.0.0.1:8265")
job_id = client.submit(entrypoint="python my_script.py")
print(client.get_status(job_id))

Read the full quickstart.

For a sealed Ray runtime containing the first-party dependency closure, see the runtime image guide.

Architecture

For a detailed map of current capabilities, planned work, and API stability guarantees, see the System Landscape, Architecture Documentation, and API Stability Inventory.

Installation

git clone --branch tributo-1.1.0 --depth 1 https://github.com/jiangxt2/Tributo.git
cd Tributo

# Each runtime profile below is an alternative. Combine extras in one uv sync.

# Core install
uv sync --locked --no-dev

# With training data, export, and storage dependencies
uv sync --locked --no-dev --extra training

# With BayesOpt search for Ray Tune
uv sync --locked --no-dev --extra tune

# With data formats (Lance / Iceberg)
uv sync --locked --no-dev --extra data

# With structured HiveServer2 table reads through Ray Data
uv sync --locked --no-dev --extra hive-ray

# With Hugging Face sources/exporters
uv sync --locked --no-dev --extra model-export-hf

# With Lance vector-index operations
uv sync --locked --no-dev --extra vector-index

# Development dependencies
uv sync --locked --extra dev

# Dual-engine files/tables and PostgreSQL
uv sync --locked --no-dev --extra data --extra data-daft --extra postgresql

Data sources

Data sources are opt-in extras where applicable. Install the extra for the dialect or backend you use:

Provider/binding presence is not a support claim. The canonical full image contains the locked v1.0 Doris connector packages, but the Ray ClickHouse route requires separately installing ray-clickhouse==1.0 from PyPI; that package remains outside Tributo's lock and canonical full image. These paths remain adapter-only until their real-database Conformance gates pass. HDFS still requires its own infrastructure gate. Hive is Ray-only, uses binary HiveServer2 transport, and does not imply native ORC/HDFS access or a Daft Hive route. Tributo never installs optional providers or bindings at runtime.

Modules

Formal distributed algorithms

Production implementations, including XGBoost, DNN, and PU learning, are distributed as independently versioned official algorithm Wheels. Install a compatible Wheel, confirm it appears in tributo algo list --json, and follow the formal algorithm guide.

Positive-unlabeled learning

The formal nnPU/uPU implementation uses the shared Ray Train/PyTorch DDP kernel with an explicit class prior and PU-specific fail-closed data checks. The Beta PUTrainerImpl compatibility entry delegates to the same distributed kernel and accepts one or more Ray Train workers. See the PU learning guide and support matrix.

Custom batch inference

Distributed inference with a user-supplied Ray BasePredictor, output to Parquet or Lance.

from tributo.inference import BasePredictor, InferenceConfig, run_batch_inference


class MyPredictor(BasePredictor):
    def _load_model(self):
        self.model = load_model_from_your_runtime()

    def __call__(self, batch):
        return predict_with_your_model(self.model, batch)


run_batch_inference(config, predictor_cls=MyPredictor)

ONNX inference serving

Ray Serve deployment for ONNX models with HTTP API.

uv run tributo serve start --model-path /path/to/model.onnx
uv run tributo serve status
uv run tributo serve stop

Batch inference

XGBoost + ONNX distributed batch inference.

from tributo.inference.pipeline import InferenceConfig, run_batch_inference

config = InferenceConfig(
    input_uri="s3://bucket/input.parquet",
    output_uri="s3://bucket/output/",
    model_uri="s3://bucket/model.onnx",
)
run_batch_inference(config)

Streaming LLM inference

SSE-based streaming inference for LLMs on Ray Serve.

uv run tributo serve streaming start --model-path /path/to/model --tokenizer-path /path/to/tokenizer
uv run tributo serve streaming status

Hyperparameter tuning with Ray Tune

Random search / BayesOpt with FIFO / ASHA / HyperBand schedulers. BayesOpt requires the optional tune extra (uv sync --locked --no-dev --extra tune); the full runtime image already contains it. Tune trials execute setup and fit only: they report the configured metric and checkpoint without publishing production Bundles. After selecting parameters, run the Trainer explicitly to publish the single production Bundle. Ray owns experiment and checkpoint state below the Tune output root's trials/ namespace; Tributo does not remove that recovery state. Treat the Tune output root as Ray-managed storage, not as a production Bundle destination.

uv run tributo tune run \
  --trainer xgboost \
  --config train_config.json \
  --space search_space.json \
  --output ./tune_results \
  --num-samples 50 \
  --search-alg bayesopt

Project structure

src/tributo/
├── __init__.py          # Public API (TributoClient, JobConfig, exceptions)
├── job.py               # TributoClient core
├── config.py            # JobConfig (Pydantic models)
├── exceptions.py        # Exception hierarchy
├── cli.py               # CLI entry point (Click)
├── _common/             # Shared utilities (runtime_env, IO, logging, Serve)
├── data/                # Ingestion, transforms, typed handles, and writing
├── algorithms/          # Formal distributed algorithm execution contracts
├── training/            # Trainer compatibility, XGBoost, DNN, PU, and Tune
├── exporting/           # Model bundle planning, validation, and publication
├── inference/           # Bundle-backed distributed batch inference
├── serving/             # Ray Serve HTTP, gRPC, and streaming transports
├── vector_index/        # Lance vector-index jobs and maintenance
├── explainability/      # Batch explanation planning and adapters
├── registry/            # MLflow tracking and registry integration
├── integrations/        # Optional framework, format, sink, and hook adapters
└── util/                # @PublicAPI decorator, stability annotations

Development

# Run tests
uv run pytest

# Format
uv run ruff check --fix src/ tests/
uv run ruff format src/ tests/

# Type checking
uv run mypy src/tributo

License

Apache 2.0. See LICENSE.