Skip to content

feat: expose logical conversation rounds over flat turn history #394

Description

@cpsievert

Why this matters

Chatlas stores a flat sequence of SystemTurn, UserTurn, and AssistantTurn objects. A single user request that invokes tools can span several user/assistant turns, making transcript review, UIs, and tracing consumers reconstruct the logical exchange themselves.

Ellmer added a read-only Round abstraction in tidyverse/ellmer#1056 (59bbe9d4): each round starts with input turn(s) and includes the assistant/tool-result turns that follow. Storage remains flat.

Scope

  • Design and add a public, read-only Python API that groups current history into logical conversation rounds without changing how turns are stored or submitted to providers.
  • Include a clear definition for tool loops, system turns, and partial assistant turns.
  • Provide an ergonomic way to retrieve all rounds and the final round.
  • Ensure returned round objects preserve the original turns rather than duplicating provider state.
  • Add tests for ordinary exchanges, multiple tool-result cycles, system-prompt inclusion, manually supplied history where supported, and interrupted/partial responses.

Starting points

  • chatlas/_chat.py: get_turns(), get_last_turn(), and partial-turn helpers.
  • chatlas/_turn.py: SystemTurn, UserTurn, AssistantTurn, and partial_reason.
  • Chat.get_turns(tool_result_role="assistant") already offers display-oriented collapsing, but it is not a round API.
  • Ellmer reference: git -C ../ellmer show 59bbe9d4.

Non-goals

  • Do not replace the flat internal history or alter provider serialization.
  • Do not add mutation APIs such as set_rounds() without a separate design decision.

Design note

This is a public API addition. Settle names, object shape, and system-turn semantics before implementation; the ellmer behavior is a useful reference, not a requirement to mirror verbatim.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Priority: LowLow-impact bug, docs polish, papercut, or unclear low-severity request.ai-triage:doneMarks an issue whose AI triage workflow is complete.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions