posit-dev / posit-dev/chatlas

feat: expose logical conversation rounds over flat turn history

Open
#394 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ai-triage:done Priority: Low
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, 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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.