gognee

type AddOptions struct {
	Source string
}

type AddedDocument struct {
	Text    string
	Source  string
	AddedAt time.Time
}

type CognifyOptions struct {
	// SkipProcessed enables incremental mode, skipping previously processed documents.
	// Default: true (incremental by default). Use pointer to distinguish unset from explicit false.
	// When true, documents are identified by content hash (SHA-256).
	// Documents with matching hash are skipped unless Force is true.
	SkipProcessed *bool

	// Force reprocesses all documents regardless of cached state.
	// Overrides SkipProcessed when true.
	// Use after changing chunker settings or to rebuild the knowledge graph.
	Force bool

	// TraceEnabled enables detailed timing instrumentation for performance analysis.
	// Default: false (off by default to minimize overhead).
	// When enabled, timing spans are collected and returned in CognifyResult.Trace.
	TraceEnabled bool
}

type CognifyResult struct {
	DocumentsProcessed int // Documents actually processed (chunked + extracted)
	DocumentsSkipped   int // Documents skipped due to incremental caching
	ChunksProcessed    int
	ChunksFailed       int
	NodesCreated       int
	EdgesCreated       int
	EdgesSkipped       int             // Count of edges skipped due to entity lookup failure or ambiguity
	Errors             []error         // Includes details of skipped edges ("skipped edge" in message)
	Trace              *OperationTrace // Timing data (populated when CognifyOptions.TraceEnabled is true)
}

type Config struct {
	// OpenAI API key for embeddings and LLM
	OpenAIKey string

	// Embedding model (default: "text-embedding-3-small")
	EmbeddingModel string

	// LLM model for entity extraction (default: "gpt-4o-mini")
	LLMModel string

	// Chunk size in tokens (default: 512)
	ChunkSize int

	// Chunk overlap in tokens (default: 50)
	ChunkOverlap int

	// DBPath is the path to the SQLite database file.
	// If empty or ":memory:", an in-memory database is used.
	DBPath string

	// DecayEnabled enables time-based memory decay scoring (default: false)
	DecayEnabled bool

	// DecayHalfLifeDays is the number of days after which a node's score is halved (default: 30)
	DecayHalfLifeDays int

	// DecayBasis determines decay calculation: "access" (last access time) or "creation" (creation time)
	// Default: "access"
	DecayBasis string

	// AccessFrequencyEnabled enables frequency-based decay modification (default: true when DecayEnabled)
	// When enabled, frequently accessed memories resist time-based decay
	AccessFrequencyEnabled bool

	// ReferenceAccessCount is the access count at which heat_multiplier = 1.0 (default: 10)
	// Memories with this many accesses get full heat protection from decay
	ReferenceAccessCount int
}

type Edge = store.Edge

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

type MemoryInput struct {
	Topic     string
	Context   string
	Decisions []string
	Rationale []string
	Metadata  map[string]interface{}
	Source    string
	// TraceEnabled enables timing instrumentation (Plan 015)
	TraceEnabled bool
	// Supersedes lists memory IDs that this new memory replaces (M4: Plan 021)
	Supersedes []string
	// SupersessionReason explains why this memory supersedes the old ones (M4: Plan 021)
	SupersessionReason string
	// RetentionPolicy sets the retention policy for this memory (M6: Plan 021)
	// Valid values: permanent, decision, standard, ephemeral, session (default: standard)
	RetentionPolicy string
}

type MemoryResult struct {
	MemoryID     string
	NodesCreated int
	EdgesCreated int
	NodesDeleted int
	EdgesDeleted int
	Errors       []error
	// Trace contains timing data when TraceEnabled is true (Plan 015)
	Trace *OperationTrace
	// MemoriesSuperseded is the count of memories marked as Superseded (M4: Plan 021)
	MemoriesSuperseded int
}

type Node = store.Node

type OperationTrace struct {
	// Spans contains timing data for each stage of the operation
	Spans []Span `json:"spans"`

	// TotalDurationMs is the total elapsed time for the operation in milliseconds
	TotalDurationMs int64 `json:"totalDurationMs"`
}

type PruneOptions struct {
	// MaxAgeDays prunes nodes older than this many days (based on decay basis).
	// If zero, this criterion is not used.
	MaxAgeDays int

	// MinDecayScore prunes nodes with decay score below this threshold.
	// If zero, this criterion is not used.
	// Score is calculated using current decay settings.
	MinDecayScore float64

	// DryRun reports what would be pruned without actually deleting.
	DryRun bool

	// PruneSuperseded enables pruning of Superseded memories (M5: Plan 021, default: true)
	PruneSuperseded bool

	// SupersededAgeDays only prunes Superseded memories older than this (M5: Plan 021, default: 30)
	SupersededAgeDays int
}

type PruneResult struct {
	NodesEvaluated int      // Total number of nodes considered
	NodesPruned    int      // Number of nodes deleted
	EdgesPruned    int      // Number of edges deleted (via cascade)
	NodeIDs        []string // IDs of pruned nodes (for verification)
	// SupersededMemoriesPruned is the count of Superseded memories pruned (M5: Plan 021)
	SupersededMemoriesPruned int
	// MemoriesEvaluated is the total number of memories considered for pruning (M5: Plan 021)
	MemoriesEvaluated int
}

type RetentionPolicyDef struct {
	HalfLifeDays int  // Decay half-life in days (0 = no decay for permanent)
	Prunable     bool // Whether memories with this policy can be pruned
}

type SearchOptions = search.SearchOptions

type SearchResponse struct {
	Results []search.SearchResult // The search results
	Trace   *OperationTrace       // Timing data (populated when SearchOptions.TraceEnabled is true)
}

type SearchResult = search.SearchResult

type SearchType = search.SearchType

type Span struct {
	// Name identifies the operation stage (see Span documentation for stable names)
	Name string `json:"name"`

	// DurationMs is the elapsed time for this span in milliseconds
	DurationMs int64 `json:"durationMs"`

	// OK indicates whether the span completed successfully
	OK bool `json:"ok"`

	// Error contains error message if OK is false (optional)
	Error string `json:"error,omitempty"`

	// ErrorType classifies the error for metrics (added in Plan 016 M3)
	ErrorType string `json:"errorType,omitempty"`

	// Counters provides additional metrics for the span (optional)
	// Example keys: "chunkCount", "nodeUpserts", "edgeUpserts", "resultsReturned"
	Counters map[string]int64 `json:"counters,omitempty"`
}

type Stats struct {
	NodeCount     int64
	EdgeCount     int64
	MemoryCount   int64
	BufferedDocs  int
	LastCognified time.Time
}