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]"

[all] covers every extra except [snowflake]: hillclimb requires pandas 3 and no stable snowflake-connector-python allows it yet, so the two cannot share an environment. Install rebase-toolkit[snowflake] on its own.

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 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.

Stitching and Forecast Windows

rebase.ForecastWindow is the standard vocabulary for a forecast run's target range: offsets relative to an issue time, in ISO-8601 durations (the compact "45m"/"2h" style also works). It survives the JSON round-trip through workflow parameters, and scheduled runs resolve it against ctx.fired_at so replays reproduce the original window:

import rebase as rb
from datetime import UTC, datetime

project = rb.project("forecasting")


@project.workflow(schedule=rb.Cron("0 * * * *"))
def forecast(ctx=None, window=rb.ForecastWindow(start="PT1H", end="P10D")) -> dict:
    window = rb.ForecastWindow.coerce(window)
    start, end = window.resolve(ctx.fired_at if ctx and ctx.fired_at else datetime.now(UTC))
    ...

rebase.stitch composes prioritised time series layers (pandas required): the first layer whose window covers a timestamp and whose value is non-null wins, lower layers only fill the gaps. Windows are [start, end) offsets relative to the issue time, or absolute timezone-aware datetimes. rebase.Exclude blocks fallback inside a window — deliberate nulls that lower layers must not fill (e.g. masking a storm week out of training data):

combined = rb.stitch(
    [
        rb.Layer(forecast_df, start="PT0H", name="forecast"),
        rb.Layer(history_df, end="PT0H", name="history"),
        rb.Exclude(start=uri_start, end=uri_end),
        rb.Layer(climatology_df, name="climatology"),
    ],
    issue_time=ctx.fired_at,
)

combined, sources = rb.stitch([...], issue_time=..., return_sources=True)

HTTP Endpoints

rb.endpoint gives a deployed function, model, or workflow a stable HTTP route. Auth defaults to api_key, so endpoints are not public unless you say so (auth also accepts "workspace" and "public"):

@rb.endpoint(method="POST", path="/forecast")
@rb.function(project="forecasting")
def forecast(zone: str = "SE3") -> dict:
    return {"zone": zone}

rebase api-key create forecast-agent
curl -X POST "$ENDPOINT_URL" -H "Authorization: Bearer rb_..." \
  -H "Content-Type: application/json" -d '{"zone": "SE3"}'

ASGI Apps

rb.asgi_app deploys a whole FastAPI/Starlette app instead of a single route. The decorated function builds and returns the app:

image = rb.Image.python("3.12").uv_pip_install("fastapi==0.141.1")


@rb.asgi_app(project="grid", name="grid-api", image=image)
def grid_api():
    from fastapi import FastAPI

    web_app = FastAPI()

    @web_app.get("/zones/{zone}")
    def read_zone(zone: str):
        return {"zone": zone}

    return web_app


rb.deploy(grid_api)

Two things to know when writing the app function, because its source is shipped and re-executed remotely:

• Import inside the function — module-scope imports must also resolve on the machine running deploy.
• FastAPI resolves annotations against module globals, so a name imported inside the function is invisible to it. Header/Query/Body parameters with plain types work; a request: Request parameter is silently read as a query parameter instead.

If the app does its own auth (auth="public"), carry the credential in a header other than Authorization: Rebase invokes the app with its own Google service account, whose token occupies Authorization. FastAPI's HTTPBearer and OAuth2PasswordBearer read that header and would validate the platform's token rather than your caller's. See ASGI Apps.

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.