nveil (top-level)¶

Module-level functions for configuring the SDK 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, or compatible input. 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 SDK 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, or list of lists. 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 (require kaleido), .html

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`	Image width in pixels. TYPE: `int` DEFAULT: `1200`
`height`	Image height in pixels. TYPE: `int` DEFAULT: `800`
`scale`	Font/margin scale factor. 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'`