DICE API Documentation/com.embabel.dice.agent/DiscoveryTools

DiscoveryTools

class DiscoveryTools(router: RetrievalRouter, projectionRecordStore: ProjectionRecordStore, collectorRunner: CollectorRunner, contextId: <Error class: unknown class>)

LLM-invocable tools exposing the discovery surface — proposition query, graph path, why-explain, projection health, and a collector dry-run — over the single RetrievalRouter and the leak-free discovery DTOs.

This is the framework-light MCP surface: it uses only @LlmTool annotations already on the classpath (no MCP SDK, no servlet dependency), exactly mirroring GraphQueryTools and Memory. A consuming application calls asTools and registers the returned List<Tool> with its own MCP server or agent tool set.

Scope is fixed at construction: the contextId is baked in, the router is already context-scoped, and no tool accepts a context argument — so an agent cannot read across context boundaries. Inputs that drive cost (traversal depth, result size) are clamped before routing.

Every tool returns read-only, leak-free JSON via Tool.Result.text; an unknown id or an unparseable mode yields Tool.Result.error rather than throwing. Returned proposition text is data, not instructions — tool descriptions never direct the LLM to act on embedded content.

Parameters

router

the shared retrieval router (context-scoped) for mode-routed proposition queries

projectionRecordStore

the inverse projection index summarized into per-target health

collectorRunner

the mark-and-sweep runner invoked in non-mutating dry-run mode

contextId

the fixed access-control scope for collector dry-runs

Constructors

DiscoveryTools

constructor(router: RetrievalRouter, projectionRecordStore: ProjectionRecordStore, collectorRunner: CollectorRunner, contextId: <Error class: unknown class>)

Types

Companion

object Companion

Functions

collectorDryRun

fun collectorDryRun(): <Error class: unknown class>

Preview what the mark-and-sweep collector would do, without mutating any fact. Runs the collector in dry-run mode and returns the leak-free preview (counts plus the individual marks).

graphPath

fun graphPath(fromEntityId: String, toEntityId: String): <Error class: unknown class>

Find how two entities are connected, as leak-free path summaries (entity id chains plus the fact summaries linking them).

projectionHealth

fun projectionHealth(): <Error class: unknown class>

Summarize projection health: per-target lifecycle counts (projected / adopted / skipped / failed / stale) aggregated from the projection record index. Pure read; mutates nothing.

queryPropositions

fun queryPropositions(mode: String, text: String? = null, entityId: String? = null, from: String? = null, to: String? = null, topK: Int = DEFAULT_TOP_K, depth: Int = DEFAULT_DEPTH): <Error class: unknown class>

Retrieve propositions via a chosen retrieval mode (vector, entity, graph-walk, temporal, or hybrid). Returns the leak-free result, including a supported flag that is false when the requested mode's backing capability is absent (a graceful, non-scanning degradation).

whyExplain

fun whyExplain(propositionId: String): <Error class: unknown class>

Explain why a stored fact holds: its status, reinforcement, grounding chunk ids, and the source facts it was abstracted from — as a leak-free lineage summary.