Concepts

Workspace

A workspace is the tenant boundary. User sign-in resolves to a Rebase profile and workspace membership, and every project, function, workflow, model, endpoint, and run is scoped to one workspace. API keys can also be created for direct API or agent access, and those keys are scoped to a workspace.

Workspaces have a source mode:

Project

A project is a namespace inside a workspace. Use projects for repo-level, product-level, or team-level grouping.

Function, workflow, model, and endpoint names are unique within a project. The same name can exist in another project, so cross-project references use both pieces:

rb.get_function("shared-energy-utils/normalize-weather")
rb.get_workflow("forecasting/site-forecast")

Projects can inherit workspace source settings or override them. In a workspace repo layout, a project usually stores repo_path, such as projects/forecasting.

Function

A function is a private SDK-callable Python callable. It belongs to one project and has a stable name plus a current immutable version.

Use functions for reusable computation that other projects may call through the SDK. Functions default to run_type="quick", which runs each call synchronously on an isolated private Cloud Run service with a tagged Cloud Run revision per immutable function version. Set run_type="long" when runs should execute as Cloud Run Jobs, or run_type="quick_shared" to use the shared runner path for trusted development workloads with the fastest cold start.

Isolated Cloud Run stores service metadata on the function and revision metadata on each function version:

Step

A step is a function that is also allowed inside a workflow definition.

@project.step(retries=2, timeout_seconds=60)
def load_weather(site_id: str) -> dict:
    return {"site_id": site_id}

Deploying a project registers steps as normal functions first. When a workflow calls a step handle, Rebase records a graph node that points at the current immutable function version for that step.

Workflow

A workflow is a pipeline-style callable. It belongs to one project and has a stable name plus a current immutable version.

Use workflows for multi-step orchestration and pipeline entrypoints. Workflows can call step handles in the same project, and those calls become a static graph on the workflow version.

@project.workflow(
    name="site-forecast",
    schedule=rb.Cron("0 6 * * *", timezone="Europe/Stockholm"),
)
def forecast(site_id: str = "site-001") -> dict:
    weather = load_weather(site_id)
    return {"weather": weather}

At runtime, Rebase executes the workflow graph as Prefect tasks. Rebase owns the SDK, versioning, API records, and source snapshots; Prefect owns the task DAG execution semantics.

Workflows default to run_type="quick": manual runs are submitted to a Cloud Run-hosted Prefect API and picked up by a warm Cloud Run service worker. Use run_type="long" when each workflow run should execute as a Cloud Run Job. Workflows accept quick or long; quick_shared is functions-only.

Execution Targets

Execution targets are mutually exclusive for workflows:

Functions always use source_code plus entrypoint, and function versions also store run_type, image_spec, and any Cloud Run isolation settings. run_type may be null on versions created before the run-type model was introduced.

Step workflows also store step_graph on the workflow version. The graph contains ordered nodes, input bindings, retry and timeout hints, and the exact function version ID for each step.

Disabled functions, workflows, and models can be updated and read, but triggering one returns 409.

Schedule

A schedule is an optional trigger on a workflow version. The SDK currently supports cron schedules:

@project.workflow(schedule=rb.Cron("0 6 * * *", timezone="Europe/Stockholm"))
def forecast() -> dict:
    return {"status": "ok"}

Deploying a scheduled workflow stores the schedule on the immutable workflow version and syncs a Prefect deployment for that workflow. When the cron fires, Prefect starts a scheduled runner, and the runner creates a normal Rebase run row before executing the workflow.

Cron schedules only define timing. Scheduled workflow runs use the workflow function defaults, so every workflow parameter must have a Python default before the workflow can be deployed with a schedule.

Removing the schedule from the decorator and redeploying removes the Prefect schedule for that workflow.

Versions

Function and workflow versions are immutable execution snapshots. Deploying a target computes a fingerprint from source, entrypoint, defaults, enabled state, dependency image spec, and provenance metadata.

Versions can include Git metadata when available:

Rebase always stores the executable source snapshot on the version, even when Git metadata is present.

Model Publication

A model publication records that an immutable Rebase model version was published to an external model or dataset repository. The first supported provider is Hugging Face.

