/**
 * intelligent-assistant - eight retrieval operations over a document corpus the
 * caller supplies.
 *
 * WHAT THIS FILE REPLACES: the tool advertised the eight operations below and
 * served every one of them from a single body that read none of its arguments:
 *
 *     data = { result: "<the operation name> completed successfully" }
 *     return { success: true, data, metadata: { confidence: 0.85, ... } }
 *
 * (written here in quotes rather than as the template literal it was, so the
 * ratchet that detects that stub body by its text does not read this comment as
 * one.)
 *
 * An `ask` that answers "ask completed successfully" with a confidence of 0.85
 * is worse than one that refuses, because nothing in the shape of the response
 * tells the caller which of the two they got.
 *
 * WHAT "INTELLIGENT" MEANS HERE, since the name invites the wrong expectation:
 * this package has no model and makes no inference. Every answer is a sentence
 * QUOTED from a document the caller passed in, carrying the id of that document
 * and the terms that selected it, and the ranking is the published idf cosine
 * in `knowledge-core.ts`. Nothing is generated. `ask` with a question the
 * corpus has nothing on reports that, and names the terms it could not find,
 * rather than returning the best of a bad list.
 *
 * WHAT IS NOT CLAIMED: no operation returns a confidence. A score is the cosine
 * defined in `knowledge-core.ts` -- comparable within one corpus and meaningless
 * across two -- and `troubleshoot` names the shallow verb rule it used to pick
 * out a remedy rather than implying it understood the text.
 *
 * `learn` writes into the same cache as every other result, so it reports
 * `durability: "cache"` and `evictable: true`, and every operation that reads
 * the store reports how many documents came from it. A store that lost its
 * contents must not look like a corpus that never had them.
 */
import type { CacheEngine } from '../../core/cache-engine.js';
import type { TokenCounter } from '../../core/token-counter.js';
import type { MetricsCollector } from '../../core/metrics.js';
import type { JsonSchemaNode } from '../../validation/schema-from-definition.js';
import { type KnowledgeDocument } from './knowledge-core.js';
/**
 * The operations, in one place: the TS union and the published enum are both
 * derived from this tuple, so the two cannot drift apart.
 */
export declare const INTELLIGENT_ASSISTANT_OPERATIONS: readonly ["ask", "suggest", "explain", "troubleshoot", "learn", "get-context", "search-knowledge", "generate-example"];
export type IntelligentAssistantOperation = (typeof INTELLIGENT_ASSISTANT_OPERATIONS)[number];
/** What `learn` did with one incoming document. */
export declare enum StoreOutcome {
    Added = "added",
    Replaced = "replaced",
    Duplicate = "duplicate",
    Conflicting = "conflicting"
}
/** What `learn` does when a stored document and an incoming one disagree. */
export declare enum ConflictPolicy {
    KeepStored = "keep-stored",
    Replace = "replace"
}
/** Why a document did not make it into a result. */
export declare enum ExclusionReason {
    NoSharedTerm = "no-shared-term",
    AlreadySeen = "already-seen",
    OverBudget = "over-budget"
}
/** Why `ask` could not quote an answer. */
export declare enum UnansweredReason {
    NoSharedTerm = "no-document-shares-a-term-with-the-question",
    BelowFloor = "no-document-scored-above-the-floor",
    TitleOnly = "the-question-matched-only-titles-so-no-sentence-could-be-quoted"
}
/** Where the documents a result was computed from came from. */
export interface CorpusReport {
    documents: number;
    fromCall: number;
    fromStore: number;
    topic: string | null;
    durability: 'cache' | 'call';
    evictable: boolean;
}
export declare const INTELLIGENT_ASSISTANT_DEFAULTS: Readonly<{
    limit: 5;
    /**
     * Exclusive: a document must share at least one term to appear at all. There
     * is no magic relevance threshold here, because any constant would be one --
     * the score is reported and the caller raises `floor` if they want more.
     */
    floor: 0;
    onConflict: ConflictPolicy.KeepStored;
}>;
export interface IntelligentAssistantOptions {
    operation: IntelligentAssistantOperation;
    /** ask, search-knowledge, troubleshoot, get-context. */
    question?: string;
    /** explain, suggest; also the store key for learn and every corpus read. */
    topic?: string;
    documents?: readonly KnowledgeDocument[];
    /** suggest: ids the caller has already consumed. */
    seen?: readonly string[];
    /** get-context: the token budget, measured with this package's counter. */
    budget?: number;
    /** generate-example: the JSON Schema node to construct a value for. */
    schema?: JsonSchemaNode;
    limit?: number;
    floor?: number;
    onConflict?: ConflictPolicy;
    useCache?: boolean;
}
export interface IntelligentAssistantResult {
    success: boolean;
    operation: IntelligentAssistantOperation;
    data: Record<string, unknown>;
    metadata: {
        tokensUsed: number;
        tokensSaved: number;
        cacheHit: boolean;
        processingTime: number;
    };
}
export declare class IntelligentAssistant {
    private cache;
    private tokenCounter;
    private metricsCollector;
    constructor(cache: CacheEngine, tokenCounter: TokenCounter, metricsCollector: MetricsCollector);
    run(options: IntelligentAssistantOptions): Promise<IntelligentAssistantResult>;
    /**
     * One branch per published operation. No fall-through: a value added to the
     * published enum without an implementation here reaches the default and is
     * refused rather than quietly served by a neighbour.
     */
    private compute;
    private storeKey;
    /** The documents `learn` stored under a topic, or none. */
    private readStore;
    /**
     * A short stamp of the store's contents for the result cache key. The whole
     * stored text would work too; the count and total length are enough to
     * notice every write this tool can make, because a write that changes
     * neither is a no-op by construction.
     */
    private storeStamp;
    /**
     * The corpus for one call: the documents passed in, plus anything `learn`
     * stored under the same topic. A document passed in wins over a stored one
     * with the same id, and the counts are reported so a caller can see which
     * half an answer came from.
     */
    private resolveCorpus;
    private searchKnowledge;
    private ask;
    private explain;
    private suggest;
    private troubleshoot;
    private learn;
    private getContext;
    private generateExample;
}
export declare const INTELLIGENTASSISTANTTOOL: {
    readonly name: "intelligent-assistant";
    readonly description: string;
    readonly inputSchema: {
        readonly type: "object";
        readonly properties: {
            readonly operation: {
                readonly type: "string";
                readonly enum: readonly ["ask", "suggest", "explain", "troubleshoot", "learn", "get-context", "search-knowledge", "generate-example"];
                readonly description: "The operation to perform";
            };
            readonly question: {
                readonly type: "string";
                readonly minLength: 1;
                readonly maxLength: 2000;
                readonly description: string;
            };
            readonly topic: {
                readonly type: "string";
                readonly minLength: 1;
                readonly maxLength: 200;
                readonly description: string;
            };
            readonly documents: {
                readonly type: "array";
                readonly description: "The corpus to answer from";
                readonly items: {
                    readonly type: "object";
                    readonly properties: {
                        readonly id: {
                            readonly type: "string";
                            readonly minLength: 1;
                            readonly maxLength: 200;
                        };
                        readonly title: {
                            readonly type: "string";
                            readonly maxLength: 500;
                        };
                        readonly text: {
                            readonly type: "string";
                            readonly minLength: 1;
                        };
                        readonly tags: {
                            readonly type: "array";
                            readonly items: {
                                readonly type: "string";
                            };
                        };
                    };
                    readonly required: readonly ["id", "text"];
                    readonly additionalProperties: false;
                };
            };
            readonly seen: {
                readonly type: "array";
                readonly items: {
                    readonly type: "string";
                    readonly minLength: 1;
                };
                readonly description: "suggest: document ids to leave out of the suggestions";
            };
            readonly budget: {
                readonly type: "integer";
                readonly minimum: 1;
                readonly description: "get-context: the token budget, measured with this package counter";
            };
            readonly schema: {
                readonly type: "object";
                readonly description: "generate-example: the JSON Schema node to construct a value for";
            };
            readonly limit: {
                readonly type: "integer";
                readonly minimum: 1;
                readonly default: 5;
                readonly description: "How many documents to return";
            };
            readonly floor: {
                readonly type: "number";
                readonly minimum: 0;
                readonly maximum: 1;
                readonly default: 0;
                readonly description: "Exclusive minimum score; scores are cosines, so this is in [0, 1]";
            };
            readonly onConflict: {
                readonly type: "string";
                readonly enum: readonly [ConflictPolicy.KeepStored, ConflictPolicy.Replace];
                readonly default: ConflictPolicy.KeepStored;
                readonly description: string;
            };
            readonly useCache: {
                readonly type: "boolean";
                readonly default: true;
            };
        };
        readonly required: readonly ["operation"];
        readonly anyOf: readonly [{
            readonly properties: {
                readonly operation: {
                    readonly const: "ask";
                };
            };
            readonly required: readonly ["operation", "question", "documents"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "ask";
                };
            };
            readonly required: readonly ["operation", "question", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "search-knowledge";
                };
            };
            readonly required: readonly ["operation", "question", "documents"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "search-knowledge";
                };
            };
            readonly required: readonly ["operation", "question", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "troubleshoot";
                };
            };
            readonly required: readonly ["operation", "question", "documents"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "troubleshoot";
                };
            };
            readonly required: readonly ["operation", "question", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "get-context";
                };
            };
            readonly required: readonly ["operation", "question", "budget", "documents"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "get-context";
                };
            };
            readonly required: readonly ["operation", "question", "budget", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "explain";
                };
            };
            readonly required: readonly ["operation", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "suggest";
                };
            };
            readonly required: readonly ["operation", "topic"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "learn";
                };
            };
            readonly required: readonly ["operation", "topic", "documents"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "generate-example";
                };
            };
            readonly required: readonly ["operation", "schema"];
        }];
    };
};
export declare function runIntelligentAssistant(options: IntelligentAssistantOptions): Promise<IntelligentAssistantResult>;
//# sourceMappingURL=intelligent-assistant.d.ts.map