history

type AppendID ¶ added in v0.60.0

type AppendID string

AppendID names one immutable append within a conversation. A retry must use the same ID and the same complete batch, including after acknowledgment loss.

func NewAppendID(value string) (AppendID, error)

func (a AppendID) String() string

func (a AppendID) Validate() error

type Batch ¶ added in v0.60.0

type Batch struct {
	// contains filtered or unexported fields
}

Batch freezes the complete append before its first write. Canonical encoding and its digest come from this owner, so adapters cannot disagree about whether a repeated identity carries the same content. Object key order and insignificant JSON whitespace do not affect identity; string values and number spellings do. Tool-call arguments are strings and retain the model's exact text.

func NewBatch(conversationID ConversationID, id AppendID, messages ...chat.Message) (Batch, error)

func (b Batch) ConversationID() ConversationID

func (b Batch) Digest() string

func (b Batch) EncodedMessages() json.RawMessage

func (b Batch) ID() AppendID

func (b Batch) Len() int

func (b Batch) MarshalJSON() ([]byte, error)

func (b Batch) Messages() []chat.Message

func (b *Batch) UnmarshalJSON(data []byte) error

func (b Batch) Validate() error

type Clearer ¶

type Clearer interface {
	// Clear atomically closes this identity, including one not yet written. Closed
	// conversations read as empty and disappear from listing. Later appends,
	// including retries of accepted batches, return ErrConversationClosed.
	// Physical message cleanup can follow closure; Clear returns nil only when
	// cleanup completes. A cleanup error leaves the identity closed, and another
	// Clear retries cleanup. Closure evidence never expires; a new conversation
	// requires a new ConversationID. Permanent closure evidence can replace the
	// closed conversation's individual append receipts.
	Clear(ctx context.Context, conversationID ConversationID) error
}

type CommitError ¶ added in v0.20.0

type CommitError struct {
	// contains filtered or unexported fields
}

CommitError retains an already completed generation's immutable append, so callers can retry persistence without invoking the model again. Receipt keeps acknowledged commit evidence even if an ancillary operation also failed.

func (c *CommitError) Batch() Batch

func (c *CommitError) Error() string

func (c *CommitError) Receipt() Receipt

func (c *CommitError) Unwrap() error

type ConversationID ¶

type ConversationID string

ConversationID identifies one history partition. Its zero value is invalid. Use NewConversationID when converting runtime input; string constants may be converted directly when the value is known at compile time.

func NewConversationID(value string) (ConversationID, error)

func (c ConversationID) String() string

func (c ConversationID) Validate() error

type Lister ¶

type Lister interface {
	// Conversations returns detached, unique identifiers in lexical order. An
	// empty store yields a non-nil empty slice; closed conversations are omitted.
	// Concurrent appends may appear according to the backend's snapshot boundary.
	Conversations(ctx context.Context) ([]ConversationID, error)
}

type Middleware ¶

type Middleware struct {
	// contains filtered or unexported fields
}

Middleware replays and persists history around synchronous and streaming chat capabilities. It is immutable and as safe for concurrent use as its Reader and Writer, but it does not serialize Read/model/Append turns of one conversation. Its zero value is invalid; construct it with NewMiddleware.

func NewMiddleware(config MiddlewareConfig) (Middleware, error)

package main

import (
	"context"
	"fmt"

	"github.com/Tangerg/scope/core/chat"
	"github.com/Tangerg/scope/core/history"
	"github.com/Tangerg/scope/core/history/inmemory"
)

func main() {
	store := new(inmemory.Store)
	middleware, err := history.NewMiddleware(history.MiddlewareConfig{Reader: store, Writer: store, ConversationID: "customer-42"})
	if err != nil {
		panic(err)
	}
	model := middleware.Call(chat.ModelFunc(func(context.Context, *chat.Request) (*chat.Response, error) {
		return &chat.Response{Output: &chat.Output{Message: new(chat.NewAssistantMessage(chat.NewTextPart("Hello"))), FinishReason: chat.FinishReasonStop}}, nil
	}))
	request, err := chat.NewRequest(chat.NewUserMessage(chat.NewTextPart("Hi")))
	if err != nil {
		panic(err)
	}
	response, err := model.Call(context.Background(), request)
	if err != nil {
		panic(err)
	}
	messages, err := store.Read(context.Background(), "customer-42")
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Text(), len(messages))
}

Output:
Hello 2

func (m Middleware) Call(next chat.Model) chat.Model

func (m Middleware) Stream(next chat.Streamer) chat.Streamer

type MiddlewareConfig ¶ added in v0.54.0

type MiddlewareConfig struct {
	Reader         Reader
	Writer         Writer
	ConversationID ConversationID
}

MiddlewareConfig binds history to one explicit partition. Calls that do not use history should use the undecorated model.

type ReadWriter ¶

type ReadWriter interface {
	Reader
	Writer
}

type Reader ¶

type Reader interface {
	// Read returns a detached snapshot in stored order. Unknown and closed conversations
	// yield a non-nil empty slice; implementations honor ctx and never expose
	// mutable backing storage.
	Read(ctx context.Context, conversationID ConversationID) ([]chat.Message, error)
}

type Receipt ¶ added in v0.60.0

type Receipt struct {
	ConversationID ConversationID
	ID             AppendID
	Digest         string
}

Receipt acknowledges the entire named batch. A zero receipt proves nothing about a failed attempt; submitting the same Batch safely resolves that doubt. Stores return a receipt only after their atomic append is acknowledged.

func (r Receipt) ValidateFor(batch Batch) error

type Store ¶

type Store interface {
	ReadWriter
	Clearer
}

type WindowReader ¶ added in v0.60.0

type WindowReader struct {
	// contains filtered or unexported fields
}

WindowReader projects reads to at most limit messages while preserving a merged system message followed by a suffix of complete conversation turns. A user message starts a turn; every following assistant and tool message remains in that turn until the next user message. This projection owns no write or clear authority. Read returns ErrWindowTooSmall rather than splitting the newest complete turn, and the merged system message counts toward the configured limit.

func NewWindowReader(reader Reader, limit int) (WindowReader, error)

func (w WindowReader) Read(ctx context.Context, conversationID ConversationID) ([]chat.Message, error)

type Writer ¶

type Writer interface {
	// Append accepts one immutable batch under its stable identity. An identical
	// retry returns the original receipt without appending again; changed content
	// returns ErrAppendConflict. Errors without a valid receipt leave the outcome
	// unconfirmed and never authorize submitting under a new identity.
	// The closed-conversation check, deduplication record, and message append share
	// one atomic boundary. While the conversation is open, message expiration must
	// not erase deduplication evidence.
	Append(ctx context.Context, batch Batch) (Receipt, error)
}

Writer orders each complete batch atomically. Relative ordering of concurrent batches is implementation-defined; messages within a batch retain their order.