graphflow

package
v2.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 12, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package graphflow provides a library-first graph extraction/build/report/export pipeline over CortexDB's graph and RDF storage.

The package is intentionally layered:

  • Detector finds input documents.
  • Extractor emits a unified extraction schema.
  • Build persists that schema into CortexDB's graph store.
  • Analyze derives deterministic graph summaries.
  • RenderReport produces markdown output.
  • Export writes graph.json plus GRAPH_REPORT.md.

The default closed loop is deterministic and does not require an LLM. Model-dependent extractors can be plugged in later via the Extractor interface.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewMCPServer 

func NewMCPServer(db *cortexdb.DB, detector Detector, extractor Extractor, opts MCPServerOptions) (*mcp.Server, error)

NewMCPServer returns an MCP server that exposes the graphflow tool surface.

func RenderReport 

func RenderReport(_ context.Context, report *AnalysisReport) (string, error)

RenderReport renders a deterministic markdown report.

func ValidateExtraction 

func ValidateExtraction(result *ExtractionResult) error

ValidateExtraction checks that an extraction result is structurally usable.

Types

type AnalysisReport 

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"`
}

AnalysisReport is the deterministic summary of a graphflow graph.

func Analyze 

func Analyze(ctx context.Context, db *cortexdb.DB, req AnalyzeRequest) (*AnalysisReport, error)

Analyze computes a deterministic summary over graphflow nodes and edges.

type AnalyzeRequest 

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

AnalyzeRequest scopes deterministic graph analysis.

type Analyzer 

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

Analyzer derives deterministic graph summaries from a persisted graphflow subgraph.

type BuildOptions 

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

BuildOptions controls persistence behavior.

type BuildResult 

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

BuildResult summarizes one build operation.

func Build 

func Build(ctx context.Context, db *cortexdb.DB, extractions []ExtractionResult, opts BuildOptions) (*BuildResult, error)

Build persists extraction results into the existing CortexDB graph store.

type Confidence 

type Confidence string

Confidence labels whether an edge was directly found or only inferred by an upstream extractor. 

const (
	ConfidenceExtracted Confidence = "EXTRACTED"
	ConfidenceInferred  Confidence = "INFERRED"
	ConfidenceAmbiguous Confidence = "AMBIGUOUS"
)

type Detector 

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

Detector enumerates input documents.

type ExportRequest 

type ExportRequest struct {
	OutputDir string          `json:"output_dir"`
	Analysis  *AnalysisReport `json:"analysis,omitempty"`
	Report    string          `json:"report,omitempty"`
}

ExportRequest writes a graphflow bundle to disk.

type ExportResult 

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"`
}

ExportResult returns the written file paths.

func Export 

func Export(ctx context.Context, db *cortexdb.DB, req ExportRequest) (*ExportResult, error)

Export writes a minimal graphflow bundle to disk.

func ExportHTML 

func ExportHTML(ctx context.Context, db *cortexdb.DB, req ExportRequest) (*ExportResult, error)

ExportHTML generates an HTML visualization of the graph. It embeds the graph data directly in the HTML file and loads Cytoscape/Dagre from a CDN at runtime. Open the HTML file in any modern browser to view it.

type Exporter 

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

Exporter writes graphflow outputs to disk.

type ExtractionEdge 

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"`
}

ExtractionEdge is one extracted graph edge before persistence.

type ExtractionNode 

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"`
}

ExtractionNode is one extracted graph node before persistence.

type ExtractionResult 

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"`
}

ExtractionResult is the canonical schema that all extractors must emit.

type Extractor 

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

Extractor converts one input document into the canonical extraction schema.

type FilesystemDetector 

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

FilesystemDetector is a deterministic detector for local text/code corpora.

func (FilesystemDetector) Detect 

func (d FilesystemDetector) Detect(ctx context.Context, root string) ([]SourceDocument, error)

Detect enumerates source documents under a root directory.

type HeuristicExtractor 

type HeuristicExtractor struct{}

HeuristicExtractor is a deterministic extractor that emits a basic node/edge graph from text and code.

func (HeuristicExtractor) Extract 

func (HeuristicExtractor) Extract(_ context.Context, doc SourceDocument) (*ExtractionResult, error)

Extract emits a document node, entity nodes, mention edges, and simple co-occurrence edges.

type JSONGenerator 

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

JSONGenerator is the minimal interface required for an LLM-backed extractor.

type LLMExtractor 

type LLMExtractor struct {
	Client   JSONGenerator
	MaxChars int
}

LLMExtractor delegates extraction to a model that returns JSON matching the extraction schema.

func (LLMExtractor) Extract 

func (e LLMExtractor) Extract(ctx context.Context, doc SourceDocument) (*ExtractionResult, error)

Extract calls the configured JSON generator and normalizes the returned payload.

type MCPServerOptions 

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

MCPServerOptions configures the graphflow MCP server wrapper.

type Pipeline 

type Pipeline struct {
	Detector  Detector
	Extractor Extractor
}

Pipeline wires detector and extractor into the deterministic graphflow loop.

func NewPipeline 

func NewPipeline(detector Detector, extractor Extractor) (*Pipeline, error)

NewPipeline constructs a graphflow pipeline.

func (*Pipeline) Run 

func (p *Pipeline) Run(ctx context.Context, db *cortexdb.DB, req RunRequest) (*RunResult, error)

Run executes detect -> extract -> build -> analyze -> report -> export.

type Reporter 

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

Reporter renders an analysis report.

type RunRequest 

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

RunRequest is the end-to-end graphflow pipeline input.

type RunResult 

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"`
}

RunResult summarizes a full graphflow pipeline execution.

type SourceDocument 

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"`
}

SourceDocument is one input document identified by a detector stage.

type Toolbox 

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

Toolbox exposes graphflow as a tool-call surface.

func NewToolbox 

func NewToolbox(db *cortexdb.DB, detector Detector, extractor Extractor) (*Toolbox, error)

NewToolbox constructs a graphflow tool facade.

func (*Toolbox) Call 

func (t *Toolbox) Call(ctx context.Context, name string, input json.RawMessage) (any, error)

Call dispatches a graphflow tool call.

func (*Toolbox) Definitions 

func (t *Toolbox) Definitions() []cortexdb.ToolDefinition

Definitions returns JSON-schema-like graphflow tool definitions.

type TopNode 

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

TopNode is one ranked node from analysis.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.