inference

type AnomalyStatus string

type AnomalyType string

type AutoApplyConfig struct {
	// Enabled activates automatic edge creation
	Enabled bool `json:"enabled"`

	// MinConfidence is the minimum confidence score to auto-apply (0.0-1.0)
	// Confidence is a composite score: similarity + distance boost + core boost
	// Gaps at or above this threshold are automatically converted to edges
	MinConfidence float64 `json:"min_confidence"`

	// PredicateTemplate is the predicate format for created edges
	// Supports {band} placeholder: "inferred.semantic.{band}"
	// Band values: "high" (>=0.95), "medium" (>=0.85), "related" (else)
	PredicateTemplate string `json:"predicate_template"`
}

type CommunityInfo struct {
	// ID is the community identifier
	ID string
	// Members is the list of entity IDs in this community
	Members []string
	// Level is the hierarchy level (0 = base communities)
	Level int
}

type Config struct {
	// Enabled activates inference detection
	Enabled bool `json:"enabled"`

	// RunWithCommunityDetection triggers inference after community detection completes
	RunWithCommunityDetection bool `json:"run_with_community_detection"`

	// MaxAnomaliesPerRun limits total anomalies detected per run to prevent runaway detection
	MaxAnomaliesPerRun int `json:"max_anomalies_per_run"`

	// Detector-specific configurations
	SemanticGap  SemanticGapConfig  `json:"semantic_gap"`
	CoreAnomaly  CoreAnomalyConfig  `json:"core_anomaly"`
	Transitivity TransitivityConfig `json:"transitivity"`

	// Review configuration for LLM-assisted and human review
	Review ReviewConfig `json:"review"`

	// VirtualEdges configuration for auto-applying high-confidence gaps as edges
	VirtualEdges VirtualEdgeConfig `json:"virtual_edges"`

	// Storage configuration
	Storage StorageConfig `json:"storage"`

	// Operation timeouts
	DetectionTimeout time.Duration `json:"detection_timeout"`
}

type CoreAnomalyConfig struct {
	// Enabled activates core-based anomaly detection (isolation + demotion)
	Enabled bool `json:"enabled"`

	// MinCoreForHubAnalysis sets minimum k-core level for hub isolation analysis
	MinCoreForHubAnalysis int `json:"min_core_for_hub_analysis"`

	// HubIsolationThreshold is the peer connectivity ratio below which hub is "isolated"
	// Value between 0.0-1.0: ratio of actual same-core connections to expected
	HubIsolationThreshold float64 `json:"hub_isolation_threshold"`

	// TrackCoreDemotions enables detection of entities that dropped k-core level
	TrackCoreDemotions bool `json:"track_core_demotions"`

	// MinDemotionDelta is the minimum core level drop to flag (e.g., 2 means core 5->3 flagged)
	MinDemotionDelta int `json:"min_demotion_delta"`
}

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

type Decision int

type Detector interface {
	// Name returns the detector identifier for logging and metrics.
	Name() string

	// Detect runs the detection algorithm and returns discovered anomalies.
	// The context should be used for cancellation and timeouts.
	Detect(ctx context.Context) ([]*StructuralAnomaly, error)

	// Configure updates the detector configuration.
	// Called during orchestrator initialization and on config updates.
	Configure(config interface{}) error

	// SetDependencies updates the detector's shared dependencies.
	// Called by the orchestrator before running detection.
	SetDependencies(deps *DetectorDependencies)
}

type DetectorDependencies struct {
	// StructuralIndices provides access to k-core and pivot indices.
	StructuralIndices *structural.Indices

	// PreviousKCore is the k-core index from the previous computation (for demotion detection).
	PreviousKCore *structural.KCoreIndex

	// Communities provides community membership for scoped detection.
	// Core isolation is analyzed within each community rather than globally.
	Communities []CommunityInfo

	// SimilarityFinder provides semantic similarity queries.
	SimilarityFinder SimilarityFinder

	// RelationshipQuerier provides relationship queries for transitivity detection.
	RelationshipQuerier RelationshipQuerier

	// AnomalyStorage provides access to persisted anomalies (for dismissed pair checks).
	AnomalyStorage Storage

	// Logger for detector logging.
	Logger *slog.Logger
}

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

type EntityManager interface {
	ExistsEntity(ctx context.Context, id string) (bool, error)
	CreateEntity(ctx context.Context, entity *gtypes.EntityState) (*gtypes.EntityState, error)
	// ListWithPrefix returns entity IDs matching a prefix (for sibling discovery)
	ListWithPrefix(ctx context.Context, prefix string) ([]string, error)
}

