Use DICE when your application needs to accumulate knowledge from text over time and then query it in more than one shape:

Do not reach for DICE when a vector store and a retrieval prompt are enough. The proposition model earns its cost when knowledge is revised — merged, reinforced, contradicted, superseded — not when it is only ever appended.

Impromptu is a classical-music exploration chatbot that builds a knowledge graph from conversation. It exercises most of the surface described in this guide: PropositionPipeline for extraction, incremental analysis for streaming conversation, an EscalatingEntityResolver with an LLM-backed candidate searcher, and Spring Boot integration with asynchronous processing.

The split at step 6 is deliberate: DICE never opens a transaction on your behalf.

This guide describes how to use DICE. For why it behaves as it does — the decisions you cannot recover by reading a single class — the design notes live in docs/design/ in the repository:

confidence is a historical fact: it is what the LLM thought at extraction time. It is not what you should rank or filter on.

PropositionQuery exposes both: withMinConfidence(…​) filters the raw number, and withMinEffectiveConfidence(…​) filters the decayed one. Reach for the effective form unless you have a specific reason not to.

The decay rate multiplier k defaults to 2.0 and is configurable per query and, for the scheduled tick, through embabel.dice.store.decay.k.

contentRevised is the decay anchor. It moves only when the claim itself changes.

Administrative changes — flipping status, pinning, attaching grounding — touch metadataRevised and leave contentRevised alone. This is what stops housekeeping from silently making stale beliefs look fresh. lastAccessed is separate again, and touchAccessed(…​) on the store updates it in bulk without disturbing either revision clock.

PropositionStatus tracks a claim’s standing. ACTIVE is the normal case; the other states record that a claim has been superseded, contradicted, or has decayed past usefulness. Transitions are governed by a StatusTransitionPolicy, which is an SPI you can replace.

DICE decays rather than deletes. A claim that stops being believed keeps its history, its evidence, and its links, so "we used to think X, then Y arrived" remains answerable. Hard deletion is a separate, opt-in sweep — see Knowledge hygiene.

When the same claim arrives again from a different source, DICE does not store a duplicate. It folds the new evidence in:

absorbEvidence combines confidence, grounding, provenance and reinforceCount. The inverse, withoutFoldedEvidence(…​), exists so a retraction can be applied without losing the rest.

Proposition is a Kotlin data class and every mutator returns a copy: withText, withStatus, withConfidence, withPinned, withGrounding, withTemporal, withProvenance, withResolvedMentions, withMetadataValue. Nothing mutates in place, so a proposition can be shared across threads without ceremony.

Java callers get a Proposition.create(…​) factory and getContextIdValue() for the value-class ContextId.

Expect raw and effective confidence to be close on a freshly extracted claim, and to diverge as the decay tick runs against it.

EscalatingEntityResolver climbs a ladder and stops at the cheapest rung that works. The rung it stopped at is reported back as a ResolutionLevel:

Each attempt returns a LevelResult carrying the level, the resolution, a confidence, and how many candidates were considered — which is what you look at when tuning.

Construct one with the shipped searcher chain:

Passing null for the bake-off means ambiguous cases mint a new entity rather than asking an LLM.

Candidate recall is pluggable. CandidateSearcher implementations ship for exact name, normalised name, partial name, fuzzy name, id, vector similarity, and AgenticCandidateSearcher, which lets an LLM go looking. DefaultCandidateSearchers assembles the standard chains.

To add a strategy, implement CandidateSearcher and compose it into the resolver’s chain.

Resolvers compose, and the order is the policy:

PropositionPipeline.process(…​) wraps your resolver with an InMemoryEntityResolver automatically — but only when mintNewEntities is on. With minting off the wrapper is skipped deliberately: remembering an entity that will never be created would produce mentions resolved to ids that do not exist.

Extraction is stateless per chunk and can be dispatched concurrently. Resolution is not: it reads and writes shared identity state, and running it concurrently is how you get two entities for one thing. DICE keeps resolution serial regardless of the ExtractionExecutionStrategy in force, so cross-chunk identity holds however extraction was dispatched. See Concurrent extraction.

Not every mention deserves resolution. A MentionFilter runs before resolution and drops low-quality spans — vague references, overly long spans, anything the schema says cannot be an entity. Filtering here is cheaper than resolving and then reclaiming.

Shipped filters include SchemaValidatedMentionFilter, the context-aware filters in ContextAwareMentionFilters, and ObservableMentionFilter, which wraps another filter to report what it rejected.

"Ada Lovelace" and "Lovelace" should resolve to the same id. If they do not, that is the tuning problem Tune entity resolution exists for.

PropositionStore is the base port and is deliberately small: save, find by id, find by entity, find by status, find by grounding, find by context, delete, count — plus one composable query.

PropositionRepository extends it with optional capability interfaces. A backend implements only what it genuinely supports:

Each capability interface carries default implementations expressed over the base primitives, so a backend that implements nothing extra still behaves correctly — just more slowly.

Selection is a property, not a code change — see Graph-backed storage.

PropositionQuery is a data class assembled through with* methods. The axes:

Kotlin infix factories have Java-friendly withXxx and againstContext equivalents throughout.

A projection is a rebuildable, typed view. Nothing in a projection is authoritative — if it and the propositions disagree, the propositions win.

EventEmittingProjector and EventEmittingPropositionRepository are decorators that publish Spring application events on projection and on save. Wire them in when you want something to react.

RetrievalRouter is the single entry point for retrieval, choosing a RetrievalMode rather than making the caller pick between vector search, graph traversal and keyword overlap. Authority filtering is applied at query time, and pushed down to the backend where the backend says it can honour it.

On the quickstart’s in-memory default this tells you exactly which capabilities you have before you write a query that needs one.

Every proposition belongs to exactly one ContextId. It is the primary scope, and the starting point of every query:

There is no PropositionQuery.create(). That is a design decision, not an omission: without a scope, "load everything" would be the shortest thing to write, and in a store that accumulates indefinitely that is a production incident waiting to happen.

ContextId is a Kotlin value class, so it costs nothing at runtime. Java callers reach the string through getContextIdValue(), on both Proposition and PropositionQuery.

What a context should represent is your decision. Common choices: one per user, one per tenant, one per conversation, one per document collection. Contexts do not nest; if you need a hierarchy, encode it in the value and query by prefix at your own layer.

SourceAnalysisContext is the per-run configuration handed to the pipeline. It carries the schema, the resolver, the ContextId, and everything else extraction needs to know:

It is a data class with with* builders, so a base context can be specialised per run:

The DataDictionary is your domain’s schema: the entity types extraction should look for, and the relationship metadata that names the predicates it may use. SchemaRegistry holds them.

SchemaAdherence decides how strictly extraction obeys it. Two independent switches:

Set it on the extractor:

Strictness is the main lever on extraction noise. Start at DEFAULT; move to STRICT when you trust the schema and want the extractor to stop inventing predicates; move to RELAXED only while exploring.

Relations declares the predicates that may hold between entities. Extraction uses them to phrase claims consistently, and RelationBasedGraphProjector uses them to decide which edges to create. Declaring relations is what turns free-text claims into a graph you can traverse rather than a bag of sentences.

The gap between the two is the size of the noise your schema is currently suppressing.

Gates run on pipeline output before the caller persists anything. They are the cheapest intervention, because nothing has been written yet.

Compose them with ExtractionGatePipeline, and wrap any of them in ObservableGate to see what is being rejected and why. A gate you cannot observe is a gate you will eventually mis-tune.

Reclamation is mark-and-sweep over what is already stored. CollectorRunner walks the store, a CollectorStrategy marks candidates, and a SweepPolicy decides each marked proposition’s fate.

The vocabulary is small and worth knowing: a PropositionMark carries a MarkReason, and the policy produces a SweepAction.

Two shipped strategies:

The MultiSignalCollectorStrategy is the production duplicate matcher, blending several signals rather than trusting any one of them. See Multi-signal collector.

Two things make reclamation safe to run: it has a dry-run mode that reports what it would do without doing it, and every live run is recorded to a CollectorRecordStore, so a surprising result is explainable after the fact. Run it dry first. Always.

Pinned propositions are exempt.

Consolidation rewrites what survives into something more useful. DreamLoopOrchestrator composes passes, and DefaultDreamLoopOrchestrator gates each pass on a threshold, so a quiet store does no work.

