DICE API Documentation/com.embabel.dice.common

Package-level declarations

Types

Picks the best canonical display name from a set of candidates for a single entity. The complement of NormalizedNameCandidateSearcher.normalizeName — which normalizes names for matching — this is for normalizing what we write to the graph.

CompositeDiceEventListener

class CompositeDiceEventListener(listeners: List<DiceEventListener>) : DiceEventListener

Delivers each event to several listeners in turn. Every delivery is made exception-safe (see SafeDiceEventListener), so one listener throwing doesn't stop the others from hearing about the event.

ContentHasher

fun interface ContentHasher

Strategy for computing a content hash from text. Used for content-based deduplication across the DICE pipeline.

ContradictionEvent

data class ~~ContradictionEvent~~(val timestamp: Instant = Instant.now()) : DiceEvent

The original contradiction signal, which carried no information about what was contradicted.

ConversationAnalysisRequestEvent

class ConversationAnalysisRequestEvent(source: Any, val user: <Error class: unknown class>, val conversation: <Error class: unknown class>) : SourceAnalysisRequestEvent

Event published after a conversation exchange to trigger async proposition extraction. Used by any application integrating the DICE memory pipeline.

DiceEvent

interface DiceEvent

Something noteworthy that happened to a proposition as it moved through DICE — discovered, merged, contradicted, saved, gone stale, and so on. Each subtype is a specific moment you can listen for; every event knows when it occurred.

DiceEventListener

fun interface DiceEventListener

Implement this to react to DiceEvents as they happen. Keep in mind handlers run inline on the emitting thread, so do anything slow off to the side.

DiceMetadataKeys

object DiceMetadataKeys

Well-known metadata keys used by DICE for values cached on a proposition's metadata map.

EntityExtractionResult

interface EntityExtractionResult

Result of entity extraction and resolution. Provides access to entities that need to be persisted.

EntityExtractionStats

data class EntityExtractionStats(val newCount: Int, val updatedCount: Int, val referenceOnlyCount: Int = 0)

Statistics about entity extraction outcomes.

EntityResolver

interface EntityResolver

Resolves entities based on existing data

EvidenceFloor

data class EvidenceFloor constructor(val minConfidence: Double? = null, val minAuthority: AuthorityTier? = null, val demoteTo: String? = null)

The minimum evidence a proposition must carry before a relation may be asserted at full strength.

ExistingEntity

data class ExistingEntity(val suggested: SuggestedEntity, val existing: <Error class: unknown class>) : SuggestedEntityResolution

An existing entity was found that matches the suggested entity. The recommended entity merges labels from both entities, preferring the more specific type (e.g., Detective over Person).

ExtractionBatchCompleted

data class ExtractionBatchCompleted constructor(val stats: PropositionExtractionStats, val timestamp: Instant = Instant.now()) : DiceEvent

A batch of text finished extraction, carrying the stats on what came out of it.

ExtractionRunTransitioned

data class ExtractionRunTransitioned constructor(val run: ExtractionRun, val timestamp: Instant = Instant.now()) : DiceEvent

An extraction run ended, and this is the call that ended it.

KnowledgeType

enum KnowledgeType : Enum<KnowledgeType>

Classification of the epistemological nature of knowledge. Describes what kind of fact or relationship is being expressed.

KnownEntity

data class KnownEntity(val entity: <Error class: unknown class>, val role: String, val aliases: List<String> = emptyList())

A known entity with additional context for this extraction. Delegates to the wrapped NamedEntity.

LoggingDiceEventListener

class LoggingDiceEventListener : DiceEventListener

Logs every event it receives at debug level and nothing more. A cheap way to see the event stream while developing or debugging; it never throws.

NewEntity

data class NewEntity(val suggested: SuggestedEntity) : SuggestedEntityResolution, DiceEvent

No entity existed. We simply create a new entity.

ProjectionBatchCompleted

data class ProjectionBatchCompleted constructor(val successCount: Int, val skipCount: Int, val failureCount: Int, val totalCount: Int, val timestamp: Instant = Instant.now()) : DiceEvent

A batch of propositions finished projecting, with a tally of how each one turned out.

PropositionContradicted

