Visualization

---
name: visualization
description: "Use LangExtract visualization to save, reload, inspect, and render
  AnnotatedDocument JSONL outputs without model inference."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# LangExtract Visualization

Use this sub-skill when the user already has LangExtract `AnnotatedDocument`
objects or saved JSONL output and wants to persist, reload, inspect, or render an
interactive HTML visualization without calling a model.

## Route first

- To create new extraction results with `lx.extract()`, read
  `../extraction/SKILL.md` first.
- For model IDs, API keys, Vertex/OpenAI batch settings, Ollama, or provider
  credentials, read `../providers/SKILL.md`.
- For frontend code changes beyond the HTML generated by LangExtract, treat the
  request as unsupported by this repo skill and explain that custom UI work is a
  gap.

## Common workflows

1. **Save one or more annotated documents to JSONL.** Use
   `lx.io.save_annotated_documents([doc], output_dir=..., output_name=..., show_progress=...)`.
   The default filename is `data.jsonl`; when `output_dir=None`, LangExtract
   writes under a relative `test_output/` directory. Prefer an explicit output
   directory in agent-written code.
2. **Reload JSONL for later inspection.** Use
   `lx.io.load_annotated_documents_jsonl(path, show_progress=...)` and
   materialize the iterator only when the file is small enough. Use
   `langextract.data_lib` conversions when you need JSON dictionaries rather
   than dataclass objects.
3. **Visualize a document or JSONL file.** Use `lx.visualize(doc_or_jsonl_path)`
   or `langextract.visualization.visualize(...)` with
   `animation_speed`, `show_legend`, and `gif_optimized` as needed. A JSONL path
   visualizes the first document in the file; load and select a document
   yourself for multi-document outputs.
4. **Write HTML safely.** In a notebook, the return value may be an
   `IPython.display.HTML` object with `.data`; in plain Python it is a string.
   Use `payload = html.data if hasattr(html, "data") else html` before writing.
5. **Check grounding before blaming visualization.** Only extractions with a
   usable `char_interval` can be highlighted. Missing or invalid intervals
   usually mean the extraction was ungrounded or manually constructed with bad
   offsets.

Read `references/workflows.md` for verified signatures, JSONL round trips,
selection patterns, and HTML writing details. Read
`references/troubleshooting.md` for save/load/visualization failures and their
fixes.

## Bundled helper

Run `scripts/save_and_visualize.py` when you need a no-model smoke helper that
creates a handcrafted `AnnotatedDocument`, saves JSONL, reloads it, generates
HTML, and writes all outputs under a caller-selected directory:

```bash
python scripts/save_and_visualize.py --output-dir ./lx-viz-demo
```

The helper does not require API keys, provider credentials, network access, or
source-repository files.

## Verification anchors

This guidance is based on the public README save/visualization snippets,
long-document and medication visualization examples, implementation behavior in
`langextract/io.py`, `langextract/visualization.py`, `langextract/data_lib.py`,
`langextract/progress.py`, and `langextract/core/data.py`, installed-package
signature inspection, and the safe native candidate families `io_test.py`,
`data_lib_test.py`, `visualization_test.py`, and `progress_test.py`.