/**
 * @fileoverview GKG theme lookup: downloads GDELT's theme lookup file on first use, holds the
 * parsed index for the life of the process, and matches query words against theme identifiers.
 * The file lives on data.gdeltproject.org rather than the DOC/TV API host, so its one request
 * does not queue behind the API pacer.
 * @module services/gdelt/gdelt-theme-service
 */
import type { Context } from '@cyanheads/mcp-ts-core';
/** GDELT's GKG theme lookup — the list the DOC 2.0 documentation links for the `theme:` operator. */
export declare const GKG_THEMES_URL = "https://data.gdeltproject.org/api/v2/guides/LOOKUP-GKGTHEMES.TXT";
/** A theme identifier and the count the lookup lists for it. */
export type ThemeMatch = {
    readonly theme: string;
    readonly count: number;
};
/** Matches for a query, and the singular words retried when the query as given matched nothing. */
export type ThemeSearchResult = {
    /** Ranked matches: the exact identifier first, then count descending, then identifier. */
    matches: readonly ThemeMatch[];
    /** Set when the plural fallback ran — the words it retried, whether or not they matched. */
    singularWords?: string[];
};
/**
 * The query's search words: a leading `theme:` dropped, lowercased, split on every run of
 * characters other than `a–z`/`0–9`, deduplicated. Empty when the query has no letter or digit.
 */
export declare function themeQueryWords(query: string): string[];
export declare class GdeltThemeService {
    private readonly timeoutMs;
    /** The one load in flight or finished. Reset on failure so the next call fetches again. */
    private index;
    constructor(timeoutMs: number);
    /**
     * Match `query` against every theme identifier. A theme matches when each query word is a
     * prefix of one of its tokens or of consecutive tokens joined, or when all the words joined
     * are. When nothing matches, the search retries once with a trailing `s` dropped from each
     * word of four or more characters. The query must have at least one word — callers reject an
     * empty {@link themeQueryWords} first, since no words would match every theme.
     */
    search(query: string, ctx: Context): Promise<ThemeSearchResult>;
    /** The parsed index, loading it on first use. Concurrent first calls share the one load. */
    private load;
    /**
     * Download and parse the lookup. Every failure — an HTTP error status (a 404 included, which
     * would otherwise read as "no such theme"), a network error, a timeout, or a body that is not
     * `THEME<TAB>count` lines — surfaces as the retryable `gdelt_unavailable`.
     */
    private fetchIndex;
}
export declare function initGdeltThemeService(timeoutMs: number): void;
export declare function getGdeltThemeService(): GdeltThemeService;
//# sourceMappingURL=gdelt-theme-service.d.ts.map