@retinue/agentkit 0.2.0 → 0.3.1

package/dist/knowledge/graph-global.js

@@ -0,0 +1,246 @@
+/**
+ * `graph-global` — map-reduce over community summaries. REQ-064 (#270), task #274.
+ *
+ * The mode that answers *"what are the main themes in our incident reports?"* — a question that requires having
+ * read everything, which top-k retrieval by construction does not.
+ *
+ * ## The output shape, decided — AC-7
+ *
+ * The issue left this open, and it is the one real design question here. Three candidates:
+ *
+ * 1. **A synthesised answer** in a new shape. Most honest about what happened, and it breaks every existing
+ *    consumer of `RetrievalOutcome` — citations, the empty-result union, the tools above.
+ * 2. **Synthetic chunks** whose content is the community summary. Tempting and wrong: a `KnowledgeChunk` has an
+ *    id that resolves and a source that exists, and a fabricated one produces a citation pointing at nothing.
+ *    The model would present a generated summary as though a document said it, which is the failure provenance
+ *    exists to prevent.
+ * 3. **Real chunk hits from the communities the map phase selected.** Citations resolve, every consumer works
+ *    unchanged, and the corpus-level reasoning is real — it happened in *choosing which communities matter*,
+ *    which is what reading everything buys you.
+ *
+ * **Three**, and the summaries are not discarded: they come back on `GraphGlobalResult` alongside coverage, for
+ * a caller that wants the thematic answer rather than the passages behind it. What this mode does *not* do is
+ * hand the model a summary dressed as a source.
+ *
+ * ## The ceiling is the design, not a guard bolted on
+ *
+ * Cost scales with the number of communities, which scales with the corpus. A large tenant's global query could
+ * issue hundreds of model calls. So the ceiling is checked **before spending**, from the community count — a
+ * refusal that arrives after two hundred calls is not a ceiling, it is a bill with an apology.
+ *
+ * And it **refuses** rather than truncating. A partial map-reduce presented as a whole-corpus answer is a wrong
+ * answer with a confident shape, which is worse than no answer: "the main themes are X and Y" is false if it
+ * read a third of the corpus, and nothing in the sentence says so.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { isCommunityStale, } from "../persistence/index.js";
+/**
+ * How many model calls one global query may make, by default.
+ *
+ * Forty is a corpus of a few hundred documents at a coarse level. It is deliberately a number somebody has to
+ * raise consciously: the failure this bounds is not a slow query, it is a tenant growing until one question
+ * costs more than a day of ordinary use.
+ */
+export const DEFAULT_GLOBAL_CALL_CEILING = 40;
+/** A companion ceiling, because a small number of enormous summaries costs as much as many small ones. */
+export const DEFAULT_GLOBAL_TOKEN_CEILING = 120_000;
+/** Below this the map phase considered the community irrelevant and its chunks are not gathered. */
+export const DEFAULT_RELEVANCE_SCORE = 1;
+/**
+ * Which level of the hierarchy to read.
+ *
+ * The coarsest available, by default. Reading every level multiplies cost for largely repeated content — a
+ * level-1 community contains the level-0 ones under it, so summarising both says the same thing twice at twice
+ * the price. Coarse suits "what are the main themes"; a caller with a narrower question passes a finer level.
+ *
+ * Exported because the choice is worth testing on its own: picking the wrong level is the difference between
+ * an answer about the corpus and an answer about one team.
+ */
+export const chooseLevel = (available, requested) => {
+    if (available.length === 0)
+        return 0;
+    if (requested !== undefined && available.includes(requested))
+        return requested;
+    return Math.max(...available);
+};
+export const createGraphGlobalSearch = (deps) => {
+    const callCeiling = Math.max(1, deps.callCeiling ?? DEFAULT_GLOBAL_CALL_CEILING);
+    const tokenCeiling = Math.max(1, deps.tokenCeiling ?? DEFAULT_GLOBAL_TOKEN_CEILING);
+    const minScore = deps.minScore ?? DEFAULT_RELEVANCE_SCORE;
+    const chunksPerCommunity = Math.max(1, deps.chunksPerCommunity ?? 3);
+    const now = deps.now ?? (() => Date.now());
+    const allCommunities = async (tenantId) => {
+        const out = [];
+        let cursor;
+        do {
+            const page = await deps.graph.listCommunities({
+                tenantId,
+                limit: 200,
+                ...(cursor === undefined ? {} : { cursor }),
+            });
+            out.push(...page.items);
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+        return out;
+    };
+    return {
+        async search(context, input) {
+            const started = now();
+            const everything = await allCommunities(context.tenantId);
+            const level = chooseLevel([...new Set(everything.map((c) => c.level))], input.level ?? deps.level);
+            const atLevel = everything.filter((community) => community.level === level);
+            const empty = {
+                hits: [],
+                themes: [],
+                coverage: {
+                    level,
+                    communitiesTotal: atLevel.length,
+                    communitiesRead: 0,
+                    communitiesRelevant: 0,
+                    communitiesUnsummarised: atLevel.filter((c) => c.summary === undefined).length,
+                    staleSummaries: 0,
+                    calls: 0,
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    elapsedMs: now() - started,
+                },
+            };
+            if (input.authSubjects.length === 0 || atLevel.length === 0)
+                return empty;
+            // Only summarised communities can be mapped. Counted rather than quietly skipped — a corpus that is half
+            // unsummarised produces a partial answer, and the caller has to be able to see that.
+            const readable = atLevel.filter((community) => community.summary !== undefined);
+            if (readable.length === 0)
+                return empty;
+            /**
+             * **The ceiling, checked before spending.** AC-3, AC-4.
+             *
+             * From the community count, which is known without calling anything. A check after the loop, or inside
+             * it, would refuse having already spent most of what it was refusing.
+             */
+            if (readable.length > callCeiling) {
+                throw new AgentPlatformError({
+                    code: "budget_exceeded",
+                    message: `A corpus-wide answer at level ${level} would read ${readable.length} community summaries, and the ` +
+                        `ceiling is ${callCeiling} model calls. Raise the ceiling, ask at a coarser level, or narrow the ` +
+                        "question so graph-local can answer it. Nothing was spent.",
+                    retryable: false,
+                });
+            }
+            let calls = 0;
+            let inputTokens = 0;
+            let outputTokens = 0;
+            const scored = [];
+            // Sorted, so a run is reproducible and a token-ceiling stop cuts at the same place.
+            for (const community of [...readable].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+                const { relevance, usage } = await deps.mapper.map({ query: input.query, community });
+                calls += 1;
+                inputTokens += usage?.inputTokens ?? 0;
+                outputTokens += usage?.outputTokens ?? 0;
+                scored.push({ community, relevance });
+                /**
+                 * The token ceiling can only be checked *during* the loop — summary sizes are not knowable up front —
+                 * so unlike the call ceiling this one can be reached mid-flight. It still refuses rather than
+                 * returning what it has, for the same reason: a partial map-reduce presented as a whole-corpus answer
+                 * is confidently wrong.
+                 */
+                if (inputTokens + outputTokens > tokenCeiling) {
+                    throw new AgentPlatformError({
+                        code: "budget_exceeded",
+                        message: `A corpus-wide answer at level ${level} passed the ${tokenCeiling}-token ceiling after ` +
+                            `${calls} of ${readable.length} community summaries. Raise the ceiling or ask at a coarser level. ` +
+                            "A partial reading is not reported as a whole-corpus answer.",
+                        retryable: false,
+                    });
+                }
+            }
+            const relevant = scored
+                .filter((entry) => entry.relevance.score >= minScore)
+                // Best first; ties by id so the order is total and the result reproducible.
+                .sort((a, b) => b.relevance.score - a.relevance.score || (a.community.id < b.community.id ? -1 : 1));
+            const allowed = new Set(input.authSubjects);
+            const wantedTypes = input.sourceTypes === undefined ? null : new Set(input.sourceTypes);
+            // Mutable locals, widened from the readonly result type — the arrays are built here and frozen by
+            // the return type, which is the shape every other result in this module uses.
+            const hits = [];
+            const best = relevant[0]?.relevance.score ?? 1;
+            for (const entry of relevant) {
+                let taken = 0;
+                for (const chunkId of entry.community.chunkIds) {
+                    if (taken >= chunksPerCommunity || hits.length >= input.limit)
+                        break;
+                    const chunk = await deps.knowledge.get({ tenantId: context.tenantId, id: chunkId });
+                    if (chunk === null)
+                        continue;
+                    /**
+                     * AC-8. The same primary-key read `graph-local` guards, and the same reasoning: a community spans
+                     * whatever its entities span, including sources this principal cannot read.
+                     *
+                     * The *summary* is the harder half of AC-8 and is handled below — see `themes`.
+                     */
+                    if (!allowed.has(chunk.authSubject))
+                        continue;
+                    if (wantedTypes !== null && !wantedTypes.has(chunk.sourceType))
+                        continue;
+                    hits.push({
+                        chunk,
+                        score: best === 0 ? 0 : entry.relevance.score / best,
+                        communityId: entry.community.id,
+                    });
+                    taken += 1;
+                }
+                if (hits.length >= input.limit)
+                    break;
+            }
+            /**
+             * **The summary leak, and what is actually done about it — AC-8.**
+             *
+             * A community summary is generated text over every chunk in the community, so it can paraphrase a
+             * document this principal cannot read. Filtering the summary is not possible: it is prose, and there is
+             * no way to remove one source's contribution from a sentence after the fact.
+             *
+             * So a theme is returned **only when the principal can read every chunk behind it**. That is stricter
+             * than necessary — a summary may not in fact mention the restricted source — and it is the only rule
+             * that cannot leak. The alternative, returning it and hoping, is exactly the kind of "probably fine" that
+             * a permission boundary must not be built on.
+             *
+             * The cost is real and worth naming: on a corpus with mixed permissions, a principal sees fewer themes
+             * than a colleague, and the coverage numbers say how many. That is a comprehensible answer. A summary
+             * quoting a document they were never allowed to open is not.
+             */
+            const themes = [];
+            for (const entry of relevant) {
+                const chunks = await Promise.all(entry.community.chunkIds.map((id) => deps.knowledge.get({ tenantId: context.tenantId, id })));
+                const readableToCaller = chunks.every((chunk) => chunk === null || allowed.has(chunk.authSubject));
+                if (!readableToCaller)
+                    continue;
+                themes.push({
+                    communityId: entry.community.id,
+                    summary: entry.community.summary,
+                    score: entry.relevance.score,
+                    points: entry.relevance.points,
+                    // Disclosed rather than hidden: an answer built on summaries written before the last three documents
+                    // landed is defensible; presenting it as current is not.
+                    stale: isCommunityStale(entry.community),
+                });
+            }
+            return {
+                hits,
+                themes,
+                coverage: {
+                    level,
+                    communitiesTotal: atLevel.length,
+                    communitiesRead: calls,
+                    communitiesRelevant: relevant.length,
+                    communitiesUnsummarised: atLevel.length - readable.length,
+                    staleSummaries: themes.filter((theme) => theme.stale).length,
+                    calls,
+                    inputTokens,
+                    outputTokens,
+                    elapsedMs: now() - started,
+                },
+            };
+        },
+    };
+};
+//# sourceMappingURL=graph-global.js.map

package/dist/knowledge/graph-retrieval.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `graph-local` — entity-centric retrieval. REQ-064 (#270), task #273.
+ *
+ * The mode that answers *"which teams depend on the retry budget?"* — a question whose answer exists in no
+ * single chunk. Semantic search finds chunks that look like the question; this finds the chunks that are
+ * *connected to what the question is about*.
+ *
+ * Four steps, and the interesting decisions are in the first and the last:
+ *
+ * 1. **Resolve** the entities the question names.
+ * 2. **Traverse** their neighbourhood, bounded.
+ * 3. **Gather** the chunks those entities and edges came from.
+ * 4. **Filter and rank**, returning ordinary `RetrievalHit`s.
+ *
+ * ## Why the query is swept for n-grams rather than read by a model
+ *
+ * The obvious way to find the entities in a question is to ask a model. It costs a call per query, it is not
+ * reproducible across model versions, and #275 has to measure this against a fixed baseline.
+ *
+ * So instead every 1-to-4 word window of the question is normalised and looked up, and **the graph itself is
+ * the filter** — a window that is not an entity simply matches nothing. That is deterministic, free, and uses
+ * exactly the normalisation the index used, which is what makes AC-3 hold by construction rather than by two
+ * functions agreeing.
+ *
+ * It will miss an entity the question refers to obliquely ("the budget thing"). That is a real limit, it is
+ * measurable, and #275 is where it gets measured.
+ *
+ * ## Why there is no fallback to semantic search
+ *
+ * When nothing resolves, this returns an honest empty result. Falling back would mean a caller attributing
+ * semantic results to `graph-local` — which is precisely why `not-configured` exists as its own reason rather
+ * than as `no-match`, and the same reasoning applies one level down.
+ */
+import type { TenantId } from "../core/ids.js";
+import type { GraphStore, KnowledgeChunk, KnowledgeRelationship, KnowledgeSourceType, KnowledgeStore } from "../persistence/index.js";
+import type { EmbeddingProvider } from "./index.js";
+/**
+ * How far a traversal goes by default.
+ *
+ * One hop is often too few — "which teams depend on the retry budget" is one hop, but "what does the retry
+ * budget affect downstream" is two. Three is a large fraction of a connected graph, and the cost is not the
+ * traversal but the chunks it drags in. Two is the useful middle, and it is a parameter because the right
+ * answer is corpus-shaped.
+ */
+export declare const DEFAULT_GRAPH_DEPTH = 2;
+/** Edges considered per hop. A hub entity can have hundreds; taking all of them buries the specific ones. */
+export declare const DEFAULT_NEIGHBOUR_LIMIT = 50;
+/** The longest phrase treated as a possible entity name. Four words covers "the retry budget policy". */
+export declare const MAX_ENTITY_NGRAM = 4;
+/**
+ * Every phrase in the query that could name an entity, normalised and deduplicated.
+ *
+ * Longest first, which matters for ranking rather than correctness: "retry budget policy" is a more specific
+ * match than "retry budget", and a caller that stops early should see the specific one.
+ *
+ * Exported for its own test — this is the function that decides whether a real question finds anything, and
+ * its failure mode is silent (an empty result that looks like an empty corpus).
+ */
+export declare const entityCandidates: (query: string) => readonly string[];
+/** A chunk reached through the graph, with the reason it was reached. */
+export type GraphChunkHit = {
+    readonly chunk: KnowledgeChunk;
+    /** 0–1 relative to the best hit in this result, as every other mode's score is. */
+    readonly score: number;
+    /** The entities that led here, so the answer can say *why* this chunk is relevant. */
+    readonly viaEntities: readonly string[];
+};
+export type GraphLocalResult = {
+    readonly hits: readonly GraphChunkHit[];
+    /** The entities the question resolved to. Empty means nothing matched — an honest empty result. */
+    readonly matchedEntities: readonly string[];
+    /**
+     * The edges traversed, with their provenance — AC-6.
+     *
+     * Returned rather than folded into the chunks because "Team A depends on the retry budget" is a fact stored
+     * on an *edge*, and a model handed two adjacent chunks would have to infer the connection. Handing it the
+     * relationship lets it state one.
+     */
+    readonly relationships: readonly KnowledgeRelationship[];
+    /** True when the traversal hit a bound. Reported, never silent — the same rule pagination follows. */
+    readonly truncated: boolean;
+    /**
+     * Which ranking produced the order — #277, AC-1.
+     *
+     * Reported because the two are not interchangeable and a measurement of one must never be mistaken for a
+     * measurement of the other. `connectivity` means no embedder was configured.
+     */
+    readonly rankedBy: "relevance" | "connectivity";
+};
+export type GraphLocalSearchDeps = {
+    readonly graph: GraphStore;
+    readonly knowledge: KnowledgeStore;
+    readonly depth?: number;
+    readonly neighbourLimit?: number;
+    /**
+     * Ranks the chunks the traversal gathered — #277.
+     *
+     * **Optional, and the mode is materially worse without it.** Measured on this repository's corpus,
+     * connectivity-only ranking scored 20.8% success@5 against semantic search's 75%. The gap between its own
+     * columns was the tell: it found the right *document* 45.8% of the time and the right *chunk* half as often
+     * again, because an entity's provenance is every chunk that mentioned it and counting entity touches cannot
+     * tell two chunks of one document apart.
+     *
+     * So the graph is used for **selection** and embeddings for **ranking**, which is what Microsoft's local
+     * search does and what ours did not.
+     *
+     * Left optional rather than required because a deployment that has a graph and no embedder still gets a
+     * working traversal, and `docs/29` says plainly what it costs. `rankedBy` in the result reports which
+     * happened, so a measurement can never silently be of the other one.
+     */
+    readonly embeddings?: EmbeddingProvider;
+    /**
+     * How many candidates to gather before ranking, as a multiple of the caller's limit.
+     *
+     * Ranking can only reorder what selection handed it, so a pool of exactly `limit` makes the re-rank a no-op
+     * — which is precisely the bug: the old code stopped gathering at `limit`, so the top-k by connectivity were
+     * the only chunks that could ever be returned.
+     */
+    readonly poolFactor?: number;
+};
+/** Gathered wide, then ranked. Below this a re-rank has too little to choose between. */
+export declare const DEFAULT_POOL_FACTOR = 8;
+export declare const MIN_POOL = 40;
+/**
+ * How much an entity's breadth discounts it — the hub problem, in one line.
+ *
+ * `docs/01-architecture.md` and `concepts/architecture.md` appeared in miss after miss. Generic entities
+ * ("run", "tool", "platform") are extracted from nearly every chunk, link to nearly everything, and drag the
+ * architecture overview into every traversal. An entity that touches half the corpus tells you almost nothing
+ * about *which* chunk you want, and counting it equally with a specific one is the mechanism by which the
+ * overview outranks the page that answers the question.
+ *
+ * A logarithmic discount rather than an IDF proper, because IDF needs the corpus size and this needs only what
+ * is already in hand. An entity in 2 chunks keeps most of its weight; one in 200 keeps about a seventh of it.
+ */
+export declare const hubDiscount: (provenanceSize: number) => number;
+/** Cosine similarity. Vectors from one provider share a dimension, and a mismatch is a bug worth surfacing. */
+export declare const cosine: (a: readonly number[], b: readonly number[]) => number;
+export interface GraphLocalSearch {
+    search(context: {
+        readonly tenantId: TenantId;
+    }, input: {
+        readonly query: string;
+        readonly authSubjects: readonly string[];
+        readonly limit: number;
+        readonly sourceTypes?: readonly KnowledgeSourceType[];
+    }): Promise<GraphLocalResult>;
+}
+export declare const createGraphLocalSearch: (deps: GraphLocalSearchDeps) => GraphLocalSearch;
+//# sourceMappingURL=graph-retrieval.d.ts.map