semantic-primitives 0.1.0

package/dist/types/object-literal/object-literal.d.ts

@@ -0,0 +1,223 @@
+/**
+ * SemanticObjectLiteral
+ * An object literal type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces for:
+ * - Semantic equality comparison with property mappings
+ * - Schema inference
+ * - Domain detection
+ * - Semantic property search
+ * - Sensitive data detection
+ * - Key transformation
+ * - Interface generation
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResultWithMappings, InferSchemaResult, SensitiveResult } from '../../shared/types.ts';
+export type { SemanticEqualsResultWithMappings, InferSchemaResult, SensitiveResult, } from '../../shared/types.ts';
+/** Result of validation against semantic rules */
+export interface ObjectLiteralValidateResult {
+    valid: boolean;
+    violations: {
+        rule: string;
+        field?: string;
+        reason: string;
+    }[];
+}
+/** Result of domain detection */
+export interface DetectDomainResult {
+    domain: string;
+    confidence: number;
+    suggestedInterface?: string;
+}
+/** Result of property search */
+export interface PropertySearchResult {
+    key: string;
+    value: unknown;
+    relevance: number;
+}
+/** Suggestion for missing property */
+export interface MissingPropertySuggestion {
+    property: string;
+    type: string;
+    reason: string;
+}
+/** Key naming conventions */
+export type KeyConvention = 'camelCase' | 'snake_case' | 'PascalCase' | 'kebab-case';
+/**
+ * SemanticObjectLiteral - Object literal with LLM-powered semantic understanding
+ *
+ * Unlike SemanticObject which wraps general objects, SemanticObjectLiteral
+ * focuses on ad-hoc data shapes with schema inference and domain detection.
+ *
+ * @template T - The type of the underlying object
+ */
+export declare class SemanticObjectLiteral<T extends object = object> {
+    private readonly data;
+    private readonly context?;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticObjectLiteral from a plain object.
+     *
+     * @param obj - Object literal
+     * @param context - Optional context about the object's purpose
+     * @returns SemanticObjectLiteral instance
+     *
+     * @example
+     * SemanticObjectLiteral.from({ name: "John", age: 30 }, "user data")
+     */
+    static from<T extends object>(obj: T, context?: string, client?: LLMClient): SemanticObjectLiteral<T>;
+    /**
+     * Get the underlying object value.
+     *
+     * @returns Plain object
+     */
+    valueOf(): T;
+    /**
+     * Check if two object literals are semantically equivalent.
+     * Handles property name synonyms and structural variations.
+     *
+     * @param other - Object to compare
+     * @returns Equivalence result with property mappings
+     *
+     * @example
+     * obj1.semanticallyEquals({ firstName: "John" })
+     * // { equivalent: true, mappings: { "name": "firstName" }, confidence: 0.9 }
+     */
+    semanticallyEquals(other: SemanticObjectLiteral<T> | object): Promise<SemanticEqualsResultWithMappings>;
+    /**
+     * Infer the schema/type of this object.
+     *
+     * @returns Inferred schema with name, properties, required/optional fields
+     *
+     * @example
+     * obj.inferSchema()
+     * // {
+     * //   name: "User",
+     * //   properties: { name: "string", age: "number" },
+     * //   required: ["name"],
+     * //   optional: ["age"],
+     * //   confidence: 0.92
+     * // }
+     */
+    inferSchema(): Promise<InferSchemaResult>;
+    /**
+     * Validate the object against semantic rules.
+     *
+     * @param rules - Natural language validation rules
+     * @returns Validation result with violations
+     *
+     * @example
+     * user.validateWithRules([
+     *   "email must be valid",
+     *   "age must be reasonable for a human"
+     * ])
+     */
+    validateWithRules(rules: string[]): Promise<ObjectLiteralValidateResult>;
+    /**
+     * Detect what domain/entity this object represents.
+     *
+     * @returns Domain detection result
+     *
+     * @example
+     * obj.detectDomain()
+     * // { domain: "user-profile", confidence: 0.92, suggestedInterface: "interface User { ... }" }
+     */
+    detectDomain(): Promise<DetectDomainResult>;
+    /**
+     * Find properties matching a semantic description.
+     *
+     * @param description - What to look for
+     * @returns Matching properties with relevance scores
+     *
+     * @example
+     * obj.findProperties("contact information")
+     * // [{ key: "email", value: "...", relevance: 0.95 }]
+     */
+    findProperties(description: string): Promise<PropertySearchResult[]>;
+    /**
+     * Suggest missing properties based on the object's apparent purpose.
+     *
+     * @returns Suggested properties
+     *
+     * @example
+     * user.suggestMissingProperties()
+     * // [{ property: "createdAt", type: "Date", reason: "Common in user records" }]
+     */
+    suggestMissingProperties(): Promise<MissingPropertySuggestion[]>;
+    /**
+     * Check if a property contains sensitive data.
+     *
+     * @param propertyPath - Property to check
+     * @returns Sensitivity assessment
+     *
+     * @example
+     * obj.isSensitive("ssn")
+     * // { sensitive: true, type: "PII", recommendation: "encrypt" }
+     */
+    isSensitive(propertyPath: string): Promise<SensitiveResult>;
+    /**
+     * Transform property names to a naming convention.
+     *
+     * @param convention - Target convention
+     * @returns Transformed object literal
+     *
+     * @example
+     * obj.transformKeys("snake_case")
+     */
+    transformKeys(convention: KeyConvention): Promise<SemanticObjectLiteral>;
+    /**
+     * Generate a TypeScript interface for this object.
+     *
+     * @param name - Interface name
+     * @returns TypeScript interface code
+     *
+     * @example
+     * obj.generateInterface("User")
+     * // "interface User { name: string; age?: number; }"
+     */
+    generateInterface(name: string): Promise<string>;
+    /**
+     * Summarize the object contents.
+     *
+     * @returns Human-readable summary
+     */
+    summarize(): Promise<string>;
+    /**
+     * Get all keys of the object
+     */
+    keys(): string[];
+    /**
+     * Get all values of the object
+     */
+    values(): unknown[];
+    /**
+     * Get all entries of the object
+     */
+    entries(): [string, unknown][];
+    /**
+     * Check if object has a property (exact match)
+     */
+    has(key: string): boolean;
+    /**
+     * Get a property value (exact match)
+     */
+    get<K extends keyof T>(key: K): T[K];
+    /**
+     * Get the context string if provided
+     */
+    getContext(): string | undefined;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): T;
+    /**
+     * Helper to get nested value by dot-notation path
+     */
+    private getNestedValue;
+}
+//# sourceMappingURL=object-literal.d.ts.map

