@squidcloud/client 1.0.481 → 1.0.483

package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts

@@ -2,7 +2,7 @@ import { AgentContextRequest, AiChatModelSelection, UpsertContextStatusError } f
 import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
 import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
 import { DocumentExtractionMethod } from './extraction.public-types';
-import { MetadataAndFilter, MetadataFieldFilter, MetadataFilter, MetadataOrFilter, MetadataSimpleFilter, MetadataValue, MetadataValueArray } from './metadata-filter.public-types';
+import { MetadataAndFilter, MetadataFieldFilter, MetadataOrFilter, MetadataSimpleFilter, MetadataValue, MetadataValueArray } from './metadata-filter.public-types';
 /**
  * The set of supported vector store backends for a knowledge base. The authoritative backend for a
  * given KB is persisted on its record; reads/writes route through the matching vector provider.
@@ -37,6 +37,23 @@ export interface AiKnowledgeBase {
      * Optional on the read type for backwards compatibility with older records.
      */
     vectorDbType?: VectorDbType;
+    /**
+     * Opt-in GraphRAG configuration. Only honored for `vectorDbType:'mongoAtlas'` KBs; enables
+     * per-chunk entity/relationship extraction at ingest and `searchMode:'graph'` at query time.
+     */
+    graphRag?: AiKnowledgeBaseGraphConfig;
+    /**
+     * Default RAG strategy for newly ingested contexts; a per-request `options.ragType` overrides it.
+     * Omitted ⇒ the server default (`'basic'`). Changing it affects future ingests only — existing chunks
+     * are not re-processed.
+     */
+    ragType?: AiRagType;
+    /**
+     * Lifetime LLM usage of the contextual-RAG situating-blurb calls on this KB (server-managed; ignored
+     * on upsert). Persisted on the KB itself so the record survives Core restarts and covers any vector
+     * store. Under the combined-ingest strategy this stays ≈0 — growth is a visible fallback-rate signal.
+     */
+    contextualIngestUsage?: KnowledgeBaseGraphUsage;
     /** The timestamp the knowledge base was last updated */
     updatedAt: Date;
 }
@@ -66,6 +83,13 @@ export interface AiKnowledgeBaseMetadataField {
      * false once a human edits the description.
      */
     descriptionGeneratedByAi?: boolean;
+    /**
+     * Whether the LLM extraction pass may fill this field when it is missing. Defaults to `true` when
+     * undefined, so knowledge bases created before this flag existed keep their behavior. Set to `false`
+     * for fields whose value the caller supplies deterministically (e.g. folder-derived path metadata): a
+     * missing value then stays absent rather than being guessed from the document.
+     */
+    llmExtraction?: boolean;
 }
 /**
  * A record of metadata key-value pairs for AI context, where values are primitive types or undefined.
@@ -113,9 +137,120 @@ export type AiContextMetadataOrFilter = MetadataOrFilter;
  * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific — native Lucene BM25
  *   on Mongo Atlas (ranked, term-optional: a partial-term query still matches), and a boolean substring
  *   filter on pgvector (every term must appear literally; unranked).
+ * - `'graph'`: GraphRAG retrieval — seeds entities via vector search, expands relationships via graph
+ *   traversal, then maps entities back to their source chunks, RRF-fused with a standard hybrid search.
+ *   Only available on `vectorDbType:'mongoAtlas'` KBs with `graphRag.enabled`; tuned via
+ *   {@link AiKnowledgeBaseGraphSearchOptions}. This is the DEFAULT mode when a search omits `searchMode`
+ *   on a `graphRag.enabled` KB (non-graph KBs default to `'hybrid'`).
  * @category AI
  */
-export type AiKnowledgeBaseSearchMode = 'vector' | 'hybrid' | 'keyword';
+export type AiKnowledgeBaseSearchMode = 'vector' | 'hybrid' | 'keyword' | 'graph';
+/**
+ * Fine-grained options for `searchMode: 'graph'` retrieval (GraphRAG). The graph channel is always
+ * RRF-fused with a standard hybrid search; themes-level "global" answering has moved to the
+ * `globalSummary` op of the `queryKnowledgeGraph` surface.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphSearchOptions {
+    /** Entities seeded via vector search before graph expansion. Default 8, max 25. */
+    seedLimit?: number;
+    /** Number of hops to expand from each seed (traversal depth + 1). Default 2, max 3. */
+    maxHops?: number;
+    /** When true, attach the traversed {@link AiKnowledgeBaseGraphContext} to the response. Default false. */
+    includeGraphContext?: boolean;
+}
+/**
+ * Per-knowledge-base GraphRAG configuration. Opt-in and mutable (unlike `embeddingModel`/`vectorDbType`);
+ * only honored for `vectorDbType:'mongoAtlas'` KBs. Enabling it on a KB that already has content requires a
+ * graph backfill (the `rebuildGraph` endpoint).
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphConfig {
+    /** When true, ingestion extracts an entity/relationship graph and `searchMode:'graph'` becomes available. */
+    enabled: boolean;
+    /** Chat model used for per-chunk entity/relationship extraction. Defaults to the server's graph model. */
+    extractionModel?: AiChatModelSelection;
+    /** Optional domain taxonomy hint (entity types) injected into the extraction prompt. */
+    entityTypes?: string[];
+    /** Concept-layer (facet taxonomy) configuration. Omitted ⇒ `facets: 'auto'`. */
+    concepts?: AiKnowledgeBaseGraphConceptsConfig;
+}
+/**
+ * Configuration of the graph's concept layer (Layered KB Graph L3 facets — deterministic trees built
+ * from metadata values at rebuild).
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphConceptsConfig {
+    /**
+     * Which metadata fields become value facets (flat sets of categorical values). `'auto'` (the default)
+     * profiles the KB's context metadata and selects the categorical fields; an explicit list overrides
+     * auto-selection (fields still subject to the hard cardinality cap); `[]` disables value facets.
+     */
+    facets?: string[] | 'auto';
+    /**
+     * Explicit path facets — deterministic trees split from a hierarchical path field (e.g. a folder path)
+     * rather than LLM-grouped. Independent of {@link facets}: a path facet always builds when its field has
+     * values, coexists with auto value-facet selection (reserved outside the facet cap), and is exempt from
+     * the categorical eligibility gates (a path field is near-unique by leaf). Omitted/`[]` ⇒ no path facets.
+     */
+    pathFacets?: AiKnowledgeBaseGraphPathFacetConfig[];
+}
+/**
+ * The canonical folder-path metadata field: a POSIX-separated path relative to the upload root, no
+ * leading/trailing slash, case-preserved. Stamped by folder-aware ingestion (console folder upload,
+ * SDK clients). Register it under `graphRag.concepts.pathFacets` (`[{ field: 'folderPath', type: 'path' }]`)
+ * to build a navigable folder tree in the graph — the field name is never treated specially on its own.
+ * @category AI
+ */
+export declare const FOLDER_PATH_METADATA_FIELD_NAME = "folderPath";
+/**
+ * A path facet: a deterministic tree built by splitting a hierarchical path field on {@link separator}.
+ * Interior nodes are the path prefixes; scoping a search to one node matches that folder and everything
+ * beneath it. Exempt from the near-unique/cardinality eligibility gates (those judge flat value sets).
+ * Declared under {@link AiKnowledgeBaseGraphConceptsConfig.pathFacets}.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphPathFacetConfig {
+    /** The metadata field holding the path values (e.g. `'folderPath'`). */
+    field: string;
+    /** Marks this as a path facet. */
+    type: 'path';
+    /** Path segment separator. Defaults to `'/'`. */
+    separator?: string;
+}
+/** A single entity surfaced in a graph search's {@link AiKnowledgeBaseGraphContext}. @category AI */
+export interface AiKnowledgeBaseGraphContextEntity {
+    /** Canonical display name of the entity. */
+    name: string;
+    /** Entity type (e.g. PERSON, ORGANIZATION). */
+    type: string;
+    /** Compacted description of the entity. */
+    description: string;
+    /** Traversal relevance score in [0,1]. */
+    score: number;
+}
+/** A single relationship surfaced in a graph search's {@link AiKnowledgeBaseGraphContext}. @category AI */
+export interface AiKnowledgeBaseGraphContextRelationship {
+    /** Source entity display name. */
+    source: string;
+    /** Target entity display name. */
+    target: string;
+    /** Relationship label (short verb phrase). */
+    type: string;
+    /** Optional description of the relationship. */
+    description?: string;
+}
+/**
+ * The subgraph traversed to answer a `searchMode:'graph'` query. Additive/optional — returned only when
+ * `graphOptions.includeGraphContext` is set; clients that ignore it are unaffected.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphContext {
+    /** Entities reached by the traversal, sorted by score descending. */
+    entities: Array<AiKnowledgeBaseGraphContextEntity>;
+    /** Outgoing relationships between reached entities. */
+    relationships: Array<AiKnowledgeBaseGraphContextRelationship>;
+}
 /**
  * The options for the AI knowledgebase search method.
  * @category AI
@@ -152,6 +287,9 @@ export interface AiKnowledgeBaseChatOptions {
      *
      * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
      * on the same backend.
+     *
+     * When omitted, the default is `'graph'` (RRF-fused GraphRAG) on a `graphRag.enabled` KB and
+     * `'hybrid'` otherwise. See {@link AiKnowledgeBaseSearchMode}.
      */
     searchMode?: AiKnowledgeBaseSearchMode;
     /**
@@ -161,6 +299,27 @@ export interface AiKnowledgeBaseChatOptions {
      * default). Useful for A/B evaluating dense-vs-keyword weighting on the same backend.
      */
     hybridWeights?: AiHybridSearchWeights;
+    /** Tuning for `searchMode:'graph'` (GraphRAG). Ignored for other search modes. */
+    graphOptions?: AiKnowledgeBaseGraphSearchOptions;
+    /**
+     * Scopes the search to the documents under one concept of the KB's graph (Layered KB Graph).
+     * Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
+     */
+    graphFilter?: AiKnowledgeBaseGraphFilter;
+}
+/**
+ * Graph scope for a knowledge-base search: restricts results to the documents under one concept.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphFilter {
+    /**
+     * The concept to scope to: a facet nodeId (`facet_…` — exact, the only persistable concept handles)
+     * or a concept name, resolved server-side (exact → alias → similarity). Facet scopes filter by exact
+     * metadata membership; topic scopes are thematic (recall-safe but fuzzy — docs outside the theme's
+     * current membership are excluded). An unresolvable ref fails with `CONCEPT_NOT_FOUND` and the
+     * nearest matching concept names.
+     */
+    underConcept: string;
 }
 /**
  * Per-pipeline weights for native hybrid fusion. Sub-keys mirror the `$rankFusion` pipeline names.
@@ -173,10 +332,58 @@ export interface AiHybridSearchWeights {
     keyword?: number;
 }
 /**
+ * Segment-safe subtree match on a hierarchical string field such as a folder path: matches when the
+ * field's value is exactly the operand, or begins with the operand followed by a `/` separator. Unlike
+ * a raw character prefix, `{ folderPath: { $underPath: 'reports/2023' } }` matches `reports/2023` and
+ * `reports/2023/q1/deck` but never the lexical sibling `reports/2023 drafts` — the separator supplies
+ * the segment boundary, so subtree scoping never leaks into a sibling that merely shares a prefix.
+ *
+ * The operand is normalized by stripping any leading and trailing `/` before matching, so a caller that
+ * writes `reports/2023/` addresses the same subtree as `reports/2023`. The empty operand matches every
+ * document that HAS the field. Matching is case-sensitive.
+ *
+ * ### Canonical `folderPath` contract
+ * The value this operator is designed for — a document's `folderPath` metadata — is written and matched
+ * under one canonical form so filters, subtree scoping and the knowledge-graph path facet never
+ * fragment by how a value was authored:
+ * - POSIX `/` separators; no leading or trailing slash.
+ * - The empty string denotes the upload root (a file directly under it), never `undefined`.
+ * - Case-preserved on write and matched case-sensitively (`Reports` and `reports` are distinct folders).
+ * - NFC-normalized on write, so canonically-equivalent Unicode spellings compare equal.
+ *
+ * `folderPath` is an ordinary metadata key (not reserved); this operator is the tool for scoping to it.
+ * `$underPath` is knowledge-base-only: it is deliberately absent from the shared {@link MetadataSimpleFilter}
+ * that metrics and matchmaking consume (they reject unknown operators at runtime).
+ * @category AI
+ */
+export interface MetadataUnderPathFilter {
+    /** The subtree root the field's value must equal or sit under (leading/trailing `/` are ignored). */
+    $underPath: string;
+}
+/** A knowledge-base single-field operator: the shared {@link MetadataSimpleFilter} operators plus `$underPath`. */
+export type AiKbMetadataSimpleFilter = MetadataSimpleFilter | MetadataUnderPathFilter;
+/** A knowledge-base field filter: field names mapped to a {@link AiKbMetadataSimpleFilter} or a direct scalar. */
+export interface AiKbMetadataFieldFilter {
+    /** A record where keys are field names and values are either operator objects or direct scalar values. */
+    [field: string]: AiKbMetadataSimpleFilter | MetadataValue;
+}
+/** Knowledge-base filters combined with logical AND; each branch may itself use `$underPath`. */
+export interface AiKbMetadataAndFilter {
+    /** An array of filters that must all be true for the condition to pass. */
+    $and: AiContextMetadataFilter[];
+}
+/** Knowledge-base filters combined with logical OR; each branch may itself use `$underPath`. */
+export interface AiKbMetadataOrFilter {
+    /** An array of filters where at least one must be true for the condition to pass. */
+    $or: AiContextMetadataFilter[];
+}
+/**
+ * The knowledge-base context metadata filter: the shared MongoDB-style filter syntax extended with the
+ * KB-only `$underPath` operator (see {@link MetadataUnderPathFilter}). Other subsystems (metrics,
+ * matchmaking) use the plain `MetadataFilter`, which omits `$underPath`.
  * @category AI
- * @deprecated Use {@link MetadataFilter} from `metadata-filter.public-types` instead.
  */
-export type AiContextMetadataFilter = MetadataFilter;
+export type AiContextMetadataFilter = AiKbMetadataFieldFilter | AiKbMetadataAndFilter | AiKbMetadataOrFilter;
 /**
  * Represents an AI knowledge base's context entry with metadata and content.
  * @category AI
@@ -386,6 +593,9 @@ export interface AiKnowledgeBaseSearchOptions {
      *
      * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
      * on the same backend.
+     *
+     * When omitted, the default is `'graph'` (RRF-fused GraphRAG) on a `graphRag.enabled` KB and
+     * `'hybrid'` otherwise. See {@link AiKnowledgeBaseSearchMode}.
      */
     searchMode?: AiKnowledgeBaseSearchMode;
     /**
@@ -395,6 +605,13 @@ export interface AiKnowledgeBaseSearchOptions {
      * default). Useful for A/B evaluating dense-vs-keyword weighting on the same backend.
      */
     hybridWeights?: AiHybridSearchWeights;
+    /** Tuning for `searchMode:'graph'` (GraphRAG). Ignored for other search modes. */
+    graphOptions?: AiKnowledgeBaseGraphSearchOptions;
+    /**
+     * Scopes the search to the documents under one concept of the KB's graph (Layered KB Graph).
+     * Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
+     */
+    graphFilter?: AiKnowledgeBaseGraphFilter;
 }
 /**
  * A single chunk of data returned from an AI search operation.
@@ -417,6 +634,12 @@ export interface AiKnowledgeBaseSearchResultChunk {
 export interface UpsertKnowledgeBaseContextResponse {
     /** List of the upsert status of each item sent in the request. */
     failure?: UpsertContextStatusError;
+    /**
+     * Set when the context was stored (and is fully searchable via vector/keyword) but NOT graph-indexed
+     * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; the
+     * singular counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
+     */
+    graphIndexingSkipped?: boolean;
 }
 /**
  * Response structure for upserting contexts for an AiKnowledgeBase
@@ -435,6 +658,12 @@ export interface UpsertKnowledgeBaseContextsResponse {
      * `undefined` at runtime — callers must handle its absence rather than trust it is always populated.
      */
     contextIds?: Array<AiContextId>;
+    /**
+     * Contexts that were stored (and are fully searchable via vector/keyword) but NOT graph-indexed because
+     * the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; surfaced so a
+     * caller can report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
+     */
+    graphIndexingSkippedContextIds?: Array<AiContextId>;
 }
 /**
  * Request structure for searching an AiKnowledgeBase
@@ -610,6 +839,11 @@ export interface ListAiKnowledgeBaseContextsPageResponse {
 export interface AiKnowledgeBaseSearchResponse {
     /** Array of result chunks from the search */
     chunks: Array<AiKnowledgeBaseSearchResultChunk>;
+    /**
+     * The subgraph traversed for a `searchMode:'graph'` query. Present only when
+     * `graphOptions.includeGraphContext` was set; absent for all other searches.
+     */
+    graphContext?: AiKnowledgeBaseGraphContext;
 }
 /**
  * Response containing the list of AI knowledge bases in an application.
@@ -640,3 +874,420 @@ export interface GeneratedMetadataFieldDescription {
     /** The AI-generated description for the field. */
     description: string;
 }
+/**
+ * Request structure for reading a knowledge base's GraphRAG build/readiness status.
+ * @category AI
+ */
+export interface GetKnowledgeBaseGraphStatusRequest {
+    /** The id of the AiKnowledgeBase. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Response structure for a knowledge base's GraphRAG build/readiness status. Drives the ai-eval
+ * readiness poll (index until `contextsIndexed === contextsTotal` and `buildJob` is not in-progress).
+ * @category AI
+ */
+export interface GetKnowledgeBaseGraphStatusResponse {
+    /** Whether GraphRAG is enabled on the KB. */
+    enabled: boolean;
+    /** Number of entities in the KB's graph partition. */
+    entityCount: number;
+    /** Number of outgoing relationships (mirrors excluded). */
+    relationshipCount: number;
+    /** Number of communities detected (Phase 3), 0 when none. */
+    communityCount: number;
+    /** Contexts stamped as graph-indexed. */
+    contextsIndexed: number;
+    /** Total contexts in the KB. */
+    contextsTotal: number;
+    /** Document nodes in the KB's graph (Layered KB Graph L1) — one per graph-indexed context. */
+    docNodesTotal?: number;
+    /** Document nodes carrying a non-empty LLM description (failed descriptions retry on rebuild). */
+    docsDescribed?: number;
+    /** The KB's facet trees (Layered KB Graph L3, deterministic) — empty until a rebuild builds them. */
+    facets?: Array<KnowledgeBaseGraphFacetStatus>;
+    /**
+     * The KB's topic (theme) hierarchy — present once a graph build has clustered topics. Ids churn on
+     * rebuild ({@link KnowledgeBaseGraphTopic.id}); resolve them per session, never persist them.
+     */
+    topics?: Array<KnowledgeBaseGraphTopic>;
+    /**
+     * Leaf-level inter-topic edges (relationship counts crossing topic boundaries), present once a graph
+     * build has computed them. Roll up to coarser tiers by mapping each endpoint to its ancestor.
+     */
+    topicEdges?: Array<KnowledgeBaseGraphTopicEdge>;
+    /**
+     * True when documents were graph-indexed after the last topic build — themes may lag content until
+     * the next `rebuildGraph`. Only meaningful once topics exist (absent before the first rebuild).
+     */
+    structureStale?: boolean;
+    /** Documents added since the last topic build (the `structureStale` numerator). */
+    staleDocCount?: number;
+    /** Status of the most recent backfill/rebuild job, when one exists. */
+    buildJob?: KnowledgeBaseGraphBuildJob;
+    /** Lifetime LLM usage of incremental graph ingestion (per-upsert extraction), when any was recorded. */
+    ingestUsage?: KnowledgeBaseGraphUsage;
+    /** LLM usage of the most recent `rebuildGraph` run (including its re-extraction), when one ran. */
+    lastRebuildUsage?: KnowledgeBaseGraphUsage;
+    /**
+     * Lifetime LLM usage of the combined contextual-blurb + graph-extraction call (run automatically for
+     * `ragType:'contextual'` graph-enabled KBs), when any was recorded. Covers BOTH the contextual blurb
+     * and graph extraction in one call, so it is not directly comparable to the graph-only
+     * {@link ingestUsage}.
+     */
+    combinedIngestUsage?: KnowledgeBaseGraphUsage;
+}
+/** The most recent graph backfill/rebuild job of a knowledge base. @category AI */
+export interface KnowledgeBaseGraphBuildJob {
+    /** The job's lifecycle state. */
+    status: 'in_progress' | 'completed' | 'failed';
+    /** Failure message, present when `status` is `'failed'`. */
+    error?: string;
+}
+/**
+ * Aggregated LLM token usage (and best-effort cost) of graph work on a KB. Token counts are the
+ * provider-reported ground truth; `estCostUsd` is estimated from model list prices at call time —
+ * recompute from the tokens for exact accounting.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphUsage {
+    /** Number of LLM calls. */
+    llmCalls: number;
+    /** Prompt (input) tokens. */
+    inputTokens: number;
+    /** Completion (output) tokens. */
+    outputTokens: number;
+    /** Reasoning tokens, where the provider reports them separately. */
+    reasoningTokens: number;
+    /** Input tokens served from the provider's prompt cache. */
+    cacheReadTokens: number;
+    /** Input tokens written into the provider's prompt cache. */
+    cacheWriteTokens: number;
+    /** Best-effort USD estimated from list prices at call time. */
+    estCostUsd: number;
+    /**
+     * Per-model split of the totals above (LLM calls only), present when any usage was recorded. The
+     * per-model figures sum to the aggregate; embedding usage is excluded from both.
+     */
+    byModel?: Array<KnowledgeBaseGraphModelUsage>;
+}
+/**
+ * One model's slice of a KB's graph LLM usage, keyed by the resolved model name. Token counts are the
+ * provider-reported ground truth; `estCostUsd` is estimated from model list prices at call time.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphModelUsage {
+    /** The resolved model these totals are attributed to. */
+    model: string;
+    /** Number of LLM calls billed to this model. */
+    llmCalls: number;
+    /** Prompt (input) tokens. */
+    inputTokens: number;
+    /** Completion (output) tokens. */
+    outputTokens: number;
+    /** Reasoning tokens, where the provider reports them separately. */
+    reasoningTokens: number;
+    /** Input tokens served from the provider's prompt cache. */
+    cacheReadTokens: number;
+    /** Input tokens written into the provider's prompt cache. */
+    cacheWriteTokens: number;
+    /** Best-effort USD estimated from list prices at call time. */
+    estCostUsd: number;
+}
+/**
+ * One facet tree in a graph status response: the metadata field it is built from and its value leaves
+ * (most-populated first, capped — compare `values.length` against `valueCount` for truncation).
+ * @category AI
+ */
+export interface KnowledgeBaseGraphFacetStatus {
+    /** The metadata field the facet is built from. */
+    facetKey: string;
+    /** Display name of the facet root. */
+    name: string;
+    /** Total facet-value leaves (may exceed `values.length` — the list is capped). */
+    valueCount: number;
+    /** Documents carrying any value of this facet. */
+    docCount: number;
+    /** The facet's value leaves. */
+    values: Array<KnowledgeBaseGraphFacetValueStatus>;
+}
+/** One value leaf of a facet in a graph status response. @category AI */
+export interface KnowledgeBaseGraphFacetValueStatus {
+    /** Display name of the value (the most frequent raw variant). */
+    name: string;
+    /** Documents assigned to this value. */
+    docCount: number;
+    /** Raw variants consolidated into this value ("USA" under "United States"), when any. */
+    aliases?: string[];
+}
+/**
+ * How much of the knowledge base's graph a rebuild recomputes.
+ *
+ * - `'full'` — wipes the graph and re-extracts entities/relationships from every chunk with an LLM,
+ *   then rebuilds the concept layer. The expensive deep-clean: re-extraction dominates its cost.
+ * - `'structural'` — keeps the already-extracted entity graph (LLM extraction runs only for contexts
+ *   that were never graph-indexed, e.g. after an interrupted ingest) and recomputes the derived
+ *   structure on top of it: entity resolution, lexical mentions, topics and facets. Typically a small
+ *   fraction of a full rebuild's cost — the right choice for folding freshly ingested documents into
+ *   topics/facets.
+ * @category AI
+ */
+export type KnowledgeBaseGraphRebuildMode = 'full' | 'structural';
+/**
+ * Request structure for enqueuing a GraphRAG rebuild/backfill of a knowledge base.
+ * @category AI
+ */
+export interface RebuildKnowledgeBaseGraphRequest {
+    /** The id of the AiKnowledgeBase. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** What to recompute (see {@link KnowledgeBaseGraphRebuildMode}). Default `'full'`. */
+    mode?: KnowledgeBaseGraphRebuildMode;
+}
+/**
+ * Request structure for exploring a bounded subgraph of a knowledge base's graph (Phase 3 visualization).
+ * Returns the highest-degree entities and the relationships among them. Seed-based exploration
+ * (prompt/entity-name seeding + traversal depth) is a planned extension; its fields will be added
+ * here once implemented.
+ * @category AI
+ */
+export interface ExploreKnowledgeBaseGraphRequest {
+    /** The id of the AiKnowledgeBase. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Hard cap on returned nodes. Default 200, max 1000. */
+    nodeLimit?: number;
+    /**
+     * Restricts the subgraph to entities under the given topic node id — any hierarchy level; an entity
+     * matches when the topic appears anywhere in its `topicPath`. Unknown ids fail with
+     * `TOPIC_NOT_FOUND`. Ids come from {@link KnowledgeBaseGraphTopic.id} and churn on rebuild.
+     */
+    topicId?: string;
+}
+/** A node in an {@link ExploreKnowledgeBaseGraphResponse}. @category AI */
+export interface KnowledgeBaseGraphNode {
+    /** Stable node id (the entity's document id). */
+    id: string;
+    /** Canonical display name. */
+    name: string;
+    /** Entity type. */
+    type: string;
+    /** Compacted description. */
+    description: string;
+    /** Relationship degree (denormalized). */
+    degree: number;
+    /** Community id (Phase 3), when community detection has run. */
+    communityId?: string;
+    /** Level-0..k topic nodeIds (bottom-up, Layered KB Graph), when a topic rebuild has run. */
+    topicPath?: string[];
+    /** Norm-names this entity absorbed via resolution merges (present only when non-empty). */
+    aliases?: string[];
+}
+/** An edge in an {@link ExploreKnowledgeBaseGraphResponse}. @category AI */
+export interface KnowledgeBaseGraphEdge {
+    /** Source node id. */
+    source: string;
+    /** Target node id. */
+    target: string;
+    /** Relationship label. */
+    type: string;
+    /** Co-mention weight. */
+    weight: number;
+}
+/**
+ * Response structure for the bounded subgraph exploration (Phase 3 visualization).
+ * @category AI
+ */
+export interface ExploreKnowledgeBaseGraphResponse {
+    /** The subgraph nodes. */
+    nodes: Array<KnowledgeBaseGraphNode>;
+    /** The subgraph edges (outgoing only, both endpoints present in `nodes`). */
+    edges: Array<KnowledgeBaseGraphEdge>;
+    /**
+     * The KB's topic (theme) nodes — the id→name/hierarchy table for the nodes' `topicPath` ids, so a
+     * visualization can label and group by theme without extra round trips. Present when the concept
+     * layer has been built (a rebuild ran).
+     */
+    topics?: Array<KnowledgeBaseGraphTopic>;
+}
+/**
+ * A topic (theme) node of the graph's concept layer, as referenced by
+ * {@link KnowledgeBaseGraphNode.topicPath}.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphTopic {
+    /** Topic nodeId (matches `topicPath` entries). Churns on rebuild — not a persistable handle. */
+    id: string;
+    /** Topic display name. Re-resolves by name across rebuilds. */
+    name: string;
+    /** Hierarchy level: 0 = leaf tier, higher = coarser tiers. */
+    level: number;
+    /** Parent topic nodeId, when the topic sits under a coarser tier. */
+    parentId?: string;
+    /** Documents under the topic, when tracked. */
+    docCount?: number;
+}
+/**
+ * An aggregated relationship edge between two leaf topics: how many entity relationships cross
+ * between their member entities. Undirected (one entry per pair) and pruned to each topic's
+ * strongest neighbors, so weak long-tail links may be absent. Ids churn on rebuild, like
+ * {@link KnowledgeBaseGraphTopic.id}.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphTopicEdge {
+    /** One endpoint's topic nodeId. */
+    source: string;
+    /** The other endpoint's topic nodeId. */
+    target: string;
+    /** Number of entity relationships crossing between the two topics. */
+    weight: number;
+}
+/**
+ * The closed operation set of the `queryKnowledgeGraph` surface (Layered KB Graph P4). Every op is one
+ * round trip with a complete answer — no per-level walking.
+ * @category AI
+ */
+export type KnowledgeBaseGraphQueryOp = 'overview' | 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'conceptsOf' | 'neighborhood' | 'pathBetween' | 'globalSummary';
+/**
+ * Request structure for querying a knowledge base's graph (documents, entities, topics, facets) through
+ * the closed op set. `ref` accepts a facet nodeId (`facet_…` — exact; the only persistable concept
+ * handles) or a name, resolved server-side (exact → alias → similarity). An unresolvable ref fails with
+ * `CONCEPT_NOT_FOUND` plus the nearest matching names.
+ * @category AI
+ */
+export interface QueryKnowledgeBaseGraphRequest {
+    /** The id of the AiKnowledgeBase. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The operation to run. */
+    op: KnowledgeBaseGraphQueryOp;
+    /** Node ref (name or facet nodeId). Required by resolve/describe/subtree/docsUnder/neighborhood/pathBetween. */
+    ref?: string;
+    /** Second node ref for `pathBetween`. */
+    refB?: string;
+    /** The document's contextId for `conceptsOf`. */
+    contextId?: string;
+    /** The free-text question for `globalSummary` (ranks the KB's topic summaries against it). */
+    query?: string;
+    /** `subtree`: maximum depth below the resolved node. Default (and cap) 3. */
+    depth?: number;
+    /** `neighborhood`: expansion hops from the resolved entity. Default 1, max 2. */
+    hops?: number;
+    /** `docsUnder`: when true (default), include documents under the whole subtree, not just the node itself. */
+    recursive?: boolean;
+    /** `docsUnder`: maximum documents returned. Default 25, max 100 (`totalDocs` always reports the full count). */
+    limit?: number;
+}
+/** One node matched by a graph query (`resolve`, and the anchors of other ops). @category AI */
+export interface KnowledgeBaseGraphQueryMatch {
+    /** What kind of node matched. */
+    kind: 'document' | 'entity' | 'topic' | 'facetRoot' | 'facetValue';
+    /** Display name (document title, entity/topic/facet name). */
+    name: string;
+    /**
+     * Persistable handle, present only where one exists: facet nodeIds (stable across rebuilds) and
+     * document contextIds. Topic and entity refs re-resolve by name — their internal ids are omitted.
+     */
+    id?: string;
+    /** The metadata field a facet node belongs to. */
+    facetKey?: string;
+    /** Node description (may be empty for facet leaves). */
+    description?: string;
+    /** Documents under the node, where tracked (topics and facet nodes). */
+    docCount?: number;
+}
+/** A node in a `subtree` response: the resolved node with its children, recursively. @category AI */
+export interface KnowledgeBaseGraphQuerySubtreeNode {
+    /** Display name. */
+    name: string;
+    /** Persistable facet nodeId (present on facet nodes; see {@link KnowledgeBaseGraphQueryMatch.id}). */
+    id?: string;
+    /** Documents under this node. */
+    docCount?: number;
+    /** Raw variants consolidated into a facet value ("United States of America" under "United States"). */
+    aliases?: string[];
+    /** Child nodes, depth-limited by the request. */
+    children?: Array<KnowledgeBaseGraphQuerySubtreeNode>;
+}
+/** A document summary returned by `docsUnder`. @category AI */
+export interface KnowledgeBaseGraphQueryDoc {
+    /** The document's contextId (usable with `conceptsOf` and the KB context APIs). */
+    contextId: string;
+    /** Document title, when one exists. */
+    title?: string;
+    /** The document node's LLM description ('' when generation failed). */
+    description?: string;
+}
+/** A document's concept memberships (`conceptsOf`): facet paths + topics. @category AI */
+export interface KnowledgeBaseGraphQueryConcepts {
+    /** The facet values the document carries, with their persistable leaf ids. */
+    facets: Array<{
+        facetKey: string;
+        value: string;
+        id: string;
+    }>;
+    /** Names of the topics (flat themes) the document belongs to. Thematic — refs re-resolve by name. */
+    topics: Array<string>;
+}
+/**
+ * One topic (community) summary returned by the `globalSummary` op — the themes-level "global" answer
+ * content, ranked against the query. @category AI
+ */
+export interface KnowledgeBaseGraphQueryGlobalSummary {
+    /** Topic display name. Thematic — re-resolves by name across rebuilds. */
+    topic: string;
+    /** The topic's LLM-generated summary. */
+    summary: string;
+}
+/**
+ * A `pathBetween` answer. Two-tier: an entity path when one exists (explanatory — the chain of typed
+ * relationships), else concept/topic co-membership labeled `thematic` (the refs share concepts but no
+ * entity chain connects them).
+ * @category AI
+ */
+export interface KnowledgeBaseGraphQueryPath {
+    /** Which tier answered: `'entity'` (relationship chain) or `'thematic'` (shared concepts only). */
+    tier: 'entity' | 'thematic';
+    /** Entity tier: the relationship chain, in order. */
+    steps?: Array<{
+        from: string;
+        type: string;
+        to: string;
+    }>;
+    /** Thematic tier: names of concepts both refs sit under. */
+    sharedConcepts?: Array<string>;
+}
+/**
+ * Response structure for a graph query. `op` echoes the request; exactly the fields that op produces
+ * are set (e.g. `matches` for `resolve`, `tree` for `subtree`).
+ * @category AI
+ */
+export interface QueryKnowledgeBaseGraphResponse {
+    /** The operation that ran. */
+    op: KnowledgeBaseGraphQueryOp;
+    /** `overview`: the rendered knowledge-graph map (names + counts). */
+    overview?: string;
+    /** `resolve`: matching nodes across all kinds, best first. */
+    matches?: Array<KnowledgeBaseGraphQueryMatch>;
+    /** `describe`: the resolved node. */
+    node?: KnowledgeBaseGraphQueryMatch;
+    /** `describe`: ancestor names root-first (facet path / topic hierarchy), when the node has one. */
+    path?: Array<string>;
+    /** `describe`: immediate related nodes — children with counts, a document's concepts, an entity's edges. */
+    related?: Array<{
+        relation: string;
+        name: string;
+        docCount?: number;
+    }>;
+    /** `subtree`: the resolved node's subtree with doc counts. */
+    tree?: KnowledgeBaseGraphQuerySubtreeNode;
+    /** `docsUnder`: documents in the resolved node's closure (capped by `limit`). */
+    documents?: Array<KnowledgeBaseGraphQueryDoc>;
+    /** `docsUnder`: the full closure size (compare with `documents.length` for truncation). */
+    totalDocs?: number;
+    /** `conceptsOf`: the document's concept memberships. */
+    concepts?: KnowledgeBaseGraphQueryConcepts;
+    /** `neighborhood`: the entity subgraph around the resolved entity. */
+    graph?: ExploreKnowledgeBaseGraphResponse;
+    /** `pathBetween`: the two-tier path answer; absent when the refs are entirely unconnected. */
+    pathBetween?: KnowledgeBaseGraphQueryPath;
+    /** `globalSummary`: the KB's topic summaries ranked against the query, most relevant first. */
+    summaries?: Array<KnowledgeBaseGraphQueryGlobalSummary>;
+}