Metadata-Version: 2.4
Name: orion-ui
Version: 0.18.1
Summary: Python authoring API for Orion-native notebook UI outputs
Author: Nicolas Fonteyne
License: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# orion-ui

Python library for building interactive notebook UI in [Orion](https://www.orion-agent.ai). Author controls in a code cell with `import orion_ui as ui`; Orion renders them as native notebook outputs.

This package is separate from **`orion-notebook`** (the `orion` CLI). Install `orion-ui` into the **same Python environment as your notebook kernel**.

## Install

```bash
pip install orion-ui
```

### Orion managed runtime

If you start Orion with `orion` and use its managed Jupyter environment (`~/.orion/runtime/venv` on macOS/Linux, `%USERPROFILE%\.orion\runtime\venv` on Windows), **`orion-ui` is installed automatically**. You do not need a separate install.

### External kernel (conda, venv, your own Jupyter)

Install into that kernel's Python:

```bash
python -m pip install orion-ui
```

Then restart the notebook kernel and re-run your cells.

## Quick example

Put a component tree as the **last expression** in a code cell:

```python
import orion_ui as ui

ui.card(
    ui.stack(
        ui.select("model", ["gpt-4.1", "claude-sonnet"], label="Model", default_value="gpt-4.1"),
        ui.slider("temperature", label="Temperature", min=0, max=2, default_value=0.7, step=0.1),
    ),
    title="Controls",
    class_name="controls-card",
)
```

Read values in later cells:

```python
model = ui.get("model")
temperature = ui.get("temperature")
```

## Run cells when a control changes

Every user-editable, state-bound control accepts an optional `on_change`
action. Target cells must already have stable Orion cell ids:

```python
ui.date_picker(
    "start_date",
    label="Start date",
    on_change={
        "type": "execute_cells",
        "cellIds": ["stable-orion-cell-id"],
    },
)
```

Orion writes the new value to Python state before running the target cells.
Selections, presets, and keyboard nudges run immediately. Typing waits 500 ms
after the latest edit, while slider and date-range dragging wait 250 ms. Use
`debounce_ms=0` for immediate execution or another non-negative millisecond
value to override the default. Date ranges run only after both endpoints are
selected, and `ui.date_time_picker()` applies one action to its date, start
time, and end time values.

The supported controls are `ui.input`, `ui.textarea`, `ui.select`,
`ui.slider`, `ui.checkbox`, `ui.switch`, `ui.radio_group`, `ui.toggle`,
`ui.toggle_group`, `ui.calendar`, `ui.date_picker`,
`ui.date_range_slider`, and `ui.date_time_picker`. Prefer an explicit
`ui.button(..., action=...)` when running cells is expensive or destructive.

## DataFrame tables

Use `ui.table()` for interactive pandas DataFrame browsing without sending the
entire DataFrame to the frontend:

```python
import orion_ui as ui

ui.table(
    df,
    source="df",
    page_size=50,
    default_filters=[
        {"column": "status", "operation": "equals", "value": "active"},
    ],
    default_sort={"column": "score", "direction": "desc"},
    column_descriptions={
        "score": "Priority score from 1 to 10.",
        "status": "Current account status.",
    },
)
```

Table filtering, sorting, grouping, stats, and export requests run in the
Python kernel. Saved table views are stored on the notebook output metadata as
structured operations plus a readable pandas expression.
Column descriptions, when provided, appear as info-icon tooltips in table
headers.

Use `default_filters` and `default_sort` to set the table's initial operations.
`default_filters` accepts the same `column`, `operation`, and `value` shape as
the filter menu; `default_sort` accepts one `column` and `direction` (`"asc"`
or `"desc"`). Resetting the Default view restores these defaults.

Filter operations and controls follow each pandas column's semantic dtype.
Text columns provide text matching, ordered numeric and temporal columns
provide comparisons and inclusive `between`, booleans use a true/false
selector, and bounded categoricals support `in` and `notIn`. Range filters use
`{"lower": "...", "upper": "..."}` as their value, while categorical set
filters use a list of values. Date and datetime values use ISO syntax:

```python
default_filters=[
    {
        "column": "created_at",
        "operation": "between",
        "value": {
            "lower": "2026-01-01T00:00:00",
            "upper": "2026-01-31T23:59:59",
        },
    },
]
```

`class_name` adds semantic CSS hooks for Orion UI in Notebook View and App View. Do not write CSS into notebook metadata; if a notebook needs custom styling, include it in the relevant cell source/output and scope selectors to rendered markdown/output areas. Orion also exposes JupyterLab-compatible rendered-content selectors such as `.jp-MarkdownOutput`, `.jp-RenderedHTMLCommon`, and `.jp-OutputArea-output` for cell-authored styles. Do not rely on arbitrary Tailwind classes generated at runtime.

## Requirements

- Python 3.8+
- [Orion](https://www.orion-agent.ai) (or another frontend that renders `application/vnd.orion.ui+json`) for interactive display

Other Jupyter frontends may show a static fallback instead of live controls.

## Version coupling

Pin `orion-ui` to the same version as your Orion app when using managed runtimes (for example `orion-ui==0.6.0`). The Python output format and Orion's renderer are released together.

## Links

- [Orion website](https://www.orion-agent.ai)
- [User docs](https://docs.orion-agent.ai)
- [Fix: orion_ui import error](https://docs.orion-agent.ai/troubleshooting/orion-ui-import-error.html)
- [orion-notebook on PyPI](https://pypi.org/project/orion-notebook/) (CLI launcher)

## License

Apache-2.0
