feat: expose logical conversation rounds over flat turn history
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 176
- Forks
- 28
- Avg merge
- 18h 42m
- Merged PRs (30d)
- 16
Description
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, andpartial_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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in chatlas/_chat.py with get_turns(), get_last_turn(), and the partial-turn helpers, then inspect the turn types and partial_reason in chatlas/_turn.py. Review Ellmer commit 59bbe9d4 for comparison, settle the public names and semantics for tool loops and system or partial turns, and add coverage for the listed exchange and history cases without changing flat storage or provider serialization.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100