type Evidence struct {
	// Semantic-Structural Gap evidence
	Similarity         float64 `json:"similarity,omitempty"`           // Embedding similarity score
	StructuralDistance int     `json:"structural_distance,omitempty"`  // Actual or estimated hop count
	DistanceLowerBound int     `json:"distance_lower_bound,omitempty"` // Triangle inequality lower bound
	DistanceUpperBound int     `json:"distance_upper_bound,omitempty"` // Triangle inequality upper bound

	// Core Isolation evidence
	CoreLevel         int     `json:"core_level,omitempty"`          // Entity's k-core number
	PeerCount         int     `json:"peer_count,omitempty"`          // Number of same-core neighbors
	ExpectedPeerCount int     `json:"expected_peer_count,omitempty"` // Expected based on core level
	PeerConnectivity  float64 `json:"peer_connectivity,omitempty"`   // Ratio of actual/expected peers
	CommunityID       string  `json:"community_id,omitempty"`        // Community where isolation detected

	// Core Demotion evidence
	PreviousCoreLevel int `json:"previous_core_level,omitempty"` // Core level before demotion
	CurrentCoreLevel  int `json:"current_core_level,omitempty"`  // Core level after demotion
	LostConnections   int `json:"lost_connections,omitempty"`    // Number of connections lost

	// Transitivity Gap evidence
	Predicate       string   `json:"predicate,omitempty"`         // The transitive predicate
	ChainPath       []string `json:"chain_path,omitempty"`        // The A->B->C path entities
	ActualDistance  int      `json:"actual_distance,omitempty"`   // Measured A-C distance
	ExpectedMaxHops int      `json:"expected_max_hops,omitempty"` // Config max for transitivity
}

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

type HierarchyConfig struct {
	// Enabled activates hierarchy inference on entity creation
	Enabled bool `json:"enabled"`

	// CreateTypeEdges enables type membership edges (5-part prefix → type container)
	// StandardIRI: skos:broader
	CreateTypeEdges bool `json:"create_type_edges"`

	// CreateSystemEdges enables system membership edges (4-part prefix → system container)
	// StandardIRI: skos:broader
	CreateSystemEdges bool `json:"create_system_edges"`

	// CreateDomainEdges enables domain membership edges (3-part prefix → domain container)
	// StandardIRI: skos:broader
	CreateDomainEdges bool `json:"create_domain_edges"`

	// CreateTypeSiblings enables sibling edges between entities with the same type (5-part prefix)
	// When enabled, creates bidirectional hierarchy.type.sibling edges
	// Cost: O(N) per new entity where N is existing sibling count
	CreateTypeSiblings bool `json:"create_type_siblings"`
}

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

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

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

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

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

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

type OrchestratorConfig struct {
	Config  Config
	Storage Storage
	Applier RelationshipApplier
	Logger  *slog.Logger
}

type RelationshipApplier interface {
	// ApplyRelationship publishes a new relationship triple to the entity stream.
	ApplyRelationship(ctx context.Context, suggestion *RelationshipSuggestion) error
}

type RelationshipInfo struct {
	FromEntityID string `json:"from_entity_id"`
	ToEntityID   string `json:"to_entity_id"`
	Predicate    string `json:"predicate"`
}

type RelationshipQuerier interface {
	// GetOutgoingRelationships returns all outgoing relationships from an entity.
	GetOutgoingRelationships(ctx context.Context, entityID string) ([]RelationshipInfo, error)

	// GetIncomingRelationships returns all incoming relationships to an entity.
	GetIncomingRelationships(ctx context.Context, entityID string) ([]RelationshipInfo, error)
}

type RelationshipSuggestion struct {
	// FromEntity is the source entity ID for the suggested relationship.
	FromEntity string `json:"from_entity"`

	// ToEntity is the target entity ID for the suggested relationship.
	ToEntity string `json:"to_entity"`

	// Predicate is the suggested relationship type (e.g., "inferred.related_to").
	Predicate string `json:"predicate"`

	// Confidence is the confidence in this specific suggestion.
	Confidence float64 `json:"confidence"`

	// Reasoning explains why this relationship is suggested.
	Reasoning string `json:"reasoning"`
}

type Result struct {
	StartedAt       time.Time            `json:"started_at"`
	CompletedAt     time.Time            `json:"completed_at"`
	Anomalies       []*StructuralAnomaly `json:"anomalies"`
	Truncated       bool                 `json:"truncated"`         // Hit max anomalies limit
	AutoApplied     int                  `json:"auto_applied"`      // Virtual edges auto-applied
	QueuedForReview int                  `json:"queued_for_review"` // Anomalies sent to review queue
}

