Daejeon, July 27–31
Keywords: Voyant Tools; Spyral notebooks; text analysis, large language models; interactive reading; reproducible workflows; text analysis pedagogy
Voyant Tools has long functioned as an on-ramp to computer-assisted interpretation: it lowers technical barriers while keeping analytic operations close to textual evidence through inspectable panels (concordances, collocates, trends, topic modeling, and related visualizations). The rapid normalization of large language models (LLMs), however, is reshaping what students and scholars expect to be able to do with text and how they expect to do it. For some it has become a sycophantic companion who can be prompted to do just about anything with data. In many emerging workflows, the LLM becomes an end-to-end substitute for analysis: users ask a model to interpret, classify, or summarize without making transparent what passages were examined, what assumptions guided the output, or how results could be challenged. This risks short-circuiting the pedagogical and scholarly value Voyant has traditionally offered—namely, a workflow where interpretive claims remain tethered to inspectable evidence.
This paper asks: how can contemporary AI be integrated into the Voyant ecosystem in a way that supplements—rather than supplants—hermeneutic practice? Our answer is a hybrid workflow that treats LLMs as modular components inside evidence-first pipelines. We ground this approach in the Hermeneutica account of computer-assisted interpretation, which argues that interpretive tools should augment and extend reading rather than replace it, and that the rhetorical presentation of analytics determines whether techniques can meaningfully assist interpretation (Rockwell & Sinclair, 2016). In that account, the main obstacle for computer-assisted interpretation is often rhetorical: technique is either encapsulated in a black box or presented in unusable detail, and both extremes impede interpretive uptake. Instead, analytic methods must become “part of reading” in forms that support exploratory, revisable argumentation.
Our strategy integrates LLM interactions in Spyral, Voyant’s notebook programming extension, rather than in a stand-alone tool or chatbot. Spyral (voyant-tools.org/spyral) allows users to combine explanatory prose, executable code, and embedded Voyant panels in a literate workflow (Knuth 1984). This makes the interpretative pipeline between Voyant and an LLM explicit and repeatable, showing: (1) evidence selection and transformation using Voyant services (e.g., extracting keyword-in-context windows, collocate lists, or topic summaries); (2) LLM annotation or synthesis at a precise point in the pipeline; and (3) return of structured outputs to tables and visualizations for inspection, critique, and recapitulation. By situating LLM calls inside code cells alongside the evidence that motivates them and documentation of the interpreter, Spyral supports the “show your work” ethos required for accountable computer-assisted interpretation.
Our paper will demonstrate three contributions: (a) a platform-agnostic LLM library for Spyral notebooks; (b) a staged tutorial suite of notebooks that teaches accountable LLM use; and (c) hybrid case studies that demonstrate how Voyant’s traditional analytics and LLM capabilities can be productively braided together.
LLM Library: Firstly, our project aims at providing a LLM library for Spyral. In the presentation we will describe the design and implementation of a lightweight JavaScript library that supports both commercial APIs and local models on macOS and Windows. The central design goal is provider agnosticism: notebooks should express analytical intent (chat, classify, summarize, extract) without hard-coding a vendor. Users configure a “provider” in a notebook settings cell (endpoint, model id, credentials, token limits, etc.), enabling the same notebook to run against a remote OpenAI-compatible service one day and a local model the next. This design responds to practical realities in DH: privacy constraints, institutional policy, cost, and the need for stable teaching environments.
To reduce black-box effects, the library is not just a general API wrapper. It exposes a small set of DH-oriented primitives:
Our other design goal is “structured data over prose.” Wherever possible, calls return JSON objects (labels, confidence or self-ratings, evidence pointers, and brief justifications). This enables immediate downstream use inside Voyant/Spyral using tables, filters, counts, timelines, and comparisons. Pedagogically, it reframes the LLM as a fallible annotator whose outputs are meant to be inspected and contested rather than treated as interpretation. Also, the library records provenance in-notebook: the exact prompt, parameters (temperature, max tokens), timestamps, provider/model identifiers, and a hash of the input payload. This provenance turns LLM use into a documented analytical move that can be rerun, compared across models, and critiqued. In short, the library aims to make LLM work compatible with hybrid, self-documenting hermeneutic workflows.
Tutorial: Secondly, we intentionally created a set of tutorial notebooks that will help users experiment with this integration of LLM and Spyral. These tutorial sequences are designed for humanities users with minimal programming experience and for instructors who want replicable classroom activities. Our tutorials emphasize a consistent pedagogical stance: LLMs are not authorities; they are tools whose outputs must be checked against the corpus evidence surfaced by Voyant panels.
Hybrid Case Studies: Finally, we present one of a set of case studies that show Voyant + LLM annotation and synthesis. Some of the case studies include:
Veliza as a pedagogical bridge from ELIZA to LLMs
Voyant’s Veliza tool offers a playful, inspectable re-imagining of ELIZA (Weizenbaum 1966) where users can “chat” while remaining aware that the apparent intelligence is produced by editable scripts and corpus statistics. We treat Veliza as a conceptual ancestor rather than an obsolete toy. The notebook pairs Veliza with an LLM call that is intentionally constrained: the model is only allowed to respond using passages retrieved from the corpus (with those passages displayed), making explicit the difference between scripted chatter, evidence-bounded synthesis, and unconstrained model improvisation. The point is not to replace Veliza with an LLM, but to use Veliza to teach interface skepticism and to stage “talking to the text” as a constructed, inspectable interaction.
Topic modeling with accountable LLM labelling
Topic models can yield statistically coherent term lists that remain semantically opaque, especially for newcomers. In this notebook, we run topic modeling in Voyant/Spyral, extract each topic’s top terms and representative passages, and ask the LLM to propose short labels under strict constraints: 2–4 words; no external knowledge claims; and an explanation that points to specific terms and passages motivating the label. The outputs populate a topic table (topic id, terms, evidence passages, proposed label, justification). Because results are structured, users can compare labels across providers/models, identify unstable topics, and explicitly mark disagreements as interpretive decisions rather than model facts. This preserves the statistical grounding of topic modeling while offering an accountable mechanism for semantic description.
Character description and sentiment across narrative time
Building on concordance-based reading, this notebook extracts all passages that mention a target character in a nineteenth-century novel. We then (i) use Voyant concordances and collocates to establish the character’s lexical neighborhood; (ii) partition passages by narrative time (chapters or equal-sized segments); (iii) apply classifyMany with a custom affective schema (e.g., Romantic, Ironical, Dismissive, Aggressive, Passive) defined in the notebook, prompting the model to return a label plus an evidence-based justification for each passage; and (iv) visualize label distributions over the text, comparing them against shifts in collocates and topic proportions. We close with a constrained synthesis: the LLM must draft a short character sketch that cites counts and exemplar passages from the table rather than general author knowledge. The notebook thereby treats LLM output as a kind of annotation layer that can be inspected, counted, and visualized—an interpretive aid rather than an interpretive replacement.
We conclude by returning to interface politics. LLM chat lowers barriers to computer assisted interpretation by offering conversational inquiry as an interface, but it invites confusion between corpus evidence and model priors. Voyant dashboards keep users close to evidence, but can feel mechanical to users habituated to chat. Our proposal argues for Spyral as a middle path: conversation is permitted, but it is anchored in explicit evidence and preserved as an analyzable history of moves. This stance aligns with research-tool design that frames interactivity as conversational while warning that visualization can hide what is “non-essential”—including the history of analytical filtering that would allow critique and recapitulation (Rockwell et al. 1999). By embedding LLM calls in a notebook that also displays the evidence being sent, we make the interpretive exchange interruptible, revisable, and auditable.