@nice-tools/fake-llm 1.3.0

package/dist/browser.d.mts

@@ -0,0 +1,349 @@
+/**
+ * Runtime connection configuration (passed at agent creation, NOT in config files)
+ */
+interface AdapterConnections {
+    cosmos?: {
+        endpoint: string;
+        key: string;
+    };
+    blob?: {
+        connectionString?: string;
+        sasToken?: string;
+        accountKey?: string;
+    };
+    gcs?: {
+        projectId: string;
+        keyFilePath: string;
+    };
+    mockCosmos?: {
+        basePath: string;
+    };
+    fallbackLLM?: {
+        enabled: boolean;
+        endpoint: string;
+        apiKey: string;
+        model: string;
+    };
+}
+/**
+ * Describes where configuration files are stored
+ */
+interface ConfigSource {
+    type: 'local' | 'blob' | 'cosmos' | 'gcs';
+    location: {
+        container?: string;
+        databaseId?: string;
+        bucket?: string;
+        path?: string;
+    };
+}
+/**
+ * A keyword defines a domain concept (e.g., "habit", "skill", "moral")
+ */
+interface KeywordEntry {
+    keyword: string;
+    aliases: string[];
+    category: string;
+    data_source: string;
+    source_kind?: 'cosmos' | 'blob' | 'logs' | 'static';
+    schema?: Record<string, string>;
+}
+interface StoryContract {
+    source_kind: 'cosmos' | 'blob' | 'logs' | 'cross-source';
+    sources: string[];
+    patterns?: string[];
+    query_examples?: string[];
+    notes?: string;
+}
+/**
+ * A story defines how keywords relate and how to resolve queries
+ */
+interface Story {
+    story_id: string;
+    description: string;
+    keywords: string[];
+    relations: Relation[];
+    resolution_steps: ResolutionStep[];
+    contract?: StoryContract;
+}
+interface Relation {
+    from_keyword: string;
+    to_keyword: string;
+    cardinality: 'one-to-one' | 'one-to-many' | 'many-to-many';
+    join_via?: string;
+}
+interface ResolutionStep {
+    step: number;
+    action: 'fetch' | 'filter' | 'enrich' | 'compare' | 'diff';
+    keyword?: string;
+    from_source?: string;
+    on?: string;
+    left?: string;
+    right?: string;
+}
+/**
+ * Parsed user intent from NLP
+ */
+interface Intent {
+    action: 'list' | 'find' | 'compare' | 'diff' | 'explain';
+    keywords: string[];
+    filters: Record<string, any>;
+    confidence: number;
+}
+interface QueryParams {
+    source: string;
+    filters?: Record<string, any>;
+    limit?: number;
+    orderBy?: string;
+}
+interface AnswerDebugStep {
+    step: number;
+    action: string;
+    source?: string;
+    queryParams?: QueryParams;
+    builtFilter?: string;
+    generatedQuery?: string;
+    searchPattern?: string;
+    rowsReturned: number;
+    sampleRows: any[];
+}
+interface AnswerDebug {
+    rawQuery: string;
+    intent: Intent;
+    resolvedKeywords: KeywordEntry[];
+    unresolvedTerms: string[];
+    storyCandidates: Array<{
+        storyId: string;
+        score: number;
+        matchedKeywords: string[];
+        storyKeywords: string[];
+    }>;
+    selectedStory?: {
+        storyId: string;
+        score: number;
+    };
+    threshold: number;
+    decision: 'matched-story' | 'no-story-fallback-llm' | 'no-story-no-results' | 'fallback-llm-error';
+    steps: AnswerDebugStep[];
+    totals: {
+        results: number;
+        durationMs: number;
+    };
+}
+/**
+ * Resolved answer from the engine
+ */
+interface Answer {
+    intent: Intent;
+    story?: Story;
+    results: any[];
+    summary: string;
+    metadata: {
+        execution_time_ms: number;
+        source: 'mock-llm' | 'fallback-llm';
+    };
+    debug?: AnswerDebug;
+}
+
+/**
+ * Base adapter interface for data sources
+ */
+interface IDataAdapter {
+    query(params: QueryParams): Promise<any[]>;
+    getById(id: string): Promise<any>;
+}
+
+declare abstract class BaseAdapter implements IDataAdapter {
+    abstract query(params: QueryParams): Promise<any[]>;
+    abstract getById(id: string): Promise<any>;
+    protected buildWhereClause(filters: Record<string, any>): string;
+}
+
+declare class NLPMatcher {
+    parseQuery(query: string): Intent;
+    private extractAction;
+    private extractKeywords;
+    private extractFilters;
+}
+
+declare class KeywordResolver {
+    private keywords;
+    constructor(keywords: KeywordEntry[]);
+    resolve(term: string): KeywordEntry | undefined;
+    /**
+     * Resolves a list of NLP-extracted terms AND also checks the full original query
+     * against all keyword aliases (to handle multi-word alias phrases).
+     */
+    resolveAll(terms: string[], fullQuery?: string): KeywordEntry[];
+    getRelatedKeywords(keyword: KeywordEntry): KeywordEntry[];
+}
+
+interface StoryMatch {
+    story: Story;
+    score: number;
+    matchedKeywords: string[];
+}
+interface StoryScore {
+    storyId: string;
+    score: number;
+    matchedKeywords: string[];
+    storyKeywords: string[];
+}
+declare const STORY_THRESHOLD = 0.1;
+declare class StoryResolver {
+    private stories;
+    constructor(stories: Story[]);
+    scoreAll(intent: Intent, resolvedKeywords: KeywordEntry[]): StoryScore[];
+    findBestStory(intent: Intent, resolvedKeywords: KeywordEntry[]): StoryMatch | undefined;
+    private scoreStory;
+}
+
+declare class QueryBuilder {
+    buildQuery(step: ResolutionStep, intent: Intent): QueryParams;
+    buildQueryPreview(step: ResolutionStep, intent: Intent, resolvedKeywords?: string[]): {
+        generatedQuery: string;
+        searchPattern: string;
+    };
+    buildSQLWhere(filters: Record<string, any>): string;
+}
+
+declare class ResponseBuilder {
+    buildAnswer(intent: Intent, story: Story | undefined, results: any[], executionTime: number, source: 'mock-llm' | 'fallback-llm'): Answer;
+    private buildSummary;
+}
+
+interface FetchConfigLoaderOptions {
+    /** URL to a pre-aggregated JSON array of all keyword entries, e.g. '/data/keywords.json' */
+    keywordsUrl: string;
+    /** URL to a pre-aggregated JSON array of all story definitions, e.g. '/data/stories.json' */
+    storiesUrl: string;
+}
+/**
+ * Isomorphic config loader that fetches keyword and story definitions from
+ * pre-aggregated JSON files via `fetch()`.
+ *
+ * Works in both browser and Node.js (≥ 18) environments with no file-system
+ * dependencies. Intended for use with `BrowserMockLLM` and static hosting
+ * (e.g. GitHub Pages, CDN, or any HTTP server that can serve JSON files).
+ *
+ * The expected JSON format for each URL is either:
+ *   - An array: `[{ keyword: "sky", ... }, ...]`
+ *   - A single object: `{ keyword: "sky", ... }` (wrapped into a one-element array)
+ */
+declare class FetchConfigLoader {
+    private options;
+    constructor(options: FetchConfigLoaderOptions);
+    loadKeywords(): Promise<KeywordEntry[]>;
+    loadStories(): Promise<Story[]>;
+}
+
+interface HttpMockAdapterOptions {
+    /**
+     * Base URL for all data-source JSON files, e.g. `'https://example.com/data'`
+     * or `'/data'` for a relative path on the same origin.
+     *
+     * A query for `source: 'knowledge/science'` fetches
+     * `{baseUrl}/knowledge/science.json`.
+     */
+    baseUrl: string;
+}
+/**
+ * Isomorphic data adapter that retrieves pre-aggregated JSON from a static
+ * HTTP endpoint via `fetch()`.
+ *
+ * Works in both browser and Node.js (≥ 18) environments with no file-system
+ * dependencies. Intended for use with `BrowserMockLLM` and static hosting
+ * (e.g. GitHub Pages, CDN, or any HTTP server that can serve JSON files).
+ *
+ * Filtering and limiting are applied client-side after fetching the full
+ * collection, matching the behaviour of `MockCosmosAdapter`.
+ */
+declare class HttpMockAdapter extends BaseAdapter {
+    private options;
+    constructor(options: HttpMockAdapterOptions);
+    query(params: QueryParams): Promise<any[]>;
+    getById(_id: string): Promise<any>;
+    private matchesFilters;
+    private getNestedValue;
+}
+
+interface QueryOptions {
+    debug?: boolean;
+}
+interface FallbackLLMConfig {
+    enabled: boolean;
+    endpoint: string;
+    apiKey: string;
+    model: string;
+}
+/**
+ * Isomorphic query engine — works in both Node.js and browser environments.
+ *
+ * Constructed with already-loaded keywords, stories, a data adapter, and an
+ * optional fallback-LLM config. Both `MockLLM` (server) and `BrowserMockLLM`
+ * (browser) delegate all query logic to this class.
+ */
+declare class MockLLMEngine {
+    private keywords;
+    private stories;
+    private adapter;
+    private fallbackLLM?;
+    private nlpMatcher;
+    private keywordResolver;
+    private storyResolver;
+    private queryBuilder;
+    private responseBuilder;
+    constructor(keywords: KeywordEntry[], stories: Story[], adapter: BaseAdapter, fallbackLLM?: FallbackLLMConfig | undefined);
+    getKeywords(): KeywordEntry[];
+    getStories(): Story[];
+    listDataSources(): string[];
+    getDataSourceSnapshot(source: string, limit?: number): Promise<any[]>;
+    query(userQuery: string, opts?: QueryOptions): Promise<Answer>;
+    private queryFallbackLLM;
+}
+
+interface BrowserMockLLMOptions {
+    /** URL to a pre-aggregated JSON array of all keyword entries, e.g. '/data/keywords.json' */
+    keywordsUrl: string;
+    /** URL to a pre-aggregated JSON array of all story definitions, e.g. '/data/stories.json' */
+    storiesUrl: string;
+    /**
+     * Base URL for data-source JSON files. A query for `source: 'knowledge/science'`
+     * fetches `{dataBaseUrl}/knowledge/science.json`.
+     */
+    dataBaseUrl: string;
+    fallbackLLM?: FallbackLLMConfig;
+}
+/**
+ * Browser-safe orchestrator for the mock-LLM engine.
+ *
+ * Loads configuration and data via `fetch()` with no file-system dependencies.
+ * Import from `@nice-tools/mock-llm/browser` to keep bundlers from pulling in
+ * Node.js-only modules (`fs`, `path`, `@google-cloud/storage`, etc.).
+ *
+ * @example
+ * ```ts
+ * import { BrowserMockLLM } from '@nice-tools/mock-llm/browser';
+ *
+ * const llm = new BrowserMockLLM({
+ *   keywordsUrl: '/data/keywords.json',
+ *   storiesUrl:  '/data/stories.json',
+ *   dataBaseUrl: '/data',
+ * });
+ * await llm.initialize();
+ * const answer = await llm.query('what is the color of sky');
+ * ```
+ */
+declare class BrowserMockLLM {
+    private options;
+    private engine;
+    constructor(options: BrowserMockLLMOptions);
+    initialize(): Promise<void>;
+    getKeywords(): KeywordEntry[];
+    getStories(): Story[];
+    listDataSources(): string[];
+    getDataSourceSnapshot(source: string, limit?: number): Promise<any[]>;
+    query(userQuery: string, opts?: QueryOptions): Promise<Answer>;
+}
+
+export { type AdapterConnections, type Answer, type AnswerDebug, type AnswerDebugStep, BaseAdapter, BrowserMockLLM, type BrowserMockLLMOptions, type ConfigSource, type FallbackLLMConfig, FetchConfigLoader, type FetchConfigLoaderOptions, HttpMockAdapter, type HttpMockAdapterOptions, type IDataAdapter, type Intent, type KeywordEntry, KeywordResolver, MockLLMEngine, NLPMatcher, QueryBuilder, type QueryOptions, type QueryParams, type Relation, type ResolutionStep, ResponseBuilder, STORY_THRESHOLD, type Story, type StoryContract, type StoryMatch, StoryResolver, type StoryScore };

