schema

type ChatMessageType string

type CodeChunk struct {
	// Content is the code content of the chunk.
	Content string `json:"content"`
	// LineStart is the starting line number in the source file.
	LineStart int `json:"lineStart"`
	// LineEnd is the ending line number in the source file.
	LineEnd int `json:"lineEnd"`
	// Type is the chunk type (e.g., "function", "struct", "import").
	Type string `json:"type"`
	// Identifier is the primary identifier of the chunk (e.g., function name).
	Identifier string `json:"identifier"`
	// Annotations contains additional annotations for the chunk.
	Annotations map[string]string `json:"annotations"`
	// TokenCount is the estimated number of tokens in the chunk.
	TokenCount int `json:"tokenCount"`
	// EnrichedContent contains the content with added context.
	EnrichedContent string `json:"enrichedContent"`
	// ParentContext contains context from the parent structure.
	ParentContext string `json:"parentContext"`
	// ContextLevel indicates the nesting level of the context.
	ContextLevel int `json:"contextLevel"`
	// Sparse is an optional sparse vector for hybrid search.
	Sparse *SparseVector `json:"sparse,omitempty"`
	// ParentID uniquely identifies the parent code structure (function/class) this chunk belongs to.
	// Empty for top-level chunks that are not split.
	ParentID string `json:"parentID,omitempty"`
	// FullParentText contains the complete text of the parent structure.
	// WARNING: This can be large. Logic should truncate this before storage.
	FullParentText string `json:"fullParentText,omitempty"`
	// IsDefinition is true if this chunk represents the primary source-of-truth definition of a symbol.
	IsDefinition bool `json:"is_definition"`
	// SymbolType is the category of the symbol (e.g., struct, interface, function).
	SymbolType string `json:"symbol_type"`
}

type CodeChunkingOptions struct {
	// ChunkSize is the target size in tokens for each chunk.
	ChunkSize int
	// OverlapTokens is the number of overlapping tokens between chunks.
	OverlapTokens int
	// PreserveStructure attempts to keep related code together.
	PreserveStructure bool
	// LanguageHints provides hints about the language for better chunking.
	LanguageHints []string
	// MaxLinesPerChunk limits the maximum lines per chunk.
	MaxLinesPerChunk int
	// MinCharsPerChunk is the minimum characters required for a valid chunk.
	MinCharsPerChunk int
}

type CodeEntityDefinition struct {
	// Type is the entity type (e.g., "function", "struct", "interface").
	Type string `json:"type"`
	// Name is the entity name.
	Name string `json:"name"`
	// LineStart is the starting line number.
	LineStart int `json:"line_start"`
	// LineEnd is the ending line number.
	LineEnd int `json:"line_end"`
	// Visibility is the export visibility (e.g., "public", "private").
	Visibility string `json:"visibility"`
	// Signature is the function/method signature.
	Signature string `json:"signature"`
	// Documentation is the doc comment for the entity.
	Documentation string `json:"documentation"`
}

type CodeSymbol struct {
	// Name is the symbol name.
	Name string `json:"name"`
	// Type is the symbol type (e.g., "function", "variable", "type").
	Type string `json:"type"`
	// LineStart is the starting line number.
	LineStart int `json:"line_start"`
	// LineEnd is the ending line number.
	LineEnd int `json:"line_end"`
	// IsExport indicates if the symbol is exported.
	IsExport bool `json:"is_export"`
}

type ContentChoice struct {
	// Content is the generated text content.
	Content string
	// StopReason is the reason generation stopped (e.g., "stop", "length").
	StopReason string
	// GenerationInfo contains metadata about the generation.
	GenerationInfo map[string]any
	// ReasoningContent contains chain-of-thought reasoning (for models that support it).
	ReasoningContent string
}

type ContentPart interface {
	String() string
	// contains filtered or unexported methods
}

type ContentResponse struct {
	// Choices contains the generated content choices.
	Choices []*ContentChoice
}

type Document struct {
	// PageContent is the text content of the document.
	PageContent string
	// Metadata contains arbitrary key-value pairs associated with the document.
	Metadata map[string]any
	// Sparse is an optional sparse vector for hybrid search.
	Sparse *SparseVector
}

type FileMetadata struct {
	// FilePath is the path to the file.
	FilePath string `json:"file_path"`
	// Language is the programming language (e.g., "go", "typescript").
	Language string `json:"language"`
	// PackageName is the name of the package/module.
	PackageName string `json:"package_name"`
	// Imports is the list of imported packages/modules.
	Imports []string `json:"imports"`
	// Definitions contains the top-level definitions in the file.
	Definitions []CodeEntityDefinition `json:"definitions"`
	// Symbols contains all symbols found in the file.
	Symbols []CodeSymbol `json:"symbols"`
	// Properties contains additional file properties.
	Properties map[string]string `json:"properties"`
}

type MessageContent struct {
	// Role is the role of the message sender.
	Role ChatMessageType
	// Parts contains the content parts of the message.
	Parts []ContentPart
}

type ModelDetails struct {
	// Family is the model family (e.g., "llama", "gemma").
	Family string
	// ParameterSize is the parameter count (e.g., "7B", "13B").
	ParameterSize string
	// Quantization is the quantization level (e.g., "q4_0", "f16").
	Quantization string
	// Dimension is the embedding dimension of the model.
	Dimension int64
}

type NoOpReranker struct{}

type OutputParser[T any] interface {
	// Parse converts the raw text output into type T.
	Parse(ctx context.Context, text string) (T, error)
}

type ParserPlugin interface {
	// Name returns the name of the parser (e.g., "go", "typescript").
	Name() string
	// Extensions returns the file extensions this parser handles (e.g., ".go", ".ts").
	Extensions() []string
	// CanHandle returns true if this parser can handle the given file.
	CanHandle(path string, info fs.FileInfo) bool
	// Chunk splits the content into semantic chunks with metadata.
	Chunk(content string, path string, opts *CodeChunkingOptions) ([]CodeChunk, error)
	// ExtractMetadata extracts file-level metadata like package name and imports.
	ExtractMetadata(content string, path string) (FileMetadata, error)
	// IsGenerated returns true if the file appears to be auto-generated.
	IsGenerated(content string, path string) bool
	// ExtractUsedSymbols identifies potential external types/functions
	// being used in the code that might need a definition lookup.
	ExtractUsedSymbols(content string) []string
}

type Reranker interface {
	// Rerank reorders documents by relevance to the query,
	// returning scored documents with explanations.
	Rerank(ctx context.Context, query string, docs []Document) ([]ScoredDocument, error)
}

type Retriever interface {
	// GetRelevantDocuments returns documents relevant to the query.
	GetRelevantDocuments(ctx context.Context, query string) ([]Document, error)
}

type ScoredDocument struct {
	Document
	// Score is the relevance score, typically between 0 and 10.
	Score float64
	// Reason contains an explanation for the score, if available.
	Reason string
}

type SparseVector struct {
	Indices []uint32  `json:"indices"`
	Values  []float32 `json:"values"`
}

type StringParser struct{}

type TextContent struct {
	// Text is the text content.
	Text string
}