@adonis-agora/agent/dist/src/telescope/rag-data-providers.d.ts

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

import type { DataProvider } from './telescope-sdk.js';
/**
 * RAG data providers for the "Agent" Telescope tab — a DELIBERATELY PARTIAL port of the Nest
 * reference's `rag-data-providers.ts`.
 *
 * ## What Adonis's retrieval instrumentation actually publishes
 *
 * `@adonis-agora/agent` has exactly ONE retrieval telemetry point today: `agent-loop.ts`'s
 * inject-mode retrieval path (`deps.retriever` configured) publishes `agora:agent:retrieved` via
 * `publishAgentRetrieved` (`src/diagnostics.ts`) with payload `{ runId, queryLength, count }` —
 * nothing else. Telescope's generic diagnostics bridge records it as any other `lib:agent` event:
 * `type: 'diagnostic'`, `tag: 'lib:agent'`, `content: { event: 'retrieved', payload: {...} }`.
 *
 * That payload has NO `store`, `collection`, `retriever` kind, `topScore`, or `durationMs` — unlike
 * `@dudousxd/nestjs-agent-rag`'s dedicated `aviary:rag:retrieval` channel, which is what lets the
 * Nest reference build latency histograms, score distributions, and store/collection breakdowns.
 * `agent-loop.ts` DOES span the retrieval (`spannedAgent('retrieval', ...)`, which carries `topK` and
 * a `count` result on its `asyncEnd`), but those spans ride raw `node:diagnostics_channel` sub-channels
 * (`agora:agent:retrieval:start/end/asyncStart/asyncEnd/error`) that NOTHING in `@adonis-agora/telescope`
 * subscribes to today — confirmed by reading its `diagnostics_watcher.ts` and every `metrics/*.ts` file:
 * the generic bridge only auto-subscribes to POINT channels a producer registers via
 * `@adonis-agora/diagnostics`'s `registry.channels`, and `spannedAgent` publishes on ad-hoc sub-channel
 * names it never registers there (by design — it avoids importing `@adonis-agora/diagnostics` at all).
 * So the span data is not lost, exactly, but nothing today turns it into a recorded Telescope entry;
 * building that bridge is a `@adonis-agora/telescope` (or `@adonis-agora/diagnostics`) change, not
 * something this file can conjure from the entries Telescope already has.
 *
 * ## What that leaves portable
 *
 * From `{ runId, queryLength, count }` alone: how many retrievals happened, what fraction came back
 * empty (`count === 0`), the mean passage count, and a retrievals/zero-hits trend. That is FOUR of the
 * Nest reference's ten RAG providers. The other six — latency distribution, score distribution,
 * store breakdown, retriever breakdown, per-collection table, slowest-retrievals table — are NOT
 * ported: there is no field in the recorded entry for any of them, and faking one (e.g. a
 * `durationMs` of 0 for every row) would render a chart that looks real and lies. Widening
 * `AgentRetrieved`'s payload (and `agent-loop.ts`'s publish call) to carry that data is the real fix;
 * it's a `src/diagnostics.ts`/`src/agent-loop.ts` instrumentation change, out of scope for a telescope
 * extension change, and is called out as the recommended follow-up.
 *
 * ## Shares the SAME 5,000-entry window as every other agent provider
 *
 * Unlike the Nest reference — where `RagTelescopeWatcher` gives retrieval events their OWN entry type
 * (`agent-rag`) specifically so a busy retrieval stream can never crowd `run.finished` out of the
 * agent window — Adonis has no per-extension entry-type/watcher mechanism (see `extension.ts`'s
 * header for why), so `retrieved` entries live in the exact same capped `lib:agent` slice
 * `data-providers.ts` reads. A retrieval-heavy deployment can push older `run.*`/`tool-call` entries
 * out of that window, and vice versa. This is an accepted, documented limitation, not an oversight.
 */
/** One retrieval, normalized out of an entry's `content.payload`. */
interface RagRetrieval {
    at: number;
    queryLength: number;
    count: number;
}
/** Fraction (0–1) of retrievals that came back with nothing. `0` over an empty window. */
export declare function zeroHitRate(retrievals: RagRetrieval[]): number;
/** Mean passages returned per retrieval. `0` over an empty window. */
export declare function meanChunks(retrievals: RagRetrieval[]): number;
/** stat → retrievals recorded in the current window. */
export declare function ragRetrievalsProvider(): DataProvider;
/** stat (percent) → share of retrievals that returned nothing. */
export declare function ragZeroHitRateProvider(): DataProvider;
/** stat → mean passages returned per retrieval. */
export declare function ragChunksProvider(): DataProvider;
/** timeseries → retrievals and zero-hits per bucket, using the same bucketing every other agent
 * timeseries provider uses (`data-providers.ts`'s `timeBuckets`), not a second bucketing scheme. */
export declare function ragTrendProvider(): DataProvider;
export {};
//# sourceMappingURL=rag-data-providers.d.ts.map