Docs · API reference

API reference.

Every public function in the waveassist runtime. Terse and complete, ordered the way an agent uses them.

Lifecycle

init

init(token=None, project_key=None, environment_key=None, run_id=None, check_credits=False) -> None

Initialize the runtime. Resolves token, project, environment, and run from arguments, env vars, or .env. Call once at the top of every node.

tokenYour UID. Falls back to env `uid`.

project_keyProject identifier. Falls back to env `project_key`.

environment_keyEnvironment. Defaults to `<project>_default`.

run_idCurrent run id. Injected by the runtime.

check_creditsIf True, raise when credits are exhausted.

returns None. Raises ValueError if token or project_key is missing.

import waveassist
waveassist.init()

set_worker_defaults

set_worker_defaults(token=None, project_key=None, environment_key=None, run_id=None) -> None

Set process-wide defaults used by later init() calls. For multi-project workers.

set_default_environment_key

set_default_environment_key(key: str) -> None

Set the default environment key for subsequent calls.

State

store_data

store_data(key, data, run_based=False, data_type=None)

Persist a value under a key. Carries state between runs. `data_type` is inferred when omitted.

keyString key.

dataString, JSON-serializable object, or a pandas DataFrame.

run_basedIf True, scope the value to the current run_id.

data_type"string" | "json" | "dataframe".

waveassist.store_data("last_review", review, data_type="json")

fetch_data

fetch_data(key, run_based=False, default=None)

Read a previously stored value. Returns `default` when the key is absent.

keyString key.

run_basedIf True, read the current run's scoped value.

defaultReturned when the key is missing.

pr = waveassist.fetch_data("pull_request", default={})

StoreDataType

StoreDataType = Literal["string", "json", "dataframe"]

The accepted `data_type` values for store_data.

Intelligence

call_llm

call_llm(model, prompt, response_model, should_retry=False, claude_cli_args=None, **kwargs) -> T

The wrapped model call. `response_model` is a Pydantic class, so the return is a typed, schema-locked instance. Same structure every run.

modelModel id, e.g. "anthropic/claude-haiku-4.5".

promptThe composed prompt string.

response_modelA Pydantic BaseModel subclass. The output JSON schema.

should_retryRetry once on a parse or transport failure.

**kwargsPassed through to the provider (temperature, etc.).

returns An instance of `response_model` (type T).

class Review(BaseModel):
    summary: str
    risk: str
    comments: list[str]

review = waveassist.call_llm(
    model="anthropic/claude-haiku-4.5",
    prompt=review_prompt(pr),
    response_model=Review,
)

Output

send_email

send_email(subject, html_content, attachment_file=None, cc=None, bcc=None, raise_on_failure=True) -> bool

Send an HTML email from the agent. Optional attachment, cc, bcc.

returns True on success.

publish_dashboard

publish_dashboard(html_content, data_key="dashboard_html", run_based=False) -> Optional[str]

Store an HTML dashboard and return a public shareable URL.

returns The public URL string, or None on failure.

Credits & run control

check_credits_and_notify

check_credits_and_notify(required_credits: float, assistant_name: str) -> bool

Verify enough runtime credit before doing costly work, notifying the owner if not.

returns True if credits are sufficient.

fetch_openrouter_credits

fetch_openrouter_credits() -> dict

Fetch the current project's credit balance.

mark_run_idle

mark_run_idle() -> bool

Flag the current run as idle: it executed but did no meaningful work. The dashboard collapses idle runs into a heartbeat. Absence of the flag means the run did work.

returns True on success.

is_test_run

is_test_run() -> bool

True during a dry/verify run, before the schedule arms. Use to guard side effects.

returns True on a test run, else False.