semantic-primitives 0.1.0

package/dist/types/tuple/tuple.d.ts

@@ -0,0 +1,221 @@
+/**
+ * SemanticTuple
+ * A tuple type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<T> - Base semantic wrapper
+ * - Comparable<SemanticTuple<T>> - Semantic equality comparison
+ * - Explainable - Human-readable explanations
+ * - PatternDetectable - Pattern detection
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResultWithReason, DetectPatternResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, Explainable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResultWithReason, DetectPatternResult, } from '../../shared/types.ts';
+/** Result of inferring positional meaning */
+export interface PositionalMeaning {
+    meaning: string;
+    confidence: number;
+}
+/** Result of inferPositionalMeaning */
+export interface InferPositionalMeaningResult {
+    positions: Record<number, PositionalMeaning>;
+    overallConfidence: number;
+}
+/** Result of validateRelationship */
+export interface ValidateRelationshipResult {
+    valid: boolean;
+    violations: string[];
+}
+/** Result of toObject */
+export interface ToObjectResult {
+    object: Record<string, unknown>;
+    labelsUsed: string[];
+    confidence: number;
+}
+/** Result of getByLabel */
+export interface GetByLabelResult<T> {
+    value: T | undefined;
+    matchedPosition: number | undefined;
+    confidence: number;
+}
+/** Issue found during structure validation */
+export interface StructureIssue {
+    position: number;
+    expected: string;
+    actual: string;
+}
+/** Result of validateStructure */
+export interface ValidateStructureResult {
+    valid: boolean;
+    issues: StructureIssue[];
+}
+/**
+ * SemanticTuple - Tuple with LLM-powered semantic understanding
+ *
+ * Unlike traditional tuples that only support index-based operations,
+ * semantic tuples can understand positional meaning, detect patterns,
+ * and validate relationships between elements.
+ *
+ * @template T - The tuple type
+ */
+export declare class SemanticTuple<T extends unknown[]> implements Semantic<T>, Comparable<SemanticTuple<T> | unknown[], SemanticEqualsResultWithReason>, Explainable {
+    private readonly elements;
+    private readonly client;
+    private readonly labels;
+    private constructor();
+    /**
+     * Create a SemanticTuple from values with optional position labels.
+     *
+     * @param values - Tuple values
+     * @param labels - Optional labels for each position
+     * @returns SemanticTuple instance
+     *
+     * @example
+     * SemanticTuple.from([37.7749, -122.4194], ["latitude", "longitude"])
+     * SemanticTuple.from(["John", 30, true], ["name", "age", "active"])
+     */
+    static from<T extends unknown[]>(values: T, labels?: string[], client?: LLMClient): SemanticTuple<T>;
+    /**
+     * Create an empty SemanticTuple
+     */
+    static empty<T extends unknown[] = []>(client?: LLMClient): SemanticTuple<T>;
+    /**
+     * Get the underlying tuple value
+     */
+    valueOf(): T;
+    /**
+     * Get the length of the tuple
+     */
+    get length(): number;
+    /**
+     * Get the labels if provided
+     */
+    getLabels(): string[] | undefined;
+    /**
+     * Get element at index
+     */
+    at(index: number): T[number] | undefined;
+    /**
+     * Check if two tuples are semantically equivalent.
+     * Considers position meanings, not just values.
+     *
+     * @param other - Tuple to compare
+     * @returns Equivalence result with confidence and reason
+     *
+     * @example
+     * SemanticTuple.from([lat, lng]).semanticallyEquals([lat, lng, alt])
+     * // { equivalent: false, reason: "Different arity (2 vs 3)" }
+     */
+    semanticallyEquals(other: SemanticTuple<T> | unknown[]): Promise<SemanticEqualsResultWithReason>;
+    /**
+     * Infer the meaning of each position in the tuple.
+     *
+     * @param context - Optional context to improve inference
+     * @returns Position meanings with confidence scores
+     *
+     * @example
+     * SemanticTuple.from([37.7749, -122.4194]).inferPositionalMeaning()
+     * // { positions: { 0: { meaning: "latitude", confidence: 0.9 }, 1: { meaning: "longitude", confidence: 0.9 } } }
+     */
+    inferPositionalMeaning(context?: string): Promise<InferPositionalMeaningResult>;
+    /**
+     * Validate relationships between tuple elements.
+     *
+     * @param rules - Validation rules
+     * @returns Validation result with any violations
+     *
+     * @example
+     * SemanticTuple.from([startDate, endDate]).validateRelationship([
+     *   "end should be after start"
+     * ])
+     * // { valid: true, violations: [] }
+     */
+    validateRelationship(rules: string[]): Promise<ValidateRelationshipResult>;
+    /**
+     * Detect what type of tuple this is (coordinate, range, RGB, etc.).
+     *
+     * @returns Detected tuple pattern with confidence
+     *
+     * @example
+     * SemanticTuple.from([255, 128, 0]).detectPattern()
+     * // { pattern: "RGB color", confidence: 0.95, suggestedType: "Color" }
+     */
+    detectPattern(): Promise<DetectPatternResult>;
+    /**
+     * Convert tuple to a labeled object.
+     *
+     * @param labels - Optional custom labels (uses inferred or provided if not specified)
+     * @returns Object with labeled properties
+     *
+     * @example
+     * SemanticTuple.from([37.7749, -122.4194]).toObject()
+     * // { latitude: 37.7749, longitude: -122.4194 }
+     */
+    toObject(labels?: string[]): Promise<ToObjectResult>;
+    /**
+     * Access an element by semantic label instead of index.
+     *
+     * @param label - Semantic label for the position
+     * @returns Value at that position with match info
+     *
+     * @example
+     * coords.getByLabel("latitude") // { value: 37.7749, matchedPosition: 0, confidence: 0.95 }
+     */
+    getByLabel(label: string): Promise<GetByLabelResult<T[number]>>;
+    /**
+     * Validate that the tuple matches expected structure.
+     *
+     * @param expectedTypes - Expected type for each position
+     * @returns Validation result with issues
+     *
+     * @example
+     * tuple.validateStructure(["string", "number", "boolean"])
+     * // { valid: true, issues: [] }
+     */
+    validateStructure(expectedTypes: string[]): Promise<ValidateStructureResult>;
+    /**
+     * Explain what this tuple represents.
+     *
+     * @param context - Optional context for more relevant explanation
+     * @returns Human-readable explanation
+     *
+     * @example
+     * SemanticTuple.from([200, "OK"]).explain()
+     * // "HTTP status response: status code 200 with message 'OK'"
+     */
+    explain(context?: string): Promise<string>;
+    /**
+     * Map elements and return a new SemanticTuple
+     */
+    map<U>(fn: (element: T[number], index: number) => U): SemanticTuple<U[]>;
+    /**
+     * Execute a function for each element
+     */
+    forEach(fn: (element: T[number], index: number) => void): void;
+    /**
+     * Check if some element satisfies the predicate
+     */
+    some(predicate: (element: T[number], index: number) => boolean): boolean;
+    /**
+     * Check if every element satisfies the predicate
+     */
+    every(predicate: (element: T[number], index: number) => boolean): boolean;
+    /**
+     * Reduce the tuple to a single value
+     */
+    reduce<U>(fn: (acc: U, element: T[number], index: number) => U, initial: U): U;
+    /**
+     * Iterator support
+     */
+    [Symbol.iterator](): Iterator<T[number]>;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): T;
+}
+//# sourceMappingURL=tuple.d.ts.map

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

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

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

