aidialog

aidialog provides the Dialog/Message model used by solveit and the fastai AI tooling ecosystem. An AI dialog is a Jupyter notebook whose cells are messages: notes, runnable code, and prompts with replies. Five modules build on each other:

• aidialog.msg_parts: the canonical Msg/Part chat message model and its wire text form
• aidialog.dialog: the core Dialog/Message model, including plain-text rendering of Jupyter outputs
• aidialog.ipynb: reading and writing dialogs as .ipynb files
• aidialog.hist: conversions between dialogs, chat histories, and formatted replies
• aidialog.dlgskill: search and editing tools for dialogs and notebooks, registered as a pyskill

Provider session files (Claude Code transcripts, Codex rollouts) and conversation compaction live in llmsurgery.

The theory

A dialog is a conversation between a human, an AI, and an interpreter. Each message type addresses one of them and expects a certain kind of answer:

• A prompt asks the AI a question and holds its reply.
• A code message gives the interpreter source and holds its outputs.
• A note is read by everyone and answered by nobody.
• A raw message addresses no one. It is inert matter the conversation carries along.

A reply may itself contain runnable code with results, so a whole dialog can live inside one message. reply2dlg opens a reply up as a dialog and dlg2reply puts it back.

Dialogs and Jupyter notebooks both serialize to the ipynb format, but they are not the same thing. A notebook has cells. A dialog has messages. Messages can be prompts, which notebooks cannot express, and they make structure explicit that notebooks leave implicit. E.g a heading opens a section that runs to the next heading of the same level; an export directive marks the code that belongs to a module. The shared file format means the same tools read both. The word tells you which layer you are on. File-level tools such as fastcore.nbio and exhash speak of cells and notebooks. Everything in this library speaks of messages and dialogs.

The Dialog is the center of the library. Everything else is a projection of it. A storage projection must preserve everything that means something. What it does not understand it carries verbatim in metadata, and what is broken it heals rather than rejects. A transmission projection normalizes on purpose, and what it drops is written into its contract. A display projection only goes one way. The rule is to convert in, edit at the center, and project out. The function names say the same thing. Every converter has dlg on exactly one side.

The session codecs (in llmsurgery) route through chat on their way to the wire: ant’s dlg2msgs and oai’s dlg2items are each denorm_msgs(dlg2chat(...)).

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/AnswerDotAI/aidialog.git

or from pypi:

$ pip install aidialog

Documentation

Documentation can be found hosted on this GitHub repository’s pages.

How to use

A quick taste - create a dialog, add a message, and view it as concise XML:

from aidialog.dlgskill import *
import tempfile

p = tempfile.mkdtemp() + '/demo.ipynb'
d = create_dlg(p, '## A tiny dialog', 'note')
add_msg('6*7', after=d.messages[0].id, dlg=p)
view_dlg(p)

<dialog name="demo"><markdown id="1d693c32">## A tiny dialog</markdown><code id="02048a43">6*7</code></dialog>

To make a file the default for subsequent calls, use set_dlg(p). It expands ~ and resolves an absolute path immediately, so the current dialog stays the same after %cd or another working-directory change.

Command line

The flat commands expose dialog-aware reading and structural edits without a Python kernel:

aidialog-summary nbs/00_core.ipynb
aidialog-find nbs/00_core.ipynb 'read_csv' --context 1
aidialog-view nbs/00_core.ipynb ab12cd34 --out
aidialog-add nbs/00_core.ipynb --after ab12cd34 --msg-type code < new-cell.py
aidialog-del nbs/00_core.ipynb ab12cd34
aidialog-move nbs/00_core.ipynb ab12cd34,ef56ab78 --before 9012cdef

Message ID arguments are comma-separated where a command accepts several. Mutating commands accept --dry-run; run any command with --help for its full filters and display options.