---

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:

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.