nveil (top-level)¶

Module-level functions for configuring the Toolkit and generating specs.

configure ¶

configure(api_key, base_url='https://app.nveil.com', verify=True, verbose=False, timing=False, **kwargs)

Configure the global NVEIL client.

PARAMETER	DESCRIPTION
`api_key`	Your NVEIL API key (starts with `nveil_`). TYPE: `str`
`base_url`	NVEIL server URL (default: `https://app.nveil.com`). TYPE: `str` DEFAULT: `'https://app.nveil.com'`
`verify`	Verify SSL certificates (set `False` for local dev with self-signed certs). TYPE: `bool` DEFAULT: `True`
`verbose`	Enable internal library logging (default: silent). TYPE: `bool` DEFAULT: `False`
`timing`	Enable timing instrumentation (default: `False`). TYPE: `bool` DEFAULT: `False`

session ¶

Scoped session — owns a temporary workspace for the duration of a with: block.

Usage::

with nveil.session() as s:
    spec = s.generate_spec("bar chart of revenue", df)
    fig = spec.render(df)    # reuses the same workspace — no re-run
    nveil.show(fig)
    print(s.timer.summary())
# workspace cleaned up here

Session ¶

Session(client=None, timing=False)

Scoped workspace session.

The session owns a temporary workspace and a pipeline instance. generate_spec builds and runs the pipeline once; subsequent render() calls reuse the already-computed outputs.

When timing=True, all operations are tracked in self.timer.

generate_spec ¶

generate_spec(prompt, data)

Generate a visualization specification.

All internal processing is done by the compiled engine. The session keeps the pipeline instance alive for render() reuse.

If the server-generated data pipeline fails locally, retries with a new server call (the plan is non-deterministic).

PARAMETER	DESCRIPTION
`prompt`	Natural language visualization request. TYPE: `str`
`data`	pandas DataFrame, dict of DataFrames, path (`str` / `pathlib.Path`) to a CSV/Parquet/JSON/Excel file, or a dict mixing those types. TYPE: `Any`

RETURNS	DESCRIPTION
`NveilSpec`	NveilSpec bound to this session's workspace.

generate_spec ¶

generate_spec(prompt, data)

Generate a visualization specification from data and a prompt.

Only metadata leaves your machine — never raw data. All internal processing is handled by the compiled engine.

If the server-generated data pipeline fails locally, the Toolkit retries with a new server call (the plan is non-deterministic).

PARAMETER	DESCRIPTION
`prompt`	Natural language description of the desired visualization. TYPE: `str`
`data`	pandas DataFrame, dict of DataFrames, numpy array, list of lists, or a path (`str` / `pathlib.Path`) to a CSV / Parquet / JSON / Excel file. A dict of paths is also accepted for multi-dataset inputs. Path inputs avoid holding the DataFrame in your process — the engine registers them as disk-backed choregraph inputs. TYPE: `Any`

RETURNS	DESCRIPTION
`NveilSpec`	NveilSpec that can render locally and be saved/reused.

load_spec ¶

load_spec(path)

Load a spec from an opaque .nveil file.

No API call — loaded specs can be rendered locally for free.

PARAMETER	DESCRIPTION
`path`	Path to a `.nveil` file. TYPE: `str`

RETURNS	DESCRIPTION
`NveilSpec`	NveilSpec ready to render.

show ¶

show(fig, theme='dark')

Display a figure in the default browser.

PARAMETER	DESCRIPTION
`fig`	Figure object returned by `NveilSpec.render()`. TYPE: `Any`
`theme`	Display theme ("dark" or "light"). TYPE: `str` DEFAULT: `'dark'`

save_image ¶

save_image(fig, path, theme='dark', width=1200, height=800, scale=1)

Save a figure as a static image.

Format is inferred from the file extension. Supported: .png, .jpg, .svg, .pdf, .html, .json

Raster / vector formats (png, jpg, svg, pdf) render the figure via a headless Chromium instance provided by Playwright. The first run downloads Chromium one time (~170 MB); after that exports are local and offline.

PARAMETER	DESCRIPTION
`fig`	Figure object returned by `NveilSpec.render()`. TYPE: `Any`
`path`	Output file path (e.g. `"chart.png"`). TYPE: `str`
`theme`	Export theme ("dark" or "light"). TYPE: `str` DEFAULT: `'dark'`
`width`	Output image width in pixels. Always honored exactly — this is the final pixel dimension of the saved file. TYPE: `int` DEFAULT: `1200`
`height`	Output image height in pixels. Same contract as `width`. TYPE: `int` DEFAULT: `800`
`scale`	Font / zoom factor — how large text and chart elements appear relative to the chart area. Internally mapped to Chromium's `deviceScaleFactor`: the CSS viewport shrinks to `(width / scale, height / scale)` while the rasteriser multiplies back to `width × height` device pixels. At `scale=2` text looks twice as prominent inside the same chart, not twice as many pixels. `scale=1` is the native layout; values above 2 rarely add visual quality. TYPE: `int` DEFAULT: `1`

save_html ¶

save_html(fig, path, theme='dark')

Save a figure as an interactive HTML file.

PARAMETER	DESCRIPTION
`fig`	Figure object returned by `NveilSpec.render()`. TYPE: `Any`
`path`	Output file path (e.g. `"chart.html"`). TYPE: `str`
`theme`	Export theme ("dark" or "light"). TYPE: `str` DEFAULT: `'dark'`