model

package
v0.0.0-...-df7bb04 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package model defines the core data structures for the knowledge graph.

Index

Constants

View Source 
const MaxContentLength = 4096

MaxContentLength is the maximum allowed length (in bytes) for entry content. Entries exceeding this limit should be broken into smaller pieces.

View Source 
const MaxTitleLength = 200

MaxTitleLength is the maximum allowed length (in bytes) for entry titles.

View Source 
const RootScope = "root"

RootScope is the default top-level scope.

Variables

This section is empty.

Functions

func CommonAncestor 

func CommonAncestor(a, b Scope) string

CommonAncestor returns the longest common prefix path between two scopes.

func ComputeContentHash 

func ComputeContentHash(content string) string

ComputeContentHash returns the SHA-256 hex digest of the given content string.

func IsValidScopeSegment 

func IsValidScopeSegment(s string) bool

IsValidScopeSegment reports whether s is a valid single scope segment (alphanumeric with optional hyphens/underscores, starting with a letter).

func ParseScopePath 

func ParseScopePath(path string) ([]string, error)

ParseScopePath splits a scope path into its segments.

Types

type Duration 

type Duration struct {
	time.Duration
}

Duration wraps time.Duration for JSON serialization.

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Duration.

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for Duration.

type Edge 

type Edge struct {
	ID        ID        `json:"id"`
	FromID    ID        `json:"from_id"`
	ToID      ID        `json:"to_id"`
	Type      EdgeType  `json:"type"`
	Weight    *float64  `json:"weight,omitempty"` // optional relationship strength
	Meta      Metadata  `json:"meta,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

Edge represents a directed relationship between two entries.

func NewEdge 

func NewEdge(from, to ID, edgeType EdgeType) Edge

NewEdge creates a new edge with a generated ID and current timestamp.

func (Edge) EffectiveWeight 

func (e Edge) EffectiveWeight() float64

EffectiveWeight returns the edge's weight, defaulting to 1.0 if unset.

func (Edge) Reverse 

func (e Edge) Reverse() Edge

Reverse returns a new edge with from and to swapped. Useful for bidirectional relationship queries.

func (Edge) Validate 

func (e Edge) Validate() error

Validate checks that the edge has all required fields and valid values.

func (Edge) WithMeta 

func (e Edge) WithMeta(m Metadata) Edge

WithMeta returns a copy of the edge with the specified metadata.

func (Edge) WithWeight 

func (e Edge) WithWeight(w float64) Edge

WithWeight returns a copy of the edge with the specified weight.

type EdgeType 

type EdgeType string

EdgeType defines the kind of relationship between entries. 

const (
	EdgeDependsOn   EdgeType = "depends-on"  // X requires Y
	EdgeContradicts EdgeType = "contradicts" // X conflicts with Y
	EdgeSupersedes  EdgeType = "supersedes"  // X replaces Y (newer version)
	EdgeElaborates  EdgeType = "elaborates"  // X provides detail about Y
	EdgeRelatedTo   EdgeType = "related-to"  // generic association
)

Predefined edge types for common relationships.

func PredefinedEdgeTypes 

func PredefinedEdgeTypes() []EdgeType

PredefinedEdgeTypes returns all built-in edge types.

func (EdgeType) IsPredefined 

func (et EdgeType) IsPredefined() bool

IsPredefined returns true if this is a built-in edge type.

func (EdgeType) Validate 

func (et EdgeType) Validate() error

Validate checks if the edge type is valid (non-empty).

type Entry 

type Entry struct {
	ID             ID         `json:"id"`
	Title          string     `json:"title,omitempty"`
	Content        string     `json:"content"`
	ContentHash    string     `json:"content_hash,omitempty"` // SHA-256 hex digest of content
	Embedding      []float32  `json:"embedding,omitempty"`
	EmbeddingDim   int        `json:"embedding_dim,omitempty"`   // dimension for mixed model support
	EmbeddingModel string     `json:"embedding_model,omitempty"` // which model generated this
	Source         Source     `json:"source"`
	Provenance     Provenance `json:"provenance"`
	Freshness      Freshness  `json:"freshness"`
	Scope          string     `json:"scope"` // hierarchical scope path
	TTL            *Duration  `json:"ttl,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Meta           Metadata   `json:"meta,omitempty"`
	Labels         []string   `json:"labels,omitempty"`
	Version        int        `json:"version"`
	CreatedAt      time.Time  `json:"created_at"`
	UpdatedAt      time.Time  `json:"updated_at"`

	// Conflict tracking - populated by queries, not stored directly
	ConflictsWith    []ID             `json:"-"`
	ResolutionStatus ResolutionStatus `json:"-"`
}