The four shipped passes:

A run produces a DreamLoopReport describing what each pass did.

DefaultMemoryMaintenanceOrchestrator is the older four-step pipeline. Prefer the dream loop for new work.

Underneath all three sits the same principle: DICE fades beliefs rather than erasing them. Decay lowers effective confidence, status records that a claim was superseded or contradicted, and the evidence stays attached. Hard deletion of STALE propositions is available but off by default — embabel.dice.store.decay.prune-stale is false — because most applications would rather answer "why did you stop believing that?" than reclaim the rows.

Read the marks and their reasons before you ever run this live.

dice-ingestion turns artifacts into chunks and keeps a ledger so the same source is not extracted twice.

The ledger keys on content, not on filename or path. Renaming a file does not cause re-extraction; editing one does.

process handles cross-chunk entity identity for you: when minting is enabled it wraps your resolver so an entity minted in chunk 2 is recognised in chunk 7.

The pipeline stores nothing. That is deliberate — DICE never decides your transaction boundary.

If you forget persist, nothing is saved and nothing complains.

For a corpus that grows, use incremental analysis rather than reprocessing. ChunkHistoryStore records which chunks have been analysed; AbstractIncrementalAnalyzer and its subclasses skip those. dice-storage-autoconfigure provides a ChunkHistoryStore bean for whichever backend is selected.

Grounding links a claim to the chunk it came from and is created automatically. Provenance is richer: a ProvenanceEntry plus a SourceLocator records how to get back to the original material, which is what RationaleProjector uses to explain a belief.

Document text carries far more noise than conversation does — headers, boilerplate, citations. A MentionFilter drops weak mentions before the expensive resolution step:

Wrapping in ObservableMentionFilter while you tune tells you what is being dropped.

Extraction is the slow stage and is stateless per chunk, so it can be dispatched concurrently. Resolution stays serial regardless. See Concurrent extraction — including the thread-safety condition you must verify before turning it on.

IncrementalAnalyzer processes an IncrementalSource and remembers what it has already seen. ConversationSource wraps a conversation; ConversationSegmenter decides where one unit of analysis ends and the next begins, so a claim spanning three turns is not cut in half.

Re-analysing the same conversation is cheap: ChunkHistoryStore reports what has already been processed and the analyser skips it.

Without this, "I prefer the early recordings" produces a claim about nobody.

KnownEntity.asCurrentUser(…​) is the important line: it gives the resolver a first-class identity for the speaker, so first-person claims attach to them.

Conversation analysis costs an LLM call, so it should not sit in the request path. ConversationAnalysisRequestEvent exists for exactly this:

SourceAnalysisRequestEvent is the general form for non-conversation sources.

In a conversation the same thing gets said repeatedly, and sometimes retracted. Without revision you accumulate near-duplicates; with it, restatements reinforce and reversals are classified as contradictions.

Revision compares against what is already stored and classifies each new claim as new, merged, reinforced or contradicted. It still persists nothing — hasRevision tells you which set propositionsToPersist() will return.

Give each user their own ContextId. It is the boundary that keeps one user’s beliefs out of another’s retrieval, and it is what makes "forget everything about me" a bounded operation.

LevelResult reports the ResolutionLevel that produced each answer, and how many candidates were considered. That distribution is the diagnostic:

The cheap searchers decide what the expensive ones ever see.

DefaultCandidateSearchers.create(repository) assembles the standard chain; DefaultCandidateSearchers.withoutVector(repository) drops the vector searcher for stores with no index.

And separately, whether minting is allowed at all:

Minting off is the right default for a closed catalogue. Minting on is necessary for open-domain extraction, and is what makes mention filtering matter.

ChainedEntityResolver tries resolvers in order and takes the first hit, so order is policy:

Do not add InMemoryEntityResolver by hand for a process(…​) run — the pipeline adds it when minting is on, and adding it when minting is off produces mentions resolved to ids that will never exist.

Every mention that should never have been a mention is a chance to resolve wrongly. A MentionFilter is cheaper than the resolution it prevents:

Tightening SchemaAdherence to STRICT has the same effect earlier still, at the extractor. See Context and schema.