@@ -0,0 +1,5 @@
+/**
+ * SemanticUnknown exports
+ */
+export { SemanticUnknown, type BasicType, type UnknownInferTypeResult, type TypeSuggestion, type ValidateShapeResult, type GenerateTypeGuardResult, type MatchesResult, type NarrowToResult, } from './unknown.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/unknown/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,45 @@
+/**
+ * Prompts for SemanticUnknown LLM operations
+ * These prompts are used to analyze and reason about unknown values
+ */
+/**
+ * System prompt for unknown value interpretation tasks
+ */
+export declare const UNKNOWN_SYSTEM_PROMPT = "You are a semantic type analyzer. Your task is to analyze unknown values, infer their types, and help safely narrow them to proper TypeScript types.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nKey concepts:\n- \"unknown\" represents type-safe uncertainty\n- Type inference should consider value structure, patterns, and common conventions\n- Type guards help safely narrow unknown values\n- Confidence scores from 0.0 to 1.0 indicate certainty\n\nGuidelines:\n- Analyze value structure to determine probable types\n- Consider common naming patterns and data shapes\n- Suggest practical TypeScript types when possible\n- Generate safe type guard code that checks all necessary conditions\n- Be conservative with confidence scores for ambiguous values";
+/**
+ * Prompt template for inferring the type of an unknown value
+ */
+export declare function createInferTypePrompt(value: unknown, context?: {
+    source?: string;
+}): string;
+/**
+ * Prompt template for suggesting possible TypeScript types
+ */
+export declare function createSuggestTypesPrompt(value: unknown, limit?: number): string;
+/**
+ * Prompt template for validating value shape
+ */
+export declare function createValidateShapePrompt(value: unknown, description: string): string;
+/**
+ * Prompt template for generating a type guard function
+ */
+export declare function createGenerateTypeGuardPrompt(value: unknown): string;
+/**
+ * Prompt template for safe property access
+ */
+export declare function createSafeAccessPrompt(value: unknown, path: string): string;
+/**
+ * Prompt template for checking if value matches a description
+ */
+export declare function createMatchesPrompt(value: unknown, description: string): string;
+/**
+ * Prompt template for narrowing to a specific type
+ */
+export declare function createNarrowToPrompt(value: unknown, typeName: string, validator?: string[]): string;
+/**
+ * Prompt template for explaining what an unknown value appears to be
+ */
+export declare function createExplainPrompt(value: unknown, context?: {
+    source?: string;
+}): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/unknown/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB,sxBAe4B,CAAC;AAE/D;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CAwBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,KAAK,SAAI,GACR,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAepE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,MAAM,CAwBR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CAwBR"}

