models

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jul 7, 2025 License: MIT Imports: 2 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClusteringAlgorithm

type ClusteringAlgorithm string

ClusteringAlgorithm represents different clustering algorithms

const (
	// AlgorithmLouvain uses the Louvain method for community detection
	AlgorithmLouvain ClusteringAlgorithm = "louvain"

	// AlgorithmLeiden uses the Leiden algorithm for community detection
	AlgorithmLeiden ClusteringAlgorithm = "leiden"

	// AlgorithmKMeans uses K-means clustering
	AlgorithmKMeans ClusteringAlgorithm = "kmeans"

	// AlgorithmHierarchical uses hierarchical clustering
	AlgorithmHierarchical ClusteringAlgorithm = "hierarchical"

	// AlgorithmSpectral uses spectral clustering
	AlgorithmSpectral ClusteringAlgorithm = "spectral"

	// AlgorithmDBSCAN uses DBSCAN clustering
	AlgorithmDBSCAN ClusteringAlgorithm = "dbscan"
)

type Community

type Community struct {
	// ID is the unique identifier for the community
	ID string `json:"id" db:"id" validate:"required"`

	// TenantID identifies which tenant this community belongs to
	TenantID string `json:"tenant_id" db:"tenant_id" validate:"required"`

	// Name is a human-readable name for the community
	Name string `json:"name" db:"name" validate:"required,min=1,max=255"`

	// Description provides context about what this community represents
	Description string `json:"description" db:"description" validate:"max=1000"`

	// MemberEntityIDs contains the IDs of entities that belong to this community
	MemberEntityIDs []string `json:"member_entity_ids" db:"member_entity_ids"`

	// CentralEntityID is the most representative entity in the community (optional)
	CentralEntityID string `json:"central_entity_id,omitempty" db:"central_entity_id"`

	// Cohesion represents how tightly connected the entities in this community are (0.0 to 1.0)
	Cohesion float64 `json:"cohesion" db:"cohesion" validate:"min=0,max=1"`

	// Size is the number of entities in this community
	Size int `json:"size" db:"size" validate:"min=0"`

	// Level represents the hierarchical level of this community (for hierarchical clustering)
	Level int `json:"level" db:"level" validate:"min=0"`

	// ParentCommunityID points to the parent community in hierarchical clustering (optional)
	ParentCommunityID string `json:"parent_community_id,omitempty" db:"parent_community_id"`

	// ChildCommunityIDs contains IDs of child communities (for hierarchical clustering)
	ChildCommunityIDs []string `json:"child_community_ids,omitempty" db:"child_community_ids"`

	// Algorithm specifies which clustering algorithm was used to create this community
	Algorithm string `json:"algorithm" db:"algorithm" validate:"required"`

	// Parameters contains the parameters used by the clustering algorithm
	Parameters map[string]interface{} `json:"parameters,omitempty" db:"parameters"`

	// CreatedAt is when this community was created
	CreatedAt time.Time `json:"created_at" db:"created_at"`

	// UpdatedAt is when this community was last updated
	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`

	// Active indicates whether this community is currently active
	Active bool `json:"active" db:"active"`

	// Metadata contains additional information about the community
	Metadata map[string]interface{} `json:"metadata,omitempty" db:"metadata"`
}

Community represents a cluster of conceptually related entities in the knowledge graph Communities are discovered through graph clustering algorithms and help organize the knowledge space into coherent semantic groups

func (*Community) AddChild

func (c *Community) AddChild(communityID string)

AddChild adds a child community

func (*Community) AddMember

func (c *Community) AddMember(entityID string)

AddMember adds an entity to the community

func (*Community) GetMemberCount

func (c *Community) GetMemberCount() int

GetMemberCount returns the number of member entities

func (*Community) GetParameter

func (c *Community) GetParameter(key string) (interface{}, bool)

GetParameter gets a clustering parameter value

func (*Community) HasChild

func (c *Community) HasChild(communityID string) bool

HasChild checks if a community is a child of this community

func (*Community) HasMember

func (c *Community) HasMember(entityID string) bool

HasMember checks if an entity is a member of this community

func (*Community) IsActive

func (c *Community) IsActive() bool

IsActive returns true if the community is active

func (*Community) IsLeaf

func (c *Community) IsLeaf() bool

IsLeaf returns true if this community has no children

func (*Community) IsRoot

func (c *Community) IsRoot() bool

IsRoot returns true if this community has no parent

func (*Community) RemoveChild

func (c *Community) RemoveChild(communityID string)

RemoveChild removes a child community

func (*Community) RemoveMember

func (c *Community) RemoveMember(entityID string)

RemoveMember removes an entity from the community

func (*Community) SetDefaults

func (c *Community) SetDefaults()

SetDefaults sets default values for the community

func (*Community) SetParameter

func (c *Community) SetParameter(key string, value interface{})

SetParameter sets a clustering parameter value

func (*Community) Validate

func (c *Community) Validate() error

Validate validates the community model

type CommunityCreateRequest

type CommunityCreateRequest struct {
	// Name is a human-readable name for the community
	Name string `json:"name" validate:"required,min=1,max=255"`

	// Description provides context about what this community represents
	Description string `json:"description,omitempty" validate:"max=1000"`

	// MemberEntityIDs contains the IDs of entities that belong to this community
	MemberEntityIDs []string `json:"member_entity_ids" validate:"required,min=1"`

	// CentralEntityID is the most representative entity in the community (optional)
	CentralEntityID string `json:"central_entity_id,omitempty"`

	// Algorithm specifies which clustering algorithm was used
	Algorithm string `json:"algorithm" validate:"required"`

	// Parameters contains the parameters used by the clustering algorithm
	Parameters map[string]interface{} `json:"parameters,omitempty"`

	// Level represents the hierarchical level (optional)
	Level int `json:"level,omitempty" validate:"min=0"`

	// ParentCommunityID points to the parent community (optional)
	ParentCommunityID string `json:"parent_community_id,omitempty"`

	// Metadata contains additional information
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

CommunityCreateRequest represents the request payload for creating a new community

type CommunitySearchRequest

type CommunitySearchRequest struct {
	// Query is the search query text
	Query string `json:"query" validate:"required,min=1"`

	// Algorithm filters communities by clustering algorithm
	Algorithm string `json:"algorithm,omitempty"`

	// MinSize filters communities by minimum size
	MinSize int `json:"min_size,omitempty" validate:"omitempty,min=0"`

	// MaxSize filters communities by maximum size
	MaxSize int `json:"max_size,omitempty" validate:"omitempty,min=0"`

	// MinCohesion filters communities by minimum cohesion
	MinCohesion float64 `json:"min_cohesion,omitempty" validate:"omitempty,min=0,max=1"`

	// Level filters communities by hierarchical level
	Level *int `json:"level,omitempty" validate:"omitempty,min=0"`

	// IncludeInactive indicates whether to include inactive communities
	IncludeInactive bool `json:"include_inactive,omitempty"`

	// Limit is the maximum number of results to return
	Limit int `json:"limit,omitempty" validate:"omitempty,min=1,max=100"`

	// Offset is the number of results to skip
	Offset int `json:"offset,omitempty" validate:"omitempty,min=0"`
}

CommunitySearchRequest represents the request payload for searching communities

type CommunitySearchResponse

type CommunitySearchResponse struct {
	// Communities is the list of matching communities
	Communities []CommunitySearchResult `json:"communities"`

	// Total is the total number of matching communities
	Total int `json:"total"`

	// Limit is the limit that was applied
	Limit int `json:"limit"`

	// Offset is the offset that was applied
	Offset int `json:"offset"`

	// SearchTime is how long the search took
	SearchTime time.Duration `json:"search_time"`
}

CommunitySearchResponse represents the response from community search

type CommunitySearchResult

type CommunitySearchResult struct {
	// Community is the matching community
	Community Community `json:"community"`

	// Score is the relevance score for this result
	Score float64 `json:"score"`

	// MatchType indicates how this community matched the query
	MatchType MatchType `json:"match_type"`

	// MemberEntities contains the actual entity objects (if requested)
	MemberEntities []Entity `json:"member_entities,omitempty"`
}

CommunitySearchResult represents a single community search result

type CommunityUpdateRequest

type CommunityUpdateRequest struct {
	// Name is the updated name
	Name *string `json:"name,omitempty" validate:"omitempty,min=1,max=255"`

	// Description is the updated description
	Description *string `json:"description,omitempty" validate:"omitempty,max=1000"`

	// MemberEntityIDs contains updated member entity IDs
	MemberEntityIDs []string `json:"member_entity_ids,omitempty"`

	// CentralEntityID is the updated central entity
	CentralEntityID *string `json:"central_entity_id,omitempty"`

	// Active is the updated active status
	Active *bool `json:"active,omitempty"`

	// Metadata contains updated metadata
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

CommunityUpdateRequest represents the request payload for updating a community

type Entity

type Entity struct {
	// ID is the unique identifier for the entity
	ID string `json:"id" db:"id" validate:"required"`

	// TenantID identifies which tenant this entity belongs to
	TenantID string `json:"tenant_id" db:"tenant_id" validate:"required"`

	// Name is the canonical name of the entity
	Name string `json:"name" db:"name" validate:"required,min=1,max=255"`

	// Type categorizes the entity (e.g., "person", "organization", "location", "concept")
	Type string `json:"type" db:"type" validate:"required,min=1,max=100"`

	// Description provides additional context about the entity
	Description string `json:"description" db:"description" validate:"max=1000"`

	// Properties contains structured metadata about the entity
	Properties map[string]interface{} `json:"properties,omitempty" db:"properties"`

	// Confidence represents the confidence level of entity extraction (0.0 to 1.0)
	Confidence float64 `json:"confidence" db:"confidence" validate:"min=0,max=1"`

	// CreatedAt is when this entity was first created
	CreatedAt time.Time `json:"created_at" db:"created_at"`

	// UpdatedAt is when this entity was last updated
	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`

	// Active indicates whether this entity is currently active
	Active bool `json:"active" db:"active"`

	// Aliases contains alternative names for this entity
	Aliases []string `json:"aliases,omitempty" db:"aliases"`

	// SourceEpisodes tracks which episodes this entity was extracted from
	SourceEpisodes []string `json:"source_episodes,omitempty" db:"source_episodes"`
}