Entry represents a single piece of knowledge in the graph.

func NewEntry 

func NewEntry(content string, source Source) Entry

NewEntry creates a new entry with a generated ID, timestamps, and content hash.

func (Entry) HasConflicts 

func (e Entry) HasConflicts() bool

HasConflicts returns true if conflicts have been detected.

func (Entry) HasEmbedding 

func (e Entry) HasEmbedding() bool

HasEmbedding returns true if the entry has an embedding vector.

func (Entry) IsExpired 

func (e Entry) IsExpired() bool

IsExpired returns true if the entry has passed its expiration time.

func (Entry) ScopeObj 

func (e Entry) ScopeObj() Scope

ScopeObj returns the Scope object for this entry's scope path.

func (*Entry) SetTTL 

func (e *Entry) SetTTL(ttl time.Duration)

SetTTL sets the TTL and calculates the expiration time.

func (*Entry) Touch 

func (e *Entry) Touch()

Touch updates the UpdatedAt timestamp to now and recomputes the content hash.

func (Entry) Validate 

func (e Entry) Validate() error

Validate checks that the entry has all required fields and valid values.

func (Entry) WithEmbedding 

func (e Entry) WithEmbedding(embedding []float32, model string) Entry

WithEmbedding returns a copy of the entry with the embedding set.

func (Entry) WithFreshness 

func (e Entry) WithFreshness(f Freshness) Entry

WithFreshness returns a copy of the entry with the freshness set.

func (Entry) WithLabels 

func (e Entry) WithLabels(labels []string) Entry

WithLabels returns a copy of the entry with the labels set.

func (Entry) WithMeta 

func (e Entry) WithMeta(m Metadata) Entry

WithMeta returns a copy of the entry with the metadata set.

func (Entry) WithProvenance 

func (e Entry) WithProvenance(p Provenance) Entry

WithProvenance returns a copy of the entry with the provenance set.

func (Entry) WithScope 

func (e Entry) WithScope(scope string) Entry

WithScope returns a copy of the entry with the scope set.

func (Entry) WithTitle 

func (e Entry) WithTitle(title string) Entry

WithTitle returns a copy of the entry with the title set.

type EventType 

type EventType string

EventType identifies the kind of CLI action that occurred. 

const (
	EventRecall EventType = "recall"
	EventSearch EventType = "search"
	EventShow   EventType = "show"
	EventAdd    EventType = "add"
	EventUpdate EventType = "update"
	EventLink   EventType = "link"
	EventDelete EventType = "delete"
)

type Freshness 

type Freshness struct {
	ObservedAt time.Time `json:"observed_at"`
	ObservedBy string    `json:"observed_by,omitempty"`
	SourceHash string    `json:"source_hash,omitempty"`
}

Freshness tracks when knowledge was last observed and whether the source has changed.

func (Freshness) FreshnessLabel 

func (f Freshness) FreshnessLabel() string

FreshnessLabel returns a display label based on age since last observation: "fresh" (< 7d), "aging Nd" (7-30d), "stale Nd" (> 30d).

type ID 

type ID struct {
	ulid.ULID
}

ID is a ULID-based identifier for all entities. ULIDs are sortable, URL-safe, and encode creation time.

func MustParseID 

func MustParseID(s string) ID

MustParseID parses a string into an ID, panicking on error.

func NewID 

func NewID() ID

NewID generates a new ID using the current time.

func ParseID 

func ParseID(s string) (ID, error)

ParseID parses a string into an ID.

func (ID) IsZero 

func (id ID) IsZero() bool

IsZero returns true if the ID is the zero value.

func (ID) MarshalJSON 

func (id ID) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (ID) String 

func (id ID) String() string

String returns the string representation of the ID.

func (ID) Time 

func (id ID) Time() time.Time

Time returns the timestamp encoded in the ULID.

func (*ID) UnmarshalJSON 

func (id *ID) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Metadata 

type Metadata map[string]any

