history

type Clearer ¶

type Clearer interface {
	// Clear removes the complete conversation and is idempotent when it is
	// already absent. Implementations must honor ctx.
	Clear(ctx context.Context, conversationID ConversationID) error
}

type CommitError ¶ added in v0.20.0

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

CommitError means model generation completed but history persistence failed. It owns the exact batch submitted to Write, so recovery need not call the model again. Outcome governs whether a suffix is safe to submit: uncertain writes require reconciliation, and Accepted messages must not be appended again. During streaming this error can follow the terminal model delta.

func (c *CommitError) ConversationID() ConversationID

func (c *CommitError) Error() string

func (c *CommitError) Messages() []chat.Message

func (c *CommitError) Outcome() WriteOutcome

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; concurrent writes may appear or
	// not 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 Store, but it does not serialize Read/model/Write 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{Store: 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 {
	Store          ReadWriter
	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 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 Sequence ¶ added in v0.16.0

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

Sequence reserves contiguous, strictly increasing positions despite wall-clock regression or repeated instants. It never reissues a position through the same value; ordering across separate Store instances remains implementation-defined.

func NewSequence(stride time.Duration) (*Sequence, error)

func (s *Sequence) Reserve(count int) int64

type Store ¶

type Store interface {
	ReadWriter
	Clearer
}

type WindowStore ¶

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

WindowStore 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. Writes and clears pass through to the authoritative Store. Read returns ErrWindowTooSmall rather than splitting the newest complete turn, and the merged system message counts toward the configured limit.

func NewWindowStore(store Store, limit int) (WindowStore, error)

func (w WindowStore) Clear(ctx context.Context, conversationID ConversationID) error

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

func (w WindowStore) Write(ctx context.Context, conversationID ConversationID, messages ...chat.Message) (WriteOutcome, error)

type WriteOutcome ¶ added in v0.20.0

type WriteOutcome struct {
	Accepted  int
	Uncertain bool
}

WriteOutcome describes the acknowledged facts of one Write attempt. It never implies idempotency or rollback. The zero value confirms that nothing was written. Accepted counts the confirmed prefix in argument order. Uncertain means additional messages after that prefix may have been stored; the caller must reconcile them before retrying. Otherwise all remaining messages are confirmed unwritten. All messages may be accepted even if ancillary work fails.

func (w WriteOutcome) ValidateFor(count int, err error) error

type Writer ¶

type Writer interface {
	// Write validates and snapshots the full argument batch before appending it
	// in argument order. The outcome must account for every acknowledged or
	// uncertain effect even on error; validation failures return the zero outcome.
	// A nil error acknowledges the complete batch.
	Write(ctx context.Context, conversationID ConversationID, messages ...chat.Message) (WriteOutcome, error)
}

Writer leaves the relative order of concurrent calls, or of writes through separate Store instances, implementation-defined.