Entity represents a semantic entity extracted from text Entities are the building blocks of the knowledge graph

func (*Entity) AddAlias

func (e *Entity) AddAlias(alias string)

AddAlias adds an alias to the entity

func (*Entity) AddSourceEpisode

func (e *Entity) AddSourceEpisode(episodeID string)

AddSourceEpisode adds a source episode to the entity

func (*Entity) GetProperty

func (e *Entity) GetProperty(key string) (interface{}, bool)

GetProperty gets a property value

func (*Entity) HasProperty

func (e *Entity) HasProperty(key string) bool

HasProperty checks if the entity has a specific property

func (*Entity) IsActive

func (e *Entity) IsActive() bool

IsActive returns true if the entity is active

func (*Entity) SetDefaults

func (e *Entity) SetDefaults()

SetDefaults sets default values for the entity

func (*Entity) SetProperty

func (e *Entity) SetProperty(key string, value interface{})

SetProperty sets a property value

func (*Entity) Validate

func (e *Entity) Validate() error

Validate validates the entity model

type EntityCreateRequest

type EntityCreateRequest struct {
	// Name is the canonical name of the entity
	Name string `json:"name" validate:"required,min=1,max=255"`

	// Type categorizes the entity
	Type string `json:"type" validate:"required,min=1,max=100"`

	// Description provides additional context about the entity
	Description string `json:"description,omitempty" validate:"max=1000"`

	// Properties contains structured metadata about the entity
	Properties map[string]interface{} `json:"properties,omitempty"`

	// Confidence represents the confidence level of entity extraction
	Confidence float64 `json:"confidence,omitempty" validate:"min=0,max=1"`

	// Aliases contains alternative names for this entity
	Aliases []string `json:"aliases,omitempty"`

	// SourceEpisodeID is the episode this entity was extracted from
	SourceEpisodeID string `json:"source_episode_id,omitempty"`
}