Metadata provides extensible key-value storage for custom attributes.

func (Metadata) Clone 

func (m Metadata) Clone() Metadata

Clone creates a deep copy of the metadata.

func (Metadata) Get 

func (m Metadata) Get(key string) any

Get retrieves a value from metadata, returning nil if not found.

func (Metadata) GetInt 

func (m Metadata) GetInt(key string) int

GetInt retrieves an int value from metadata.

func (Metadata) GetString 

func (m Metadata) GetString(key string) string

GetString retrieves a string value from metadata.

type Provenance 

type Provenance struct {
	Level ProvenanceLevel `json:"level"`
}

Provenance tracks how a piece of knowledge was obtained.

type ProvenanceLevel 

type ProvenanceLevel string

ProvenanceLevel indicates how knowledge was obtained (assertion strength). These are stable values, not LLM-generated scores. 

const (
	ProvenanceVerified  ProvenanceLevel = "verified"  // user/human stated or confirmed this fact
	ProvenanceInferred  ProvenanceLevel = "inferred"  // agent derived from analysis of source material
	ProvenanceUncertain ProvenanceLevel = "uncertain" // source or conclusion is questionable
)

type ResolutionStatus 

type ResolutionStatus string

ResolutionStatus indicates the state of conflict resolution. 

const (
	ResolutionUnresolved ResolutionStatus = "unresolved"
	ResolutionResolved   ResolutionStatus = "resolved"
	ResolutionSuperseded ResolutionStatus = "superseded"
)

type Scope 

type Scope struct {
	Path      string    `json:"path"`
	Meta      Metadata  `json:"meta,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

Scope represents a hierarchical namespace for organizing knowledge. Paths are dot-separated, e.g., "project.auth.oauth".

func NewScope 

func NewScope(path string) Scope

NewScope creates a new scope with the given path.

func (Scope) Child 

func (s Scope) Child(segment string) (Scope, error)

Child returns a new scope path with the given segment appended.

func (Scope) Depth 

func (s Scope) Depth() int

Depth returns the nesting level of the scope (1 for root-level).

func (Scope) IsAncestorOf 

func (s Scope) IsAncestorOf(other Scope) bool

IsAncestorOf returns true if this scope is an ancestor of the other.

func (Scope) IsDescendantOf 

func (s Scope) IsDescendantOf(other Scope) bool

IsDescendantOf returns true if this scope is a descendant of the other.

func (Scope) IsParentOf 

func (s Scope) IsParentOf(other Scope) bool

IsParentOf returns true if this scope is a direct parent of the other.

func (Scope) Parent 

func (s Scope) Parent() string

Parent returns the parent scope path, or empty string if at root level.

func (Scope) Segments 

func (s Scope) Segments() []string

Segments returns the path split into individual segments.

func (Scope) Validate 

func (s Scope) Validate() error

Validate checks that the scope path is properly formatted.

func (Scope) WithMeta 

func (s Scope) WithMeta(m Metadata) Scope

WithMeta returns a copy of the scope with the specified metadata.

type Session 

type Session struct {
	ID        ID         `json:"id"`
	StartedAt time.Time  `json:"started_at"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
	Scope     string     `json:"scope,omitempty"`
	Agent     string     `json:"agent,omitempty"`
}

Session represents an agent interaction session.

type SessionEvent 

type SessionEvent struct {
	ID        ID        `json:"id"`
	SessionID ID        `json:"session_id"`
	EventType EventType `json:"event_type"`
	EntryIDs  []ID      `json:"entry_ids,omitempty"`
	EdgeIDs   []ID      `json:"edge_ids,omitempty"`
	Query     string    `json:"query,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

SessionEvent records a single CLI action within a session.

type Source 

type Source struct {
	Type      SourceType `json:"type"`
	Reference string     `json:"reference"` // path, URL, or identifier
	Meta      Metadata   `json:"meta,omitempty"`
}

Source tracks the provenance of a piece of knowledge.

func (Source) Validate 

func (s Source) Validate() error

Validate checks that the source has required fields.

type SourceType 

type SourceType string

SourceType identifies the origin category of knowledge. 

const (
	SourceFile         SourceType = "file"
	SourceURL          SourceType = "url"
	SourceConversation SourceType = "conversation"
	SourceManual       SourceType = "manual"
)

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.