Task variables (qualia)

When you have multiple agents working on a research problem, they often need to share information — one task produces a result that another task uses as input. Qualia’s task-variable evidence system passes those values between tasks through the qualia package, which is available in every notebook kernel and in every script an agent runs.

How it works

The basic flow:

Declare required variables on a task
Assign values in a notebook cell (just use the variable name)
Capture happens automatically when the cell runs
Other agents read values in downstream tasks with qualia.get()

Reading captured evidence

In a downstream task’s notebook, read values captured by upstream tasks. The qualia namespace is already in scope — no import needed:

# Python — pandas DataFrame indexed by (notebook_id, variable_name)
df = qualia.get(variable_names=["accuracy", "best_model"])

# R — data.frame
df <- qualia_get(variable_names = c("accuracy", "best_model"))

# Julia — vector of records
records = Qualia.get_evidence(variable_names = ["accuracy", "best_model"])

To recover a value scoped to one task (for example after a kernel reset, or in a fresh subagent), use the typed read:

rows = (await qualia.get_evidence(task_id="T-1", variable_names=["accuracy"]))["rows"]

Capturing variables

In a notebook, variables are captured from cells automatically:

Define required variables when creating a task
Run code that assigns values to those variable names
Qualia captures the values when the cell executes

For example, if a task requires best_model and accuracy:

best_model = "random_forest"
accuracy = 0.94

After this cell runs, both values are captured and available to downstream tasks. You can also be explicit, from the cell that produced the value:

await qualia.submit_variable(variable_name="accuracy", value=accuracy)

The value fills the matching required variable on each active task in the chat. For an interesting value the task did not declare, record it as evidence without filling a slot:

await qualia.add_evidence(
    "class_counts",
    description="Counts per class in the training set",
)

Pass recall_priority ("low" by default, up to "high") when the value is something later agents should be shown rather than have to go looking for. See recall priority.

Captured variables become runtime-captured claims in the Knowledge System, creating a documented trail of data flow.

Capturing from a script

Scripts use the same package. There is no cell boundary, so there is no automatic capture — the script submits before it exits — and it imports the client itself. The qualia methods are async. Notebook cells can await them directly because IPython enables autoawait, but a script has to run them itself: top-level await is a SyntaxError outside a cell.

import asyncio
import qualia

async def main():
    accuracy = train_and_eval(...)
    await qualia.submit_variable(variable_name="accuracy", value=accuracy)

asyncio.run(main())

Use await when calling asynchronous capture methods; without it, the value is not captured.

R and Julia work the same way, with one difference worth knowing. Julia cannot read a calling function’s local variables by name, so add_evidence there is a macro:

using Qualia
Qualia.@add_evidence class_counts description="Counts per class"

A script claim points at the line of the script that produced the value, the way a notebook claim points at its cell. That line is re-checked whenever the claim is read, so editing the script past it marks the source as changed.

Saving a figure from a script

Use save_figure to save a chart from a script with its underlying values, so captured figures support data inspection.

import matplotlib.pyplot as plt
import qualia

fig, ax = plt.subplots()
ax.plot(folds, rmse)
qualia.save_figure(fig, "figures/rmse_by_fold.svg")

source(Sys.getenv("QUALIA_R_SOURCE_PATH"))
qualia_save_figure(p, "figures/rmse_by_fold.svg")

using Qualia
Qualia.save_figure(plt, "figures/rmse_by_fold.svg")

A few things worth knowing:

It is a drop-in for the library’s own save. Extra arguments — dpi, bbox_inches, width — pass straight through, and the call returns the path it wrote.
Save to a path inside your workspace, and prefer SVG: it prints at any size and keeps its text as text.
The library’s own save still works, and the figure can still be captured — it just arrives as a picture with nothing behind it.
Plotly, Altair, and ggplot2 additionally produce a live chart, which is stored alongside the image and stays pannable and zoomable.
For Python Plotly in scripts, use fig.write_json("figures/name.plotly.json") and capture that file with capture_figure_file, naming the producing script. Embed the returned claim in a writeup with [[figure:C-123]] in its own paragraph.
Static Matplotlib and ggplot2 saves need no extra exporter. Altair image saves require vl-convert-python.

Evidence values

Record computed values from the notebook or script that produced them. This keeps the value’s precision and a link to its source.

When tasks use variable evidence

Most useful when:

Chaining experiments: One task trains a model, another evaluates it
Aggregating results: Multiple parallel tasks produce metrics, a final task compares them
Parameterized workflows: Pass configuration between stages

Example workflow:

T-1: Load and clean data → cleaned_rows
T-2: Train model A → model_a_accuracy (depends on T-1)
T-3: Train model B → model_b_accuracy (depends on T-1)
T-4: Compare models (depends on T-2, T-3)
     → qualia.get(variable_names=["model_a_accuracy", "model_b_accuracy"])

Exporting notebooks

When you export a notebook for standalone use, Qualia replaces qualia.get() calls (and the R/Julia equivalents) with their actual values. The exported notebook runs without Qualia — all variable references are resolved to concrete data, so it works in other IDEs such as JupyterLab and VS Code.

Supported values

The system supports:

Python, R, and Julia, in notebooks and scripts
Primitive values: numbers, strings, booleans, and homogeneous lists of those. Dicts, DataFrames, and other complex objects are rejected — capture separate scalar variables instead
Shared task results: a captured value fills the matching required variable on each active task in the chat

Welcome

Core Features

Research Workflow

Tools

Customization & Settings

Interface

Task variables (qualia)

How it works

Reading captured evidence

Capturing variables

Capturing from a script

Saving a figure from a script

Evidence values

When tasks use variable evidence

Exporting notebooks

Supported values

​How it works

​Reading captured evidence

​Capturing variables

​Capturing from a script

​Saving a figure from a script

​Evidence values

​When tasks use variable evidence

​Exporting notebooks

​Supported values

How it works

Reading captured evidence

Capturing variables

Capturing from a script

Saving a figure from a script

Evidence values

When tasks use variable evidence

Exporting notebooks

Supported values