graphflow

type AnalysisReport struct {
	GeneratedAt        time.Time      `json:"generated_at"`
	NodeCount          int            `json:"node_count"`
	EdgeCount          int            `json:"edge_count"`
	NodeTypes          map[string]int `json:"node_types,omitempty"`
	RelationTypes      map[string]int `json:"relation_types,omitempty"`
	Confidence         map[string]int `json:"confidence,omitempty"`
	TopNodes           []TopNode      `json:"top_nodes,omitempty"`
	SuggestedQuestions []string       `json:"suggested_questions,omitempty"`
}

type AnalyzeRequest struct {
	TopN int `json:"top_n,omitempty"`
}

type Analyzer interface {
	Analyze(ctx context.Context, db *cortexdb.DB, req AnalyzeRequest) (*AnalysisReport, error)
}

type BuildOptions struct {
	Collection   string `json:"collection,omitempty"`
	ReplaceEdges bool   `json:"replace_edges,omitempty"`
}

type BuildResult struct {
	NodeCount int `json:"node_count"`
	EdgeCount int `json:"edge_count"`
}

type CommunityOptions struct {
	LLM     JSONGenerator // required: writes each community report
	MinSize int           // skip communities with fewer entities (default 3)
	Max     int           // cap communities summarized (0 = all)
}

type CommunityReport struct {
	Communities []CommunitySummary `json:"communities"`
}

type CommunitySummary struct {
	ID       int      `json:"id"`
	Title    string   `json:"title"`
	Summary  string   `json:"summary"`
	Findings []string `json:"findings,omitempty"`
	Entities []string `json:"entities"`
	Size     int      `json:"size"`
}

type Confidence string

type Detector interface {
	Detect(ctx context.Context, root string) ([]SourceDocument, error)
}

type ExportRequest struct {
	OutputDir string          `json:"output_dir"`
	Analysis  *AnalysisReport `json:"analysis,omitempty"`
	Report    string          `json:"report,omitempty"`
	// View selects the ExportHTML renderer: "2d" (default, Cytoscape) or "3d"
	// (a WebGL 3d-force-graph scene). Ignored by Export (JSON-only).
	View string `json:"view,omitempty"`
}

type ExportResult struct {
	OutputDir      string `json:"output_dir"`
	GraphJSON      string `json:"graph_json"`
	ReportMarkdown string `json:"report_markdown,omitempty"`
	GraphHTML      string `json:"graph_html,omitempty"`
}

type Exporter interface {
	Export(ctx context.Context, db *cortexdb.DB, req ExportRequest) (*ExportResult, error)
}

