> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bravenlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline scripts

> Full reference for the braven API as used inside a script Braven runs for you (not from your own machine).

This is the API surface available when your script runs **as a pipeline** — executed by the Braven worker against one experiment's files, rather than run directly on your own machine. See [Write a pipeline script](/guides/write-a-pipeline-script) for how execution works.

```python theme={null}
import braven

def process(braven=None):
    braven.log_config("lr", "0.001")
    braven.log_summary("acc", "0.94")
    braven.log_artifact("plot.png")
```

<Note>
  Defining a top-level `process(braven=None)` function is supported for backward compatibility; a plain top-level script (no wrapper function) works identically and is the simpler default.
</Note>

## Logging helpers

<ResponseField name="braven.log_config(key, value)" type="→ None">
  Queue an **input** parameter for this pipeline run. `value` is stored as a string — format numbers yourself, e.g. `f"{slope:.4f}"`.
</ResponseField>

<ResponseField name="braven.log_summary(key, value)" type="→ None">
  Queue an **output** metric for this pipeline run. Same string-value rule as `log_config`.
</ResponseField>

<ResponseField name="braven.log_series(key, values)" type="→ None">
  Queue a numeric list as a plottable Series (stored as JSON).
</ResponseField>

<ResponseField name="braven.plot_series(name, y, x=None, x_label=None, y_label=None, mode='line')" type="→ None">
  Log a labeled interactive-plot trace. Call again with the same `name` and a different `y_label` to group multiple traces onto one chart (e.g. one line per device on a shared axis).
</ResponseField>

<ResponseField name="braven.upload(path_or_fig, name=None)" type="→ None">
  Upload a file, or a live matplotlib `Figure`. A Figure is saved as a PNG and best-effort auto-extracted into an interactive companion (line/scatter data only — see [Series vs. Figures](/concepts/data-model)). Works from a bare top-level script exactly like it does in direct logging.
</ResponseField>

<ResponseField name="braven.log_artifact(path, name=None)" type="→ None">
  Upload a plain file attached to the pipeline's experiment. Equivalent to `upload()` for a non-Figure file; kept as a separate name for backward compatibility.
</ResponseField>

<ResponseField name="braven.device(key, type=None)" type="→ Device">
  Return a device-scoped handle — every value logged on it is tagged to that device instead of the whole experiment. See [Link a device](/guides/link-a-device).
</ResponseField>

## Reading experiment context

<ResponseField name="braven.files" type="dict[str, str]">
  Filename → local temp path, for every file attached to this experiment.
</ResponseField>

<ResponseField name="braven.path_params()" type="→ dict">
  Parses filenames in `braven.files` for common scientific naming conventions and returns them as a dict. Recognizes patterns like `30C` → `temperature`, `3v3` → `vdd`, `run_5` → `run_index`, `Sample_2` → `sample`, `10deg` → `angle_deg`, `2.4MHz` → `freq_mhz`, and similar.
</ResponseField>

<ResponseField name="braven.params" type="dict">
  Canonical parameter values already extracted for this experiment, if the pipeline has field mappings configured (raw CSV/column names mapped to canonical names). Missing keys return `None` with a printed warning rather than raising — safe to use even for experiments missing an expected column.
</ResponseField>

<ResponseField name="braven.column_maps" type="dict[str, str]">
  Raw → canonical column name map, populated the same way as `braven.params` — useful for `df.rename(columns=braven.column_maps)`.
</ResponseField>

## Removed helpers

<Warning>
  `braven.log(key, value)` and `braven.log_plot(fig, name)` (Plotly) are **removed**. Both still exist as stubs — calling them raises a `RuntimeError` with migration guidance, instead of an opaque `AttributeError`, since some older stored pipeline scripts still reference them.

  * Replace `braven.log(...)` with `braven.log_config(...)` or `braven.log_summary(...)` — state which one explicitly.
  * Replace `braven.log_plot(fig, name)` with `braven.upload(fig, name)` using a matplotlib Figure. Plotly is no longer the plotting API.
</Warning>

## Full cheat sheet

```python theme={null}
braven.log_config(k, v); braven.log_summary(k, v)
braven.log_series(k, values); braven.upload(fig_or_path, name)
braven.log_artifact(path, name=None)
braven.device(key, type=None).log_summary(k, v)
braven.path_params(); braven.files; braven.params; braven.column_maps
```