Skip to content

binding-llm: canonical section attributes #2637

Description

@jfallows

Depends on: #2634

Summary

Name-value attributes on LlmDataEx that describe a canonical section independently of any dialect, so a block decoded from one dialect can be encoded into another.

A section type alone does not carry everything llm(client) needs to encode a block. A canonical attribute is a dialect-neutral concept a section can carry, named independently of any dialect.

attribute type sections what it describes
media-type string user-image, user-document, user-audio, user-video media type of the content
source inline, url, reference user-image, user-document, user-audio, user-video how the content is supplied
ref-id string the four media sections, when source is reference provider-side file handle
filename string user-document name of the document
tool-name string tool-definition, tool-call, server-tool-result name of the tool
tool-call-id string tool-call, tool-result, server-tool-result joins a call to its result
is-error bool tool-result the call failed
provider-executed bool server-tool-result the tool was executed by the provider rather than the caller

Eight, and no more without a reason: a new attribute must be a dialect-neutral concept that the section type cannot express. Anything specific to one dialect is a dialect extension (#2638). Names are canonical, never dialect-specific.

The location of a url source is not an attribute. It is unbounded, and the payload already carries it, so hoisting it would duplicate an unbounded value into a bounded extension. A url section is classified by source alone and its location streams in the payload. A ref-id is a bounded provider handle and is hoisted.

Acceptance criteria (test-first)

  • Unit tests: decode populates each attribute for openai and anthropic (and ollama where it applies), and never on a section that does not carry it.
  • Unit tests: llm(client) encode renders each attribute into the target dialect's wire form where the dialect has one.
  • .rpt coverage for source: url and source: reference blocks.

Activity

  1. added theissue type on Oct 2, 2026
  2. self-assigned this
    on Oct 2, 2026
  3. changed the title [-]binding-llm: canonical attribute vocabulary[/-] [+]binding-llm: canonical section attributes[/+] on Oct 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions