types

package
v1.0.0-alpha Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: MIT Imports: 4 Imported by: 0

README

Types Package

Core type definitions for the semantic event mesh, extracted to avoid import cycles.

Overview

This package contains foundational types that are shared across multiple packages. It was extracted from message/ to allow component/ to reference these types without creating an import cycle.

Types

Keyable

Interface for types that produce dotted notation keys for NATS subjects:

type Keyable interface {
    Key() string
}
Type

Message type identifier with three parts: domain, category, version.

msgType := types.Type{Domain: "agentic", Category: "task", Version: "v1"}
subject := "events." + msgType.Key() // "events.agentic.task.v1"
EntityType

Entity type identifier with two parts: domain, type.

entityType := types.EntityType{Domain: "robotics", Type: "drone"}
key := entityType.Key() // "robotics.drone"
EntityID

Six-part federated entity identifier following the hierarchy: org.platform.domain.system.type.instance.

entityID := types.EntityID{
    Org: "c360", Platform: "prod", Domain: "robotics",
    System: "gcs1", Type: "drone", Instance: "42",
}
key := entityID.Key() // "c360.prod.robotics.gcs1.drone.42"

// Parse from string
parsed, err := types.ParseEntityID("c360.prod.robotics.gcs1.drone.42")

Import Pattern

The message/ package re-exports these types as aliases for backwards compatibility:

// These are equivalent:
import "github.com/c360studio/semstreams/pkg/types"
var t types.Type

import "github.com/c360studio/semstreams/message"
var t message.Type  // Alias to types.Type

Why This Package Exists

The payload registry in component/ needs to validate that payload Schema() methods return the correct type. This requires access to the Type struct. However:

  • message/ imports component/ for CreatePayload() in UnmarshalJSON
  • component/ cannot import message/ (would create cycle)

Solution: Extract Type and related types to pkg/types/, which both packages can import.

pkg/types/   <── component/ imports for Schema validation
     ^
     |
message/     <── re-exports as aliases for backwards compatibility
     |
     v
component/   <── message/ imports for CreatePayload()

Documentation

Overview

Package types provides core type definitions for the semantic event mesh.

This package contains foundational types that are shared across multiple packages without creating import cycles. It includes:

  • Keyable interface: Foundation for dotted notation semantic keys
  • Type: Message type identifier (domain.category.version)
  • EntityType: Entity type identifier (domain.type)
  • EntityID: 6-part federated entity identifier

These types enable NATS wildcard queries and consistent storage patterns through their Key() methods which produce dotted notation strings.

Example Usage 

// Message type for routing
msgType := types.Type{Domain: "sensors", Category: "gps", Version: "v1"}
subject := "events." + msgType.Key() // "events.sensors.gps.v1"

// Entity identification
entityID := types.EntityID{
    Org: "c360", Platform: "prod", Domain: "robotics",
    System: "gcs1", Type: "drone", Instance: "42",
}
key := entityID.Key() // "c360.prod.robotics.gcs1.drone.42"

Index

Constants

View Source 
const (
	StatusSuccess = "success"
	StatusFailed  = "failed"
	StatusPending = "pending"
)

Status constants for agent results and workflow steps. Using constants prevents typos and enables IDE autocompletion.

View Source 
const (
	SourceTypeGraphEntity       = "graph_entity"
	SourceTypeGraphRelationship = "graph_relationship"
	SourceTypeDocument          = "document"
)

Source type constants for ContextSource.Type

Variables

This section is empty.

Functions

This section is empty.

Types

type ConstructedContext 

type ConstructedContext struct {
	Content       string          `json:"content"`                  // Formatted context for LLM
	TokenCount    int             `json:"token_count"`              // Exact token count
	Entities      []string        `json:"entities,omitempty"`       // Entity IDs included
	Sources       []ContextSource `json:"sources,omitempty"`        // Provenance tracking
	ConstructedAt time.Time       `json:"constructed_at,omitempty"` // When context was built
}

ConstructedContext is pre-built context ready to embed in task payload. When present in a TaskMessage, the agent loop uses this directly instead of performing discovery or hydration, enabling the "embed context, don't make agents discover it" pattern.

type ContextSource 

type ContextSource struct {
	Type string `json:"type"` // "graph_entity", "graph_relationship", "document"
	ID   string `json:"id"`   // Entity/doc ID
}

ContextSource tracks where context came from, providing provenance information for debugging and auditing.

type EntityID 

type EntityID struct {
	// Federation hierarchy (3 parts)
	Org      string // Organization namespace (e.g., "c360")
	Platform string // Platform/instance ID (e.g., "platform1")
	System   string // System/source ID - RUNTIME from message (e.g., "mav1", "gcs255")

	// Domain hierarchy (2 parts)
	Domain string // Data domain (e.g., "robotics")
	Type   string // Entity type (e.g., "drone", "battery")

	// Instance identifier (1 part)
	Instance string // Simple instance ID (e.g., "1", "42")
}

EntityID represents a complete entity identifier with semantic structure. Follows the pattern: org.platform.domain.system.type.instance for federated entity management.

Examples:

  • EntityID{Org: "c360", Platform: "platform1", Domain: "robotics", System: "gcs1", Type: "drone", Instance: "1"} -> "c360.platform1.robotics.gcs1.drone.1"
  • EntityID{Org: "c360", Platform: "platform1", Domain: "robotics", System: "mav1", Type: "battery", Instance: "0"} -> "c360.platform1.robotics.mav1.battery.0"

EntityID enables federated entity identification where multiple sources may have entities with the same local ID but different canonical identities.

func ParseEntityID 

func ParseEntityID(s string) (EntityID, error)

ParseEntityID creates EntityID from dotted string format. Expects exactly 6 parts: org.platform.domain.system.type.instance Returns an error if the format is invalid.

func (EntityID) DomainPrefix 

func (eid EntityID) DomainPrefix() string

DomainPrefix returns the 3-part prefix identifying the domain level. Format: org.platform.domain This groups all systems within the same domain.

Example: 

eid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
eid.DomainPrefix() // Returns "c360.logistics.environmental"

func (EntityID) EntityType 

func (eid EntityID) EntityType() EntityType

EntityType returns the EntityType component of this EntityID

func (EntityID) HasPrefix 

func (eid EntityID) HasPrefix(prefix string) bool

HasPrefix checks if this EntityID has the given prefix. Used for hierarchical grouping and sibling detection.

Example: 

eid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
eid.HasPrefix("c360.logistics.environmental.sensor.temperature") // true (same type)
eid.HasPrefix("c360.logistics.environmental.sensor")             // true (same system)
eid.HasPrefix("c360.logistics.environmental")                    // true (same domain)
eid.HasPrefix("c360.logistics.facility")                         // false (different domain)

func (EntityID) IsSameDomain 

func (eid EntityID) IsSameDomain(other EntityID) bool

IsSameDomain checks if another EntityID is in the same domain. Entities in the same domain may have different systems but share the domain-level prefix.

func (EntityID) IsSameSystem 

func (eid EntityID) IsSameSystem(other EntityID) bool

IsSameSystem checks if another EntityID is in the same system. Entities in the same system may have different types but share the system-level prefix.

func (EntityID) IsSibling 

func (eid EntityID) IsSibling(other EntityID) bool

IsSibling checks if another EntityID is a sibling (same type-level prefix). Siblings are entities of the same type within the same system.

Example: 

sensor1 := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                    System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
sensor2 := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                    System: "sensor", Type: "temperature", Instance: "cold-storage-02"}
sensor1.IsSibling(sensor2) // true - same type prefix

humid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                  System: "sensor", Type: "humidity", Instance: "zone-a"}
sensor1.IsSibling(humid) // false - different type

func (EntityID) IsValid 

func (eid EntityID) IsValid() bool

IsValid checks if the EntityID has all required fields populated

func (EntityID) Key 

func (eid EntityID) Key() string

Key returns the full 6-part dotted notation in domain-first format This implements the Keyable interface for unified semantic keys.

func (EntityID) PlatformPrefix 

func (eid EntityID) PlatformPrefix() string

PlatformPrefix returns the 2-part prefix identifying the platform level. Format: org.platform This groups all domains within the same platform.

Example: 

eid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
eid.PlatformPrefix() // Returns "c360.logistics"

func (EntityID) String 

func (eid EntityID) String() string

String returns the same as Key() for backwards compatibility

func (EntityID) SystemPrefix 

func (eid EntityID) SystemPrefix() string

SystemPrefix returns the 4-part prefix identifying the system level. Format: org.platform.domain.system This groups all entity types within the same system.

Example: 

eid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
eid.SystemPrefix() // Returns "c360.logistics.environmental.sensor"

func (EntityID) TypePrefix 

func (eid EntityID) TypePrefix() string

TypePrefix returns the 5-part prefix identifying the entity type level. Format: org.platform.domain.system.type This groups all instances of the same type (siblings).

Example: 

eid := EntityID{Org: "c360", Platform: "logistics", Domain: "environmental",
                System: "sensor", Type: "temperature", Instance: "cold-storage-01"}
eid.TypePrefix() // Returns "c360.logistics.environmental.sensor.temperature"

type EntityType 

type EntityType struct {
	// Domain identifies the business or system domain (lowercase)
	Domain string
	// Type identifies the specific entity type within the domain (lowercase)
	Type string
}

EntityType represents a structured entity type identifier using dotted notation.

Format: EntityType{Domain: "domain", Type: "type"} -> Key() returns "domain.type"

Examples:

  • EntityType{Domain: "robotics", Type: "drone"} -> "robotics.drone"
  • EntityType{Domain: "robotics", Type: "battery"} -> "robotics.battery"
  • EntityType{Domain: "sensors", Type: "gps"} -> "sensors.gps"

EntityType is used by Identifiable payloads to specify their entity type, enabling entity extraction and property graph construction with consistent dotted keys.

func (EntityType) IsValid 

func (et EntityType) IsValid() bool

IsValid checks if the EntityType has required fields populated

func (EntityType) Key 

func (et EntityType) Key() string

Key returns the dotted notation representation: "domain.type" This implements the Keyable interface for unified semantic keys.

func (EntityType) String 

func (et EntityType) String() string

String returns the same as Key() for backwards compatibility

type GraphContextSpec 

type GraphContextSpec struct {
	Entities      []string `json:"entities,omitempty"`      // Entity IDs to hydrate
	Relationships bool     `json:"relationships,omitempty"` // Include relationships
	Depth         int      `json:"depth,omitempty"`         // Traversal depth (default 1)
	MaxTokens     int      `json:"max_tokens,omitempty"`    // Token budget for graph context
}

GraphContextSpec defines what graph context to inject into an agent. This is used declaratively in workflow definitions to specify context needs.

type Keyable 

type Keyable interface {
	// Key returns the dotted notation representation of this semantic type.
	// Examples: "robotics.drone", "telemetry.robotics.drone.1", "robotics.battery.v1"
	Key() string
}

Keyable interface represents types that can be converted to semantic keys using dotted notation. This is the foundation of the unified semantic architecture enabling NATS wildcard queries and consistent storage patterns.

type Relationship 

type Relationship struct {
	Subject   string `json:"subject"`
	Predicate string `json:"predicate"`
	Object    string `json:"object"`
}

Relationship represents a relationship between entities in the knowledge graph. Used by context building and graph query operations.

type Type 

type Type struct {
	// Domain identifies the business or system domain.
	// Examples: "sensors", "robotics", "finance"
	Domain string `json:"domain"`

	// Category identifies the specific message type within the domain.
	// Examples: "gps", "temperature", "heartbeat", "trade"
	Category string `json:"category"`

	// Version identifies the schema version.
	// Format: "v1", "v2", etc. Enables schema evolution.
	Version string `json:"version"`
}

Type provides structured type information for messages. It enables type-safe routing and processing by clearly identifying the domain, category, and version of each message.

Type constants should be defined in domain packages to maintain clear ownership and avoid coupling. This package only provides the type definition itself.

Example definition in a domain package: 

var GPSMessage = types.Type{
    Domain:   "sensors",
    Category: "gps",
    Version:  "v1",
}

func (Type) Equal 

func (mt Type) Equal(other Type) bool

Equal compares two Type instances for equality. Returns true if all fields (Domain, Category, Version) are identical.

func (Type) IsValid 

func (mt Type) IsValid() bool

IsValid checks if the Type has all required fields populated with non-empty values.

func (Type) Key 

func (mt Type) Key() string

Key returns the dotted notation representation: "domain.category.version" This implements the Keyable interface for unified semantic keys.

func (Type) String 

func (mt Type) String() string

String returns the same as Key() for backwards compatibility

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.