Some duplication is unavoidable, and reclamation exists to absorb it. The MultiSignalCollectorStrategy blends vector, lexical, entity-overlap, grounding-overlap and provenance-overlap signals, with a polarity veto that stops a claim merging with its own negation. Tune embabel.dice.collector.match-threshold and the per-signal weights rather than loosening resolution — see Multi-signal collector.

Run it dry first, and read the trace.

Filter on effective confidence, not raw confidence, unless you specifically want the extractor’s original opinion:

withAllEntities is how you ask about a relationship without traversing a graph: claims that mention both endpoints are the claims about the pair.

level is the abstraction ladder: 0 is extracted, higher levels were built by the consolidation AbstractionPass.

Three independent clocks, three independent filters:

Filtering on revisedAfter is what you want for "what changed"; createdAfter misses claims that were revised, and accessedAfter tells you about readers, not writers.

count(query) returns the size without materialising the rows.

PropositionStore also offers direct lookups — findById, findByEntity, findByStatus, findByGrounding, findByMinLevel, findPinned — plus keywordOverlap(base, tokens, limit) for lexical scoring over a base query, and pin/unpin for exempting a claim from reclamation.

touchAccessed(ids) records that a set of propositions was read, without touching either revision clock.

Capabilities are optional per backend — check before you rely on one:

GraphQueryCapable gives you GraphNeighborhood, GraphPath and PropositionLineage. Backends that support it may also report honorsAuthorityFilter, letting authority-filtered traversals run natively rather than being filtered afterwards.

When you would rather not choose, use RetrievalRouter: it picks a RetrievalMode — vector, graph or lexical — from the shape of the query, and applies authority filtering at query time.

Start relation-based. Reach for the LLM projector when you find real relationships your Relations cannot express.

GraphProjectionService wraps this for the common case; NamedEntityDataRepositoryGraphRelationshipPersister is the persister for entity repositories.

A ProjectionPolicy decides which propositions are eligible — typically a confidence or trust floor, so a weakly believed claim does not become a hard edge. ProjectionPolicySupport holds the shipped building blocks.

The ProjectionEligibilityGate does the same job earlier, at admission time, marking a claim as stored but not yet worth projecting.

Deciding this deliberately matters: an edge reads as a fact, even when the claim behind it was believed at 0.4.

RelationshipDescriptionSynthesizer generates human-readable descriptions for projected relationships; LlmRelationshipDescriptionSynthesizer does it with an LLM. Useful when the graph is something people will look at rather than only traverse.

Every projected edge records which propositions produced it, in a ProjectionRecordStore. Two things follow.

The stale cascade. When a source proposition changes, the edges derived from it are marked stale rather than left silently wrong. You can find them, and you can see why.

Idempotent reconciliation. Reconciler brings the graph back into agreement with the propositions without rebuilding it. Re-running projection over unchanged input is a no-op, so projection can be scheduled rather than orchestrated.

The REST layer exposes the same information at GET /api/v1/contexts/{contextId}/discovery/projection-health.

With a GraphQueryCapable repository:

lineage is the "why does this edge exist" query: it walks back from a projected edge to the propositions and, through grounding and provenance, to the source text.

EventEmittingProjector decorates any projector and publishes Spring application events as projections happen — the hook for cache invalidation, search reindexing, or notifying a UI.

MemoryProjector.project(propositions) returns a MemoryProjection with propositions sorted into four buckets, following the standard cognitive split:

KnowledgeType is the enum behind the split. MemoryProjection exposes size and all(), so you can budget the context window across buckets rather than truncating a flat list.

MemoryRetriever is the read side, with four entry points shaped by how agents actually ask:

DefaultMemoryRetriever implements all four. recallAbout is the one to reach for when the agent has already identified who or what it is talking about — it is more precise than a semantic query over the same text.

Memory is where accumulation hurts first: an agent whose recall is 80% stale beliefs is worse than one with no memory at all.

Run the dream loop periodically. DefaultDreamLoopOrchestrator gates each pass on a threshold, so a quiet context does nothing:

The passes fold sessions into durable claims, build abstractions, resolve contradictions and apply decay. See Knowledge hygiene.

MemoryConsolidator is the lower-level piece if you want to compose your own cycle; DefaultMemoryMaintenanceOrchestrator is the older four-step pipeline, kept for compatibility.

Some things should never decay out of memory — a user’s name, a hard constraint, a standing instruction:

Pinned propositions are exempt from decay-driven reclamation. Use it sparingly; every pin is a permanent claim on the context window.

MemoryController exposes memory at /api/v1/contexts/{contextId}/memory — list, search, recall by entity, create, fetch and delete. It is opt-in. See Web API.

The Oracle answers from stored propositions, and nothing else. That is the point: every answer is traceable to claims that carry confidence, grounding and provenance. If it does not know, the honest answer is that it does not know — which is only useful because the propositions behind it are auditable.

To show your work, pair the Oracle with RationaleProjector from dice-report:

LlmRationaleProjector produces the narrative form; rationale(PropositionGroup) explains a set of claims together rather than one at a time.

The Oracle answers within a ContextId like everything else. Asking a question against the wrong context is the most common way to get a confidently wrong answer — one user’s beliefs are not another’s.

Plus Drivine’s own Neo4j connection configuration. Nothing else in your application changes: the auto-configuration swaps PropositionRepository, ChunkHistoryStore, DecayManager, ProjectionRecordStore and CollectorRecordStore for their Drivine equivalents, and registers the schema catalogues that create the constraints and the vector index.

See Graph-backed storage for the full activation detail.

Every auto-configured bean is @ConditionalOnMissingBean. Define your own PropositionRepository and the auto-configuration steps aside — which is also how you implement PropositionStore against a backend DICE does not ship.

Implement only the capabilities you genuinely support. The default implementations on VectorSearchCapable, GraphTraversalCapable, GraphQueryCapable and TemporalQueryCapable express each operation over the base primitives, so an unimplemented capability degrades in performance rather than breaking.

There is no shipped migration tool. Propositions are the system of record and everything else is a projection, so a migration is: read every proposition and entity from the old store, write them to the new one, then re-project. Reconciliation is idempotent, so re-projecting is safe to repeat.

Two decorators publish Spring application events. Neither is wired by default — you opt in by wrapping:

EventEmittingPropositionRepository publishes on save; EventEmittingProjector publishes on projection. PropositionPersisted is the canonical durable signal — the one to build on when you need to know something was actually stored.

DiceEvent is the event hierarchy; DiceEventListeners holds the listener support types.

The pipeline emits its own, pre-persistence events:

process emits one aggregate ExtractionBatchCompleted per run. With a reviser configured, processChunk also emits a per-proposition candidate event for each RevisionResult.

Those candidate events are pre-persistence signals, and the distinction matters: a candidate event means the pipeline classified something, not that anything was written. If your listener has side effects, build them on PropositionPersisted instead.

A listener that throws cannot abort a run — the pipeline wraps whatever you register in SafeDiceEventListener. The default is DiceEventListener.DEV_NULL, so behaviour is unchanged when no listener is set.

Two decorators exist purely so you can see what is being rejected:

Both are for tuning. A filter or gate you cannot observe is one you will eventually set wrong and not notice — the symptom is silence, and silence looks like success.

Every live collector run is recorded to a CollectorRecordStore, and detailed decisions to a CollectorTraceStore. The trace records the edges considered, the connected components found, and the decision made for each — enough to explain any individual merge after the fact.

InMemoryCollectorTraceStore is the default; DrivineCollectorTraceStore persists to Neo4j when the graph backend is selected.

Tells you what is stale, which is the signal that a reconciliation pass is due. Also exposed at GET /api/v1/contexts/{contextId}/discovery/projection-health.

Use it in production, and whenever you need any of: durability across restarts, more than one process writing, native graph traversal, or decay applied in the database rather than in your heap.

Leave it off for development, tests and single-process applications. The in-memory backend is the default precisely because most of what you do while building DICE into an application does not need Neo4j.

Plus Drivine’s Neo4j connection configuration.

With type=graph, DiceStorageAutoConfiguration provides:

Every one is @ConditionalOnMissingBean, so your own bean always wins.

dice-storage maps propositions onto typed nodes: PropositionNode, SourceNode, ProcessedChunkNode, Mention and DerivedFrom, with PropositionView and PropositionWithProvenanceView as the read projections. PropositionGraphMapper handles the mapping; GraphProjectionCypher holds the traversal queries.