package/dist/browser.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Runtime connection configuration (passed at agent creation, NOT in config files)
+ */
+interface AdapterConnections {
+    cosmos?: {
+        endpoint: string;
+        key: string;
+    };
+    blob?: {
+        connectionString?: string;
+        sasToken?: string;
+        accountKey?: string;
+    };
+    gcs?: {
+        projectId: string;
+        keyFilePath: string;
+    };
+    mockCosmos?: {
+        basePath: string;
+    };
+    fallbackLLM?: {
+        enabled: boolean;
+        endpoint: string;
+        apiKey: string;
+        model: string;
+    };
+}
+/**
+ * Describes where configuration files are stored
+ */
+interface ConfigSource {
+    type: 'local' | 'blob' | 'cosmos' | 'gcs';
+    location: {
+        container?: string;
+        databaseId?: string;
+        bucket?: string;
+        path?: string;
+    };
+}
+/**
+ * A keyword defines a domain concept (e.g., "habit", "skill", "moral")
+ */
+interface KeywordEntry {
+    keyword: string;
+    aliases: string[];
+    category: string;
+    data_source: string;
+    source_kind?: 'cosmos' | 'blob' | 'logs' | 'static';
+    schema?: Record<string, string>;
+}
+interface StoryContract {
+    source_kind: 'cosmos' | 'blob' | 'logs' | 'cross-source';
+    sources: string[];
+    patterns?: string[];
+    query_examples?: string[];
+    notes?: string;
+}
+/**
+ * A story defines how keywords relate and how to resolve queries
+ */
+interface Story {
+    story_id: string;
+    description: string;
+    keywords: string[];
+    relations: Relation[];
+    resolution_steps: ResolutionStep[];
+    contract?: StoryContract;
+}
+interface Relation {
+    from_keyword: string;
+    to_keyword: string;
+    cardinality: 'one-to-one' | 'one-to-many' | 'many-to-many';
+    join_via?: string;
+}
+interface ResolutionStep {
+    step: number;
+    action: 'fetch' | 'filter' | 'enrich' | 'compare' | 'diff';
+    keyword?: string;
+    from_source?: string;
+    on?: string;
+    left?: string;
+    right?: string;
+}
+/**
+ * Parsed user intent from NLP
+ */
+interface Intent {
+    action: 'list' | 'find' | 'compare' | 'diff' | 'explain';
+    keywords: string[];
+    filters: Record<string, any>;
+    confidence: number;
+}
+interface QueryParams {
+    source: string;
+    filters?: Record<string, any>;
+    limit?: number;
+    orderBy?: string;
+}
+interface AnswerDebugStep {
+    step: number;
+    action: string;
+    source?: string;
+    queryParams?: QueryParams;
+    builtFilter?: string;
+    generatedQuery?: string;
+    searchPattern?: string;
+    rowsReturned: number;
+    sampleRows: any[];
+}
+interface AnswerDebug {
+    rawQuery: string;
+    intent: Intent;
+    resolvedKeywords: KeywordEntry[];
+    unresolvedTerms: string[];
+    storyCandidates: Array<{
+        storyId: string;
+        score: number;
+        matchedKeywords: string[];
+        storyKeywords: string[];
+    }>;
+    selectedStory?: {
+        storyId: string;
+        score: number;
+    };
+    threshold: number;
+    decision: 'matched-story' | 'no-story-fallback-llm' | 'no-story-no-results' | 'fallback-llm-error';
+    steps: AnswerDebugStep[];
+    totals: {
+        results: number;
+        durationMs: number;
+    };
+}
+/**
+ * Resolved answer from the engine
+ */
+interface Answer {
+    intent: Intent;
+    story?: Story;
+    results: any[];
+    summary: string;
+    metadata: {
+        execution_time_ms: number;
+        source: 'mock-llm' | 'fallback-llm';
+    };
+    debug?: AnswerDebug;
+}
+
+/**
+ * Base adapter interface for data sources
+ */
+interface IDataAdapter {
+    query(params: QueryParams): Promise<any[]>;
+    getById(id: string): Promise<any>;
+}
+
+declare abstract class BaseAdapter implements IDataAdapter {
+    abstract query(params: QueryParams): Promise<any[]>;
+    abstract getById(id: string): Promise<any>;
+    protected buildWhereClause(filters: Record<string, any>): string;
+}
+
+declare class NLPMatcher {
+    parseQuery(query: string): Intent;
+    private extractAction;
+    private extractKeywords;
+    private extractFilters;
+}
+
+declare class KeywordResolver {
+    private keywords;
+    constructor(keywords: KeywordEntry[]);
+    resolve(term: string): KeywordEntry | undefined;
+    /**
+     * Resolves a list of NLP-extracted terms AND also checks the full original query
+     * against all keyword aliases (to handle multi-word alias phrases).
+     */
+    resolveAll(terms: string[], fullQuery?: string): KeywordEntry[];
+    getRelatedKeywords(keyword: KeywordEntry): KeywordEntry[];
+}
+
+interface StoryMatch {
+    story: Story;
+    score: number;
+    matchedKeywords: string[];
+}
+interface StoryScore {
+    storyId: string;
+    score: number;
+    matchedKeywords: string[];
+    storyKeywords: string[];
+}
+declare const STORY_THRESHOLD = 0.1;
+declare class StoryResolver {
+    private stories;
+    constructor(stories: Story[]);
+    scoreAll(intent: Intent, resolvedKeywords: KeywordEntry[]): StoryScore[];
+    findBestStory(intent: Intent, resolvedKeywords: KeywordEntry[]): StoryMatch | undefined;
+    private scoreStory;
+}
+
+declare class QueryBuilder {
+    buildQuery(step: ResolutionStep, intent: Intent): QueryParams;
+    buildQueryPreview(step: ResolutionStep, intent: Intent, resolvedKeywords?: string[]): {
+        generatedQuery: string;
+        searchPattern: string;
+    };
+    buildSQLWhere(filters: Record<string, any>): string;
+}
+
+declare class ResponseBuilder {
+    buildAnswer(intent: Intent, story: Story | undefined, results: any[], executionTime: number, source: 'mock-llm' | 'fallback-llm'): Answer;
+    private buildSummary;
+}
+
+interface FetchConfigLoaderOptions {
+    /** URL to a pre-aggregated JSON array of all keyword entries, e.g. '/data/keywords.json' */
+    keywordsUrl: string;
+    /** URL to a pre-aggregated JSON array of all story definitions, e.g. '/data/stories.json' */
+    storiesUrl: string;
+}
+/**
+ * Isomorphic config loader that fetches keyword and story definitions from
+ * pre-aggregated JSON files via `fetch()`.
+ *
+ * Works in both browser and Node.js (≥ 18) environments with no file-system
+ * dependencies. Intended for use with `BrowserMockLLM` and static hosting
+ * (e.g. GitHub Pages, CDN, or any HTTP server that can serve JSON files).
+ *
+ * The expected JSON format for each URL is either:
+ *   - An array: `[{ keyword: "sky", ... }, ...]`
+ *   - A single object: `{ keyword: "sky", ... }` (wrapped into a one-element array)
+ */
+declare class FetchConfigLoader {
+    private options;
+    constructor(options: FetchConfigLoaderOptions);
+    loadKeywords(): Promise<KeywordEntry[]>;
+    loadStories(): Promise<Story[]>;
+}
+
+interface HttpMockAdapterOptions {
+    /**
+     * Base URL for all data-source JSON files, e.g. `'https://example.com/data'`
+     * or `'/data'` for a relative path on the same origin.
+     *
+     * A query for `source: 'knowledge/science'` fetches
+     * `{baseUrl}/knowledge/science.json`.
+     */
+    baseUrl: string;
+}
+/**
+ * Isomorphic data adapter that retrieves pre-aggregated JSON from a static
+ * HTTP endpoint via `fetch()`.
+ *
+ * Works in both browser and Node.js (≥ 18) environments with no file-system
+ * dependencies. Intended for use with `BrowserMockLLM` and static hosting
+ * (e.g. GitHub Pages, CDN, or any HTTP server that can serve JSON files).
+ *
+ * Filtering and limiting are applied client-side after fetching the full
+ * collection, matching the behaviour of `MockCosmosAdapter`.
+ */
+declare class HttpMockAdapter extends BaseAdapter {
+    private options;
+    constructor(options: HttpMockAdapterOptions);
+    query(params: QueryParams): Promise<any[]>;
+    getById(_id: string): Promise<any>;
+    private matchesFilters;
+    private getNestedValue;
+}
+
+interface QueryOptions {
+    debug?: boolean;
+}
+interface FallbackLLMConfig {
+    enabled: boolean;
+    endpoint: string;
+    apiKey: string;
+    model: string;
+}
+/**
+ * Isomorphic query engine — works in both Node.js and browser environments.
+ *
+ * Constructed with already-loaded keywords, stories, a data adapter, and an
+ * optional fallback-LLM config. Both `MockLLM` (server) and `BrowserMockLLM`
+ * (browser) delegate all query logic to this class.
+ */
+declare class MockLLMEngine {
+    private keywords;
+    private stories;
+    private adapter;
+    private fallbackLLM?;
+    private nlpMatcher;
+    private keywordResolver;
+    private storyResolver;
+    private queryBuilder;
+    private responseBuilder;
+    constructor(keywords: KeywordEntry[], stories: Story[], adapter: BaseAdapter, fallbackLLM?: FallbackLLMConfig | undefined);
+    getKeywords(): KeywordEntry[];
+    getStories(): Story[];
+    listDataSources(): string[];
+    getDataSourceSnapshot(source: string, limit?: number): Promise<any[]>;
+    query(userQuery: string, opts?: QueryOptions): Promise<Answer>;
+    private queryFallbackLLM;
+}
+
+interface BrowserMockLLMOptions {
+    /** URL to a pre-aggregated JSON array of all keyword entries, e.g. '/data/keywords.json' */
+    keywordsUrl: string;
+    /** URL to a pre-aggregated JSON array of all story definitions, e.g. '/data/stories.json' */
+    storiesUrl: string;
+    /**
+     * Base URL for data-source JSON files. A query for `source: 'knowledge/science'`
+     * fetches `{dataBaseUrl}/knowledge/science.json`.
+     */
+    dataBaseUrl: string;
+    fallbackLLM?: FallbackLLMConfig;
+}
+/**
+ * Browser-safe orchestrator for the mock-LLM engine.
+ *
+ * Loads configuration and data via `fetch()` with no file-system dependencies.
+ * Import from `@nice-tools/mock-llm/browser` to keep bundlers from pulling in
+ * Node.js-only modules (`fs`, `path`, `@google-cloud/storage`, etc.).
+ *
+ * @example
+ * ```ts
+ * import { BrowserMockLLM } from '@nice-tools/mock-llm/browser';
+ *
+ * const llm = new BrowserMockLLM({
+ *   keywordsUrl: '/data/keywords.json',
+ *   storiesUrl:  '/data/stories.json',
+ *   dataBaseUrl: '/data',
+ * });
+ * await llm.initialize();
+ * const answer = await llm.query('what is the color of sky');
+ * ```
+ */
+declare class BrowserMockLLM {
+    private options;
+    private engine;
+    constructor(options: BrowserMockLLMOptions);
+    initialize(): Promise<void>;
+    getKeywords(): KeywordEntry[];
+    getStories(): Story[];
+    listDataSources(): string[];
+    getDataSourceSnapshot(source: string, limit?: number): Promise<any[]>;
+    query(userQuery: string, opts?: QueryOptions): Promise<Answer>;
+}
+
+export { type AdapterConnections, type Answer, type AnswerDebug, type AnswerDebugStep, BaseAdapter, BrowserMockLLM, type BrowserMockLLMOptions, type ConfigSource, type FallbackLLMConfig, FetchConfigLoader, type FetchConfigLoaderOptions, HttpMockAdapter, type HttpMockAdapterOptions, type IDataAdapter, type Intent, type KeywordEntry, KeywordResolver, MockLLMEngine, NLPMatcher, QueryBuilder, type QueryOptions, type QueryParams, type Relation, type ResolutionStep, ResponseBuilder, STORY_THRESHOLD, type Story, type StoryContract, type StoryMatch, StoryResolver, type StoryScore };