longterm

type Consolidatable interface {
	Store

	// ListEntities returns every entity of the user, ordered by name.
	ListEntities(ctx context.Context, userID string) ([]Entity, error)

	// ReplaceEntities rewrites the entities of snapshot (what ListEntities returned) as entities, atomically: a
	// snapshot entity not in entities is removed, one in entities is created or rewritten. It returns
	// ErrChangedDuringConsolidation, changing nothing, if any snapshot entity was modified or removed since the
	// snapshot; entities created since are left alone. renames maps the name of an entity merged into another to the
	// name it now has, so that relations follow it; a relation left without both endpoints, or pointing to itself, is
	// removed.
	ReplaceEntities(ctx context.Context, userID string, snapshot []Entity, entities []EntityInput, renames map[string]string) error
}

type ConsolidationReport struct {
	EntitiesBefore, EntitiesAfter         int
	ObservationsBefore, ObservationsAfter int
	// SnapshotID names the copy of the memory taken before the rewrite; UndoLast, or Snapshotter.RestoreSnapshot with
	// this id, puts it back.
	SnapshotID string
}

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

type ConsolidatorConfig struct {
	// MinObservations is the number of observations a user must hold before consolidation is worth a model call.
	// Default: 60.
	MinObservations int

	// MinInterval is the shortest time between two consolidations of the same user, kept per process. Default: 24h.
	MinInterval time.Duration

	// MaxInputChars caps the memory sent to the model. Entities past it are left as they are. Default: 60000.
	MaxInputChars int

	// MinKeepRatio is the share of the observations a result must keep to be applied: a result that drops more is
	// taken for a model error and refused. Default: 0.3.
	MinKeepRatio float64

	// Model is the model that consolidates. Zero uses the caller's default.
	Model types.ModelIdentifier

	// Timeout is the deadline of the model call. Default: 120s.
	Timeout time.Duration
}

type Entity struct {
	ID           string    `json:"id"`
	UserID       string    `json:"user_id"`
	Name         string    `json:"name"`
	EntityType   string    `json:"entity_type"`
	Observations []string  `json:"observations"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

type EntityInput struct {
	Name         string   `json:"name"`
	EntityType   string   `json:"entity_type"`
	Observations []string `json:"observations"`
}

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

type ExtractorConfig struct {
	// MinTurns is the minimum number of user turns required before extraction
	// runs. Short sessions rarely contain facts worth persisting.
	// Default: 3.
	MinTurns int

	// MaxTranscriptChars caps the conversation snippet fed to the LLM.
	// Keeps extraction cheap; recent turns are preferred when truncating.
	// Default: 8000.
	MaxTranscriptChars int

	// Model is the LLM model used for extraction. Haiku-class recommended.
	// When Model.Model is empty the request is sent without an explicit model
	// field, relying on the caller's default.
	Model types.ModelIdentifier

	// ExtractionTimeout is the per-call deadline passed to CreateMessage.
	// Default: 45 s.
	ExtractionTimeout time.Duration
}

type Graph struct {
	Entities  []Entity   `json:"entities"`
	Relations []Relation `json:"relations"`
}

type LLMCaller interface {
	CreateMessage(ctx context.Context, req types.APIRequest) (*types.APIResponse, error)
}

type Lister interface {
	ListEntities(ctx context.Context, userID string) ([]Entity, error)
}

type ObservationInput struct {
	EntityName string   `json:"entity_name"`
	Contents   []string `json:"contents"`
}

type ObservationResult struct {
	EntityName        string   `json:"entity_name"`
	AddedObservations []string `json:"added_observations"`
}

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

type Relation struct {
	ID           string    `json:"id"`
	UserID       string    `json:"user_id"`
	From         string    `json:"from"` // entity name
	To           string    `json:"to"`   // entity name
	RelationType string    `json:"relation_type"`
	CreatedAt    time.Time `json:"created_at"`
}

type RelationInput struct {
	From         string `json:"from"`
	To           string `json:"to"`
	RelationType string `json:"relation_type"`
}

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

type SnapshotInfo struct {
	ID           string    `json:"id"`
	Reason       string    `json:"reason"`
	CreatedAt    time.Time `json:"created_at"`
	Entities     int       `json:"entities"`
	Observations int       `json:"observations"`
}

type Snapshotter interface {
	// SaveSnapshot copies the user's entities and relations and returns the copy's description.
	SaveSnapshot(ctx context.Context, userID, reason string) (SnapshotInfo, error)

	// ListSnapshots returns the user's copies, newest first.
	ListSnapshots(ctx context.Context, userID string) ([]SnapshotInfo, error)

	// RestoreSnapshot replaces the user's memory with the copy. It first copies the memory as it is, so that a restore
	// can be undone too.
	RestoreSnapshot(ctx context.Context, userID, snapshotID string) error
}

type Store interface {
	// UpsertEntities creates entities that do not exist yet (deduplicates by name).
	// Returns only the entities that were actually inserted.
	UpsertEntities(ctx context.Context, userID string, inputs []EntityInput) ([]Entity, error)

	// AddObservations appends new observations to existing entities.
	// Duplicate observation strings are silently skipped.
	AddObservations(ctx context.Context, userID string, inputs []ObservationInput) ([]ObservationResult, error)

	// SearchNodes performs case-insensitive substring search across entity names,
	// entity types, and observation content. Returns matching entities plus all
	// relations where at least one endpoint is in the result set.
	SearchNodes(ctx context.Context, userID, query string) (*Graph, error)

	// OpenNodes returns specific entities by exact name and the relations that
	// touch them (at least one endpoint in the requested set).
	OpenNodes(ctx context.Context, userID string, names []string) (*Graph, error)

	// RetrieveForContext retrieves memory relevant to the current query and
	// formats it as a Markdown block capped to approximately maxTokens.
	// Returns an empty string when there is nothing relevant.
	RetrieveForContext(ctx context.Context, userID, query string, maxTokens int) (string, error)
}