Skip to main content
Use the qualia package to record values your code computes as evidence, and to read those values back in later tasks. It works in Python, R, and Julia, in notebook kernels and in scripts an agent runs. A task is one step of the research plan, and a task can list required variables, the named results it must produce. A captured value becomes a runtime-captured claim: a fact in the knowledge system that links back to the cell or script line that produced it. See Tasks for how agents plan tasks.

How capture works

Qualia records a variable’s value only by reading it out of running code. Neither you nor an agent can type a value in as variable evidence. That way, every captured value traces back to the code that computed it.
  1. An agent creates a task with required variables, such as best_model and accuracy.
  2. Code in a notebook cell or script assigns those names.
  3. Qualia reads the values from the running kernel or script and records them as claims.
  4. A later task reads the values with qualia.get() instead of recomputing them.

Capture a required variable in a notebook

In a notebook, you don’t call anything. When a cell finishes, Qualia captures every global variable whose name matches a required variable on an in-progress task in the same chat. For example, if a task requires best_model and accuracy, running this cell captures both:
The qualia package is already loaded in every notebook kernel, so you don’t need to import it.

Submit a value explicitly

To capture a value right away, for example from inside a function, call submit_variable from the code that produced it. The value fills the matching required variable on each in-progress task in the chat.
If Qualia can’t record a name, it prints the reason, such as an unsupported type or a slot that is already filled.

Record extra evidence

To keep a value that no task asked for, use add_evidence. It records a claim without filling a required variable. Qualia looks the name up in the calling code, so the variable must exist when you call it.
recall_priority controls how readily later agents see the claim: "low" (the default), "medium", or "high". Only "high" claims appear to agents on every turn; agents find lower ones by searching. See recall priority.

Capture from a script

Scripts use the same package, with two differences. A script has no cell boundary, so nothing is captured automatically, and the script must import the client itself. The Python capture methods are async. A notebook cell can await them directly, but a script must run them inside an event loop because top-level await is a syntax error there.
Don’t drop the await in Python, because without it the call never runs and nothing is captured.
In Julia scripts, use the @add_evidence macro:
A script claim cites the command that ran the script and, where available, the line that produced the value. If you later edit that line, the claim’s source shows it changed.

Read captured values

In a downstream task, read values captured by earlier tasks:
To read the values one task produced, for example after a kernel restart, filter by task ID:
Each row holds the task ID, variable name, value, and value type.

Save a figure from a script

To save a chart from a script along with the values it plots, use save_figure instead of the library’s own save. A figure saved this way supports data inspection once it is captured, such as reading points and toggling series.
  • Extra arguments, such as dpi or bbox_inches, pass through to the library’s save. The call returns the path it wrote.
  • Save inside your workspace, and prefer SVG because it scales to any size and keeps text as text.
  • If you use the library’s own save, an agent can still capture the figure, but only as a picture with no values behind it.
  • For Plotly, Altair, and ggplot2 figures, Qualia also keeps an interactive version of the chart.
  • Plotly image saves need the kaleido package, and Altair image saves need vl-convert-python.
To add a script’s figure to the knowledge graph, ask the agent to capture it. The agent records the image together with the script that saved it.

Supported values

Qualia captures:
  • Primitive values: numbers, strings, and booleans. NumPy scalars, such as the result of argmax, count as numbers.
  • Lists whose items all share one primitive type, such as [0.91, 0.94].
Qualia rejects dicts, DataFrames, arrays, and mixed lists, so capture separate scalar variables instead. Evidence values over 1 MB are also rejected; save large results to a file and capture a summary, such as a path or a metric.

Export a notebook that runs without Qualia

On the desktop app, right-click a notebook and choose Open with Default App. Qualia saves a copy to Downloads/Qualia Exports with each qualia.get() call, or its R and Julia equivalent, replaced by the captured values. The copy runs in other tools, such as JupyterLab or VS Code.