package/dist/types/object-literal/object-literal.d.ts.map

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

package/dist/types/object-literal/prompts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompts for SemanticObjectLiteral LLM operations
+ * These prompts enable semantic operations on object literal data structures
+ */
+/**
+ * System prompt for object literal semantic operations
+ */
+export declare const OBJECT_LITERAL_SYSTEM_PROMPT = "You are a semantic object literal analyzer. Your task is to analyze ad-hoc object structures and their properties to provide semantic understanding.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Consider property names, values, and their semantic meanings\n- Understand common naming conventions (camelCase, snake_case, etc.)\n- Recognize synonymous property names (e.g., \"email\" and \"emailAddress\")\n- Detect patterns that indicate domain/entity types\n- Provide confidence scores from 0.0 to 1.0\n- Be precise and consistent in your analysis";
+/**
+ * Prompt for semantic equality comparison with property mappings
+ */
+export declare function createSemanticallyEqualsPrompt(obj1: object, obj2: object): string;
+/**
+ * Prompt for schema inference
+ */
+export declare function createInferSchemaPrompt(obj: object): string;
+/**
+ * Prompt for validation against semantic rules
+ */
+export declare function createValidateWithRulesPrompt(obj: object, rules: string[]): string;
+/**
+ * Prompt for domain/entity detection
+ */
+export declare function createDetectDomainPrompt(obj: object): string;
+/**
+ * Prompt for finding properties by semantic description
+ */
+export declare function createFindPropertiesPrompt(obj: object, description: string): string;
+/**
+ * Prompt for suggesting missing properties
+ */
+export declare function createSuggestMissingPropertiesPrompt(obj: object): string;
+/**
+ * Prompt for sensitive data detection
+ */
+export declare function createIsSensitivePrompt(obj: object, propertyPath: string): string;
+/**
+ * Prompt for key transformation
+ */
+export declare function createTransformKeysPrompt(obj: object, convention: 'camelCase' | 'snake_case' | 'PascalCase' | 'kebab-case'): string;
+/**
+ * Prompt for TypeScript interface generation
+ */
+export declare function createGenerateInterfacePrompt(obj: object, name: string): string;
+/**
+ * Prompt for summarization
+ */
+export declare function createSummarizePrompt(obj: object): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/types/object-literal/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/object-literal/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,4BAA4B,ylBAUI,CAAC;AAE9C;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoB3D;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAgBlF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgB5D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAoBnF;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBxE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAmBjF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,GACnE,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB/E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAezD"}

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

