> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/sdk-getting-started/sdk-api-reference/module-functions.md).

# Module functions

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

## rc.login

```python
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

```python
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

```python
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

```python
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`](/api-and-integrations/sdk-getting-started/sdk-api-reference/graph.md#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

```python
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`](/api-and-integrations/sdk-getting-started/sdk-api-reference/twin.md#twin), trained parameters included.

## rc.render\_widget

```python
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

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