Rebase Toolkit

Python client and toolkit for the Rebase Platform.

The toolkit is intentionally small by default: it contains the API-key client, SDK handles for functions and workflows, and optional entry points for Rebase's energy data/modeling packages. It does not run a database or platform backend locally.

Install

During early development, install directly from GitHub into a clean uv environment:

uv venv .venv
source .venv/bin/activate
uv pip install "rebase-toolkit @ git+ssh://git@github.com/rebase-energy/rebase-toolkit.git@master"

Install from a branch by replacing master with the branch name:

uv pip install --upgrade "rebase-toolkit @ git+ssh://git@github.com/rebase-energy/rebase-toolkit.git@my-branch"

Once the package is published to PyPI:

pip install rebase-toolkit

The rebase PyPI project is a compatibility metapackage that installs the same toolkit:

pip install rebase

When releasing to PyPI, publish rebase-toolkit first, then publish the alias package from pypi/rebase with the same version:

uv build
uv build --project pypi/rebase

For local development:

uv sync --dev

To smoke-test a fresh install from this checkout before pushing:

scripts/smoke_uv_install.sh local

To smoke-test a GitHub ref:

REBASE_TOOLKIT_GIT_REF=master scripts/smoke_uv_install.sh github

Optional data/modeling packages:

uv pip install "rebase-toolkit[data]"
uv pip install "rebase-toolkit[modeling]"
uv pip install "rebase-toolkit[hillclimb]"
uv pip install "rebase-toolkit[all]"

Configure

rebase setup

The setup command asks for a Rebase API key and stores it in ~/.rebase/config.json. The hosted Rebase API URL is built into the SDK, so normal user code does not need an API URL or API key argument.

You can select a named local profile when needed:

rebase setup --profile prod

For fast local development against a locally running workflow API, start the API from the platform checkout and run the editable toolkit setup helper:

cd /Users/sebaheg/Documents/Github/platform/workflows
./scripts/dev_api.sh

cd /Users/sebaheg/Documents/Github/platform/rebase-toolkit
./scripts/dev_setup_local.sh --print-command
./scripts/dev_setup_local.sh

The helper waits for http://127.0.0.1:18082/health and then runs:

uv run rebase setup --force-auth --api-url http://127.0.0.1:18082

Common overrides:

REBASE_DEV_PROFILE=local ./scripts/dev_setup_local.sh
REBASE_DEV_PROVIDER=github ./scripts/dev_setup_local.sh
REBASE_DEV_REPO=sebaheg/toolkit-test REBASE_DEV_GITHUB=1 ./scripts/dev_setup_local.sh

For local development against the internal deployed workflow API, port-forward the API and store that URL in the profile:

kubectl -n rebase-workflows port-forward svc/workflow-mvp-api 8080:8080
rebase setup --api-url http://127.0.0.1:8080

rebase workspace list
rebase workspace switch prod

Minimal Function

import rebase as rb

project = rb.project("first-user")


@project.function()
def add(a: int = 0, b: int = 0) -> dict:
    return {"sum": a + b}


project.deploy()

run = add.spawn(a=2, b=3)
print(run.result(timeout=120))

Minimal Workflow

import rebase as rb

project = rb.project("forecasting")


@project.step()
def load_weather(site_id: str) -> dict:
    return {"site_id": site_id}


@project.step()
def build_forecast(weather: dict, horizon_hours: int = 24) -> dict:
    return {"weather": weather, "horizon_hours": horizon_hours}


@project.workflow()
def forecast(site_id: str = "site-001", horizon_hours: int = 24) -> dict:
    weather = load_weather(site_id)
    return build_forecast(weather, horizon_hours=horizon_hours)


project.deploy()
print(forecast.remote(site_id="site-001"))

Deploy a file from the command line:

rebase deploy workflow.py

Run a function from local source and force the interactive backend:

rebase run functions.py::add --backend interactive --param a=2 --param b=3

If the file contains exactly one Rebase function, the function name can be omitted:

rebase run functions.py --parameters-json '{"a": 2, "b": 3}'

Models

rebase.Model is the shared base for model metadata and deployment config. Deployable models use typed emflow-style subclasses such as rebase.Predictor, rebase.Optimizer, and rebase.Agent.

import rebase


class PriceForecastPredictor(rebase.Predictor):
    name = "price-forecast"

    def predict(self, zone: str = "SE3", horizon_hours: int = 24) -> dict:
        return {"zone": zone, "horizon_hours": horizon_hours}


model = PriceForecastPredictor()
rebase.deploy(model)

Call a deployed model through its generated predict endpoint:

model = rebase.get_predictor("default/price-forecast")
result = model.predict.remote(zone="SE4")

Hillclimb Searches

rebase hillclimb runs agentic model searches with rebase-hillclimb: coding agents draft, debug, improve, and ensemble emflow Predictor classes; every candidate is backtested leakage-safe on the problem's validation split and the winner is selected on a hidden holdout. Requires the hillclimb extra.

Start a search — hosted on the platform by default (a long-running Cloud Run job), or on your own machine with --local:

rebase hillclimb start emflow://gefcom2014:solar --budget 2h
rebase hillclimb start emflow://gefcom2014:solar --budget 2h --local

Any problem in emflow's registry is a valid target (emflow://<name>), as are plain hillclimb problem folders. --backend dummy runs the search loop without agent calls (smoke tests).

Watch and control a hosted search — its state (candidate tree, scores, budget) syncs to the workspace artifacts bucket every ~30 s:

rebase hillclimb list
rebase hillclimb status <run-id>   # candidates, best score, budget left
rebase hillclimb stop <run-id>     # graceful: parks after the current operator

When the search finishes, promote the selected model into your workspace repo as versioned source, then deploy it like any other model:

rebase hillclimb promote <run-id>            # writes models/<problem_id>.py
# review, commit, open a PR (protected environments deploy through gitops)
rebase model deploy models/gefcom2014_solar.py

The promoted file exposes get_model() -> emflow.Predictor — the same class that won the backtest is what serves in production.

Hosted searches bill agent calls to the workspace's configured Claude credentials (a CLAUDE_CODE_OAUTH_TOKEN for subscription billing, or an API key); --local searches use your local Claude login. Search state lives under gs://<artifacts-bucket>/hillclimb/<sync-id>/; set REBASE_HILLCLIMB_BUCKET to read it from the CLI. Server-side requirements (job image, secrets, artifacts bucket) are documented in platform/workflows/HILLCLIMB.md.

Dependencies

Function dependencies are declared with a Modal-like image builder:

image = rb.Image.python("3.13").uv_pip_install("boltons==24.0.0")


@project.function(image=image)
def add_with_boltons(a: int = 0, b: int = 0) -> dict:
    from boltons.iterutils import flatten

    return {"sum": sum(flatten([[a], [b]]))}

Data and Modeling Packages

The toolkit can expose optional emflow and EnergyDataModel modules through:

from rebase import data
from rebase import modeling

Install rebase-toolkit[modeling] to use emflow through rebase.modeling. Install rebase-toolkit[data] to import energydatamodel through rebase.data.