Hugging Face publications are always tied to an immutable Rebase model version and the Hub commit returned by the upload. GitHub/Git sync is optional: when a clean git_commit_sha exists, Rebase can record it on the publication; if the model version has no Git metadata, the publication is still valid and is marked as published without source Git sync. Rebase only rejects a publication when a client explicitly submits a source_git_commit_sha that is dirty, unverifiable, or does not match the Rebase model version.

Endpoint

An endpoint is a stable HTTP route for a deployed function, workflow, or model. The target remains callable through the SDK, and the endpoint creates normal Rebase runs under the selected target version.

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

Endpoint routes are scoped by workspace and project:

/e/{workspace_id}/{project_name}/{endpoint_path}

Endpoint definitions store the current route and target pointer:

Deploying a target with an endpoint creates an endpoint version whenever the route, auth mode, response mode, target version, or enabled state changes.

Run

A run is an execution attempt for one function, workflow, or model. Runs include:

The server stores a run first, then dispatches it according to the run type. Model runs are model-native in Rebase metadata and use their linked backing Function version for execution. Function and model runs dispatch from the API layer straight to Cloud Run — synchronously for quick and quick_shared, as a Cloud Run Job execution for long. Workflow runs are submitted through the self-hosted Prefect API, which routes quick runs to the warm Cloud Run service worker and long runs to Cloud Run Jobs.

Run events are persisted status messages for packaging, backend submission, execution, and completion. Use run.events() in Python or rebase run logs <run-id> in the CLI to inspect them.

Step Run

A step run is the per-node execution record for a step workflow run. It includes the node key, step name, function version, status, attempt count, resolved parameters, normalized result, error, and Prefect task run ID.

run = forecast.spawn(site_id="site-001")

for step in run.steps():
    print(step["node_key"], step["status"])

Step runs are created by the workflow runner just before each Prefect task is submitted. Retries increment the step run attempt count.

Task

A step reports one outcome for everything inside it. When a step fans work out with Function.map, each item becomes a task of the run — one row per unit of work, with its own status, parameters, and result or error. Tasks are where "which one of them failed" survives a step that ran a thousand calls.

tasks = rb.Client().list_run_tasks(run.id)                            # whole run
tasks = rb.Client().list_run_tasks(run.id, step_run_id=step["id"])    # one step

Attribution is automatic: the runner injects REBASE_RUN_ID and REBASE_STEP_RUN_ID into the container's environment, and a Function.map issued inside a step attaches them to its batch. rebase.current_run() reads the same context and returns None outside the platform — a map from a laptop belongs to no run, which is accepted.

See Tasks and Artifacts for sequential, thread-pool, and platform fan-out examples.

Artifact

An artifact is a durable output pointer registered by user code with rb.artifact(...). Rebase stores the URI and descriptive metadata; the bytes stay in the object store, warehouse, report service, or other system that produced them.

uri = upload_forecast(...)
artifact = rb.artifact(
    "SE3 day-ahead forecast",
    uri=uri,
    key="forecast/SE3",
    media_type="application/parquet",
    size_bytes=218_420,
    metadata={"zone": "SE3", "rows": 24},
)

The active run, step, and task are inferred from runtime context. An artifact produced by a mapped function is owned by the parent workflow's Artifacts view while retaining the child function run as its producer. Use disposition="reused" for an output that already existed. Registration is strict during a hosted run: if the pointer cannot be recorded, ArtifactReportingError is raised instead of silently losing provenance. Calling rb.artifact locally validates the record but makes no API request.

See Tasks and Artifacts for artifact registration inside inline and mapped tasks.

Parameters

Parameters are plain JSON objects. The server merges them in this order:

parameters = {
    **target.default_parameters,
    **request.parameters,
}

Use version defaults for stable configuration and request parameters for per-run inputs.

Status Lifecycle

Function and workflow return values are normalized before storage: None becomes {}, dictionaries are stored as-is, and other values become {"value": result}.

Workspace Scoping

User sessions map to workspace memberships. API keys map to a workspace ID. List and get operations filter by the active workspace. A project, function, workflow, model, endpoint, or run from another workspace behaves like a missing resource.