package/dist/types/unknown/unknown.d.ts

@@ -0,0 +1,220 @@
+/**
+ * SemanticUnknown
+ * An unknown type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<unknown> - Base semantic wrapper
+ * - Explainable - Human-readable explanation
+ * - TypeInferable - Type inference capabilities
+ *
+ * Core Principle: unknown represents type-safe uncertainty - semantic
+ * operations help infer types and generate proper type guards.
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { Semantic, Explainable, TypeInferable } from '../../shared/interfaces.ts';
+import type { ConfidenceResult, InferTypeResult } from '../../shared/types.ts';
+/** Basic JavaScript types that can be inferred */
+export type BasicType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'undefined' | 'function';
+/** Result of type inference */
+export interface UnknownInferTypeResult extends InferTypeResult {
+    type: BasicType;
+    shape?: string;
+    confidence: number;
+}
+/** Type suggestion with confidence and reason */
+export interface TypeSuggestion extends ConfidenceResult {
+    type: string;
+    reason?: string;
+}
+/** Result of shape validation */
+export interface ValidateShapeResult {
+    matches: boolean;
+    missingFields: string[];
+    extraFields: string[];
+}
+/** Result of type guard generation */
+export interface GenerateTypeGuardResult {
+    code: string;
+    typeName: string;
+}
+/** Result of matches check */
+export interface MatchesResult extends ConfidenceResult {
+    matches: boolean;
+}
+/** Result of narrowTo operation */
+export type NarrowToResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * SemanticUnknown - Unknown with LLM-powered semantic understanding
+ *
+ * Unlike plain unknown that only represents type uncertainty,
+ * SemanticUnknown can infer types, validate shapes, generate type guards,
+ * and help safely narrow unknown values to proper types.
+ *
+ * Implements:
+ * - Semantic<unknown> - valueOf() returns the wrapped value
+ * - Explainable - explain() for human-readable description
+ * - TypeInferable - inferType() for type inference
+ */
+export declare class SemanticUnknown implements Semantic<unknown>, Explainable, TypeInferable {
+    private readonly value;
+    private readonly context;
+    private readonly client;
+    private constructor();
+    /**
+     * Wrap an unknown value with semantic capabilities.
+     *
+     * @param value - The unknown value
+     * @param context - Optional context about the value's source
+     * @param client - Optional LLM client for dependency injection
+     * @returns SemanticUnknown wrapper
+     *
+     * @example
+     * SemanticUnknown.from(JSON.parse(data), { source: "API response" })
+     */
+    static from(value: unknown, context?: {
+        source?: string;
+    }, client?: LLMClient): SemanticUnknown;
+    /**
+     * Infer the most likely type of this unknown value.
+     *
+     * @returns Type inference with confidence
+     *
+     * @example
+     * SemanticUnknown.from({ id: 1, name: "test" }).inferType()
+     * // {
+     * //   type: "object",
+     * //   shape: "{ id: number; name: string }",
+     * //   confidence: 0.95
+     * // }
+     */
+    inferType(): Promise<UnknownInferTypeResult>;
+    /**
+     * Suggest possible TypeScript types this value could be.
+     *
+     * @param limit - Maximum number of suggestions (default: 3)
+     * @returns Type suggestions ranked by likelihood
+     *
+     * @example
+     * unknownValue.suggestTypes(3)
+     * // [
+     * //   { type: "User", confidence: 0.9, reason: "Has typical user fields" },
+     * //   { type: "{ name: string; email: string }", confidence: 0.85 }
+     * // ]
+     */
+    suggestTypes(limit?: number): Promise<TypeSuggestion[]>;
+    /**
+     * Validate the value has a specific shape.
+     *
+     * @param description - Natural language description of expected shape
+     * @returns Validation result
+     *
+     * @example
+     * unknownValue.validateShape("user object with name and email")
+     * // { matches: true, missingFields: [], extraFields: ["age"] }
+     */
+    validateShape(description: string): Promise<ValidateShapeResult>;
+    /**
+     * Generate a type guard function for this value's inferred type.
+     *
+     * @returns Generated type guard code
+     *
+     * @example
+     * unknownValue.generateTypeGuard()
+     * // {
+     * //   code: "function isUser(x: unknown): x is User { ... }",
+     * //   typeName: "User"
+     * // }
+     */
+    generateTypeGuard(): Promise<GenerateTypeGuardResult>;
+    /**
+     * Safely access a property with semantic understanding.
+     *
+     * @param path - Property path or semantic description
+     * @returns Wrapped property value or undefined
+     *
+     * @example
+     * unknownValue.safeAccess("user's email address")
+     * // SemanticUnknown containing the email, or undefined
+     */
+    safeAccess(path: string): Promise<SemanticUnknown | undefined>;
+    /**
+     * Check if the value matches a semantic description.
+     *
+     * @param description - Description of what the value should be
+     * @returns Match result
+     *
+     * @example
+     * unknownValue.matches("array of user objects")
+     * // { matches: true, confidence: 0.92 }
+     */
+    matches(description: string): Promise<MatchesResult>;
+    /**
+     * Narrow the unknown to a specific type with validation.
+     *
+     * @param typeName - Name of the expected type
+     * @param validator - Optional custom validation rules
+     * @returns Narrowed value or error
+     *
+     * @example
+     * unknownValue.narrowTo("User", ["must have email", "id must be positive"])
+     */
+    narrowTo<T>(typeName: string, validator?: string[]): Promise<NarrowToResult<T>>;
+    /**
+     * Explain what this unknown value appears to be.
+     *
+     * @returns Human-readable explanation
+     *
+     * @example
+     * unknownValue.explain()
+     * // "This appears to be a user profile object with personal information..."
+     */
+    explain(): Promise<string>;
+    /**
+     * Get the underlying unknown value.
+     *
+     * @returns The wrapped value
+     */
+    valueOf(): unknown;
+    /**
+     * Check if the value is "empty" (null, undefined, empty string/array/object).
+     *
+     * @returns Whether the value is semantically empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the context/source for this unknown value.
+     *
+     * @returns The context object or undefined
+     */
+    getContext(): {
+        source?: string;
+    } | undefined;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        value: unknown;
+        context?: {
+            source?: string;
+        };
+    };
+    /**
+     * Try direct property access for simple dot-notation paths
+     */
+    private tryDirectAccess;
+    /**
+     * Get simple type without LLM for primitive values
+     */
+    private getSimpleType;
+}
+//# sourceMappingURL=unknown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unknown.d.ts","sourceRoot":"","sources":["../../../src/types/unknown/unknown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,aAAa,EACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAa/E,kDAAkD;AAClD,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,WAAW,GACX,UAAU,CAAC;AAEf,+BAA+B;AAC/B,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8BAA8B;AAC9B,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mCAAmC;AACnC,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,qBAAa,eACX,YAAW,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,aAAa;IAExD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC,OAAO;IAUP;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,CACT,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAC7B,MAAM,CAAC,EAAE,SAAS,GACjB,eAAe;IAIlB;;;;;;;;;;;;OAYG;IACG,SAAS,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAmBlD;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,KAAK,SAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAexD;;;;;;;;;OASG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYtE;;;;;;;;;;;OAWG;IACG,iBAAiB,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAY3D;;;;;;;;;OASG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IA6BpE;;;;;;;;;OASG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAY1D;;;;;;;;;OASG;IACG,QAAQ,CAAC,CAAC,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAqB7B;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAqBhC;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAmBlB;;;;OAIG;IACH,UAAU,IAAI;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAI7C;;OAEG;IACH,QAAQ,IAAI,MAAM;IAclB;;OAEG;IACH,MAAM,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;IAO3D;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;OAEG;IACH,OAAO,CAAC,aAAa;CA0BtB"}

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