EntityCreateRequest represents the request payload for creating a new entity

type EntitySearchRequest

type EntitySearchRequest struct {
	// Query is the search query text
	Query string `json:"query" validate:"required,min=1"`

	// Type filters entities by type
	Type string `json:"type,omitempty"`

	// Limit is the maximum number of results to return
	Limit int `json:"limit,omitempty" validate:"omitempty,min=1,max=100"`

	// Offset is the number of results to skip
	Offset int `json:"offset,omitempty" validate:"omitempty,min=0"`

	// IncludeInactive indicates whether to include inactive entities
	IncludeInactive bool `json:"include_inactive,omitempty"`

	// MinConfidence filters entities by minimum confidence level
	MinConfidence float64 `json:"min_confidence,omitempty" validate:"omitempty,min=0,max=1"`

	// SearchType specifies the type of search to perform
	SearchType SearchType `json:"search_type,omitempty"`
}

EntitySearchRequest represents the request payload for searching entities

type EntitySearchResponse

type EntitySearchResponse struct {
	// Entities is the list of matching entities
	Entities []EntitySearchResult `json:"entities"`

	// Total is the total number of matching entities
	Total int `json:"total"`

	// Limit is the limit that was applied
	Limit int `json:"limit"`

	// Offset is the offset that was applied
	Offset int `json:"offset"`

	// SearchTime is how long the search took
	SearchTime time.Duration `json:"search_time"`
}

EntitySearchResponse represents the response from entity search

type EntitySearchResult

type EntitySearchResult struct {
	// Entity is the matching entity
	Entity Entity `json:"entity"`

	// Score is the relevance score for this result
	Score float64 `json:"score"`

	// Highlights contains highlighted text snippets
	Highlights []string `json:"highlights,omitempty"`

	// MatchType indicates how this entity matched the query
	MatchType MatchType `json:"match_type"`

	// RelatedEntities contains entities related to this one
	RelatedEntities []RelatedEntity `json:"related_entities,omitempty"`
}

EntitySearchResult represents a single entity search result

type EntityType

type EntityType string

EntityType represents common entity types

const (
	EntityTypePerson       EntityType = "person"
	EntityTypeOrganization EntityType = "organization"
	EntityTypeLocation     EntityType = "location"
	EntityTypeConcept      EntityType = "concept"
	EntityTypeEvent        EntityType = "event"
	EntityTypeProduct      EntityType = "product"
	EntityTypeDate         EntityType = "date"
	EntityTypeNumber       EntityType = "number"
	EntityTypeMoney        EntityType = "money"
	EntityTypeOther        EntityType = "other"
)

type EntityUpdateRequest

type EntityUpdateRequest struct {
	// Name is the updated canonical name of the entity
	Name *string `json:"name,omitempty" validate:"omitempty,min=1,max=255"`

	// Type is the updated entity type
	Type *string `json:"type,omitempty" validate:"omitempty,min=1,max=100"`

	// Description is the updated description
	Description *string `json:"description,omitempty" validate:"omitempty,max=1000"`

	// Properties contains updated metadata
	Properties map[string]interface{} `json:"properties,omitempty"`

	// Confidence is the updated confidence level
	Confidence *float64 `json:"confidence,omitempty" validate:"omitempty,min=0,max=1"`

	// Active is the updated active status
	Active *bool `json:"active,omitempty"`

	// Aliases contains updated alternative names
	Aliases []string `json:"aliases,omitempty"`
}

EntityUpdateRequest represents the request payload for updating an entity

type Episode

type Episode struct {
	// ID is the unique identifier for the episode
	ID string `json:"id" db:"id" validate:"required"`

	// TenantID identifies which tenant this episode belongs to
	TenantID string `json:"tenant_id" db:"tenant_id" validate:"required"`

	// SessionID identifies which conversation session this episode belongs to
	SessionID string `json:"session_id" db:"session_id" validate:"required"`

	// Text is the original text content of the episode
	Text string `json:"text" db:"text" validate:"required,min=1,max=10000"`

	// Embedding is the vector representation of the text for similarity search
	Embedding []float32 `json:"embedding,omitempty" db:"embedding"`

	// EventTime is when the event actually occurred (user's perspective)
	EventTime time.Time `json:"event_time" db:"event_time" validate:"required"`

	// TxTime is when the information was recorded in the system (system's perspective)
	TxTime time.Time `json:"tx_time" db:"tx_time"`

	// CreatedAt is when this record was created in the database
	CreatedAt time.Time `json:"created_at" db:"created_at"`

	// Metadata contains additional structured information about the episode
	Metadata map[string]interface{} `json:"metadata,omitempty" db:"metadata"`

	// Processed indicates whether this episode has been processed for entity extraction
	Processed bool `json:"processed" db:"processed"`
}

