semantic-primitives 0.1.0

package/dist/types/error/error.d.ts

@@ -0,0 +1,191 @@
+/**
+ * SemanticError
+ * An error type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Comparable<Error, SemanticEqualsResultWithReason> - Semantic equality comparison
+ * - Explainable - Human-readable explanations
+ * - Classifiable - Error classification
+ * - SemanticErrorType - Error-specific methods
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResultWithReason, ClassifyResult, RootCauseResult, SuggestedFix, RecoveryStrategy, ErrorSeverityLevel } from '../../shared/types.ts';
+import type { Comparable, Explainable, Classifiable, SemanticErrorType } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResultWithReason, ClassifyResult, RootCauseResult, SuggestedFix, RecoveryStrategy, ErrorSeverityLevel, } from '../../shared/types.ts';
+/** Result of error classification with extended fields */
+export interface ErrorClassifyResult extends ClassifyResult {
+    subcategory?: string;
+    severity: 'critical' | 'recoverable' | 'warning';
+    retryable: boolean;
+}
+/** Resource suggestion */
+export interface ResourceSuggestion {
+    title: string;
+    type: string;
+    url?: string;
+}
+/** Report recommendation */
+export interface ReportRecommendation {
+    report: boolean;
+    reason: string;
+    priority?: string;
+}
+/**
+ * SemanticError - Error with LLM-powered semantic understanding
+ *
+ * Extends the native JavaScript Error with intelligent error classification,
+ * fix suggestions, and human-readable explanations.
+ *
+ * Implements:
+ * - Comparable<Error, SemanticEqualsResultWithReason> - semanticallyEquals() for comparison
+ * - Explainable - explain() for human-readable explanations
+ * - Classifiable<ErrorClassifyResult> - classify() for categorization
+ * - SemanticErrorType - Full error-specific interface
+ */
+export declare class SemanticError extends Error implements Comparable<Error, SemanticEqualsResultWithReason>, Explainable, Classifiable<ErrorClassifyResult>, SemanticErrorType {
+    private readonly client;
+    private readonly context;
+    private cachedClassification?;
+    private constructor();
+    /**
+     * Create a SemanticError from any error-like value.
+     *
+     * @param error - Error object, string, or unknown value
+     * @param context - Additional context
+     * @param client - Optional LLM client
+     * @returns SemanticError instance
+     *
+     * @example
+     * SemanticError.from(caughtError)
+     * SemanticError.from("Connection failed", { service: "database" })
+     */
+    static from(error: unknown, context?: Record<string, unknown>, client?: LLMClient): SemanticError;
+    /**
+     * Check if two errors are semantically equivalent.
+     * Same root cause despite different messages.
+     *
+     * @param other - Error to compare
+     * @returns Equivalence result
+     *
+     * @example
+     * error1.semanticallyEquals(error2)
+     * // { equivalent: true, reason: "Both are network timeout errors", confidence: 0.85 }
+     */
+    semanticallyEquals(other: Error): Promise<SemanticEqualsResultWithReason>;
+    /**
+     * Classify the error into a category.
+     *
+     * @returns Error classification
+     *
+     * @example
+     * error.classify()
+     * // {
+     * //   category: "network",
+     * //   subcategory: "timeout",
+     * //   severity: "recoverable",
+     * //   retryable: true,
+     * //   confidence: 0.9
+     * // }
+     */
+    classify(): Promise<ErrorClassifyResult>;
+    /**
+     * Explain the error in plain language.
+     *
+     * @param audience - Target audience
+     * @returns Human-readable explanation
+     *
+     * @example
+     * error.explain("end-user")
+     * // "We couldn't connect to the server. Please check your internet connection."
+     *
+     * error.explain("developer")
+     * // "ECONNREFUSED on port 5432. The PostgreSQL server may not be running."
+     */
+    explain(audience?: 'end-user' | 'developer' | 'support'): Promise<string>;
+    /**
+     * Suggest fixes for the error.
+     *
+     * @returns Suggested fixes
+     *
+     * @example
+     * error.suggestFixes()
+     * // [
+     * //   { fix: "Check database connection string", confidence: 0.9 },
+     * //   { fix: "Ensure PostgreSQL service is running", confidence: 0.85 }
+     * // ]
+     */
+    suggestFixes(): Promise<SuggestedFix[]>;
+    /**
+     * Infer the root cause of the error.
+     *
+     * @returns Root cause analysis
+     *
+     * @example
+     * error.inferRootCause()
+     * // { cause: "Database connection pool exhausted", confidence: 0.87 }
+     */
+    inferRootCause(): Promise<RootCauseResult>;
+    /**
+     * Check if this error matches a known pattern.
+     *
+     * @param pattern - Error pattern to check
+     * @returns Match result
+     *
+     * @example
+     * error.matches("network-related") // true
+     * error.matches("authentication-failure") // false
+     */
+    matches(pattern: string): Promise<boolean>;
+    /**
+     * Get related documentation or resources.
+     *
+     * @returns Related resources
+     *
+     * @example
+     * error.getResources()
+     * // [{ title: "Troubleshooting Connection Issues", type: "docs" }]
+     */
+    getResources(): Promise<ResourceSuggestion[]>;
+    /**
+     * Determine if this error should be reported/logged.
+     *
+     * @returns Reporting recommendation
+     *
+     * @example
+     * error.shouldReport()
+     * // { report: true, reason: "Unexpected server error", priority: "high" }
+     */
+    shouldReport(): Promise<ReportRecommendation>;
+    /**
+     * Get a recovery strategy for this error.
+     *
+     * @returns Recovery strategy
+     *
+     * @example
+     * error.recoveryStrategy()
+     * // { strategy: "retry", maxAttempts: 3, backoff: "exponential" }
+     */
+    recoveryStrategy(): Promise<RecoveryStrategy>;
+    /**
+     * Get the semantic severity level.
+     *
+     * @returns Severity assessment
+     */
+    getSeverity(): Promise<ErrorSeverityLevel>;
+    /**
+     * Get the context associated with this error.
+     *
+     * @returns Error context
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        stack?: string;
+        context: Record<string, unknown>;
+    };
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/types/error/error.d.ts.map

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

package/dist/types/error/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SemanticError module
+ * LLM-enhanced error type with semantic understanding
+ */
+export { SemanticError, type ErrorClassifyResult, type ResourceSuggestion, type ReportRecommendation, type SemanticEqualsResultWithReason, type ClassifyResult, type RootCauseResult, type SuggestedFix, type RecoveryStrategy, type ErrorSeverityLevel, } from './error.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/error/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}

package/dist/types/error/prompts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompts for SemanticError LLM operations
+ * These prompts enable intelligent error classification, explanation, and fix suggestions
+ */
+/**
+ * System prompt for error analysis tasks
+ */
+export declare const ERROR_SYSTEM_PROMPT = "You are an expert error analyst and debugger. Your task is to analyze errors, classify them, suggest fixes, and provide helpful explanations.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Analyze error messages, stack traces, and context to understand root causes\n- Consider common error patterns in software development\n- Provide actionable, specific suggestions for fixes\n- Adjust explanations based on the target audience (developer, end-user, support)\n- Be precise with confidence scores based on available information";
+/**
+ * Prompt template for semantic equality comparison between errors
+ */
+export declare function createSemanticallyEqualsPrompt(error1Message: string, error1Stack: string | undefined, error2Message: string, error2Stack: string | undefined): string;
+/**
+ * Prompt template for error classification
+ */
+export declare function createClassifyPrompt(errorMessage: string, errorStack: string | undefined, context?: Record<string, unknown>): string;
+/**
+ * Prompt template for generating human-readable explanations
+ */
+export declare function createExplainPrompt(errorMessage: string, errorStack: string | undefined, audience: 'end-user' | 'developer' | 'support'): string;
+/**
+ * Prompt template for suggesting fixes
+ */
+export declare function createSuggestFixesPrompt(errorMessage: string, errorStack: string | undefined, context?: Record<string, unknown>): string;
+/**
+ * Prompt template for inferring root cause
+ */
+export declare function createInferRootCausePrompt(errorMessage: string, errorStack: string | undefined, context?: Record<string, unknown>): string;
+/**
+ * Prompt template for pattern matching
+ */
+export declare function createMatchesPatternPrompt(errorMessage: string, errorStack: string | undefined, pattern: string): string;
+/**
+ * Prompt template for getting resources
+ */
+export declare function createGetResourcesPrompt(errorMessage: string, errorStack: string | undefined): string;
+/**
+ * Prompt template for determining if error should be reported
+ */
+export declare function createShouldReportPrompt(errorMessage: string, errorStack: string | undefined, context?: Record<string, unknown>): string;
+/**
+ * Prompt template for determining recovery strategy
+ */
+export declare function createRecoveryStrategyPrompt(errorMessage: string, errorStack: string | undefined, category?: string): string;
+/**
+ * Prompt template for getting severity level
+ */
+export declare function createGetSeverityPrompt(errorMessage: string, errorStack: string | undefined, context?: Record<string, unknown>): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/types/error/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/error/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB,okBASmC,CAAC;AAEpE;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAgCR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,GAC7C,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GACd,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAwBR"}

package/dist/types/event-emitter/event-emitter.d.ts

@@ -0,0 +1,230 @@
+/**
+ * SemanticEventEmitter
+ * An EventEmitter wrapper with LLM-powered semantic understanding
+ *
+ * Implements intelligent event handling, pattern detection, and event flow analysis.
+ */
+import { EventEmitter } from 'events';
+import type { LLMClient } from '../../llm/client.ts';
+/** Result of event classification */
+export interface EventClassifyResult {
+    category: string;
+    severity?: 'low' | 'medium' | 'high';
+    recoverable?: boolean;
+}
+/** Result of handler validation */
+export interface ValidateHandlersResult {
+    valid: boolean;
+    issues: string[];
+    suggestions: string[];
+}
+/** Result of event name validation */
+export interface ValidateEventNameResult {
+    valid: boolean;
+    suggestions: string[];
+}
+/** Handler suggestion */
+export interface HandlerSuggestion {
+    event: string;
+    reason: string;
+    example: string;
+}
+/** Event flow analysis result */
+export interface AnalyzeFlowResult {
+    events: Record<string, number>;
+    patterns: string[];
+    anomalies: string[];
+}
+/** Monitoring options */
+export interface MonitorOptions {
+    reportInterval?: number;
+    onIssue?: (issue: string) => void;
+}
+/**
+ * SemanticEventEmitter - EventEmitter with LLM-powered semantic understanding
+ *
+ * Wraps a native EventEmitter and adds intelligent event handling,
+ * pattern detection, and event flow analysis capabilities.
+ */
+export declare class SemanticEventEmitter {
+    readonly [Symbol.toStringTag] = "SemanticEventEmitter";
+    private readonly _emitter;
+    private readonly _context?;
+    private readonly _client;
+    private readonly _eventRecords;
+    private readonly _semanticHandlers;
+    private _isMonitoring;
+    private constructor();
+    /**
+     * Wrap an EventEmitter with semantic capabilities.
+     *
+     * @param emitter - EventEmitter to wrap
+     * @param context - Context about the emitter's purpose
+     * @param client - Optional LLM client
+     * @returns SemanticEventEmitter instance
+     *
+     * @example
+     * SemanticEventEmitter.from(server, "HTTP server events")
+     */
+    static from(emitter: EventEmitter, context?: string, client?: LLMClient): SemanticEventEmitter;
+    /**
+     * Get the underlying EventEmitter.
+     */
+    get emitter(): EventEmitter;
+    /**
+     * Get the context description.
+     */
+    get context(): string | undefined;
+    /**
+     * Get all event names that have listeners.
+     */
+    eventNames(): (string | symbol)[];
+    /**
+     * Get the listener count for an event.
+     */
+    listenerCount(eventName: string | symbol): number;
+    /**
+     * Add a listener for an event.
+     */
+    on(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    /**
+     * Add a one-time listener for an event.
+     */
+    once(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    /**
+     * Remove a listener for an event.
+     */
+    off(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    /**
+     * Remove a listener for an event (alias for off).
+     */
+    removeListener(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    /**
+     * Remove all listeners for an event.
+     */
+    removeAllListeners(eventName?: string | symbol): this;
+    /**
+     * Emit an event.
+     */
+    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Listen for events matching semantic criteria.
+     *
+     * @param criteria - Natural language description of events to listen for
+     * @param handler - Event handler
+     * @returns this (for chaining)
+     *
+     * @example
+     * emitter.onSemantic("any error event", (event, data) => console.log(data))
+     */
+    onSemantic(criteria: string, handler: (event: string, data: unknown) => void): this;
+    /**
+     * Remove a semantic handler.
+     */
+    offSemantic(criteria: string, handler: (event: string, data: unknown) => void): this;
+    /**
+     * Analyze the event flow of this emitter.
+     *
+     * @param duration - Time to analyze (ms)
+     * @returns Event flow analysis
+     *
+     * @example
+     * emitter.analyzeFlow(60000)
+     * // {
+     * //   events: { "request": 150, "error": 3 },
+     * //   patterns: ["request always followed by response"],
+     * //   anomalies: ["error spike at minute 3"]
+     * // }
+     */
+    analyzeFlow(duration: number): Promise<AnalyzeFlowResult>;
+    /**
+     * Validate event handlers are properly set up.
+     *
+     * @returns Validation result
+     *
+     * @example
+     * emitter.validateHandlers()
+     * // { valid: false, issues: ["error event has no handler"] }
+     */
+    validateHandlers(): ValidateHandlersResult;
+    /**
+     * Validate event handlers asynchronously with LLM analysis.
+     */
+    validateHandlersAsync(): Promise<ValidateHandlersResult>;
+    /**
+     * Explain what events this emitter handles.
+     *
+     * @returns Human-readable explanation
+     *
+     * @example
+     * emitter.explain()
+     * // "HTTP server emitter with request, response, error, and close events"
+     */
+    explain(): string;
+    /**
+     * Explain with LLM-powered semantic analysis.
+     */
+    explainAsync(): Promise<string>;
+    /**
+     * Detect the category/purpose of an event.
+     *
+     * @param eventName - Event name to analyze
+     * @returns Event classification
+     *
+     * @example
+     * emitter.classifyEvent("connection_error")
+     * // { category: "error", severity: "high", recoverable: true }
+     */
+    classifyEvent(eventName: string): EventClassifyResult;
+    /**
+     * Classify event with LLM-powered semantic analysis.
+     */
+    classifyEventAsync(eventName: string): Promise<EventClassifyResult>;
+    /**
+     * Suggest event handlers based on registered events.
+     *
+     * @returns Suggested handlers
+     *
+     * @example
+     * emitter.suggestHandlers()
+     * // [{ event: "error", reason: "Unhandled errors will crash the process" }]
+     */
+    suggestHandlers(): HandlerSuggestion[];
+    /**
+     * Suggest handlers with LLM-powered analysis.
+     */
+    suggestHandlersAsync(): Promise<HandlerSuggestion[]>;
+    /**
+     * Check if an event name follows naming conventions.
+     *
+     * @param eventName - Event name to validate
+     * @returns Validation result
+     *
+     * @example
+     * emitter.validateEventName("USER_LOGIN")
+     * // { valid: true, suggestions: ["Consider using camelCase: userLogin"] }
+     */
+    validateEventName(eventName: string): ValidateEventNameResult;
+    /**
+     * Validate event name with LLM-powered analysis.
+     */
+    validateEventNameAsync(eventName: string): Promise<ValidateEventNameResult>;
+    /**
+     * Generate documentation for all registered events.
+     *
+     * @returns Event documentation
+     */
+    generateDocs(): string;
+    /**
+     * Generate documentation with LLM-powered descriptions.
+     */
+    generateDocsAsync(): Promise<string>;
+    /**
+     * Monitor events and report issues.
+     *
+     * @param options - Monitoring options
+     * @returns Cleanup function
+     */
+    monitor(options?: MonitorOptions): () => void;
+}
+//# sourceMappingURL=event-emitter.d.ts.map

package/dist/types/event-emitter/event-emitter.d.ts.map

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

package/dist/types/event-emitter/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SemanticEventEmitter module
+ * LLM-enhanced EventEmitter type with semantic understanding
+ */
+export { SemanticEventEmitter, type EventClassifyResult, type ValidateHandlersResult, type ValidateEventNameResult, type HandlerSuggestion, type AnalyzeFlowResult, type MonitorOptions, } from './event-emitter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/event-emitter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/event-emitter/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/types/event-emitter/prompts.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Prompts for SemanticEventEmitter LLM operations
+ * These prompts enable intelligent event handling, pattern detection, and event flow analysis
+ */
+/**
+ * System prompt for event emitter analysis tasks
+ */
+export declare const EVENT_EMITTER_SYSTEM_PROMPT = "You are an expert at analyzing event-driven architectures, understanding event emitter patterns, and providing semantic insights about pub/sub communication.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Analyze event names, patterns, and flows to understand their semantics\n- Consider common event-driven patterns in Node.js and browser environments\n- Provide meaningful, contextual responses about event handling\n- Be precise with classifications and recommendations";
+/**
+ * Prompt template for classifying an event based on its name
+ */
+export declare function createClassifyEventPrompt(eventName: string, context?: string, registeredEvents?: string[]): string;
+/**
+ * Prompt template for matching events against semantic criteria
+ */
+export declare function createMatchEventCriteriaPrompt(eventName: string, criteria: string, eventData?: unknown): string;
+/**
+ * Prompt template for validating event handlers
+ */
+export declare function createValidateHandlersPrompt(registeredEvents: string[], listenerCounts: Record<string, number>, context?: string): string;
+/**
+ * Prompt template for suggesting event handlers
+ */
+export declare function createSuggestHandlersPrompt(registeredEvents: string[], existingHandlers: string[], context?: string): string;
+/**
+ * Prompt template for validating event names
+ */
+export declare function createValidateEventNamePrompt(eventName: string, existingEvents?: string[]): string;
+/**
+ * Prompt template for generating event documentation
+ */
+export declare function createGenerateDocsPrompt(registeredEvents: string[], listenerCounts: Record<string, number>, context?: string): string;
+/**
+ * Prompt template for explaining what the emitter handles
+ */
+export declare function createExplainEmitterPrompt(registeredEvents: string[], listenerCounts: Record<string, number>, context?: string): string;
+/**
+ * Prompt template for analyzing event flow patterns
+ */
+export declare function createAnalyzeFlowPrompt(eventCounts: Record<string, number>, eventSequence: {
+    event: string;
+    timestamp: number;
+}[], duration: number, context?: string): string;
+/**
+ * Prompt template for detecting monitoring issues
+ */
+export declare function createDetectIssuePrompt(event: string, eventCounts: Record<string, number>, recentEvents: {
+    event: string;
+    timestamp: number;
+}[], context?: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/types/event-emitter/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/event-emitter/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,2BAA2B,6gBAQc,CAAC;AAEvD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,MAAM,CAyBR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,OAAO,GAClB,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAyBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,aAAa,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,EACrD,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAkCR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,YAAY,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,EACpD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAoBR"}