@windagency/valora 2.0.1

package/dist/utils/template-loader.js

@@ -0,0 +1,75 @@
+/**
+ * Template Loader - Loads and populates template files with variables
+ *
+ * Provides caching and variable substitution for markdown templates
+ */
+import path from 'path';
+import { readFile } from './file-utils.js';
+import { getPackageDataDir } from './paths.js';
+export class TemplateLoader {
+    templateCache = new Map();
+    /**
+     * Load a template file from data/templates/
+     * Results are cached for performance
+     */
+    async loadTemplate(templateName) {
+        // Check cache first
+        if (this.templateCache.has(templateName)) {
+            return this.templateCache.get(templateName);
+        }
+        // Construct path to template file
+        const dataDir = getPackageDataDir();
+        const templatePath = path.join(dataDir, 'templates', `${templateName}.md`);
+        // Load template content
+        const content = await readFile(templatePath);
+        // Cache for future use
+        this.templateCache.set(templateName, content);
+        return content;
+    }
+    /**
+     * Populate template with variable values
+     * Replaces {{variableName}} placeholders with actual values
+     */
+    populateTemplate(template, variables) {
+        // First, replace all provided variables
+        let result = Object.entries(variables).reduce((acc, [key, value]) => {
+            const placeholder = `{{${key}}}`;
+            const replacement = String(value ?? '');
+            // Use global regex to replace all occurrences
+            return acc.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), replacement);
+        }, template);
+        // Then, replace any remaining {{...}} placeholders with empty strings
+        result = result.replace(/\{\{[^}]+\}\}/g, '');
+        return result;
+    }
+    /**
+     * Load a template and populate it with variables in one call
+     */
+    async renderTemplate(templateName, variables) {
+        const template = await this.loadTemplate(templateName);
+        return this.populateTemplate(template, variables);
+    }
+    /**
+     * Clear the template cache
+     * Useful for testing or if templates are modified at runtime
+     */
+    clearCache() {
+        this.templateCache.clear();
+    }
+}
+// Singleton instance
+let templateLoaderInstance = null;
+/**
+ * Get the singleton TemplateLoader instance
+ */
+export function getTemplateLoader() {
+    templateLoaderInstance ??= new TemplateLoader();
+    return templateLoaderInstance;
+}
+/**
+ * Reset the singleton instance (useful for testing)
+ */
+export function resetTemplateLoader() {
+    templateLoaderInstance = null;
+}
+//# sourceMappingURL=template-loader.js.map

package/dist/utils/template-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.js","sourceRoot":"","sources":["../../src/utils/template-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAM5C,MAAM,OAAO,cAAc;IAClB,aAAa,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEvD;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,YAAoB;QACtC,oBAAoB;QACpB,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC;QAC9C,CAAC;QAED,kCAAkC;QAClC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC;QAE3E,wBAAwB;QACxB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;QAE7C,uBAAuB;QACvB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAE9C,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,QAAgB,EAAE,SAA4B;QAC9D,wCAAwC;QACxC,IAAI,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACnE,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,CAAC;YACjC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YACxC,8CAA8C;YAC9C,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;QACtG,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEb,sEAAsE;QACtE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QAE9C,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,YAAoB,EAAE,SAA4B;QACtE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,UAAU;QACT,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACD;AAED,qBAAqB;AACrB,IAAI,sBAAsB,GAA0B,IAAI,CAAC;AAEzD;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAChC,sBAAsB,KAAK,IAAI,cAAc,EAAE,CAAC;IAChD,OAAO,sBAAsB,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IAClC,sBAAsB,GAAG,IAAI,CAAC;AAC/B,CAAC"}

package/dist/utils/token-estimator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Token and Cost Estimator
+ *
+ * Estimates token usage and cost for LLM API calls.
+ * Uses approximate token counting (4 characters per token for English text).
+ */
+import type { LLMMessage } from '../types/llm.types.js';
+export interface TokenEstimate {
+    /** Estimated cost in USD */
+    estimatedCost: {
+        amount: number;
+        currency: 'USD';
+    };
+    /** Estimated completion tokens (based on typical response ratios) */
+    estimatedCompletionTokens: number;
+    /** Prompt tokens (input) */
+    promptTokens: number;
+    /** Total estimated tokens */
+    totalTokens: number;
+}
+/**
+ * Estimate token usage and cost for a set of messages
+ *
+ * @param messages - Array of LLM messages
+ * @param model - Model name for pricing lookup
+ * @returns Token estimate with cost
+ */
+export declare function estimateTokens(messages: LLMMessage[], model?: string): TokenEstimate;
+/**
+ * Estimate tokens from a single string
+ *
+ * @param text - Text to estimate
+ * @returns Approximate token count
+ */
+export declare function estimateTokensFromText(text: string): number;
+/**
+ * Format token estimate for display
+ *
+ * @param estimate - Token estimate to format
+ * @returns Formatted string
+ */
+export declare function formatTokenEstimate(estimate: TokenEstimate): string;
+/**
+ * Get pricing info for a model
+ *
+ * @param model - Model name
+ * @returns Pricing info or undefined
+ */
+export declare function getModelPricing(model: string): undefined | {
+    input: number;
+    output: number;
+};
+/**
+ * Check if a model has known pricing
+ *
+ * @param model - Model name
+ * @returns True if pricing is available
+ */
+export declare function hasKnownPricing(model: string): boolean;
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/utils/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../../src/utils/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC7B,4BAA4B;IAC5B,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAA;KAAE,CAAC;IACnD,qEAAqE;IACrE,yBAAyB,EAAE,MAAM,CAAC;IAClC,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;CACpB;AAoCD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,CAqCpF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAOnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAE5F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/utils/token-estimator.js