Nothing in your code changes. This is the same call against either backend:

What changes is that on the graph backend the repository also implements GraphQueryCapable, so native traversal is available:

Leave it on. Semantic retrieval over propositions is what makes "what do we know that is relevant to this?" answerable without an exact match, and it is also what lets VectorCandidateSearcher resolve aliases that share no characters with the canonical name.

Turn it off when your Neo4j deployment does not support vector indexes, when you are certain all retrieval is by entity and ContextId, or when the index build on a large existing store is something you want to schedule rather than have happen at startup.

To disable:

Only enabled. The index’s label, property, name and similarity function are fixed by the @VectorIndex annotation on PropositionNode.embedding and live as constants on DrivinePropositionRepository.

This is deliberate: those values must agree between the index definition and every query that uses it, and making them configurable would create a way to have them disagree.

The vector dimension comes from the configured EmbeddingService, so the index matches whatever embedding model your Ai bean is using.

With the index disabled, VectorSearchCapable operations fall back to the default implementations expressed over the base primitives — correct, but a scan.

Leave decay on. Without it, a claim made once two years ago competes on equal terms with one made this morning, and retrieval quality degrades as the store grows.

Turn prune-stale on only when you have decided that reclaiming rows matters more than being able to answer "why did you stop believing that?". For most applications it does not.

Two phases:

Pinned propositions are exempt.

k is the decay-rate multiplier. Higher k means faster erosion. It appears in three places, and they are independent:

Setting the property without the query parameter means the tick and your queries disagree about how fast things fade. Set both, or leave both at the default.

Run this against a claim you care about before choosing k. The right value is the one where a belief you would want to have forgotten has faded, and one you would want to keep has not.

Decay is anchored on contentRevised, not created and not metadataRevised. Changing a claim’s status, pinning it, or attaching grounding does not make it look fresh again. Only changing what it says does.

Use it when the same claim reaches you from more than one source and entity resolution alone has not collapsed the duplicates. That is most systems that ingest continuously.

Turn it off when your corpus is small enough to inspect, when duplicates are genuinely rare, or while you are still tuning extraction — merging is much harder to undo than to postpone.

MultiSignalCollectorStrategy scores each candidate pair on several signals and blends them. No single signal can carry a merge:

An edge scoring at or above match-threshold becomes eligible to merge its endpoints. Eligible edges form connected components, and CollectorSurvivorPolicy picks which proposition in each component survives, absorbing the others' evidence.

A null weight means "use the scorer’s own default", which is not the same as zero — the nullable type exists so "unset" and "set to the default number" stay distinguishable.

similarity-threshold and top-k apply to the vector signal only.

Raise match-threshold if you see wrong merges. Lower it, or widen the vector signal’s similarity-threshold and top-k, if duplicates survive.

Prefer tuning here over loosening entity resolution: reclamation is auditable and reversible in review, and a bad resolution is neither.

Every live run is recorded to CollectorRecordStore; the detailed edges, components and decisions go to a CollectorTraceStore — InMemoryCollectorTraceStore by default, DrivineCollectorTraceStore on the graph backend.

Use it for bulk ingestion, where extraction dominates wall-clock time and each chunk is an independent LLM call.

Leave it off for conversation analysis — one chunk at a time gains nothing — and until you have verified the condition below.

process(…​) has two stages:

Keeping resolution serial is what preserves cross-chunk entity identity regardless of how extraction was dispatched. An entity minted while processing chunk 2 is recognised in chunk 7 under every strategy.

Input order is preserved by the strategy, and a chunk whose extraction failed yields a null slot that becomes a typed failed result in the resolution stage — one bad chunk does not fail the batch.

withExecutionStrategy returns a new pipeline, like every other with* method.

Measure before and after. If extraction was not your bottleneck, this buys nothing and adds a thread-safety obligation you now have to maintain.

Use it when something outside the JVM needs to reach DICE — another service, a front end, a tool process.

Leave it off when DICE is a library inside one application. It is off by default because a knowledge store is not something to expose accidentally.

DiceRestConfiguration imports the controllers. They are ordinary @RestController beans, and each needs its collaborators present — importing the configuration without the beans behind it will fail at startup rather than silently serve nothing.

