types

type CachedAnalysis struct {
	// Versioning - tracks cache entry compatibility
	SchemaVersion   int `json:"schema_version"`   // CachedAnalysis structure version
	MetadataVersion int `json:"metadata_version"` // Metadata extraction logic version
	SemanticVersion int `json:"semantic_version"` // Semantic analysis logic version

	// Provider information - tracks which provider and model produced this analysis
	Provider string `json:"provider"` // Provider name (e.g., "claude", "openai", "gemini")
	Model    string `json:"model"`    // Model ID used (e.g., "claude-sonnet-4-5-20250929")

	// Core fields
	FilePath   string            `json:"file_path"`
	FileHash   string            `json:"file_hash"`
	AnalyzedAt time.Time         `json:"analyzed_at"`
	Metadata   FileMetadata      `json:"metadata"`
	Semantic   *SemanticAnalysis `json:"semantic,omitempty"`
	Error      *string           `json:"error,omitempty"`
}

type Cluster struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	FileCount   int      `json:"file_count"`
	FilePaths   []string `json:"file_paths,omitempty"`
	CommonTags  []string `json:"common_tags,omitempty"`
}

type Entity struct {
	Name string `json:"name"` // The entity name (e.g., "Terraform", "AWS")
	Type string `json:"type"` // Entity type: technology, person, concept, organization, project
}

type EntityCount struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Count int    `json:"count"`
}

type EntityRef struct {
	Name string `json:"name"`
	Type string `json:"type"` // technology, person, organization, concept, project
}

type Fact struct {
	ID        string    `json:"id"`
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
	Source    string    `json:"source"`
}

type FactStats struct {
	TotalFacts int `json:"total_facts"`
	MaxFacts   int `json:"max_facts"`
}

type FactsIndex struct {
	Generated time.Time `json:"generated"`
	Facts     []Fact    `json:"facts"`
	Stats     FactStats `json:"stats"`
}

type FileEntry struct {
	// Identity
	Path string `json:"path"`
	Name string `json:"name"`
	Hash string `json:"hash"`

	// Classification
	Type     string `json:"type"`     // file extension
	Category string `json:"category"` // documents, code, images, etc.

	// Physical attributes
	Size       int64     `json:"size"`
	SizeHuman  string    `json:"size_human"`
	Modified   time.Time `json:"modified"`
	IsReadable bool      `json:"is_readable"`

	// Type-specific metadata (optional)
	WordCount  *int      `json:"word_count,omitempty"`
	PageCount  *int      `json:"page_count,omitempty"`
	SlideCount *int      `json:"slide_count,omitempty"`
	Dimensions *ImageDim `json:"dimensions,omitempty"`
	Duration   *string   `json:"duration,omitempty"`
	Language   *string   `json:"language,omitempty"`
	Author     *string   `json:"author,omitempty"`

	// Semantic understanding
	Summary      string  `json:"summary,omitempty"`
	DocumentType string  `json:"document_type,omitempty"`
	Confidence   float64 `json:"confidence,omitempty"`

	// Graph relationships (the knowledge graph edges)
	Tags     []string    `json:"tags,omitempty"`
	Topics   []string    `json:"topics,omitempty"`
	Entities []EntityRef `json:"entities,omitempty"`

	// Related files (the graph value-add) - populated in verbose mode
	RelatedFiles []RelatedFile `json:"related_files,omitempty"`

	// Error (if analysis failed)
	Error *string `json:"error,omitempty"`
}

type FileIndex struct {
	// Metadata
	Generated  time.Time  `json:"generated"`
	MemoryRoot string     `json:"memory_root"`
	Stats      IndexStats `json:"stats"`

	// Files with their semantic understanding and relationships
	Files []FileEntry `json:"files"`

	// Knowledge graph summary (tag/topic/entity landscape)
	Knowledge *KnowledgeSummary `json:"knowledge,omitempty"`

	// Insights from graph analytics (verbose mode only)
	Insights *IndexInsights `json:"insights,omitempty"`

	// Usage guide for consuming files
	UsageGuide *UsageGuide `json:"usage_guide,omitempty"`
}

type FileInfo struct {
	Path       string    `json:"path"`
	RelPath    string    `json:"rel_path"`
	Hash       string    `json:"hash"`
	Size       int64     `json:"size"`
	Modified   time.Time `json:"modified"`
	Type       string    `json:"type"`
	Category   string    `json:"category"`
	IsReadable bool      `json:"is_readable"`
}