@@ -0,0 +1,114 @@
+/**
+ * Token and Cost Estimator
+ *
+ * Estimates token usage and cost for LLM API calls.
+ * Uses approximate token counting (4 characters per token for English text).
+ */
+/**
+ * Model pricing per 1K tokens (approximate as of 2024)
+ * Format: { input: pricePerMillion, output: pricePerMillion }
+ */
+const MODEL_PRICING = {
+    // Anthropic models
+    'claude-3-5-haiku-20241022': { input: 1.0, output: 5.0 },
+    'claude-3-5-haiku-latest': { input: 1.0, output: 5.0 },
+    'claude-3-5-sonnet-20241022': { input: 3.0, output: 15.0 },
+    'claude-3-5-sonnet-latest': { input: 3.0, output: 15.0 },
+    'claude-3-haiku-20240307': { input: 0.25, output: 1.25 },
+    'claude-3-opus-20240229': { input: 15.0, output: 75.0 },
+    'claude-3-sonnet-20240229': { input: 3.0, output: 15.0 },
+    // OpenAI models
+    'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+    'gpt-4': { input: 30.0, output: 60.0 },
+    'gpt-4-turbo': { input: 10.0, output: 30.0 },
+    'gpt-4o': { input: 2.5, output: 10.0 },
+    'gpt-4o-mini': { input: 0.15, output: 0.6 },
+    // Google models
+    'gemini-1.5-flash': { input: 0.075, output: 0.3 },
+    'gemini-1.5-pro': { input: 1.25, output: 5.0 },
+    'gemini-2.0-flash-exp': { input: 0.075, output: 0.3 }
+};
+/** Default pricing if model not found */
+const DEFAULT_PRICING = { input: 3.0, output: 15.0 };
+/** Average characters per token (approximate for English text) */
+const CHARS_PER_TOKEN = 4;
+/** Typical completion/prompt ratio for code generation tasks */
+const COMPLETION_RATIO = 0.3;
+/**
+ * Estimate token usage and cost for a set of messages
+ *
+ * @param messages - Array of LLM messages
+ * @param model - Model name for pricing lookup
+ * @returns Token estimate with cost
+ */
+export function estimateTokens(messages, model) {
+    // Calculate prompt tokens from all messages using reduce
+    const totalChars = messages.reduce((chars, message) => {
+        // Add content length
+        const contentLength = message.content?.length ?? 0;
+        // Add overhead for message structure (role, etc.)
+        const structureOverhead = 10;
+        // Add tool call overhead if present
+        const toolCallChars = (message.tool_calls ?? []).reduce((toolChars, toolCall) => toolChars + toolCall.name.length + JSON.stringify(toolCall.arguments).length, 0);
+        return chars + contentLength + structureOverhead + toolCallChars;
+    }, 0);
+    const promptTokens = Math.ceil(totalChars / CHARS_PER_TOKEN);
+    const estimatedCompletionTokens = Math.ceil(promptTokens * COMPLETION_RATIO);
+    const totalTokens = promptTokens + estimatedCompletionTokens;
+    // Calculate cost
+    const pricing = MODEL_PRICING[model ?? ''] ?? DEFAULT_PRICING;
+    const inputCost = (promptTokens / 1_000_000) * pricing.input;
+    const outputCost = (estimatedCompletionTokens / 1_000_000) * pricing.output;
+    const totalCost = inputCost + outputCost;
+    return {
+        estimatedCompletionTokens,
+        estimatedCost: {
+            amount: Math.round(totalCost * 10000) / 10000, // Round to 4 decimal places
+            currency: 'USD'
+        },
+        promptTokens,
+        totalTokens
+    };
+}
+/**
+ * Estimate tokens from a single string
+ *
+ * @param text - Text to estimate
+ * @returns Approximate token count
+ */
+export function estimateTokensFromText(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+ * Format token estimate for display
+ *
+ * @param estimate - Token estimate to format
+ * @returns Formatted string
+ */
+export function formatTokenEstimate(estimate) {
+    return [
+        `  Prompt:     ~${estimate.promptTokens.toLocaleString()}`,
+        `  Completion: ~${estimate.estimatedCompletionTokens.toLocaleString()}`,
+        `  Total:      ~${estimate.totalTokens.toLocaleString()}`,
+        `  Cost:       $${estimate.estimatedCost.amount.toFixed(4)} ${estimate.estimatedCost.currency}`
+    ].join('\n');
+}
+/**
+ * Get pricing info for a model
+ *
+ * @param model - Model name
+ * @returns Pricing info or undefined
+ */
+export function getModelPricing(model) {
+    return MODEL_PRICING[model];
+}
+/**
+ * Check if a model has known pricing
+ *
+ * @param model - Model name
+ * @returns True if pricing is available
+ */
+export function hasKnownPricing(model) {
+    return model in MODEL_PRICING;
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/utils/token-estimator.js.map

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

package/dist/utils/tracing.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Distributed Tracing Service
+ *
+ * Provides OpenTelemetry-compatible distributed tracing for the application.
+ *
+ * Features:
+ * - W3C Trace Context propagation
+ * - Span lifecycle management
+ * - Context-aware span creation
+ * - Async context propagation
+ * - Console and OTLP export options
+ */
+import { type SpanAttributes, type SpanData, type SpanOptions, type TraceContext, type TracerConfig } from '../types/tracing.types.js';
+/**
+ * Generate a random trace ID (32 hex characters)
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a random span ID (16 hex characters)
+ */
+export declare function generateSpanId(): string;
+/**
+ * Span class for managing individual spans
+ */
+export declare class Span {
+    private readonly config;
+    private readonly data;
+    private ended;
+    constructor(name: string, context: TraceContext, options: SpanOptions | undefined, config: TracerConfig);
+    /**
+     * Get the span's trace context
+     */
+    getContext(): TraceContext;
+    /**
+     * Get the span ID
+     */
+    getSpanId(): string;
+    /**
+     * Get the trace ID
+     */
+    getTraceId(): string;
+    /**
+     * Set a single attribute
+     */
+    setAttribute(key: string, value: boolean | boolean[] | number | number[] | string | string[]): this;
+    /**
+     * Set multiple attributes
+     */
+    setAttributes(attributes: SpanAttributes): this;
+    /**
+     * Add an event to the span
+     */
+    addEvent(name: string, attributes?: SpanAttributes): this;
+    /**
+     * Set the span status to OK
+     */
+    setOk(): this;
+    /**
+     * Set the span status to ERROR
+     */
+    setError(message?: string): this;
+    /**
+     * Record an exception
+     */
+    recordException(error: Error): this;
+    /**
+     * End the span
+     */
+    end(endTime?: number): void;
+    /**
+     * Check if span is recording
+     */
+    isRecording(): boolean;
+    /**
+     * Get span data (for export)
+     */
+    getData(): SpanData;
+    /**
+     * Get duration in milliseconds
+     */
+    getDuration(): number | undefined;
+}
+/**
+ * Tracer class for creating and managing spans
+ */
+export declare class Tracer {
+    private readonly config;
+    constructor(config?: Partial<TracerConfig>);
+    /**
+     * Check if tracing is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Create a new span
+     */
+    startSpan(name: string, options?: SpanOptions): Span;
+    /**
+     * Get the current active span
+     */
+    getCurrentSpan(): Span | undefined;
+    /**
+     * Get current trace context
+     */
+    getCurrentContext(): TraceContext | undefined;
+    /**
+     * Execute a function within a span
+     */
+    withSpan<T>(name: string, options: SpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;
+    /**
+     * Execute a synchronous function within a span
+     */
+    withSpanSync<T>(name: string, options: SpanOptions, fn: (span: Span) => T): T;
+    /**
+     * Create a trace context
+     */
+    private createContext;
+    /**
+     * Determine if a trace should be sampled
+     */
+    private shouldSample;
+    /**
+     * Shutdown the tracer and flush pending spans
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get tracer configuration
+     */
+    getConfig(): TracerConfig;
+}
+/**
+ * Parse W3C Trace Context header (traceparent)
+ */
+export declare function parseTraceParent(header: string): null | TraceContext;
+/**
+ * Format trace context as W3C Trace Context header (traceparent)
+ */
+export declare function formatTraceParent(context: TraceContext): string;
+/**
+ * Get the global tracer instance
+ */
+export declare function getTracer(config?: Partial<TracerConfig>): Tracer;
+/**
+ * Reset the global tracer and all tracing state (for testing)
+ */
+export declare function resetTracer(): Promise<void>;
+/**
+ * Convenience function to start a span using the global tracer
+ */
+export declare function startSpan(name: string, options?: SpanOptions): Span;
+/**
+ * Convenience function to get the current span
+ */
+export declare function getCurrentSpan(): Span | undefined;
+/**
+ * Convenience function to get current trace context
+ */
+export declare function getCurrentTraceContext(): TraceContext | undefined;
+/**
+ * Decorator for tracing async methods
+ */
+export declare function traced(spanName?: string, options?: Omit<SpanOptions, 'parent'>): (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator for tracing sync methods
+ */
+export declare function tracedSync(spanName?: string, options?: Omit<SpanOptions, 'parent'>): (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/utils/tracing.d.ts.map

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