type ReviewConfig struct {
	// Enabled activates the review worker
	Enabled bool `json:"enabled"`

	// Workers is the number of concurrent review workers
	Workers int `json:"workers"`

	// AutoApproveThreshold: LLM can auto-approve anomalies at or above this confidence
	AutoApproveThreshold float64 `json:"auto_approve_threshold"`

	// AutoRejectThreshold: LLM can auto-reject anomalies at or below this confidence
	AutoRejectThreshold float64 `json:"auto_reject_threshold"`

	// FallbackToHuman escalates uncertain cases (between thresholds) to human review
	FallbackToHuman bool `json:"fallback_to_human"`

	// BatchSize is the number of anomalies to process in each review batch
	BatchSize int `json:"batch_size"`

	// ReviewTimeout is the timeout for individual LLM review calls
	ReviewTimeout time.Duration `json:"review_timeout"`

	// LLM configuration for the review model
	LLM llm.Config `json:"llm"`
}

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

type ReviewQueueConfig struct {
	// Enabled activates the review queue for lower-confidence gaps
	Enabled bool `json:"enabled"`

	// MinConfidence is the minimum confidence score for review queue (0.0-1.0)
	// Gaps at or above this but below AutoApply.MinConfidence go to review
	MinConfidence float64 `json:"min_confidence"`

	// MaxConfidence is the maximum confidence score for review queue (0.0-1.0)
	// Should match AutoApply.MinConfidence for seamless handoff
	MaxConfidence float64 `json:"max_confidence"`

	// RequireLLMClassification requires LLM to suggest relationship type
	RequireLLMClassification bool `json:"require_llm_classification"`
}

type ReviewRequest struct {
	Decision          string `json:"decision"`                     // "approved" or "rejected"
	Notes             string `json:"notes,omitempty"`              // Optional notes about the decision
	OverridePredicate string `json:"override_predicate,omitempty"` // Override the suggested predicate
	TargetEntity      string `json:"target_entity,omitempty"`      // Target entity for approval (required if suggestion has empty ToEntity)
	ReviewedBy        string `json:"reviewed_by,omitempty"`        // Who reviewed this anomaly
}

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

type ReviewWorkerConfig struct {
	AnomalyBucket jetstream.KeyValue
	Storage       Storage
	LLMClient     llm.Client // optional
	Applier       RelationshipApplier
	Config        ReviewConfig
	Metrics       *ReviewMetrics // optional - nil disables metrics
	Logger        *slog.Logger
}

type SemanticGapConfig struct {
	// Enabled activates semantic-structural gap detection
	Enabled bool `json:"enabled"`

	// MinSemanticSimilarity is the minimum embedding similarity to consider (0.0-1.0)
	MinSemanticSimilarity float64 `json:"min_semantic_similarity"`

	// MinStructuralDistance is the minimum graph distance for flagging (hops)
	MinStructuralDistance int `json:"min_structural_distance"`

	// MaxGapsPerEntity limits gaps detected per entity to prevent noise
	MaxGapsPerEntity int `json:"max_gaps_per_entity"`

	// MaxCandidatesPerEntity limits semantic search candidates per entity
	MaxCandidatesPerEntity int `json:"max_candidates_per_entity"`
}

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

type SimilarityFinder interface {
	// FindSimilar returns entity IDs semantically similar to the given entity.
	// threshold is the minimum similarity score (0.0-1.0).
	// limit is the maximum number of results.
	FindSimilar(ctx context.Context, entityID string, threshold float64, limit int) ([]SimilarityResult, error)
}

type SimilarityResult struct {
	EntityID   string  `json:"entity_id"`
	Similarity float64 `json:"similarity"`
}

type StatsResponse struct {
	TotalDetected int `json:"total_detected"`
	PendingReview int `json:"pending_review"`
	LLMApproved   int `json:"llm_approved"`
	LLMRejected   int `json:"llm_rejected"`
	HumanReview   int `json:"human_review"`
	HumanApproved int `json:"human_approved"`
	HumanRejected int `json:"human_rejected"`
	Applied       int `json:"applied"`
}