type FileMetadata struct {
	FileInfo
	// Type-specific fields
	WordCount  *int      `json:"word_count,omitempty"`
	PageCount  *int      `json:"page_count,omitempty"`
	SlideCount *int      `json:"slide_count,omitempty"`
	Dimensions *ImageDim `json:"dimensions,omitempty"`
	Duration   *string   `json:"duration,omitempty"`
	Sections   []string  `json:"sections,omitempty"`
	Language   *string   `json:"language,omitempty"`
	Author     *string   `json:"author,omitempty"`
}

type Gap struct {
	Type        string `json:"type"` // topic, entity, tag, category
	Name        string `json:"name"`
	Description string `json:"description"`
	Severity    string `json:"severity"` // low, medium, high
	Suggestion  string `json:"suggestion,omitempty"`
}

type ImageDim struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

type IndexEntry struct {
	Metadata FileMetadata      `json:"metadata"`
	Semantic *SemanticAnalysis `json:"semantic,omitempty"`
	Error    *string           `json:"error,omitempty"`
}

type IndexInsights struct {
	// File recommendations based on graph relationships
	Recommendations []Recommendation `json:"recommendations,omitempty"`

	// Topic clusters detected in the graph
	TopicClusters []Cluster `json:"topic_clusters,omitempty"`

	// Coverage gaps identified in the knowledge base
	CoverageGaps []Gap `json:"coverage_gaps,omitempty"`
}

type IndexStats struct {
	// File statistics
	TotalFiles    int   `json:"total_files"`
	TotalSize     int64 `json:"total_size"`
	AnalyzedFiles int   `json:"analyzed_files"`
	CachedFiles   int   `json:"cached_files"`
	ErrorFiles    int   `json:"error_files"`

	// Graph statistics
	TotalTags     int            `json:"total_tags,omitempty"`
	TotalTopics   int            `json:"total_topics,omitempty"`
	TotalEntities int            `json:"total_entities,omitempty"`
	TotalEdges    int            `json:"total_edges,omitempty"`
	ByCategory    map[string]int `json:"by_category,omitempty"`

	// Coverage metrics
	FilesWithSummary  int     `json:"files_with_summary,omitempty"`
	FilesWithTags     int     `json:"files_with_tags,omitempty"`
	FilesWithTopics   int     `json:"files_with_topics,omitempty"`
	FilesWithEntities int     `json:"files_with_entities,omitempty"`
	AvgTagsPerFile    float64 `json:"avg_tags_per_file,omitempty"`
}

type KnowledgeSummary struct {
	// Top tags by file count
	TopTags []TagCount `json:"top_tags,omitempty"`

	// Top topics by file count
	TopTopics []TopicCount `json:"top_topics,omitempty"`

	// Top entities by mention count
	TopEntities []EntityCount `json:"top_entities,omitempty"`
}

type Recommendation struct {
	SourcePath  string   `json:"source_path"`
	TargetPath  string   `json:"target_path"`
	TargetName  string   `json:"target_name"`
	Reason      string   `json:"reason"`
	SharedItems []string `json:"shared_items,omitempty"`
	Score       float64  `json:"score"`
}

type Reference struct {
	Topic      string  `json:"topic"`      // The referenced topic
	Type       string  `json:"type"`       // Reference type: requires, extends, related-to, implements
	Confidence float64 `json:"confidence"` // Confidence score 0.0-1.0
}

type RelatedFile struct {
	Path   string   `json:"path"`
	Name   string   `json:"name"`
	Via    string   `json:"via"`    // "tags", "topics", "entities", "similarity"
	Shared []string `json:"shared"` // The actual shared items
	Score  float64  `json:"score,omitempty"`
}

type SemanticAnalysis struct {
	Summary      string      `json:"summary"`
	Tags         []string    `json:"tags"`
	KeyTopics    []string    `json:"key_topics"`
	DocumentType string      `json:"document_type"`
	Confidence   float64     `json:"confidence"`
	Entities     []Entity    `json:"entities,omitempty"`   // Named entities mentioned in content
	References   []Reference `json:"references,omitempty"` // Topic references and dependencies
}

type TagCount struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

type TopicCount struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

type UsageGuide struct {
	// Description explains what the memory index is
	Description string `json:"description"`
	// WhenToUse provides guidance on when to access files
	WhenToUse string `json:"when_to_use"`
	// DirectReadable lists file types that can be read directly by the agent
	DirectReadable string `json:"direct_readable"`
	// ExtractionRequired lists file types that need extraction before reading
	ExtractionRequired string `json:"extraction_required"`
}