The controllers speak in DTOs — PropositionDto, EntityMentionDto, ProvenanceEntryDto, ExtractRequest, MemorySearchRequest and the rest — rather than serialising domain types. The wire format is a contract you can evolve separately from the model, and internal fields do not leak.

ExtractOptions carries per-request extraction settings, including a SchemaAdherenceDto mapping to Context and schema's three constants.

Use it whenever Web API is exposed beyond your own process. The REST endpoints are unauthenticated without it, and the extraction endpoints make LLM calls on demand — an open one is both a data-exposure problem and a billing one.

Leave it off when the endpoints are not exposed, or when you already have Spring Security in front of them.

With enabled: true, ApiKeySecurityAutoConfiguration registers an InMemoryApiKeyAuthenticator over the configured keys and a servlet filter over the configured path patterns.

If you enable it and configure no keys, the authenticator logs a warning at startup — that message means every request is being rejected.

The in-memory list is for development. Provide your own ApiKeyAuthenticator bean and the auto-configuration steps aside, because it is @ConditionalOnMissingBean:

That is where key rotation, per-key scoping and revocation belong.

The filter protects path-patterns, which defaults to /api/v1/**. Anything outside that pattern — actuator endpoints, your own controllers, static resources — is untouched. If you mount DICE’s controllers under a different prefix, update the patterns to match, or you will have enabled security that guards nothing.

Use it when the questions you need answered are derived rather than stored: transitive closure, mutual exclusion, "who else is affected if this is true", rules a domain expert can read and check.

Leave it off when retrieval answers your questions. A vector search and a graph traversal cover most of what applications ask, and neither requires you to maintain a rule base.

Provide a projector, project, then query:

query is the yes/no form. queryAll returns every solution, queryFirst the first, and findAll extracts the bindings of one variable as strings — usually what you want when the answer is a list of entity ids.

PrologTools exposes the fact base to ToolOracle as a tool, so a natural-language question that needs inference rather than retrieval can be answered by running rules. See Ask questions in natural language.

PrologProjector extends the generic Projector and produces PrologFact values, one per projected relationship. The projection is derived — if the propositions change, re-project rather than editing facts.

PrologTypes holds the type mapping between DICE’s model and Prolog terms.

DICE pins tuProlog to 1.0.4. The 1.1.x series is built with Kotlin 2.2.x and is binary-incompatible with the dice module’s Kotlin 2.1.10. This constrains DICE’s build, not yours — but if you bring your own tuProlog, match the pinned version.

Read by dice-storage-autoconfigure.

The vector index’s label, property, name and similarity are not configurable — they are fixed by the @VectorIndex annotation on PropositionNode.embedding and live as constants on DrivinePropositionRepository.

Read by dice-storage-autoconfigure. Validated: match-threshold must be in [0.0, 1.0] and signal weights must be non-negative.

Valid <name> values are the built-in signals: vector, lexical, entity-overlap, grounding-overlap, provenance-overlap, polarity-veto.

Read by dice. Note the prefix: dice., not embabel.dice..

Read by dice, bound by LlmSourceAnalyzer. Configures the text-to-graph source analyser.

An LLM provider must be configured, and that configuration belongs to embabel-agent, not to DICE. Neo4j connection settings belong to Drivine. DICE reads neither.

Kotlin infix factory methods on PropositionQuery have Java-friendly withXxx and againstContext equivalents. ContextId is a value class, so Java code uses getContextIdValue(). Proposition.create(…​) is the Java-friendly factory. @JvmOverloads is applied where defaults would otherwise be unreachable from Java.

dice-storage integration tests start a Neo4j container through Testcontainers, so Docker must be running. The root pom pins api.version=1.41 as a Surefire JVM system property to meet the Docker engine’s minimum API version — without it, container-backed tests fail with HTTP 400.

Drivine’s query DSL is generated by a nested Gradle/KSP project at dice-storage/codegen-gradle, run automatically during generate-sources. Do not edit the generated files.

Snapshots and releases resolve from repo.embabel.com. An environment without internet access needs those repositories mirrored locally.

Output lands in dice-user-guide/target/generated-docs. Add -P guide-pdf for a PDF.