@@ -0,0 +1,6 @@
+/**
+ * SemanticPromise module
+ * LLM-enhanced Promise type with semantic understanding
+ */
+export { SemanticPromise, type PromiseState, type PromiseStatus, type InferredOperation, type RetryOptions, type ValidationResult, type SemanticErrorAnalysis, type SemanticEqualsResult, } from './promise.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/promise/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/types/promise/promise.d.ts

@@ -0,0 +1,240 @@
+/**
+ * SemanticPromise
+ * A Promise type with LLM-powered semantic understanding
+ *
+ * Implements:
+ * - Comparable<Promise<unknown>, SemanticEqualsResult> - Semantic equality comparison
+ * - Explainable - Operation descriptions
+ * - Extended Promise functionality with semantic retry, transform, validate, and fallback
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult } from '../../shared/types.ts';
+import { SemanticError } from '../error/error.ts';
+export type { SemanticEqualsResult } from '../../shared/types.ts';
+/** Promise state */
+export type PromiseState = 'pending' | 'fulfilled' | 'rejected';
+/** Status information for a promise */
+export interface PromiseStatus {
+    state: PromiseState;
+    description: string;
+    elapsed?: string;
+}
+/** Inferred operation details */
+export interface InferredOperation {
+    operation: string;
+    resource?: string;
+    action?: string;
+}
+/** Retry options */
+export interface RetryOptions {
+    maxAttempts: number;
+    when?: string;
+    backoff?: 'linear' | 'exponential' | 'fixed';
+}
+/** Validation result */
+export interface ValidationResult {
+    valid: boolean;
+    violations: string[];
+    confidence: number;
+}
+/** Semantic error analysis result */
+export interface SemanticErrorAnalysis {
+    explanation: string;
+    rootCause: string;
+    suggestedFixes: string[];
+    isRetryable: boolean;
+}
+/**
+ * SemanticPromise - Promise with LLM-powered semantic understanding
+ *
+ * Wraps a native Promise and adds intelligent error handling,
+ * meaningful timeout messages, and operation descriptions.
+ */
+export declare class SemanticPromise<T> implements PromiseLike<T> {
+    readonly [Symbol.toStringTag] = "SemanticPromise";
+    private readonly _promise;
+    private readonly _description?;
+    private readonly _client;
+    private readonly _startTime;
+    private _state;
+    private _resolvedValue?;
+    private constructor();
+    /**
+     * Create a SemanticPromise from a regular Promise.
+     *
+     * @param promise - Promise to wrap
+     * @param description - Description of what the promise does
+     * @param client - Optional LLM client
+     * @returns SemanticPromise instance
+     *
+     * @example
+     * SemanticPromise.from(fetch(url), "fetching user data")
+     */
+    static from<T>(promise: Promise<T>, description?: string, client?: LLMClient): SemanticPromise<T>;
+    /**
+     * Create a resolved SemanticPromise.
+     *
+     * @param value - Value to resolve with
+     * @param description - Description of the value
+     * @param client - Optional LLM client
+     */
+    static resolve<T>(value: T, description?: string, client?: LLMClient): SemanticPromise<T>;
+    /**
+     * Create a rejected SemanticPromise.
+     *
+     * @param reason - Rejection reason
+     * @param description - Description of the operation
+     * @param client - Optional LLM client
+     */
+    static reject<T = never>(reason: unknown, description?: string, client?: LLMClient): SemanticPromise<T>;
+    /**
+     * Implementation of PromiseLike.then for compatibility with native Promise
+     */
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): SemanticPromise<TResult1 | TResult2>;
+    /**
+     * Implementation of Promise.catch for compatibility
+     */
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): SemanticPromise<T | TResult>;
+    /**
+     * Implementation of Promise.finally for compatibility
+     */
+    finally(onfinally?: (() => void) | null): SemanticPromise<T>;
+    /**
+     * Check if two promises resolve to semantically equivalent values.
+     *
+     * @param other - Promise to compare
+     * @returns Equivalence result (after both resolve)
+     *
+     * @example
+     * promise1.semanticallyEquals(promise2)
+     * // { equivalent: true, confidence: 0.9 }
+     */
+    semanticallyEquals(other: Promise<unknown>): Promise<SemanticEqualsResult>;
+    /**
+     * Add timeout with meaningful error message.
+     *
+     * @param ms - Timeout in milliseconds
+     * @param context - Context for error message
+     * @returns Promise that rejects with semantic error on timeout
+     *
+     * @example
+     * apiCall.timeout(5000, "database connection")
+     */
+    timeout(ms: number, context?: string): SemanticPromise<T>;
+    /**
+     * Handle errors with semantic understanding.
+     *
+     * @param handler - Error handler with semantic error
+     * @returns Promise with error handling
+     *
+     * @example
+     * promise.catchSemantic(async (error) => {
+     *   console.log(error.explanation);
+     *   return defaultValue;
+     * })
+     */
+    catchSemantic<U>(handler: (error: SemanticError, analysis: SemanticErrorAnalysis) => U | Promise<U>): SemanticPromise<T | U>;
+    /**
+     * Explain what operation this promise represents.
+     *
+     * @returns Operation description
+     *
+     * @example
+     * promise.explain()
+     * // "Fetching user profile from /api/users/123"
+     */
+    explain(): string;
+    /**
+     * Get the current status with semantic description.
+     *
+     * @returns Status information
+     *
+     * @example
+     * promise.status()
+     * // { state: "pending", description: "Waiting for API response", elapsed: "2.3s" }
+     */
+    status(): PromiseStatus;
+    /**
+     * Add semantic retry logic.
+     *
+     * @param options - Retry options
+     * @returns Promise with retry behavior
+     *
+     * @example
+     * apiCall.retry({
+     *   maxAttempts: 3,
+     *   when: "network error or timeout",
+     *   backoff: "exponential"
+     * })
+     */
+    retry(options: RetryOptions): SemanticPromise<T>;
+    private executeWithRetry;
+    /**
+     * Transform the result with semantic understanding.
+     *
+     * @param instruction - Natural language transformation
+     * @returns Transformed promise
+     *
+     * @example
+     * userPromise.transform("extract just the name and email")
+     */
+    transform<U>(instruction: string): SemanticPromise<U>;
+    /**
+     * Validate the result against semantic rules.
+     *
+     * @param rules - Validation rules
+     * @returns Promise that rejects if validation fails
+     *
+     * @example
+     * response.validateResult(["should contain user data", "email must be valid"])
+     */
+    validateResult(rules: string[]): SemanticPromise<T>;
+    /**
+     * Provide a fallback with semantic matching.
+     *
+     * @param fallbackValue - Fallback value or function
+     * @param when - When to use fallback
+     * @returns Promise with fallback
+     *
+     * @example
+     * userPromise.fallback(defaultUser, "when user not found")
+     */
+    fallback<U>(fallbackValue: U | (() => U), when?: string): SemanticPromise<T | U>;
+    /**
+     * Log progress with semantic descriptions.
+     *
+     * @param logger - Logger function
+     * @returns Same promise with logging
+     *
+     * @example
+     * promise.withLogging(console.log)
+     * // Logs: "Starting: fetch user data"
+     * // Logs: "Completed: fetch user data (245ms)"
+     */
+    withLogging(logger: (message: string) => void): SemanticPromise<T>;
+    private generateLogMessage;
+    /**
+     * Infer what this promise is likely doing.
+     *
+     * @returns Inferred operation type
+     *
+     * @example
+     * promise.inferOperation()
+     * // { operation: "api-call", resource: "user", action: "read" }
+     */
+    inferOperation(): InferredOperation;
+    /**
+     * Asynchronously infer operation with LLM assistance.
+     */
+    inferOperationAsync(): Promise<InferredOperation>;
+    private inferFromDescription;
+    /**
+     * Get the underlying promise.
+     */
+    toPromise(): Promise<T>;
+    /**
+     * Get the description of this promise.
+     */
+    getDescription(): string | undefined;
+}
+//# sourceMappingURL=promise.d.ts.map

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

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

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