type ExtractionEdge struct {
	Source         string            `json:"source"`
	Target         string            `json:"target"`
	Relation       string            `json:"relation"`
	Confidence     Confidence        `json:"confidence"`
	Directed       bool              `json:"directed,omitempty"`
	SourceFile     string            `json:"source_file,omitempty"`
	SourceLocation string            `json:"source_location,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

type ExtractionNode struct {
	ID             string            `json:"id"`
	Label          string            `json:"label"`
	Type           string            `json:"type,omitempty"`
	Summary        string            `json:"summary,omitempty"`
	SourceFile     string            `json:"source_file,omitempty"`
	SourceLocation string            `json:"source_location,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

type ExtractionResult struct {
	SourceID   string            `json:"source_id"`
	SourceType string            `json:"source_type,omitempty"`
	Title      string            `json:"title,omitempty"`
	Nodes      []ExtractionNode  `json:"nodes"`
	Edges      []ExtractionEdge  `json:"edges"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

type Extractor interface {
	Extract(ctx context.Context, doc SourceDocument) (*ExtractionResult, error)
}

type FilesystemDetector struct {
	IncludeExtensions []string
	ExcludeDirs       []string
	MaxFileBytes      int64
	ReadContent       bool
}

type GlobalSearchOptions struct {
	LLM       JSONGenerator // required
	MaxPoints int           // top key points fed to the reduce step (default 12)
	// BuildIfEmpty builds community summaries first when none are persisted yet.
	BuildIfEmpty bool
}

type GlobalSearchResult struct {
	Query            string   `json:"query"`
	Answer           string   `json:"answer"`
	CommunitiesUsed  int      `json:"communities_used"`
	SupportingPoints []string `json:"supporting_points,omitempty"`
}

type GraphEdit struct {
	Op   string `json:"op"`   // add|update|delete
	Kind string `json:"kind"` // entity|relation

	// Entity fields (Kind == "entity").
	Name    string `json:"name,omitempty"`
	Type    string `json:"type,omitempty"`
	Summary string `json:"summary,omitempty"`

	// Relation fields (Kind == "relation").
	From    string `json:"from,omitempty"`
	To      string `json:"to,omitempty"`
	RelType string `json:"rel_type,omitempty"`

	// Reason is the model's justification; surfaced in dry runs.
	Reason string `json:"reason,omitempty"`
}

type GraphEditOptions struct {
	// LLM is required by UpdateGraphFromText; ApplyGraphEdits ignores it.
	LLM JSONGenerator
	// DryRun reports what would change without touching the graph.
	DryRun bool
	// AllowDelete must be set for delete edits to apply. Deletion is
	// destructive and not reversible, so it is opt-in.
	AllowDelete bool
	// MaxDeletes caps how many deletes may apply in one pass (0 = default 20),
	// so a confused model cannot wipe a graph in a single call.
	MaxDeletes int
	// MaxContextEntities bounds how many existing entities are shown to the
	// model (0 = default 60).
	MaxContextEntities int
}

type GraphEditPlan struct {
	Edits []GraphEdit `json:"edits"`
}

type GraphEditReport struct {
	EntitiesAdded    int         `json:"entities_added"`
	EntitiesUpdated  int         `json:"entities_updated"`
	EntitiesDeleted  int         `json:"entities_deleted"`
	RelationsAdded   int         `json:"relations_added"`
	RelationsDeleted int         `json:"relations_deleted"`
	Skipped          []string    `json:"skipped,omitempty"`
	Applied          []GraphEdit `json:"applied,omitempty"`
	DryRun           bool        `json:"dry_run,omitempty"`
}

type HeuristicExtractor struct{}

type JSONGenerator interface {
	GenerateJSON(ctx context.Context, systemPrompt string, userPrompt string) ([]byte, error)
}

type LLMExtractor struct {
	Client   JSONGenerator
	MaxChars int
}

type LearningConcept struct {
	Name       string `json:"name"`
	Type       string `json:"type,omitempty"`    // see allowedConceptTypes
	Subject    string `json:"subject,omitempty"` // physics|chemistry|math|language|…
	Summary    string `json:"summary,omitempty"`
	Difficulty int    `json:"difficulty,omitempty"` // 1..5, optional
	Mastered   bool   `json:"mastered,omitempty"`   // filled in by queries
}

type LearningGraph struct {
	Subject   string             `json:"subject,omitempty"`
	Concepts  []LearningConcept  `json:"concepts"`
	Relations []LearningRelation `json:"relations"`
}

type LearningImportReport struct {
	Subject   int `json:"-"`
	Concepts  int `json:"concepts"`
	Relations int `json:"relations"`
}

type LearningPathResult struct {
	Target string            `json:"target"`
	Steps  []LearningConcept `json:"steps"` // prerequisites first, target last
	Known  []string          `json:"known"` // already-mastered concepts that were skipped
	// Concepts that genuinely lie on a prerequisite cycle — not merely the ones
	// waiting behind one. Each appears once. See cyclicConcepts.
	Cycles  []string `json:"cycles"`
	Missing bool     `json:"missing"` // target not present in the graph
}

type LearningRelation struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type,omitempty"` // requires|part_of|example_of|applies
}

type MCPServerOptions struct {
	Implementation *mcp.Implementation
	Instructions   string
	Logger         *slog.Logger
}

type MultiHopOptions struct {
	LLM        JSONGenerator // required: decides sufficiency and emits the next query
	MaxHops    int           // cap retrieval iterations (default 4)
	TopKPerHop int           // knowledge hits pulled per hop (default 5)
}

type MultiHopResult struct {
	Query  string         `json:"query"`
	Answer string         `json:"answer"`
	Hops   int            `json:"hops"`
	Steps  []MultiHopStep `json:"steps,omitempty"`
}

type MultiHopStep struct {
	Query    string   `json:"query"`
	Snippets []string `json:"snippets,omitempty"`
}

type OrganizeOptions struct {
	// IncludeMemories scans the agent-memory store (messages). Defaults to true
	// when both IncludeMemories and IncludeKnowledge are left false.
	IncludeMemories bool
	// IncludeKnowledge scans durable knowledge (documents).
	IncludeKnowledge bool
	// MaxDocuments caps the number of texts scanned (0 = no cap).
	MaxDocuments int
	// LLM, when set, replaces the deterministic candidate extractor with an LLM
	// that distills clean, typed entities and only explicitly-stated relations.
	// When nil, extraction stays fully deterministic (no LLM, no embedder) — the
	// default. Results are written through the same GraphRAG upsert path either
	// way, so the graph view and GraphRAG retrieval read them identically.
	LLM JSONGenerator
}

type OrganizeReport struct {
	DocumentsScanned int `json:"documents_scanned"`
	EntityCount      int `json:"entity_count"`   // new entities written
	RelationCount    int `json:"relation_count"` // relations written
	CandidatesSeen   int `json:"candidates_seen"`
	CandidatesKept   int `json:"candidates_kept"`
}

type Pipeline struct {
	Detector  Detector
	Extractor Extractor
}

type Reporter interface {
	Render(ctx context.Context, report *AnalysisReport) (string, error)
}

type ResolveGroup struct {
	Canonical string   `json:"canonical"`
	Aliases   []string `json:"aliases"`
}

type ResolveOptions struct {
	// LLM, when set, additionally proposes acronym/synonym merges that
	// normalization cannot catch (e.g. K8s ↔ Kubernetes). Optional.
	LLM JSONGenerator
	// DryRun reports the merges it would make without applying them.
	DryRun bool
}

type ResolveReport struct {
	EntitiesBefore int            `json:"entities_before"`
	EntitiesMerged int            `json:"entities_merged"` // alias nodes removed
	Groups         []ResolveGroup `json:"groups"`
	DryRun         bool           `json:"dry_run,omitempty"`
}

type RunRequest struct {
	Root      string         `json:"root"`
	OutputDir string         `json:"output_dir"`
	Build     BuildOptions   `json:"build,omitempty"`
	Analyze   AnalyzeRequest `json:"analyze,omitempty"`
}

type RunResult struct {
	Documents   []SourceDocument   `json:"documents,omitempty"`
	Extractions []ExtractionResult `json:"extractions,omitempty"`
	Build       BuildResult        `json:"build"`
	Analysis    *AnalysisReport    `json:"analysis,omitempty"`
	Report      string             `json:"report,omitempty"`
	Export      *ExportResult      `json:"export,omitempty"`
}

type SourceDocument struct {
	ID       string            `json:"id"`
	Path     string            `json:"path,omitempty"`
	Type     string            `json:"type,omitempty"`
	Title    string            `json:"title,omitempty"`
	Content  string            `json:"content,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type TemporalFact struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type"`

	ValidFrom *time.Time `json:"valid_from,omitempty"`
	ValidTo   *time.Time `json:"valid_to,omitempty"`

	// Supersede, when set on SaveTemporalFact, closes any currently-open fact
	// for the same (From, Type) subject at ValidFrom before recording this one
	// — the "new value replaces old" pattern (e.g. a changed job title).
	Supersede bool `json:"supersede,omitempty"`

	// RecordedAt is the wall-clock time the fact was written (transaction time).
	// Set by SaveTemporalFact; read back by QueryFactsAsOf.
	RecordedAt *time.Time `json:"recorded_at,omitempty"`
}

type TemporalFilter struct {
	From string `json:"from,omitempty"` // subject display name or entity id
	Type string `json:"type,omitempty"` // predicate / edge type
}

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

type TopNode struct {
	ID    string  `json:"id"`
	Label string  `json:"label"`
	Type  string  `json:"type,omitempty"`
	Score float64 `json:"score"`
}