Module functions

The module-level session and the direct-mode entry points.

rc.login

rc.login(api_key: str | None = None, base_url: str | None = None) -> None

Authenticate the module-level session.

Credentials resolve in order:

1. an explicit api_key argument,

2. ROOTCAUSE_API_KEY, paired with ROOTCAUSE_BASE_URL,

3. a cached OAuth token in ~/.rootcause,

4. an interactive browser login (PKCE; on a remote kernel it prints a URL to paste a code back from).

A session with no terminal and no notebook kernel — a CI job, a scheduled script — never opens a browser: with no key and no cached token it raises rather than blocking on a login nobody can complete.

Parameter	Type	Default	Description
api_key	str | None	None	An API key (pk_...). When omitted, resolution falls through ROOTCAUSE_API_KEY, the cached OAuth token in ~/.rootcause/, then an interactive browser login with PKCE.
base_url	str | None	None	Deployment URL, for example https://sandbox.rootcause.ai. Falls back to ROOTCAUSE_BASE_URL, then the production default.

Raises

• AuthenticationError: No credentials, and no way to run a browser login here.

• InvalidArgumentError: base_url is not an http(s) URL.

rc.whoami

rc.whoami() -> dict[str, Any]

What the current credential is: ids, scopes, auth type, rate limit.

Returns (dict[str, Any]): userId, organisationId, workspaceId (the pin, or None for org-wide), scopes, authType, and rateLimit. Needs no scopes, so it is the cheap way to fail fast before starting a workflow.

rc.workspaces

rc.workspaces() -> pd.DataFrame

All workspaces the session can see.

Returns (pd.DataFrame): A DataFrame of id and name. The SDK's internal scratch workspace is excluded.

rc.discover

rc.discover(
    frame: pd.DataFrame,
    target: str | None = None,
    time: str | None = None,
    entity: str | None = None,
    kind: str | None = None,
    name: str | None = None,
    force: bool = False,
    timeout: float = 3600.0,
) -> Graph

Causal discovery on a DataFrame. Compute runs on the platform; nothing user-visible persists.

Uploads the frame (deduplicated by content hash), creates a twin directly over the uploaded source, runs discovery, and returns its graph. Identical data reuses the previously discovered twin instantly.

Parameter	Type	Default	Description
frame	pd.DataFrame	required	The data to discover over.
target	str | None	None	Outcome column of interest; recorded for downstream defaults.
time	str | None	None	Time column. Setting it makes the twin temporal.
entity	str | None	None	Entity or environment column. Setting it makes the twin multi-environment.
kind	str | None	None	One of static, temporal, multi-environment-static, multi-environment-temporal. Inferred from time and entity when omitted, and must agree with them when given.
name	str | None	None	Twin name on the platform. Derived from the data when omitted.
force	bool	False	Ignore the reuse cache and re-run discovery from scratch. The recovery path when a model is corrupt or predates an engine fix.
timeout	float	3600.0	Seconds to wait for the discovery job.

Returns (Graph): The discovered Graph.

Raises

• InvalidArgumentError: frame is not a usable, non-empty DataFrame, or target, time or entity names a column it does not have.

• KindMismatchError: An explicit kind contradicts time and entity.

• JobFailedError: Discovery ended in a terminal non-success state.

rc.load_twin

rc.load_twin(path: str | Path, timeout: float = 3600.0) -> Twin

Load a .rctwin export zip back into a runnable twin.

Parameter	Type	Default	Description
path	str | Path	required	Path to a .rctwin file written by Twin.save().
timeout	float	3600.0	Seconds to wait for the import job.

Returns (Twin): The imported Twin, trained parameters included.

rc.render_widget

rc.render_widget(widget: dict[str, Any], theme: str = 'light') -> str

Render a widget payload to a self-contained HTML fragment via the platform renderer.

Parameter	Type	Default	Description
widget	dict[str, Any]	required	A widget payload as emitted by the agent and MCP tools.
theme	str	'light'	light or dark.

Returns (str): The HTML string.

Raises

• RootCauseApiError: The payload has no session-less rendering. The error lists the renderable kinds.

rc.auto_apps

rc.auto_apps(enabled: bool | None = None) -> bool

Whether displayed result objects mount their interactive app.

On by default. Off, every object falls back to its static HTML repr — the right setting for headless notebook executors and exported documents. ROOTCAUSE_AUTO_APPS=0 sets the same switch from the environment.

Parameter	Type	Default	Description
enabled	bool | None	None	Pass True/False to change the setting; omit to just read it.

Returns (bool): The setting now in effect.