@holokai/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,7 @@
+export const VERSION = '0.1.0';
+export * from './plugin';
+export * from './provider';
+export * from './holo';
+export * from './core/worker';
+export * from './core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC"}

package/dist/plugin/base.d.ts

@@ -0,0 +1,109 @@
+import { PluginManifest } from "./manifest";
+import { PluginContext } from "./context";
+import { ClassLogger } from "../core";
+export declare enum PluginState {
+    UNINITIALIZED = "uninitialized",
+    INITIALIZING = "initializing",
+    READY = "ready",
+    ERROR = "error",
+    DESTROYING = "destroying",
+    DESTROYED = "destroyed"
+}
+/**
+ * Base plugin interface that all plugin types must implement
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin implements IPlugin {
+ *   manifest = {
+ *     name: '@myorg/my-plugin',
+ *     version: '1.0.0',
+ *     pluginType: 'provider' as const
+ *   };
+ *
+ *   async initialize(context: PluginContext): Promise<void> {
+ *     // Setup plugin resources
+ *   }
+ *
+ *   async destroy(): Promise<void> {
+ *     // Cleanup resources
+ *   }
+ * }
+ * ```
+ */
+export interface IPlugin {
+    /** Plugin metadata and configuration */
+    readonly manifest: PluginManifest;
+    /** Current plugin state */
+    readonly state: PluginState;
+    readonly family: string;
+    /**
+     * Initialize the plugin with provided context
+     * @param context Runtime context including logger, config, and environment
+     * @throws {PluginError} If initialization fails
+     */
+    initialize(context: PluginContext): Promise<void>;
+    /**
+     * Destroy the plugin and cleanup resources
+     * @throws {PluginError} If cleanup fails
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get current plugin state
+     * @returns Current state of the plugin
+     */
+    getState(): PluginState;
+    /**
+     * Perform health check on the plugin
+     * @returns Health status and diagnostic information
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+}
+/**
+ * Health check result for plugin status monitoring
+ */
+export interface HealthCheckResult {
+    healthy: boolean;
+    message?: string;
+    details?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Base abstract class implementing common plugin functionality.
+ *
+ * Lifecycle:
+ *   UNINITIALIZED → INITIALIZING → READY → DESTROYING → DESTROYED
+ *   Any failure moves the plugin to ERROR.
+ */
+export declare abstract class BasePlugin extends ClassLogger implements IPlugin {
+    /**
+     * Static manifest per-plugin implementation.
+     * Implementations SHOULD treat this as immutable metadata.
+     */
+    abstract readonly manifest: PluginManifest;
+    private _context;
+    protected _state: PluginState;
+    /**
+     * Current plugin state (read-only from outside).
+     */
+    get state(): PluginState;
+    /**
+     * Strongly typed access to the plugin context.
+     * Throws if accessed before initialize() or after destroy().
+     */
+    protected get pluginContext(): PluginContext;
+    /**
+     * Backwards-compatible state accessor.
+     */
+    getState(): PluginState;
+    initialize(context: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+    healthCheck(): Promise<HealthCheckResult>;
+    protected abstract onInitialize(context: PluginContext): Promise<void>;
+    protected abstract onDestroy(): Promise<void>;
+    protected onHealthCheck(): Promise<HealthCheckResult | void>;
+    get name(): string;
+    get family(): string;
+    get version(): string;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/plugin/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/plugin/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAExC,OAAO,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAGpC,oBAAY,WAAW;IACnB,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;IAC7B,KAAK,UAAU;IACf,KAAK,UAAU;IACf,UAAU,eAAe;IACzB,SAAS,cAAc;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,OAAO;IACpB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;OAGG;IACH,QAAQ,IAAI,WAAW,CAAC;IAExB;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,8BAAsB,UAAW,SAAQ,WAAY,YAAW,OAAO;IACnE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAE3C,OAAO,CAAC,QAAQ,CAA4B;IAC5C,SAAS,CAAC,MAAM,EAAE,WAAW,CAA6B;IAE1D;;OAEG;IACH,IAAI,KAAK,IAAI,WAAW,CAEvB;IAGD;;;OAGG;IACH,SAAS,KAAK,aAAa,IAAI,aAAa,CAS3C;IAED;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIjB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BjD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCxB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA8B/C,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtE,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;cAE7B,aAAa,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAKlE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;CACJ"}

package/dist/plugin/base.js

@@ -0,0 +1,131 @@
+import { PluginError, PluginErrorCode } from "./errors";
+import { ClassLogger } from "../core";
+export var PluginState;
+(function (PluginState) {
+    PluginState["UNINITIALIZED"] = "uninitialized";
+    PluginState["INITIALIZING"] = "initializing";
+    PluginState["READY"] = "ready";
+    PluginState["ERROR"] = "error";
+    PluginState["DESTROYING"] = "destroying";
+    PluginState["DESTROYED"] = "destroyed";
+})(PluginState || (PluginState = {}));
+/**
+ * Base abstract class implementing common plugin functionality.
+ *
+ * Lifecycle:
+ *   UNINITIALIZED → INITIALIZING → READY → DESTROYING → DESTROYED
+ *   Any failure moves the plugin to ERROR.
+ */
+export class BasePlugin extends ClassLogger {
+    _context;
+    _state = PluginState.UNINITIALIZED;
+    /**
+     * Current plugin state (read-only from outside).
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Strongly typed access to the plugin context.
+     * Throws if accessed before initialize() or after destroy().
+     */
+    get pluginContext() {
+        if (!this._context) {
+            throw new PluginError('Plugin context is not available. Initialize the plugin first.', PluginErrorCode.INVALID_STATE, this.manifest.name);
+        }
+        return this._context;
+    }
+    /**
+     * Backwards-compatible state accessor.
+     */
+    getState() {
+        return this._state;
+    }
+    async initialize(context) {
+        const logger = this.mlog(this.initialize);
+        if (this._state !== PluginState.UNINITIALIZED) {
+            throw new PluginError(`Cannot initialize plugin in state ${this._state}`, PluginErrorCode.INITIALIZATION_FAILED, this.manifest.name);
+        }
+        this._state = PluginState.INITIALIZING;
+        this._context = context;
+        try {
+            logger.debug('Initializing plugin');
+            await this.onInitialize(context);
+            this._state = PluginState.READY;
+            logger.info('Plugin initialized successfully');
+        }
+        catch (error) {
+            this._state = PluginState.ERROR;
+            logger.error('Plugin initialization failed', { error });
+            throw new PluginError('Failed to initialize plugin', PluginErrorCode.INITIALIZATION_FAILED, this.manifest.name, error);
+        }
+    }
+    async destroy() {
+        const logger = this.mlog(this.destroy);
+        if (this._state === PluginState.DESTROYED) {
+            return;
+        }
+        if (this._state === PluginState.UNINITIALIZED) {
+            this._state = PluginState.DESTROYED;
+            return;
+        }
+        this._state = PluginState.DESTROYING;
+        try {
+            logger.info('Destroying plugin');
+            await this.onDestroy();
+            this._state = PluginState.DESTROYED;
+            this._context = undefined;
+        }
+        catch (error) {
+            this._state = PluginState.ERROR;
+            // Fall back to console if logger is gone
+            try {
+                logger.error('Plugin destruction failed', { error });
+            }
+            catch {
+                console.error(`[${this.manifest.name}] Plugin destruction failed`, error);
+            }
+            throw new PluginError('Failed to destroy plugin', PluginErrorCode.DESTRUCTION_FAILED, this.manifest.name, error);
+        }
+    }
+    async healthCheck() {
+        const logger = this.mlog(this.healthCheck);
+        const timestamp = Date.now();
+        if (this._state !== PluginState.READY) {
+            return {
+                healthy: false,
+                message: `Plugin not ready (state: ${this._state})`,
+                timestamp
+            };
+        }
+        try {
+            const customCheck = await this.onHealthCheck();
+            return (customCheck ?? {
+                healthy: true,
+                timestamp
+            });
+        }
+        catch (error) {
+            logger.warn('Health check failed', { error });
+            return {
+                healthy: false,
+                message: error instanceof Error ? error.message : 'Health check failed',
+                timestamp
+            };
+        }
+    }
+    async onHealthCheck() {
+        // Default implementation: no-op (host treats as healthy if READY)
+        return;
+    }
+    get name() {
+        return this.manifest.name;
+    }
+    get family() {
+        return this.manifest.family ?? this.manifest.name;
+    }
+    get version() {
+        return this.manifest.version;
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/plugin/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/plugin/base.ts"],"names":[],"mappings":"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"}

package/dist/plugin/context.d.ts

@@ -0,0 +1,21 @@
+import { HoloLogger } from "../core/logger/index";
+/**
+ * Runtime context provided to plugins
+ */
+export interface PluginContext {
+    /**
+     * Logger instance scoped to this plugin host.
+     * The host may already have plugin-specific bindings applied.
+     */
+    logger: HoloLogger;
+    /**
+     * Optional factory to create per-plugin loggers.
+     * If provided, BasePlugin will prefer this over `logger`.
+     */
+    loggerFactory?: (pluginName: string) => HoloLogger;
+    /** Plugin-specific configuration */
+    config?: unknown;
+    /** Environment variables */
+    env?: Record<string, string | undefined>;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/plugin/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/plugin/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,UAAU,CAAC;IAEnD,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAE5C"}

package/dist/plugin/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/plugin/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/plugin/context.ts"],"names":[],"mappings":""}

package/dist/plugin/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Plugin error class for consistent error handling
+ */
+export declare class PluginError extends Error {
+    readonly code: string;
+    readonly plugin?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, plugin?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Common plugin error codes
+ */
+export declare enum PluginErrorCode {
+    INITIALIZATION_FAILED = "PLUGIN_INIT_FAILED",
+    DESTRUCTION_FAILED = "PLUGIN_DESTROY_FAILED",
+    INVALID_CONFIG = "PLUGIN_INVALID_CONFIG",
+    DEPENDENCY_MISSING = "PLUGIN_DEPENDENCY_MISSING",
+    INCOMPATIBLE_VERSION = "PLUGIN_INCOMPATIBLE_VERSION",
+    PERMISSION_DENIED = "PLUGIN_PERMISSION_DENIED",
+    HEALTH_CHECK_FAILED = "PLUGIN_HEALTH_CHECK_FAILED",
+    INVALID_STATE = "PLUGIN_INVALID_STATE",
+    UNKNOWN_ERROR = "PLUGIN_UNKNOWN_ERROR"
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/plugin/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/plugin/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGd,IAAI,EAAE,MAAM;aACZ,MAAM,CAAC,EAAE,MAAM;aACf,OAAO,CAAC,EAAE,OAAO;gBAHjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAKxC;AAED;;GAEG;AACH,oBAAY,eAAe;IACvB,qBAAqB,uBAAuB;IAC5C,kBAAkB,0BAA0B;IAC5C,cAAc,0BAA0B;IACxC,kBAAkB,8BAA8B;IAChD,oBAAoB,gCAAgC;IACpD,iBAAiB,6BAA6B;IAC9C,mBAAmB,+BAA+B;IAClD,aAAa,yBAAyB;IACtC,aAAa,yBAAyB;CACzC"}

package/dist/plugin/errors.js

@@ -0,0 +1,31 @@
+/**
+ * Plugin error class for consistent error handling
+ */
+export class PluginError extends Error {
+    code;
+    plugin;
+    details;
+    constructor(message, code, plugin, details) {
+        super(message);
+        this.code = code;
+        this.plugin = plugin;
+        this.details = details;
+        this.name = 'PluginError';
+    }
+}
+/**
+ * Common plugin error codes
+ */
+export var PluginErrorCode;
+(function (PluginErrorCode) {
+    PluginErrorCode["INITIALIZATION_FAILED"] = "PLUGIN_INIT_FAILED";
+    PluginErrorCode["DESTRUCTION_FAILED"] = "PLUGIN_DESTROY_FAILED";
+    PluginErrorCode["INVALID_CONFIG"] = "PLUGIN_INVALID_CONFIG";
+    PluginErrorCode["DEPENDENCY_MISSING"] = "PLUGIN_DEPENDENCY_MISSING";
+    PluginErrorCode["INCOMPATIBLE_VERSION"] = "PLUGIN_INCOMPATIBLE_VERSION";
+    PluginErrorCode["PERMISSION_DENIED"] = "PLUGIN_PERMISSION_DENIED";
+    PluginErrorCode["HEALTH_CHECK_FAILED"] = "PLUGIN_HEALTH_CHECK_FAILED";
+    PluginErrorCode["INVALID_STATE"] = "PLUGIN_INVALID_STATE";
+    PluginErrorCode["UNKNOWN_ERROR"] = "PLUGIN_UNKNOWN_ERROR";
+})(PluginErrorCode || (PluginErrorCode = {}));
+//# sourceMappingURL=errors.js.map

package/dist/plugin/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/plugin/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGd;IACA;IACA;IAJpB,YACI,OAAe,EACC,IAAY,EACZ,MAAe,EACf,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAS;QACf,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC9B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,eAUX;AAVD,WAAY,eAAe;IACvB,+DAA4C,CAAA;IAC5C,+DAA4C,CAAA;IAC5C,2DAAwC,CAAA;IACxC,mEAAgD,CAAA;IAChD,uEAAoD,CAAA;IACpD,iEAA8C,CAAA;IAC9C,qEAAkD,CAAA;IAClD,yDAAsC,CAAA;IACtC,yDAAsC,CAAA;AAC1C,CAAC,EAVW,eAAe,KAAf,eAAe,QAU1B"}

package/dist/plugin/evaluator.d.ts

@@ -0,0 +1,243 @@
+import { IPlugin } from "./base";
+/**
+ * Types of evaluation metrics
+ */
+export interface EvaluationMetric {
+    /**
+     * Stable identifier used as the key in EvaluationResult.metrics.
+     * If omitted, `name` MUST be used as the key.
+     */
+    id?: string;
+    /**
+     * Human-readable metric name (may be shown in UIs, logs, etc.).
+     */
+    name: string;
+    /**
+     * What this metric measures and how to interpret it.
+     */
+    description: string;
+    /**
+     * Optional unit (e.g. "probability", "score", "%", "tokens").
+     */
+    unit?: string;
+    /**
+     * Expected numeric range for this metric.
+     */
+    range?: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Result of an evaluation
+ */
+/**
+ * Issue found during evaluation
+ */
+export interface EvaluationIssue {
+    category: string;
+    severity: 'low' | 'medium' | 'high';
+    description: string;
+    location?: string;
+}
+/**
+ * Detailed evaluation breakdown
+ */
+export interface EvaluationDetails {
+    categoryScores?: Record<string, number>;
+    issues?: EvaluationIssue[];
+    suggestions?: string[];
+    rawOutput?: string;
+    evaluationMethod?: string;
+    confidence?: number;
+}
+export interface EvaluationResult {
+    /**
+     * Optional overall score, typically an aggregate over metrics.
+     */
+    score?: number;
+    /**
+     * Indicates whether the evaluated output is considered acceptable
+     * according to the evaluator's criteria and configuration.
+     */
+    passed: boolean;
+    /**
+     * Per-metric scores keyed by metric id (or name if id is not provided).
+     */
+    metrics: Record<string, number>;
+    /**
+     * Optional human-readable feedback or explanation.
+     */
+    feedback?: string;
+    /**
+     * Additional evaluation details
+     */
+    details?: {
+        /**
+         * Detailed breakdown by evaluation category
+         */
+        categoryScores?: Record<string, number>;
+        /**
+         * Specific issues found during evaluation
+         */
+        issues?: Array<{
+            category: string;
+            severity: 'low' | 'medium' | 'high';
+            description: string;
+            location?: string;
+        }>;
+        /**
+         * Suggestions for improvement
+         */
+        suggestions?: string[];
+        /**
+         * Raw model output if using LLM-based evaluation
+         */
+        rawOutput?: string;
+        /**
+         * Evaluation model/method used
+         */
+        evaluationMethod?: string;
+        /**
+         * Confidence score for the evaluation
+         */
+        confidence?: number;
+    };
+    /**
+     * Evaluation timestamp (ms since epoch).
+     */
+    timestamp: number;
+}
+/**
+ * Model-based evaluation settings
+ */
+export interface ModelEvaluation {
+    /**
+     * Model to use for evaluation
+     */
+    model: string;
+    /**
+     * Temperature for model sampling
+     */
+    temperature?: number;
+    /**
+     * Custom evaluation prompt template
+     */
+    promptTemplate?: string;
+    /**
+     * Number of evaluation samples to generate
+     */
+    numSamples?: number;
+}
+/**
+ * Rule-based evaluation settings
+ */
+export interface RuleBasedEvaluation {
+    /**
+     * Maximum response length
+     */
+    maxResponseLength?: number;
+    /**
+     * Minimum response length
+     */
+    minResponseLength?: number;
+    /**
+     * Required keywords/phrases in response
+     */
+    requiredKeywords?: string[];
+    /**
+     * Prohibited keywords/phrases in response
+     */
+    prohibitedKeywords?: string[];
+    /**
+     * Check for factual consistency
+     */
+    checkFactualConsistency?: boolean;
+    /**
+     * Check for harmful content
+     */
+    checkHarmfulContent?: boolean;
+}
+/**
+ * Configuration for evaluator plugins
+ */
+export interface EvaluatorConfig {
+    /**
+     * Whether this evaluator is enabled.
+     */
+    enabled: boolean;
+    /**
+     * Per-metric thresholds. Keys must match metric id or name.
+     * Typically interpreted as minimum acceptable scores.
+     */
+    thresholds?: Record<string, number>;
+    /**
+     * Per-metric weights used to compute the overall score.
+     */
+    weights?: Record<string, number>;
+    /**
+     * Model-based evaluation settings (if using LLM for evaluation)
+     */
+    modelEvaluation?: ModelEvaluation;
+    /**
+     * Rule-based evaluation settings
+     */
+    ruleBasedEvaluation?: RuleBasedEvaluation;
+}
+/**
+ * Evaluator plugin interface for LLM output evaluation
+ *
+ * @example
+ * ```typescript
+ * class QualityEvaluatorPlugin
+ *   extends BasePlugin
+ *   implements IEvaluatorPlugin<unknown, unknown>
+ * {
+ *   async evaluate(input: unknown, output: unknown): Promise<EvaluationResult> {
+ *     const scores = await this.calculateScores(input, output);
+ *     return {
+ *       passed: scores.quality > 0.7,
+ *       score: scores.overall,
+ *       metrics: scores,
+ *       timestamp: Date.now()
+ *     };
+ *   }
+ *
+ *   getMetrics(): EvaluationMetric[] {
+ *     return [
+ *       { name: 'quality', description: 'Overall quality score', range: { min: 0, max: 1 } },
+ *       { name: 'relevance', description: 'Relevance to input', range: { min: 0, max: 1 } }
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+export interface IEvaluatorPlugin<TInput = unknown, TOutput = unknown> extends IPlugin {
+    /**
+     * Evaluate LLM output against input.
+     * @param input The original input/prompt (typed per plugin).
+     * @param output The LLM output to evaluate (typed per plugin).
+     * @returns Evaluation result with scores and metrics.
+     */
+    evaluate(input: TInput, output: TOutput): Promise<EvaluationResult>;
+    /**
+     * Get available evaluation metrics.
+     * @returns Array of evaluation metrics.
+     */
+    getMetrics(): EvaluationMetric[];
+    /**
+     * Configure the evaluator. Implementations may merge with existing config.
+     * @param config Evaluator configuration (partial updates allowed).
+     */
+    configure(config: Partial<EvaluatorConfig>): Promise<void>;
+    /**
+     * Batch evaluate multiple input/output pairs.
+     * @param pairs Array of input/output pairs.
+     * @returns Array of evaluation results (same order as input pairs).
+     */
+    batchEvaluate?(pairs: Array<{
+        input: TInput;
+        output: TOutput;
+    }>): Promise<EvaluationResult[]>;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/plugin/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/plugin/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/plugin/evaluator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluator.js.map

package/dist/plugin/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/plugin/evaluator.ts"],"names":[],"mappings":""}