` section when output is
present). Prompts render as their bare content via the `prompt_txt` host
hook: in history, the reply is the next turn, not part of the message.
`to_xml` combines the msg input and output. A prompt renders through
`prompt_txt` — bare content here, with `last` marking the live request;
a host that wants an envelope around its prompts patches `prompt_txt`
alone:
------------------------------------------------------------------------
source
### Message.to_xml
``` python
def to_xml(
last:bool=False
):
```
*Create XML representation of this message*
------------------------------------------------------------------------
source
### Message.prompt_txt
``` python
def prompt_txt(
last:bool=False
):
```
*History text for a prompt message: the content, bare. Hosts patch this
to add their own envelope*
``` python
# Combines content and output into full XML representation
m = mk('code', 'print("hi")', 'hi\n')
test_eq(m.to_xml(), f'print("hi")hi\n')
n = mk('note', '# hey')
test_eq(n.to_xml(), f'# hey') # notes render as markdown; no out, no extra tags
```
'print("hi")'
``` python
# Prompts render bare
test_eq(mk('prompt', 'question').to_xml(), 'question')
test_eq(mk('prompt', 'question').prompt_txt(last=True), 'question')
```
------------------------------------------------------------------------
source
### Message.to_media
``` python
def to_media(
aim_info, max_im_sz:NoneType=None
):
```
*Aggregate media from attachments, `media_extra`, and code outputs*
------------------------------------------------------------------------
source
### Message.media_extra
``` python
def media_extra(
aim_info, max_im_sz:NoneType=None
):
```
*Additional media sources contributed by subclasses (e.g. app-specific
file references)*
``` python
# No media for plain messages
test_eq(mk('note', 'hello').to_media({}), [])
```
``` python
# Code output images
m = Message(msg_type='code', output=mk_code_output({'image/png': base64.b64encode(png).decode()}))
media = m.to_media(dict(supports_vision=True))
test_eq(len(media), 2) # xml tag, bytes
```
------------------------------------------------------------------------
source
### Message.to_parts
``` python
def to_parts(
aim_info:dict, last:bool=False
):
```
*Convert message to a list of history parts: media, then XML text.*
``` python
att = Attachment(_mk_img(_imgb64), 'image/png')
m = mk('prompt', f'What is in ?', attachments=[att])
res = m.to_parts(dict(supports_vision=True))
['...bytes...' if isinstance(o,bytes) else o for o in res]
```
['',
'...bytes...',
'What is in ?']
------------------------------------------------------------------------
source
### dlg2hist
``` python
def dlg2hist(
dlg, # A `Dialog`, or iterable of messages, ending with a prompt
aim_info:dict, # Model capability dict for media handling
):
```
*Convert `dlg` to LLM history. The final prompt renders with
`last=True`.*
## Dialogs to canonical messages
[`dlg2hist`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2hist)
produces alternating user parts and AI reply strings. For surgery we
usually want the replies’ tool calls back as structured messages, and
fastllm’s `fmt2hist` inverts the reply format exactly.
[`dlg2chat`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2chat)
composes the two into the canonical form every provider conversion
starts from, and rejects duplicate tool-call ids, which hand-authored
dialogs can accidentally produce. Thinking blocks survive only in the
stored reply string: explode/implode
([`reply2dlg`](https://AnswerDotAI.github.io/llmsurgery/hist.html#reply2dlg)/[`dlg2reply`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2reply))
and this transmission projection both drop them, a deliberate loss since
nothing downstream keeps them.
------------------------------------------------------------------------
source
### dlg2chat
``` python
def dlg2chat(
dlg, # A `Dialog`, ending with a prompt
aim_info:NoneType=None, # Model capability dict for media handling; images enabled if None
):
```
*Canonical fastllm messages for `dlg`, with each reply’s tool calls
recovered as real parts*
The conversion tests below need replies carrying tool-call details
blocks, so first a fixture that builds one in fastllm’s reply format.
``` python
def _mk_dtl(func, args, result, tid='x1'):
d = json.dumps(dict(id=tid, server=False, call=dict(function=func, arguments=args), result=result))
return f"{tool_dtls_tag}\n{func}(...)\n\n```json\n{d}\n```\n\n"
py_dtl = _mk_dtl('python', {'code':'1+1'}, '2')
```
``` python
ddlg = Dialog('canon')
ddlg.mk_message('What is 1+1?', msg_type=sprompt, output=f"Check:\n\n{py_dtl}\n\nIt is 2.")
cm = dlg2chat(ddlg)
test_eq([m.role for m in cm], ['user', 'assistant', 'tool', 'assistant'])
test_eq(cm[1].content[1].data['name'], 'python')
```
One reply often holds several sequential tool calls, each issued after
reading the previous result. `fmt2hist` returns them batched into a
single call message and a single result message, which reads as one
parallel volley;
[`dlg2chat`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2chat)
explodes the batch back into strict call/result alternation, the shape
live sessions record.
``` python
py_dtl2 = _mk_dtl('python', {'code':'2+2'}, '4', 'x2')
sdlg = Dialog('seq')
sdlg.mk_message('Two steps.', msg_type=sprompt, output=f"{py_dtl}\n\n{py_dtl2}\n\nDone.")
sm = dlg2chat(sdlg)
test_eq([(m.role, len(m.content)) for m in sm], [('user',1), ('assistant',1), ('tool',1), ('assistant',1), ('tool',1), ('assistant',1)])
test_eq(sm[2].content[0].data['id'], sm[1].content[0].data['id'])
test_eq(sm[4].content[0].data['id'], sm[3].content[0].data['id'])
```
``` python
bad = Dialog('dup')
bad.mk_message('a', msg_type=sprompt, output=py_dtl)
bad.mk_message('b', msg_type=sprompt, output=py_dtl)
with expect_fail(ValueError, 'duplicate tool call id'): dlg2chat(bad)
```
``` python
raw = [
mk('prompt', 'hello there', output='Hello! How can I help?'),
mk('note', 'a note between turns'),
mk('code', output="aaa", content="'some source text'"),
mk('prompt', 'add the numbers', output='They sum to 4.'),
mk('note'),
mk('note'),
mk('code', output="333"),
mk('prompt'), # empty output on purpose
mk('prompt', 'summarize the conversation so far', output='We greeted, then added some numbers.'),
mk('note', 'below we insert an image'),
mk('code', 'img=..some code to read image bytes'),
mk('prompt', 'Please tell me what you see in the image', output='I can see...'),
mk('note', 'lets add an image note'),
mk('prompt', 'Please tell me what you see in the 2 images in the above msg',output='i see two puppies!'),
mk('prompt', 'And one final question.')]
```
``` python
aim_info = dict(supports_vision=True)
```
A realistic message mix — prompts with and without preceding notes and
code, an empty AI response, media references — checks the turn
structure:
``` python
*hist,p,_ = dlg2hist(raw, aim_info)
```
Lets take a look at the history:
``` python
for idx, turn in enumerate(mk_msgs(hist)):
display(Markdown(f"**======turn: {idx}======**"))
display(turn)
```
**======turn: 0======**
**Msg**
- role: `user`
**Part** (`text`)
hello $`x`
- data: `None`
**======turn: 1======**
**Msg**
- role: `assistant`
**Part** (`text`)
Hello! I can see the variable `x`
- data: `None`
**======turn: 2======**
**Msg**
- role: `user`
**Part** (`text`)
$`not_variable1`
- data: `None`
**Part** (`text`)
‘$`not_variable2`’
- data: `None`
**Part** (`text`)
hi hi $`y`
- data: `None`
**======turn: 3======**
**Msg**
- role: `assistant`
**Part** (`text`)
Hello! I can see the variable `y`
- data: `None`
**======turn: 4======**
**Msg**
- role: `user`
**Part** (`text`)
note\>\_264125b3
- data: `None`
**Part** (`text`)
note\>\_0f5f4c5e
- data: `None`
**Part** (`text`)
code\>\_904dc672
- data: `None`
**Part** (`text`)
prompt\>\_7140d653
- data: `None`
**======turn: 5======**
**Msg**
- role: `assistant`
**Part** (`text`)
- data: `None`
**======turn: 6======**
**Msg**
- role: `user`
**Part** (`text`)
$`x`, $`y`
- data: `None`
**======turn: 7======**
**Msg**
- role: `assistant`
**Part** (`text`)
Hello! I can see the variables `x` and `y`
- data: `None`
**======turn: 8======**
**Msg**
- role: `user`
**Part** (`text`)
below we insert
an image
- data: `None`
**Part** (`text`)
img=..some code
to read image bytes
- data: `None`
**Part** (`text`)
Please tell me what you see in $`img`
- data: `None`
**======turn: 9======**
**Msg**
- role: `assistant`
**Part** (`text`)
I can see…
- data: `None`
**======turn: 10======**
**Msg**
- role: `user`
**Part** (`text`)
lets add an
image note
- data: `None`
**Part** (`text`)
Please tell me what you see in the 2 images in the above msg
- data: `None`
**======turn: 11======**
**Msg**
- role: `assistant`
**Part** (`text`)
i see two puppies!
- data: `None`
``` python
p
```
['Whats variable $`y`?']
``` python
test_eq(len(hist),12) # `raw` has 6 prompts which means 12 user+ai turns
```
``` python
hist[6]
```
['$`x`, $`y`']
``` python
# the last prompt is marked `last`, but core rendering is identical: bare content
test_eq(p, [raw[-1].content])
test_eq(hist[6], [raw[8].content])
```
A raw message carrying a `rec_kind` tag in its meta is session
bookkeeping some codec kept for reversibility (e.g. `llmsurgery.ant`’s
system records), not conversation content, so history projections skip
it:
``` python
tr = [mk('note', 'context'), mk('prompt', 'q', output='r')]
h1 = dlg2hist(tr, aim_info)
trd = Dialog('trd'); trd.messages = list(tr)
test_eq(dlg2hist(trd, aim_info), h1) # a Dialog and its message list produce the same history
tr.insert(1, Message('', msg_type=sraw, meta=dict(rec_kind='system', rec=dict(type='system'))))
test_eq(dlg2hist(tr, aim_info), h1) # tagged raws never leak into history
```
``` python
# test each user input for expected length
test_eq(len(hist[0]),1) # prompt w/o preceding msgs
test_eq(len(hist[2]),3) # prompt w preceding note and code
test_eq(len(hist[4]),4) # prompt w preceding notes (2) and code
test_eq(len(hist[6]),1) # prompt w/o preceding msgs
test_eq(len(hist[8]),3) # [note, code, prompt]
test_eq(len(hist[10]),2) # [note, prompt]
```
``` python
# Test each AI output for expected length
for i in (1,3,7,9,11): test(len(hist[i]),0,operator.gt)
test_eq(hist[5],'') # empty ai response
```
## Reply sub-dialogs
A prompt’s AI reply is one markdown string: prose interleaved with
tool-call details blocks.
[`reply2dlg`](https://AnswerDotAI.github.io/llmsurgery/hist.html#reply2dlg)
explodes that string into a
[`Dialog`](https://AnswerDotAI.github.io/llmsurgery/dialog.html#dialog)
of note and code messages, so a reply’s insides can be edited with the
ordinary message operations, and
[`dlg2reply`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2reply)
implodes the sub-dialog back into reply markdown. Parsing goes through
`fmt2hist`, so the projection normalizes a reply exactly where the
history path does: token-usage, think, and server-tool blocks are
dropped, and a reply ending in a call gains a trailing `.` note.
------------------------------------------------------------------------
source
### reply2dlg
``` python
def reply2dlg(
pmsg
):
```
*Explode `pmsg`’s AI reply into a
[`Dialog`](https://AnswerDotAI.github.io/llmsurgery/dialog.html#dialog)
of note and code messages*
Each tool call becomes a code message whose source is the literal call
with `repr`’d argument values, so the source alone is the record: `ast`
recovers the exact call dict, and nothing else stores the tool name. The
result rides in the output list and the call id in `meta`. The fixture
builds a reply with `hist2fmt` from known `Msg`s, so the expected string
is constructed rather than scraped from a captured chat.
``` python
tu1 = Part(type=PartType.tool_use, text=None, data=dict(id='x1', name='python', arguments={'code':'1+1'}))
tr1 = Part(type=PartType.tool_result, text='2', data=dict(id='x1', name='python'))
rmsgs = [Msg(role='assistant', content=[Part(PartType.text, 'Check:'), tu1]), Msg(role='tool', content=[tr1]),
Msg(role='assistant', content=[Part(PartType.text, 'It is 2.')])]
pm = Message('What is 1+1?', msg_type=sprompt, output=hist2fmt(rmsgs, mx=None))
Markdown(pm.ai_res)
```
``` python
sub = reply2dlg(pm)
sub
```
``` python
test_eq([m.msg_type for m in sub.messages], [snote, scode, snote])
test_eq(sub.messages[1].content, "python(code='1+1')")
test_eq(sub.messages[1].output, code_output('2'))
test_eq(sub.messages[1].meta['tool_id'], 'x1')
```
[`dlg2reply`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2reply)
renders each code message back into a details block through
`mk_tr_details` with truncation disabled (the summary line is
regenerated), passes note content through verbatim, and joins with blank
lines: the same bytes `hist2fmt` produces. For a fmt2hist-clean reply
the round trip is exact.
------------------------------------------------------------------------
source
### dlg2reply
``` python
def dlg2reply(
sub
):
```
*Implode a sub-dialog of note and code messages back into reply
markdown*
``` python
test_eq(dlg2reply(sub), pm.ai_res)
```
Editing one argument in a code message changes exactly that argument in
the reparsed call, and the call id is untouched:
``` python
sub.messages[1].content = "python(code='1+2')"
tu = first(p for m in fmt2hist(dlg2reply(sub)) for p in m.content if p.type==PartType.tool_use)
test_eq(tu.data['arguments'], {'code':'1+2'})
test_eq(tu.data['id'], 'x1')
```
------------------------------------------------------------------------
source
### Message.tool_call
``` python
def tool_call():
```
*Parsed `dict(name=..., arguments=...)` when this code message’s source
is a literal tool call, else None*
`tool_call` is the read-only view of a code message’s call, for UIs and
review loops; unlike the render path it has no side effects (no id
generation) and returns None rather than raising for anything that isn’t
a literal call:
``` python
test_eq(sub.messages[1].tool_call, dict(name='python', arguments={'code':'1+2'}))
test_eq(sub.messages[0].tool_call, None) # a note
test_eq(Message('x = 1', msg_type=scode).tool_call, None) # not a call expression
```
A parallel volley renders as adjacent details blocks, and explodes to
sequential code messages in document order (the trailing `.` note is
`fmt2hist`’s guard against empty assistant text).
[`dlg2chat`](https://AnswerDotAI.github.io/llmsurgery/hist.html#dlg2chat)
sees equal histories before and after an explode/implode cycle:
``` python
tus = [Part(type=PartType.tool_use, text=None, data=dict(id=f'x{i}', name='simple_add', arguments=dict(a=i, b=1))) for i in (2,3,4)]
tres = [Part(type=PartType.tool_result, text=str(i+1), data=dict(id=f'x{i}', name='simple_add')) for i in (2,3,4)]
vmsgs = [Msg(role='assistant', content=[Part(PartType.text, 'Adding.'), *tus]), Msg(role='tool', content=tres)]
vdlg = Dialog('volley')
vpm = vdlg.mk_message('Add some numbers.', msg_type=sprompt, output=hist2fmt(vmsgs, mx=None))
vsub = reply2dlg(vpm)
test_eq([m.msg_type for m in vsub.messages], [snote, scode, scode, scode, snote])
```
``` python
v2 = Dialog('volley2')
v2.mk_message('Add some numbers.', msg_type=sprompt, output=dlg2reply(vsub))
test_eq(dlg2chat(v2), dlg2chat(vdlg))
```
New messages inserted into the sub-dialog appear in the reply; a new
call gets a generated id that doesn’t collide:
``` python
vsub.mk_message('One more:', msg_type=snote)
nc = vsub.mk_message('simple_add(a=5, b=1)', output=code_output('6'))
r3 = dlg2reply(vsub)
assert 'One more:' in r3
ids = [p.data['id'] for m in fmt2hist(r3) for p in m.content if p.type==PartType.tool_use]
test_eq(len(ids), len(set(ids)))
assert nc.meta['tool_id']
```
A reply with no tool calls round-trips as a single note. Tool names that
aren’t Python identifiers raise on explode, and a code message whose
source isn’t a keyword-only call raises on implode:
``` python
sub1 = reply2dlg(Message('hi', msg_type=sprompt, output='Just prose.'))
test_eq([m.msg_type for m in sub1.messages], [snote])
test_eq(dlg2reply(sub1), 'Just prose.')
```
``` python
badp = [Msg(role='assistant', content=[Part(type=PartType.tool_use, text=None, data=dict(id='b1', name='foo-bar', arguments={}))]),
Msg(role='tool', content=[Part(type=PartType.tool_result, text='x', data=dict(id='b1', name='foo-bar'))])]
with expect_fail(ValueError, 'identifier'): reply2dlg(Message('p', msg_type=sprompt, output=hist2fmt(badp, mx=None)))
with expect_fail(ValueError, 'tool call'): dlg2reply(Dialog('b', [Message('1+1', msg_type=scode)]))
```