Episode represents a single conversation episode or text input that serves as the atomic unit of knowledge in the system. Episodes are stored with their original text, embeddings, and temporal information.

func (*Episode) GetAge

func (e *Episode) GetAge() time.Duration

GetAge returns the age of the episode based on event time

func (*Episode) GetEmbeddingDimension

func (e *Episode) GetEmbeddingDimension() int

GetEmbeddingDimension returns the dimension of the embedding

func (*Episode) GetProcessingAge

func (e *Episode) GetProcessingAge() time.Duration

GetProcessingAge returns the age of the episode based on transaction time

func (*Episode) HasEmbedding

func (e *Episode) HasEmbedding() bool

HasEmbedding returns true if the episode has an embedding

func (*Episode) IsProcessed

func (e *Episode) IsProcessed() bool

IsProcessed returns true if the episode has been processed for entity extraction

func (*Episode) SetDefaults

func (e *Episode) SetDefaults()

SetDefaults sets default values for the episode

func (*Episode) Validate

func (e *Episode) Validate() error

Validate validates the episode model

type EpisodeCreateRequest

type EpisodeCreateRequest struct {
	// SessionID identifies which conversation session this episode belongs to
	SessionID string `json:"session_id" validate:"required"`

	// Text is the original text content of the episode
	Text string `json:"text" validate:"required,min=1,max=10000"`

	// EventTime is when the event actually occurred (optional, defaults to now)
	EventTime *time.Time `json:"event_time,omitempty"`

	// Metadata contains additional structured information about the episode
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

EpisodeCreateRequest represents the request payload for creating a new episode

type EpisodeSearchRequest

type EpisodeSearchRequest struct {
	// Query is the search query text
	Query string `json:"query" validate:"required,min=1"`

	// SessionID filters results to a specific session (optional)
	SessionID string `json:"session_id,omitempty"`

	// Limit is the maximum number of results to return
	Limit int `json:"limit,omitempty" validate:"omitempty,min=1,max=100"`

	// Offset is the number of results to skip
	Offset int `json:"offset,omitempty" validate:"omitempty,min=0"`

	// IncludeEmbeddings indicates whether to include embeddings in the response
	IncludeEmbeddings bool `json:"include_embeddings,omitempty"`

	// TimeRange filters episodes by event time
	TimeRange *TimeRange `json:"time_range,omitempty"`

	// SearchType specifies the type of search to perform
	SearchType SearchType `json:"search_type,omitempty"`
}

EpisodeSearchRequest represents the request payload for searching episodes

type EpisodeSearchResponse

type EpisodeSearchResponse struct {
	// Episodes is the list of matching episodes
	Episodes []EpisodeSearchResult `json:"episodes"`

	// Total is the total number of matching episodes
	Total int `json:"total"`

	// Limit is the limit that was applied
	Limit int `json:"limit"`

	// Offset is the offset that was applied
	Offset int `json:"offset"`

	// SearchTime is how long the search took
	SearchTime time.Duration `json:"search_time"`
}

EpisodeSearchResponse represents the response from episode search

type EpisodeSearchResult

type EpisodeSearchResult struct {
	// Episode is the matching episode
	Episode Episode `json:"episode"`

	// Score is the relevance score for this result
	Score float64 `json:"score"`

	// Highlights contains highlighted text snippets
	Highlights []string `json:"highlights,omitempty"`

	// MatchType indicates how this episode matched the query
	MatchType MatchType `json:"match_type"`
}

EpisodeSearchResult represents a single search result

type EpisodeUpdateRequest

type EpisodeUpdateRequest struct {
	// Text is the updated text content of the episode
	Text *string `json:"text,omitempty" validate:"omitempty,min=1,max=10000"`

	// EventTime is the updated event time
	EventTime *time.Time `json:"event_time,omitempty"`

	// Metadata contains updated metadata
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Processed indicates whether this episode has been processed
	Processed *bool `json:"processed,omitempty"`
}

EpisodeUpdateRequest represents the request payload for updating an episode

type MatchType

type MatchType string

MatchType represents how an episode matched the search query

const (
	// MatchTypeVector indicates the episode matched via vector similarity
	MatchTypeVector MatchType = "vector"

	// MatchTypeFullText indicates the episode matched via full-text search
	MatchTypeFullText MatchType = "fulltext"

	// MatchTypeGraph indicates the episode matched via graph traversal
	MatchTypeGraph MatchType = "graph"

	// MatchTypeHybrid indicates the episode matched via multiple methods
	MatchTypeHybrid MatchType = "hybrid"
)

type RelatedEntity

type RelatedEntity struct {
	// Entity is the related entity
	Entity Entity `json:"entity"`

	// RelationType describes the type of relationship
	RelationType string `json:"relation_type"`

	// Confidence is the confidence of the relationship
	Confidence float64 `json:"confidence"`
}

RelatedEntity represents an entity related to another entity

type RelationType

type RelationType string

RelationType represents common relationship types

const (
	RelationTypeWorksFor   RelationType = "works_for"
	RelationTypeLocatedIn  RelationType = "located_in"
	RelationTypePartOf     RelationType = "part_of"
	RelationTypeRelatedTo  RelationType = "related_to"
	RelationTypeCreatedBy  RelationType = "created_by"
	RelationTypeOwnedBy    RelationType = "owned_by"
	RelationTypeMemberOf   RelationType = "member_of"
	RelationTypeSupersedes RelationType = "supersedes"
	RelationTypeDependsOn  RelationType = "depends_on"
	RelationTypeSimilarTo  RelationType = "similar_to"
)

type Relationship

type Relationship struct {
	// ID is the unique identifier for the relationship
	ID string `json:"id" db:"id" validate:"required"`

	// TenantID identifies which tenant this relationship belongs to
	TenantID string `json:"tenant_id" db:"tenant_id" validate:"required"`

	// FromEntityID is the source entity of the relationship
	FromEntityID string `json:"from_entity_id" db:"from_entity" validate:"required"`

	// ToEntityID is the target entity of the relationship
	ToEntityID string `json:"to_entity_id" db:"to_entity" validate:"required"`

	// RelationType describes the type of relationship
	RelationType string `json:"relation_type" db:"relation_type" validate:"required,min=1,max=100"`

	// Properties contains additional metadata about the relationship
	Properties map[string]interface{} `json:"properties,omitempty" db:"properties"`

	// Confidence represents the confidence level of this relationship
	Confidence float64 `json:"confidence" db:"confidence" validate:"min=0,max=1"`

	// CreatedAt is when this relationship was created
	CreatedAt time.Time `json:"created_at" db:"created_at"`

	// SupersededAt is when this relationship was superseded (if applicable)
	SupersededAt *time.Time `json:"superseded_at,omitempty" db:"superseded_at"`

	// Active indicates whether this relationship is currently active
	Active bool `json:"active" db:"active"`
}

Relationship represents a relationship between two entities

type SearchType

type SearchType string

SearchType represents the type of search to perform

const (
	// SearchTypeHybrid combines vector, full-text, and graph search
	SearchTypeHybrid SearchType = "hybrid"

	// SearchTypeVector performs vector similarity search only
	SearchTypeVector SearchType = "vector"

	// SearchTypeFullText performs full-text search only
	SearchTypeFullText SearchType = "fulltext"

	// SearchTypeGraph performs graph traversal search only
	SearchTypeGraph SearchType = "graph"
)

type TimeRange

type TimeRange struct {
	// Start is the start time (inclusive)
	Start time.Time `json:"start"`

	// End is the end time (inclusive)
	End time.Time `json:"end"`
}

TimeRange represents a time range filter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL