/**
 * ThinkHive SDK v3.1 - Quality Metrics API
 *
 * RAG Evaluation & Hallucination Detection for AI quality assurance
 */
/**
 * Retrieved context for RAG evaluation
 */
export interface RetrievedContext {
    content: string;
    chunkIndex?: number;
    metadata?: Record<string, unknown>;
    score?: number;
}
/**
 * Ground truth context
 */
export interface GroundTruthContext {
    content: string;
    chunkIndex?: number;
}
/**
 * Grounded span evidence
 */
export interface GroundedSpan {
    text: string;
    confidence: number;
    sourceChunkIndex?: number;
}
/**
 * Ungrounded span evidence
 */
export interface UngroundedSpan {
    text: string;
    confidence: number;
}
/**
 * Citation mapping
 */
export interface CitationMap {
    claim: string;
    citedIndex: number;
    isValid: boolean;
}
/**
 * RAG evaluation result
 */
export interface RAGEvaluation {
    contextRelevance: number;
    contextPrecision: number;
    contextRecall: number;
    groundedness: number;
    faithfulness: number;
    answerRelevance: number;
    citationAccuracy: number;
    citationCompleteness: number;
    overallScore: number;
    grade: 'A' | 'B' | 'C' | 'D' | 'F';
    groundedSpanCount?: number;
    ungroundedSpanCount?: number;
    issues: string[];
    recommendations: string[];
}
/**
 * RAG evaluation evidence
 */
export interface RAGEvidence {
    groundedSpans: GroundedSpan[];
    ungroundedSpans: UngroundedSpan[];
    citationMap: CitationMap[];
}
/**
 * Hallucination instance
 */
export interface HallucinationInstance {
    type: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
    text: string;
    explanation: string;
    confidence: number;
    suggestedFix?: string;
}
/**
 * Hallucination detection report
 */
export interface HallucinationReport {
    hasHallucinations: boolean;
    hallucinationScore: number;
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    factualClaims: number;
    verifiedClaims: number;
    unverifiedClaims: number;
    summary: string;
    recommendations: string[];
    instances: HallucinationInstance[];
}
/**
 * Groundedness analysis result
 */
export interface GroundednessResult {
    score: number;
    faithfulness: number;
    contextRelevance: number;
    grade: string;
}
/**
 * Batch evaluation result for a single trace
 */
export interface BatchEvaluationResult {
    traceId: string;
    success: boolean;
    error?: string;
    rag?: {
        score: number;
        grade: string;
        mainIssue?: string;
    };
    hallucination?: {
        hasIssues: boolean;
        score: number;
        topIssue?: string;
    };
}
/**
 * Batch evaluation summary
 */
export interface BatchEvaluationSummary {
    totalTraces: number;
    successfulEvaluations: number;
    avgRagScore: number;
    hallucinationRate: number;
    gradeDistribution: {
        A: number;
        B: number;
        C: number;
        D: number;
        F: number;
    };
}
/**
 * Quality Metrics API client for RAG evaluation and hallucination detection
 */
export declare const qualityMetrics: {
    /**
     * Get RAG quality scores for a specific trace
     *
     * @example
     * ```typescript
     * const scores = await qualityMetrics.getRagScores('trace_abc123');
     * console.log(`Groundedness: ${scores.evaluation.groundedness}`);
     * console.log(`Grade: ${scores.evaluation.grade}`);
     * ```
     */
    getRagScores(traceId: string): Promise<{
        traceId: string;
        evaluation: RAGEvaluation;
        evidence: RAGEvidence;
    }>;
    /**
     * Get hallucination detection report for a trace
     *
     * @example
     * ```typescript
     * const report = await qualityMetrics.getHallucinationReport('trace_abc123');
     * if (report.report.hasHallucinations) {
     *   console.log(`Risk level: ${report.report.riskLevel}`);
     *   for (const instance of report.report.instances) {
     *     console.log(`- ${instance.type}: ${instance.text}`);
     *   }
     * }
     * ```
     */
    getHallucinationReport(traceId: string): Promise<{
        traceId: string;
        report: HallucinationReport;
    }>;
    /**
     * Evaluate RAG quality for provided content (ad-hoc evaluation)
     *
     * @example
     * ```typescript
     * const result = await qualityMetrics.evaluateRag({
     *   query: 'What is the refund policy?',
     *   response: 'You can get a refund within 30 days.',
     *   retrievedContexts: [
     *     { content: 'Our refund policy allows returns within 30 days of purchase.' },
     *   ],
     * });
     * console.log(`Groundedness: ${result.evaluation.groundedness}`);
     * ```
     */
    evaluateRag(input: {
        query: string;
        response: string;
        retrievedContexts: RetrievedContext[];
        groundTruthContexts?: GroundTruthContext[];
        citations?: string[];
    }): Promise<{
        evaluation: RAGEvaluation;
        evidence: RAGEvidence;
    }>;
    /**
     * Detect hallucinations in provided content (ad-hoc detection)
     *
     * @example
     * ```typescript
     * const result = await qualityMetrics.detectHallucinations({
     *   response: 'The product costs $99 and comes with a 2-year warranty.',
     *   contexts: [
     *     { content: 'The product costs $99 with a 1-year warranty.' },
     *   ],
     * });
     * if (result.report.hasHallucinations) {
     *   console.log('Detected hallucinations:', result.report.instances);
     * }
     * ```
     */
    detectHallucinations(input: {
        response: string;
        contexts: Array<{
            content: string;
            metadata?: Record<string, unknown>;
        }>;
        query?: string;
        previousResponses?: string[];
    }): Promise<{
        report: HallucinationReport;
    }>;
    /**
     * Get groundedness analysis for a trace
     *
     * @example
     * ```typescript
     * const result = await qualityMetrics.getGroundedness('trace_abc123');
     * console.log(`Groundedness score: ${result.groundedness.score}`);
     * console.log(`Grounded spans: ${result.summary.groundedSpans}`);
     * ```
     */
    getGroundedness(traceId: string): Promise<{
        traceId: string;
        groundedness: GroundednessResult;
        spans: {
            grounded: Array<{
                text: string;
                confidence: number;
                sourceIndex: number;
            }>;
            ungrounded: Array<{
                text: string;
                confidence: number;
            }>;
        };
        summary: {
            totalSpans: number;
            groundedSpans: number;
            ungroundedSpans: number;
            groundednessRatio: number;
        };
    }>;
    /**
     * Evaluate multiple traces for quality metrics in batch
     *
     * @example
     * ```typescript
     * const result = await qualityMetrics.evaluateBatch({
     *   traceIds: ['trace_1', 'trace_2', 'trace_3'],
     * });
     * console.log(`Average RAG score: ${result.summary.avgRagScore}`);
     * console.log(`Hallucination rate: ${result.summary.hallucinationRate}%`);
     * ```
     */
    evaluateBatch(options: {
        traceIds: string[];
        includeDetails?: boolean;
    }): Promise<{
        summary: BatchEvaluationSummary;
        results: BatchEvaluationResult[];
    }>;
    /** Alias for evaluateRag() */
    evaluate(input: {
        query: string;
        response: string;
        retrievedContexts: RetrievedContext[];
        groundTruthContexts?: GroundTruthContext[];
        citations?: string[];
    }): Promise<{
        evaluation: RAGEvaluation;
        evidence: RAGEvidence;
    }>;
};
/**
 * Check if a RAG evaluation passes quality thresholds
 */
export declare function passesQualityThreshold(evaluation: RAGEvaluation, thresholds?: {
    minGroundedness?: number;
    minOverallScore?: number;
    minGrade?: 'A' | 'B' | 'C' | 'D';
}): boolean;
/**
 * Check if hallucination risk is acceptable
 */
export declare function isHallucinationRiskAcceptable(report: HallucinationReport, maxRiskLevel?: 'low' | 'medium' | 'high'): boolean;
/**
 * Get quality recommendations based on evaluation
 */
export declare function getQualityRecommendations(ragEval: RAGEvaluation, hallucinationReport?: HallucinationReport): string[];
/**
 * Format quality score for display
 */
export declare function formatQualityScore(score: number): string;
/**
 * Get color indicator for grade
 */
export declare function getGradeColor(grade: 'A' | 'B' | 'C' | 'D' | 'F'): 'green' | 'blue' | 'yellow' | 'orange' | 'red';