type Storage interface {
	// Save persists an anomaly (creates or updates).
	Save(ctx context.Context, anomaly *StructuralAnomaly) error

	// SaveWithRevision persists an anomaly with optimistic locking.
	// Returns ErrConcurrentModification if the revision has changed.
	// Pass revision=0 for new anomalies.
	SaveWithRevision(ctx context.Context, anomaly *StructuralAnomaly, revision uint64) error

	// GetWithRevision retrieves an anomaly by ID along with its KV revision.
	// The revision can be used with SaveWithRevision for optimistic locking.
	GetWithRevision(ctx context.Context, id string) (*StructuralAnomaly, uint64, error)

	// Get retrieves an anomaly by ID.
	Get(ctx context.Context, id string) (*StructuralAnomaly, error)

	// GetByStatus retrieves all anomalies with the given status.
	GetByStatus(ctx context.Context, status AnomalyStatus) ([]*StructuralAnomaly, error)

	// GetByType retrieves all anomalies of the given type.
	GetByType(ctx context.Context, anomalyType AnomalyType) ([]*StructuralAnomaly, error)

	// UpdateStatus updates an anomaly's status and optional review info.
	UpdateStatus(ctx context.Context, id string, status AnomalyStatus, reviewedBy, notes string) error

	// Delete removes an anomaly.
	Delete(ctx context.Context, id string) error

	// Watch returns a channel of anomalies as they're created/updated.
	// Used by ReviewWorker to process new pending anomalies.
	Watch(ctx context.Context) (<-chan *StructuralAnomaly, error)

	// Cleanup removes old resolved anomalies (applied/rejected) older than retention.
	// Returns the count of deleted anomalies.
	Cleanup(ctx context.Context, retention time.Duration) (int, error)

	// Count returns the total number of anomalies by status.
	Count(ctx context.Context) (map[AnomalyStatus]int, error)

	// IsDismissedPair checks if an entity pair is already tracked (any status including pending).
	// This prevents re-detecting the same semantic gap repeatedly across detection runs.
	IsDismissedPair(ctx context.Context, entityA, entityB string) (bool, error)

	// HasEntityAnomaly checks if an anomaly already exists for an entity+type combination.
	// This prevents re-detecting the same core isolation/demotion across detection runs.
	HasEntityAnomaly(ctx context.Context, entityID string, anomalyType AnomalyType) (bool, error)
}

type StorageConfig struct {
	// BucketName is the NATS KV bucket for storing anomalies
	BucketName string `json:"bucket_name"`

	// RetentionDays is how long to keep resolved anomalies (applied/rejected)
	RetentionDays int `json:"retention_days"`

	// CleanupInterval is how often to run cleanup of old anomalies
	CleanupInterval time.Duration `json:"cleanup_interval"`
}

type StructuralAnomaly struct {
	// ID is a unique identifier for this anomaly (UUID).
	ID string `json:"id"`

	// Type categorizes the anomaly detection method.
	Type AnomalyType `json:"type"`

	// EntityA is the primary entity involved in the anomaly.
	EntityA string `json:"entity_a"`

	// EntityB is the secondary entity (empty for single-entity anomalies like CoreDemotion).
	EntityB string `json:"entity_b,omitempty"`

	// Confidence is a score from 0.0 to 1.0 indicating detection certainty.
	Confidence float64 `json:"confidence"`

	// Evidence contains type-specific proof of the anomaly.
	Evidence Evidence `json:"evidence"`

	// Suggestion is the proposed relationship to address the anomaly.
	Suggestion *RelationshipSuggestion `json:"suggestion,omitempty"`

	// Status is the current lifecycle state.
	Status AnomalyStatus `json:"status"`

	// DetectedAt is when the anomaly was first identified.
	DetectedAt time.Time `json:"detected_at"`

	// ReviewedAt is when the anomaly was reviewed (nil if not yet reviewed).
	ReviewedAt *time.Time `json:"reviewed_at,omitempty"`

	// ReviewedBy identifies who reviewed (e.g., "llm", "user@example.com").
	ReviewedBy string `json:"reviewed_by,omitempty"`

	// LLMReasoning is the explanation provided by the LLM for its decision.
	LLMReasoning string `json:"llm_reasoning,omitempty"`

	// ReviewNotes are additional notes from human review.
	ReviewNotes string `json:"review_notes,omitempty"`

	// EntityAContext is cached context for human review display.
	EntityAContext string `json:"entity_a_context,omitempty"`

	// EntityBContext is cached context for human review display.
	EntityBContext string `json:"entity_b_context,omitempty"`
}

type TransitivityConfig struct {
	// Enabled activates transitivity gap detection
	Enabled bool `json:"enabled"`

	// MaxIntermediateHops is the maximum hops in A->...->B->...->C chains to analyze
	MaxIntermediateHops int `json:"max_intermediate_hops"`

	// MinExpectedTransitivity is the maximum expected A-C distance when A->B->C exists
	// Gaps where actual distance > this are flagged
	MinExpectedTransitivity int `json:"min_expected_transitivity"`

	// TransitivePredicates lists predicates that should be transitive
	// e.g., ["member_of", "part_of", "located_in"]
	TransitivePredicates []string `json:"transitive_predicates"`
}

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

type TripleAdder interface {
	AddTriple(ctx context.Context, triple message.Triple) error
}

type VirtualEdgeConfig struct {
	// AutoApply configures automatic edge creation for high-confidence gaps
	AutoApply AutoApplyConfig `json:"auto_apply"`

	// ReviewQueue configures lower-confidence gaps that need LLM/human review
	ReviewQueue ReviewQueueConfig `json:"review_queue"`
}