@@ -0,0 +1,7 @@
+/**
+ * SemanticURL Module
+ * LLM-enhanced URL type with semantic understanding
+ */
+export { SemanticURL, type URLSemanticEqualsResult, type URLClassifyResult, type URLValidateForResult, type ParsedQueryParam, type URLLLMClientInterface, } from './url.ts';
+export type { SemanticEqualsResult, ClassifyResult, SafetyResult, RelatedSuggestion, } from '../../shared/types.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/url/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,WAAW,EACX,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,UAAU,CAAC;AAGlB,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,93 @@
+/**
+ * Prompts for SemanticURL LLM operations
+ * These prompts are used for various semantic URL operations that require LLM understanding
+ */
+/**
+ * System prompt for semantic URL equality comparison
+ */
+export declare const SEMANTIC_EQUALS_SYSTEM = "You are a URL comparison assistant. Your task is to determine if two URLs are semantically equivalent.\n\nConsider these factors when comparing:\n- www prefix differences (www.example.com vs example.com)\n- Trailing slash differences (/path vs /path/)\n- Default port omission (http://example.com:80 vs http://example.com)\n- Protocol differences when appropriate (http vs https)\n- Case sensitivity in paths vs hostnames\n- Query parameter ordering\n- Fragment identifiers\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for semantic URL equality
+ */
+export declare function semanticEqualsPrompt(url1: string, url2: string): string;
+/**
+ * System prompt for URL classification
+ */
+export declare const CLASSIFY_URL_SYSTEM = "You are a URL classification assistant. Your task is to classify URLs by their type and purpose.\n\nConsider these URL types:\n- api-endpoint: REST APIs, GraphQL endpoints, webhooks\n- website: Landing pages, blogs, documentation\n- cdn: Content delivery networks, static assets\n- media: Images, videos, audio files\n- download: File downloads, artifacts\n- authentication: OAuth, SSO, login endpoints\n- social: Social media profiles, posts\n- repository: Git repositories, package registries\n- search: Search engines, query endpoints\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for URL classification
+ */
+export declare function classifyUrlPrompt(url: string): string;
+/**
+ * System prompt for URL validation for purpose
+ */
+export declare const VALIDATE_FOR_SYSTEM = "You are a URL validation assistant. Your task is to validate URLs for specific purposes.\n\nConsider:\n- Security requirements (HTTPS for sensitive operations)\n- API conventions for API endpoints\n- Domain trust for different purposes\n- Path structure expectations\n- Query parameter requirements\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for purpose validation
+ */
+export declare function validateForPrompt(url: string, purpose: string): string;
+/**
+ * System prompt for URL explanation
+ */
+export declare const EXPLAIN_URL_SYSTEM = "You are a URL explanation assistant. Your task is to explain what a URL points to in human-readable terms.\n\nConsider:\n- The domain and its purpose\n- The path structure and what it indicates\n- Query parameters and their meaning\n- Common URL patterns for well-known services\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for URL explanation
+ */
+export declare function explainUrlPrompt(url: string): string;
+/**
+ * System prompt for URL info extraction
+ */
+export declare const EXTRACT_INFO_SYSTEM = "You are a URL information extraction assistant. Your task is to extract semantic information from URL components.\n\nExtract information such as:\n- Service or platform name\n- Resource type being accessed\n- Identifiers (user IDs, post IDs, etc.)\n- Actions or operations\n- Version information\n- Locale or language settings\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for info extraction
+ */
+export declare function extractInfoPrompt(url: string): string;
+/**
+ * System prompt for URL safety assessment
+ */
+export declare const IS_SAFE_SYSTEM = "You are a URL safety assessment assistant. Your task is to assess whether a URL is safe to visit or request.\n\nConsider these safety factors:\n- Known phishing patterns\n- Suspicious domain patterns (typosquatting, lookalike domains)\n- Dangerous file extensions\n- Data exfiltration patterns\n- Suspicious query parameters\n- IP addresses instead of domains\n- Unusual ports\n- Encoded or obfuscated content\n\nSeverity levels:\n- low: Minor concerns, probably safe\n- medium: Caution advised, potential risks\n- high: Significant risk, avoid\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for safety assessment
+ */
+export declare function isSafePrompt(url: string): string;
+/**
+ * System prompt for URL canonicalization
+ */
+export declare const CANONICAL_URL_SYSTEM = "You are a URL canonicalization assistant. Your task is to suggest the canonical (standardized) form of a URL.\n\nCanonicalization rules:\n- Lowercase the hostname\n- Remove default ports (80 for HTTP, 443 for HTTPS)\n- Remove unnecessary trailing slashes (except for root path)\n- Sort query parameters alphabetically\n- Remove empty query parameters\n- Normalize percent encoding\n- Prefer HTTPS over HTTP when appropriate\n- Remove www prefix when not needed\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for canonicalization
+ */
+export declare function canonicalUrlPrompt(url: string): string;
+/**
+ * System prompt for URL variations
+ */
+export declare const VARIATIONS_SYSTEM = "You are a URL variation assistant. Your task is to generate common variations of a URL.\n\nConsider these variations:\n- With and without www prefix\n- HTTP and HTTPS versions\n- With and without trailing slash\n- With and without default port\n- Common path variations\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for URL variations
+ */
+export declare function variationsPrompt(url: string): string;
+/**
+ * System prompt for query parameter parsing
+ */
+export declare const PARSE_QUERY_SYSTEM = "You are a query parameter analysis assistant. Your task is to parse URL query parameters and explain their semantic meaning.\n\nConsider common parameter patterns:\n- Pagination: page, limit, offset, per_page\n- Filtering: filter, q, query, search\n- Sorting: sort, order, orderBy\n- API: api_key, token, version\n- Tracking: utm_*, ref, source\n- Locale: lang, locale, hl\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for query parsing
+ */
+export declare function parseQueryPrompt(url: string): string;
+/**
+ * System prompt for suggesting related URLs
+ */
+export declare const SUGGEST_RELATED_SYSTEM = "You are a URL suggestion assistant. Your task is to suggest related URLs based on the current URL's pattern and purpose.\n\nConsider:\n- Common API endpoint patterns (list, detail, create, update, delete)\n- Related resources in the same domain\n- Parent/child resource relationships\n- Common navigation patterns\n- Alternative actions on the same resource\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for related URL suggestions
+ */
+export declare function suggestRelatedPrompt(url: string): string;
+/**
+ * System prompt for URL pattern matching
+ */
+export declare const MATCHES_PATTERN_SYSTEM = "You are a URL pattern matching assistant. Your task is to determine if a URL matches a semantic pattern description.\n\nPattern types to recognize:\n- API endpoint\n- Image URL\n- Video URL\n- Document URL\n- Download link\n- Authentication endpoint\n- Search URL\n- Social media post\n- Repository URL\n- CDN URL\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for pattern matching
+ */
+export declare function matchesPatternPrompt(url: string, pattern: string): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/url/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB,sgBAWE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvE;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,skBAaK,CAAC;AAEtC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,uVASK,CAAC;AAEtC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQtE;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,mUAQM,CAAC;AAEtC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,mXAUK,CAAC;AAEtC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASrD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,6kBAiBU,CAAC;AAEtC;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,yfAYI,CAAC;AAEtC;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,0TASO,CAAC;AAEtC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,iaAUM,CAAC;AAEtC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,kZASE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,sWAcE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQzE"}