data class PropositionContradicted constructor(val contextId: <Error class: unknown class>, val original: Proposition, val new: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A new proposition directly contradicts one we already held. Both are handed to listeners so they can decide how to reconcile them.

PropositionDemoted

data class PropositionDemoted constructor(val proposition: Proposition, val toRelation: String, val reason: String, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition's relation was demoted to a weaker one because it didn't have enough supporting evidence — kept and downgraded rather than thrown away.

PropositionDiscovered

data class PropositionDiscovered constructor(val proposition: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A brand-new proposition was discovered — nothing like it existed before.

PropositionGeneralized

data class PropositionGeneralized constructor(val proposition: Proposition, val generalizes: List<Proposition>, val timestamp: Instant = Instant.now()) : DiceEvent

A higher-level proposition was formed that generalizes over a group of more specific ones.

PropositionMerged

data class PropositionMerged constructor(val original: Proposition, val revised: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

An incoming proposition was folded into one we already had, producing a combined version.

PropositionPersisted

data class PropositionPersisted constructor(val proposition: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was saved. This is the signal to rely on when you care that something actually made it to durable storage, not just that it was proposed — it fires once the write is done and carries the saved state.

PropositionPinned

data class PropositionPinned(val proposition: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was pinned, so decay sweeps will leave it alone.

PropositionProjectionSkipped

data class PropositionProjectionSkipped constructor(val proposition: Proposition, val reason: String, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was kept out of projection — it may still be saved, but it won't be pushed out to the downstream representations (graph, Prolog, memory, and so on).

PropositionReinforced

data class PropositionReinforced constructor(val original: Proposition, val revised: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A similar proposition came in and reinforced one we already trusted, strengthening it.

PropositionRejected

data class PropositionRejected constructor(val proposition: Proposition, val reason: String, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was turned away after extraction — it should be discarded rather than saved. Like every other event here, it carries the whole proposition (text included) to whichever listeners you've wired up.

PropositionRoutedToReview

data class PropositionRoutedToReview constructor(val proposition: Proposition, val reason: String, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was set aside for a human (or a later pass) to look at, rather than being saved straight away.

PropositionStatusChanged

data class PropositionStatusChanged(val proposition: Proposition, val previousStatus: PropositionStatus, val newStatus: PropositionStatus, val reason: String? = null, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition moved to a different lifecycle PropositionStatus — for example going stale during a decay sweep, or coming back to life when it's seen again.

PropositionUnpinned

data class PropositionUnpinned(val proposition: Proposition, val timestamp: Instant = Instant.now()) : DiceEvent

A proposition was unpinned, so it's back in scope for decay sweeps.

ReferenceOnlyEntity

data class ReferenceOnlyEntity(val suggested: SuggestedEntity, val existing: <Error class: unknown class>) : SuggestedEntityResolution

A known entity that should be referenced but not updated. Used for entities managed by external services (e.g., the current user) that should not be modified during proposition extraction.

Relation

data class Relation constructor(val predicate: String, val meaning: String, val knowledgeType: KnowledgeType, val subjectType: String? = null, val objectType: String? = null, val evidenceFloor: EvidenceFloor? = null)

Defines a relationship type that can exist between entities. Used to provide the LLM with vocabulary for expressing relationships in propositions.

Relations

data class Relations(val relations: List<Relation> = emptyList()) : Iterable<Relation>

A reusable, immutable collection of Relation types with a fluent builder API.

Resolution

interface Resolution<S, R>

Resolution

Resolutions

data class Resolutions<R>(val chunkIds: Set<String>, val resolutions: List<R>)

SafeDiceEventListener

class SafeDiceEventListener(delegate: DiceEventListener) : DiceEventListener

Wraps another listener and stops it from taking down the caller: if the wrapped listener throws, the error is logged and swallowed instead of bubbling up.

SchemaAdherence

data class SchemaAdherence constructor(val entities: Boolean = true, val predicates: Boolean = false)

Configuration for how strictly extraction should adhere to the schema.

SchemaRegistry

interface SchemaRegistry

Registry for named schemas (DataDictionary instances). Allows API clients to specify which schema to use for proposition extraction.

SourceAnalysisContext

data class SourceAnalysisContext constructor(val schema: <Error class: unknown class>, val entityResolver: EntityResolver, val contextId: <Error class: unknown class>, val knownEntities: List<KnownEntity> = emptyList(), val relations: Relations = Relations.empty(), val promptVariables: Map<String, Any> = emptyMap(), val sourceLocator: SourceLocator? = null, val perspective: ExtractionPerspective? = null, val mintNewEntities: Boolean = false, val mintedEntityProperties: Map<String, Any> = emptyMap(), val sourceRevision: SourceRevisionRef? = null, val profile: ExtractionContentProfileRef? = null, val currentRun: ExtractionRunRef? = null)

Base context for analyzing sources. Individual analyzers may extend this to require additional fields as needed.

SourceAnalysisRequestEvent

abstract class SourceAnalysisRequestEvent(source: Any, val user: <Error class: unknown class>)

Base event for requesting proposition extraction from any incremental source. The user is typed as NamedEntity so that any application's user type (e.g., UrbotUser, Customer) can be used directly.

SuggestedEntities

data class SuggestedEntities(val suggestedEntities: List<SuggestedEntity>, val sourceText: String? = null)

Entities suggested by the LLM based on a single input. These entities may duplicate existing entities in the knowledge graph

SuggestedEntity

data class SuggestedEntity(val labels: List<String>, val name: String, val summary: String, val chunkId: String, val id: String? = null, val properties: Map<String, Any> = emptyMap(), val confidence: <Error class: unknown class> = 1.0, val decay: <Error class: unknown class> = 0.0, val importance: <Error class: unknown class> = 0.5, val source: String = "source_analyzer") : Suggestion

Entity suggested following analysis of text.

SuggestedEntityResolution

sealed interface SuggestedEntityResolution : Resolution<SuggestedEntity, <Error class: unknown class>>

VetoedEntity

data class VetoedEntity(val suggested: SuggestedEntity) : SuggestedEntityResolution

We do not want to progress with this suggested entity.