core

type AddRequest struct {
	Context
	Type     MemoryType     `json:"type"`
	Content  string         `json:"content"`
	Metadata map[string]any `json:"metadata,omitempty"`
	TTL      time.Duration  `json:"ttl,omitempty"`
}

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

type ClientConfig struct {
	// Providers is the list of provider configurations.
	// The first provider is the primary, others are fallbacks.
	Providers []ProviderConfig `json:"providers"`

	// DefaultTTL is the default time-to-live for memories.
	DefaultTTL time.Duration `json:"default_ttl,omitempty"`

	// Embedder is the embedding generator.
	Embedder Embedder `json:"-"`

	// Logger is the logger for the client.
	Logger *slog.Logger `json:"-"`
}

type Context struct {
	TenantID       string `json:"tenant_id"`
	SubjectID      string `json:"subject_id"`   // Who the memory is about
	PrincipalID    string `json:"principal_id"` // Who is making the request
	AgentID        string `json:"agent_id,omitempty"`
	SessionID      string `json:"session_id,omitempty"`      // Current session identifier
	ConversationID string `json:"conversation_id,omitempty"` // Conversation within a session
	Scope          Scope  `json:"scope,omitempty"`
}

type DeleteRequest struct {
	Context
	ID string `json:"id"`
}

type Embedder interface {
	// Embed generates an embedding for a single text.
	Embed(ctx context.Context, text string) ([]float64, error)

	// EmbedBatch generates embeddings for multiple texts.
	EmbedBatch(ctx context.Context, texts []string) ([][]float64, error)

	// Dimension returns the embedding dimension.
	Dimension() int
}

type EmbedderConfig struct {
	// Provider is the embedding provider (openai, anthropic, cohere, etc.)
	Provider string `json:"provider"`

	// APIKey is the API key for the provider.
	APIKey string `json:"api_key"`

	// Model is the embedding model to use.
	Model string `json:"model"`

	// Dimension is the embedding dimension (if configurable).
	Dimension int `json:"dimension,omitempty"`

	// Endpoint is the custom API endpoint (optional).
	Endpoint string `json:"endpoint,omitempty"`
}

type ExtractorProvider interface {
	Provider

	// ExtractObservations extracts observations from a conversation.
	ExtractObservations(ctx context.Context, conversation string) ([]Observation, error)

	// ExtractFacts extracts facts from text.
	ExtractFacts(ctx context.Context, text string) ([]Fact, error)
}

type Fact struct {
	Subject   string         `json:"subject"`
	Predicate string         `json:"predicate"`
	Object    string         `json:"object"`
	Source    string         `json:"source,omitempty"`
	Timestamp time.Time      `json:"timestamp"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type GetRequest struct {
	Context
	ID string `json:"id"`
}

type ListRequest struct {
	Context
	Types  []MemoryType `json:"types,omitempty"`
	Scopes []Scope      `json:"scopes,omitempty"`
	Limit  int          `json:"limit,omitempty"`
	Offset int          `json:"offset,omitempty"`
}

type ListResponse struct {
	Memories   []*Memory `json:"memories"`
	TotalCount int       `json:"total_count"`
	HasMore    bool      `json:"has_more"`
}

type Memory struct {
	ID        string         `json:"id"`
	TenantID  string         `json:"tenant_id"`
	SubjectID string         `json:"subject_id"` // Who this memory is about
	AgentID   string         `json:"agent_id,omitempty"`
	SessionID string         `json:"session_id,omitempty"` // Session that created this memory
	Scope     Scope          `json:"scope"`
	Type      MemoryType     `json:"type"`
	Content   string         `json:"content"`
	Embedding []float64      `json:"embedding,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
	ExpiresAt *time.Time     `json:"expires_at,omitempty"`
}

type MemoryType string

type ObservabilityHook func(provider string, op string, duration time.Duration, err error)

type Observation struct {
	Content   string         `json:"content"`
	Source    string         `json:"source,omitempty"`
	Timestamp time.Time      `json:"timestamp"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type Provider interface {
	// Add adds a new memory.
	Add(ctx context.Context, req *AddRequest) (*Memory, error)

	// Get retrieves a memory by ID.
	Get(ctx context.Context, req *GetRequest) (*Memory, error)

	// Update updates an existing memory.
	Update(ctx context.Context, req *UpdateRequest) (*Memory, error)

	// Delete deletes a memory by ID.
	Delete(ctx context.Context, req *DeleteRequest) error

	// List lists memories with optional filters.
	List(ctx context.Context, req *ListRequest) (*ListResponse, error)

	// Search performs semantic search on memories.
	Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)

	// Recall retrieves relevant memories for a given query.
	Recall(ctx context.Context, req *RecallRequest) (*RecallResponse, error)

	// Close closes the provider and releases resources.
	Close() error

	// Name returns the provider name.
	Name() string
}

type ProviderConfig struct {
	Name     ProviderName   `json:"name"`
	DSN      string         `json:"dsn,omitempty"`
	APIKey   string         `json:"api_key,omitempty"`
	Endpoint string         `json:"endpoint,omitempty"`
	Options  map[string]any `json:"options,omitempty"`
}

type ProviderError struct {
	Provider string
	Op       string
	Err      error
}

type ProviderFactory func(config ProviderConfig, embedder Embedder) (Provider, error)

type ProviderName string

type RecallRequest struct {
	Context
	Query        string       `json:"query"`
	MaxResults   int          `json:"max_results,omitempty"`
	IncludeTypes []MemoryType `json:"include_types,omitempty"`
}

type RecallResponse struct {
	Memories []*Memory `json:"memories"`
	Summary  string    `json:"summary,omitempty"`
}

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

type Scope string

type SearchRequest struct {
	Context
	Query     string       `json:"query"`
	Types     []MemoryType `json:"types,omitempty"`
	Scopes    []Scope      `json:"scopes,omitempty"`
	Limit     int          `json:"limit,omitempty"`
	Threshold float64      `json:"threshold,omitempty"` // Similarity threshold
}

type SearchResponse struct {
	Results []*SearchResult `json:"results"`
}

type SearchResult struct {
	Memory *Memory `json:"memory"`
	Score  float64 `json:"score"`
}

type UpdateRequest struct {
	Context
	ID       string         `json:"id"`
	Content  string         `json:"content,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
}