@@ -0,0 +1,45 @@
+/**
+ * Prompts for SemanticPromise LLM operations
+ * These prompts enable intelligent error handling, result transformation, and operation inference
+ */
+/**
+ * System prompt for promise analysis tasks
+ */
+export declare const PROMISE_SYSTEM_PROMPT = "You are an expert at analyzing asynchronous operations, understanding promise behaviors, and providing semantic insights about async code.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Analyze promise descriptions, values, and errors to understand their semantics\n- Consider common async patterns in software development\n- Provide meaningful, contextual responses\n- Be precise with confidence scores based on available information";
+/**
+ * Prompt template for semantic equality comparison between promise results
+ */
+export declare function createSemanticallyEqualsPrompt(value1: unknown, value2: unknown, description1?: string, description2?: string): string;
+/**
+ * Prompt template for generating timeout error messages
+ */
+export declare function createTimeoutErrorPrompt(ms: number, context?: string, description?: string): string;
+/**
+ * Prompt template for semantic error analysis
+ */
+export declare function createCatchSemanticPrompt(error: Error, description?: string): string;
+/**
+ * Prompt template for determining if error matches retry conditions
+ */
+export declare function createShouldRetryPrompt(error: Error, whenCondition: string, attemptNumber: number): string;
+/**
+ * Prompt template for transforming promise results
+ */
+export declare function createTransformPrompt(value: unknown, instruction: string): string;
+/**
+ * Prompt template for validating promise results
+ */
+export declare function createValidateResultPrompt(value: unknown, rules: string[]): string;
+/**
+ * Prompt template for determining if fallback should be used
+ */
+export declare function createShouldUseFallbackPrompt(error: Error, whenCondition: string): string;
+/**
+ * Prompt template for inferring what a promise operation does
+ */
+export declare function createInferOperationPrompt(description?: string, resolvedValue?: unknown): string;
+/**
+ * Prompt template for generating logging messages
+ */
+export declare function createLoggingMessagePrompt(phase: 'start' | 'complete' | 'error', description?: string, elapsed?: number, error?: Error): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/promise/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB,ueAQiC,CAAC;AAEpE;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,GACpB,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,CAAC,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,OAAO,GACtB,MAAM,CA6BR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,EACrC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK,GACZ,MAAM,CA2BR"}

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

@@ -0,0 +1,5 @@
+/**
+ * SemanticRecord - Record type with LLM-powered semantic understanding
+ */
+export { SemanticRecord, type RecordSemanticEqualsResult, type ValidateKeysResult, type ValidateValuesResult, type InvalidEntry, type RecordInferPurposeResult, type SemanticGetResult, type MissingSuggestion, } from './record.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/record/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,45 @@
+/**
+ * Prompts for SemanticRecord LLM operations
+ * These prompts enable semantic operations on Record key-value collections
+ */
+/**
+ * System prompt for record semantic operations
+ */
+export declare const RECORD_SYSTEM_PROMPT = "You are a semantic record analyzer. Your task is to analyze Record key-value pairs to provide semantic understanding of keys, values, and their relationships.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Consider key meanings, synonyms, and naming conventions\n- Understand value relationships and patterns\n- Provide confidence scores from 0.0 to 1.0\n- Be precise and consistent in your analysis\n- Handle both primitive and complex object values\n- Records are uniform dictionaries where keys follow consistent patterns";
+/**
+ * Prompt for semantic key lookup
+ */
+export declare function createSemanticGetPrompt(keys: string[], query: string, context?: Record<string, unknown>): string;
+/**
+ * Prompt for semantic equality comparison
+ */
+export declare function createSemanticallyEqualsPrompt(record1Entries: [string, unknown][], record2Entries: [string, unknown][]): string;
+/**
+ * Prompt for validating keys
+ */
+export declare function createValidateKeysPrompt(keys: string[], rules: string[]): string;
+/**
+ * Prompt for validating values
+ */
+export declare function createValidateValuesPrompt(entries: [string, unknown][], rules: string[]): string;
+/**
+ * Prompt for inferring record purpose
+ */
+export declare function createInferPurposePrompt(entries: [string, unknown][]): string;
+/**
+ * Prompt for semantic filtering
+ */
+export declare function createSemanticFilterPrompt(entries: [string, unknown][], criteria: string): string;
+/**
+ * Prompt for suggesting missing keys
+ */
+export declare function createSuggestMissingKeysPrompt(entries: [string, unknown][]): string;
+/**
+ * Prompt for grouping entries
+ */
+export declare function createGroupByPrompt(entries: [string, unknown][], criteria: string): string;
+/**
+ * Prompt for summarization
+ */
+export declare function createSummarizePrompt(entries: [string, unknown][], recordSize: number): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/record/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,ikBAUwC,CAAC;AAE1E;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAClC,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5B,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAiB7E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5B,QAAQ,EAAE,MAAM,GACf,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC3B,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5B,QAAQ,EAAE,MAAM,GACf,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5B,UAAU,EAAE,MAAM,GACjB,MAAM,CAiBR"}