semantic-primitives 0.1.0

package/dist/primitives/boolean/boolean.d.ts

@@ -0,0 +1,194 @@
+/**
+ * SemanticBoolean
+ * A boolean type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<boolean> - Base semantic wrapper
+ * - Comparable<SemanticBoolean> - Semantic equality comparison
+ * - Classifiable - Category classification (affirmative, negative, etc.)
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult, ClassifyResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, Classifiable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResult, ClassifyResult } from '../../shared/types.ts';
+/** Options for parsing natural language to boolean */
+export interface FromOptions {
+    locale?: string;
+    context?: string;
+}
+/** Categories of boolean expressions */
+export type BooleanCategory = 'affirmative' | 'negative' | 'uncertain' | 'conditional';
+/**
+ * Boolean category result for classification
+ */
+export interface BooleanClassifyResult extends ClassifyResult {
+    category: BooleanCategory;
+}
+/**
+ * SemanticBoolean - Boolean with LLM-powered semantic understanding
+ *
+ * Unlike traditional booleans that only understand true/false,
+ * semantic booleans can interpret natural language, handle ambiguity,
+ * and bridge the gap between human communication and binary logic.
+ *
+ * Implements:
+ * - Semantic<boolean> - valueOf() returns the boolean value
+ * - Comparable<SemanticBoolean> - semanticallyEquals() for comparison
+ * - Classifiable<BooleanClassifyResult> - classify() for categorization
+ */
+export declare class SemanticBoolean implements Semantic<boolean>, Comparable<SemanticBoolean>, Classifiable<BooleanClassifyResult> {
+    private readonly state;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticBoolean from a raw boolean value
+     */
+    static fromBoolean(value: boolean, client?: LLMClient): SemanticBoolean;
+    /**
+     * Parse natural language into a boolean value.
+     * Understands affirmatives, negatives, and contextual expressions.
+     *
+     * @param input - Natural language text to interpret
+     * @param options - Optional locale and context settings
+     * @param client - Optional LLM client to use
+     * @returns Promise resolving to SemanticBoolean instance
+     *
+     * @example
+     * await SemanticBoolean.from("yes") // true
+     * await SemanticBoolean.from("absolutely") // true
+     * await SemanticBoolean.from("nope") // false
+     * await SemanticBoolean.from("hai", { locale: "ja" }) // true (Japanese yes)
+     */
+    static from(input: string, options?: FromOptions, client?: LLMClient): Promise<SemanticBoolean>;
+    /**
+     * Infer boolean value from an implication or statement.
+     * Analyzes statements that imply success/failure, presence/absence.
+     *
+     * @param statement - A declarative statement to analyze
+     * @param client - Optional LLM client to use
+     * @returns Promise resolving to SemanticBoolean with inferred value
+     *
+     * @example
+     * await SemanticBoolean.fromImplication("The test passed") // true
+     * await SemanticBoolean.fromImplication("We encountered errors") // false
+     * await SemanticBoolean.fromImplication("No issues found") // true
+     */
+    static fromImplication(statement: string, client?: LLMClient): Promise<SemanticBoolean>;
+    /**
+     * Check if two boolean expressions are semantically equivalent.
+     * Considers synonyms, cultural variations, and context.
+     *
+     * @param other - Another SemanticBoolean to compare
+     * @returns Promise resolving to equivalence result with confidence score
+     *
+     * @example
+     * const yes = await SemanticBoolean.from("yes");
+     * const absolutely = await SemanticBoolean.from("absolutely");
+     * await yes.semanticallyEquals(absolutely) // { equivalent: true, confidence: 0.95 }
+     */
+    semanticallyEquals(other: SemanticBoolean): Promise<SemanticEqualsResult>;
+    /**
+     * Compare the strength/emphasis of two boolean expressions.
+     * Returns negative if this is weaker, positive if stronger.
+     *
+     * @param other - Another SemanticBoolean to compare strength with
+     * @returns Promise resolving to number from -1 to 1 indicating relative strength
+     *
+     * @example
+     * const guess = await SemanticBoolean.from("I guess so");
+     * const absolutely = await SemanticBoolean.from("Absolutely!");
+     * await guess.compareStrength(absolutely) // -0.6 (weaker)
+     */
+    compareStrength(other: SemanticBoolean): Promise<number>;
+    /**
+     * Check if the expression is affirmative (yes, sure, absolutely, etc.).
+     *
+     * @returns true if the expression indicates agreement/yes
+     *
+     * @example
+     * const sb = await SemanticBoolean.from("sure thing");
+     * sb.isAffirmative() // true
+     */
+    isAffirmative(): boolean;
+    /**
+     * Check if the expression is negative (no, nope, never, etc.).
+     *
+     * @returns true if the expression indicates disagreement/no
+     *
+     * @example
+     * const sb = await SemanticBoolean.from("no way");
+     * sb.isNegative() // true
+     */
+    isNegative(): boolean;
+    /**
+     * Check if the expression indicates uncertainty (maybe, perhaps, etc.).
+     *
+     * @returns true if the expression is ambiguous or uncertain
+     *
+     * @example
+     * const sb = await SemanticBoolean.from("maybe");
+     * sb.isUncertain() // true
+     */
+    isUncertain(): boolean;
+    /**
+     * Check if the expression is conditional (yes, but...; if...; etc.).
+     *
+     * @returns true if the response depends on conditions
+     *
+     * @example
+     * const sb = await SemanticBoolean.from("yes, if the price is right");
+     * sb.isConditional() // true
+     */
+    isConditional(): boolean;
+    /**
+     * Extract conditions from a conditional boolean expression.
+     * Uses LLM for more complex condition extraction if needed.
+     *
+     * @returns Promise resolving to array of condition strings, empty if not conditional
+     *
+     * @example
+     * const sb = await SemanticBoolean.from("yes, if you can deliver by Friday");
+     * await sb.extractConditions() // ["deliver by Friday"]
+     */
+    extractConditions(): Promise<string[]>;
+    /**
+     * Get the raw boolean value.
+     *
+     * @returns The resolved true/false value
+     */
+    valueOf(): boolean;
+    /**
+     * Get the confidence level of the interpretation.
+     *
+     * @returns Number from 0 to 1 indicating interpretation confidence
+     */
+    confidence(): number;
+    /**
+     * Get the original expression that was parsed
+     */
+    getOriginalExpression(): string;
+    /**
+     * Get the category of the boolean expression
+     */
+    getCategory(): BooleanCategory;
+    /**
+     * Classify the boolean expression.
+     * Implements Classifiable interface.
+     *
+     * @returns Classification result with category and confidence
+     */
+    classify(): BooleanClassifyResult;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        value: boolean;
+        confidence: number;
+        category: BooleanCategory;
+    };
+}
+//# sourceMappingURL=boolean.d.ts.map

package/dist/primitives/boolean/boolean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../../src/primitives/boolean/boolean.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,YAAY,EACb,MAAM,4BAA4B,CAAC;AAUpC,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAElF,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wCAAwC;AACxC,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;AAWvF;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eACX,YACE,QAAQ,CAAC,OAAO,CAAC,EACjB,UAAU,CAAC,eAAe,CAAC,EAC3B,YAAY,CAAC,qBAAqB,CAAC;IAErC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC,OAAO;IAKP;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,eAAe;IAavE;;;;;;;;;;;;;;OAcG;WACU,IAAI,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,eAAe,CAAC;IA6B3B;;;;;;;;;;;;OAYG;WACU,eAAe,CAC1B,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,eAAe,CAAC;IA2B3B;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAe/E;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB9D;;;;;;;;OAQG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;;OAQG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;;;;OAQG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;OAQG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;;;OASG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAyB5C;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;OAEG;IACH,WAAW,IAAI,eAAe;IAI9B;;;;;OAKG;IACH,QAAQ,IAAI,qBAAqB;IAOjC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE;CAO5E"}

package/dist/primitives/boolean/evals/from.evals.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Evaluation dataset for SemanticBoolean.from()
+ * Tests the ability to parse natural language into boolean values
+ */
+import type { EvalDataset } from '../../../shared/eval-types.ts';
+export declare const dataset: EvalDataset;
+//# sourceMappingURL=from.evals.d.ts.map

package/dist/primitives/boolean/evals/from.evals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from.evals.d.ts","sourceRoot":"","sources":["../../../../src/primitives/boolean/evals/from.evals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,eAAO,MAAM,OAAO,EAAE,WAiXrB,CAAC"}

package/dist/primitives/boolean/evals/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Evaluation datasets for SemanticBoolean
+ */
+export { dataset as from } from './from.evals.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/boolean/evals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/primitives/boolean/evals/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/primitives/boolean/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SemanticBoolean Module
+ * Exports all SemanticBoolean types and utilities
+ */
+export { SemanticBoolean, type FromOptions, type SemanticEqualsResult, type BooleanCategory, } from './boolean.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/boolean/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/boolean/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}

package/dist/primitives/boolean/prompts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Prompts for SemanticBoolean LLM operations
+ * These prompts are used to interpret and analyze boolean expressions
+ */
+/**
+ * System prompt for boolean interpretation tasks
+ */
+export declare const BOOLEAN_SYSTEM_PROMPT = "You are a semantic boolean interpreter. Your task is to analyze natural language expressions and determine their boolean meaning.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Interpret affirmative expressions (yes, sure, absolutely, correct, right, indeed) as true\n- Interpret negative expressions (no, nope, never, not at all, negative) as false\n- Consider context and locale when interpreting culturally-specific expressions\n- Provide confidence scores from 0.0 to 1.0 based on clarity of the expression\n- Identify uncertainty when expressions are ambiguous (maybe, perhaps, it depends)";
+/**
+ * Prompt template for parsing natural language to boolean
+ */
+export declare function createFromPrompt(input: string, locale?: string, context?: string): string;
+/**
+ * Prompt template for inferring boolean from implication
+ */
+export declare function createFromImplicationPrompt(statement: string): string;
+/**
+ * Prompt template for semantic equality comparison
+ */
+export declare function createSemanticallyEqualsPrompt(expression1: string, expression2: string): string;
+/**
+ * Prompt template for strength comparison
+ */
+export declare function createCompareStrengthPrompt(expression1: string, expression2: string): string;
+/**
+ * Prompt template for extracting conditions
+ */
+export declare function createExtractConditionsPrompt(expression: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/primitives/boolean/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/boolean/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB,uoBASiD,CAAC;AAEpF;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBzF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAerE;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAYxE"}

package/dist/primitives/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Semantic Primitives
+ * LLM-enhanced primitive types with semantic understanding
+ */
+export { type SemanticEqualsResult } from '../shared/types.ts';
+export { SemanticNumber, type ReasonableResult, type InferUnitResult, type SemanticEqualsOptions, type LLMClientInterface, } from './number/index.ts';
+export { SemanticBoolean, type FromOptions, type BooleanCategory } from './boolean/index.ts';
+export { SemanticString, type ClassifyResult, type ValidateResult, type DetectIntentResult, type DetectLanguageResult, type ContainsSensitiveResult, type Correction, } from './string/index.ts';
+export { SemanticNull, type NullType, type NullClassifyResult, type SuggestDefaultResult, type SchemaInfo, type AppropriateContext, type InferReasonResult, type AppropriateResult, } from './null/index.ts';
+export { SemanticSymbol, type SymbolClassifyResult, type SemanticEqualsResultWithReason, type ValidateResultWithWarnings, type Suggestion, } from './symbol/index.ts';
+export { SemanticBigInt, type FormatStyle, type FormatOptions, type ScaleResult, type MatchPattern, type InferDomainResult, } from './bigint/index.ts';
+export { SemanticUndefined, type UndefinedType, type UndefinedClassifyResult, type SuggestInitializationResult, type TypeHint, type AcceptableResult, type CompareToNullResult, } from './undefined/index.ts';
+export { SemanticVoid, type VoidFunction, type AnalyzeSideEffectsResult, type ShouldReturnValueResult, type ValidateUsageResult, type CheckErrorHandlingResult, type SuggestSignatureResult, } from './void/index.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/primitives/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG/D,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG7F,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,KAAK,0BAA0B,EAC/B,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC"}

package/dist/primitives/null/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SemanticNull Module
+ * Exports all SemanticNull types and utilities
+ */
+export { SemanticNull, type SemanticEqualsResult, type InferReasonResult, type AppropriateResult, type NullType, type NullClassifyResult, type SuggestDefaultResult, type SchemaInfo, type AppropriateContext, } from './null.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/null/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/null/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC"}

package/dist/primitives/null/null.d.ts

@@ -0,0 +1,181 @@
+/**
+ * SemanticNull
+ * A null type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<null> - Base semantic wrapper
+ * - Comparable<SemanticNull> - Semantic equality comparison
+ * - Explainable - Human-readable explanation
+ * - SemanticAbsence<null> - Absence-specific methods
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult, InferReasonResult, AppropriateResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, Explainable, SemanticAbsence } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResult, InferReasonResult, AppropriateResult, } from '../../shared/types.ts';
+/** Classification types for null values */
+export type NullType = 'not-set' | 'not-applicable' | 'unknown';
+/** Result of null classification */
+export interface NullClassifyResult {
+    type: NullType;
+    canBeProvided: boolean;
+}
+/** Result of suggesting a default value */
+export interface SuggestDefaultResult {
+    default: unknown;
+    explanation: string;
+}
+/** Schema information for suggestDefault */
+export interface SchemaInfo {
+    type: string;
+    format?: string;
+}
+/** Context for isAppropriate */
+export interface AppropriateContext {
+    required?: boolean;
+    schema?: unknown;
+}
+/**
+ * SemanticNull - Null with LLM-powered semantic understanding
+ *
+ * Unlike plain null that only represents absence,
+ * SemanticNull can explain why a value is null, classify the type of absence,
+ * and help reason about appropriate handling.
+ *
+ * Implements:
+ * - Semantic<null> - valueOf() returns null
+ * - Comparable<SemanticNull> - semanticallyEquals() for comparison
+ * - Explainable - explain() for human-readable description
+ * - SemanticAbsence<null> - getReason() and classify()
+ */
+export declare class SemanticNull implements Semantic<null>, Comparable<SemanticNull>, Explainable, SemanticAbsence<null> {
+    private readonly reason;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticNull with context about why the value is null.
+     *
+     * @param reason - Reason or context for the null value
+     * @param client - Optional LLM client for dependency injection
+     * @returns SemanticNull instance with context
+     *
+     * @example
+     * SemanticNull.because("user has not set a phone number")
+     * SemanticNull.because("field is not applicable for this user type")
+     */
+    static because(reason: string, client?: LLMClient): SemanticNull;
+    /**
+     * Create a SemanticNull without a reason.
+     *
+     * @param client - Optional LLM client for dependency injection
+     * @returns SemanticNull instance
+     */
+    static create(client?: LLMClient): SemanticNull;
+    /**
+     * Check if two null values are semantically equivalent.
+     * Null values with similar reasons/contexts are considered equivalent.
+     *
+     * @param other - Another SemanticNull to compare
+     * @returns Equivalence result with confidence score
+     *
+     * @example
+     * await SemanticNull.because("not set").semanticallyEquals(SemanticNull.because("empty"))
+     * // { equivalent: true, confidence: 0.85 }
+     */
+    semanticallyEquals(other: SemanticNull): Promise<SemanticEqualsResult>;
+    /**
+     * Infer the likely reason for a null value based on context.
+     *
+     * @param fieldName - Name of the field that is null
+     * @param context - Surrounding context (object, schema, etc.)
+     * @param client - Optional LLM client for dependency injection
+     * @returns Inferred reason for the null
+     *
+     * @example
+     * await SemanticNull.inferReason("deletedAt", { status: "active" })
+     * // { reason: "Record has not been deleted", type: "not-applicable" }
+     */
+    static inferReason(fieldName: string, context?: Record<string, unknown>, client?: LLMClient): Promise<InferReasonResult>;
+    /**
+     * Suggest an appropriate default value for a null field.
+     *
+     * @param fieldName - Name of the field
+     * @param schema - Optional schema or type information
+     * @param client - Optional LLM client for dependency injection
+     * @returns Suggested default with explanation
+     *
+     * @example
+     * await SemanticNull.suggestDefault("phoneNumber", { type: "string", format: "phone" })
+     * // { default: null, explanation: "Phone numbers should not have a default; require user input" }
+     *
+     * await SemanticNull.suggestDefault("retryCount", { type: "number" })
+     * // { default: 0, explanation: "Retry count should start at 0" }
+     */
+    static suggestDefault(fieldName: string, schema?: SchemaInfo, client?: LLMClient): Promise<SuggestDefaultResult>;
+    /**
+     * Check if null is appropriate for this field/context.
+     *
+     * @param fieldName - Name of the field
+     * @param context - Context information
+     * @param client - Optional LLM client for dependency injection
+     * @returns Validation result
+     *
+     * @example
+     * await SemanticNull.isAppropriate("email", { required: true })
+     * // { appropriate: false, reason: "Email is a required field" }
+     */
+    static isAppropriate(fieldName: string, context?: AppropriateContext, client?: LLMClient): Promise<AppropriateResult>;
+    /**
+     * Determine if this null represents "not set" vs "not applicable".
+     *
+     * @returns Classification of the null type
+     *
+     * @example
+     * // For a middleName field where user left it blank:
+     * // { type: "not-set", canBeProvided: true }
+     *
+     * // For a spouseName field for a single person:
+     * // { type: "not-applicable", canBeProvided: false }
+     */
+    classify(): Promise<NullClassifyResult>;
+    /**
+     * Generate a human-readable explanation of this null value.
+     *
+     * @param fieldName - Name of the field
+     * @returns Human-readable explanation
+     *
+     * @example
+     * await SemanticNull.because("user skipped").explain("middleName")
+     * // "Middle name was not provided by the user"
+     */
+    explain(fieldName: string): Promise<string>;
+    /**
+     * Get the reason for this null, if provided.
+     *
+     * @returns The reason string or undefined
+     */
+    getReason(): string | undefined;
+    /**
+     * Check if this is semantically null (always true for SemanticNull).
+     *
+     * @returns true
+     */
+    isNull(): true;
+    /**
+     * Get the underlying null value.
+     *
+     * @returns null
+     */
+    valueOf(): null;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        value: null;
+        reason?: string;
+    };
+}
+//# sourceMappingURL=null.d.ts.map

package/dist/primitives/null/null.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null.d.ts","sourceRoot":"","sources":["../../../src/primitives/null/null.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EAChB,MAAM,4BAA4B,CAAC;AAWpC,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,2CAA2C;AAC3C,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEhE,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,YACX,YACE,QAAQ,CAAC,IAAI,CAAC,EACd,UAAU,CAAC,YAAY,CAAC,EACxB,WAAW,EACX,eAAe,CAAC,IAAI,CAAC;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC,OAAO;IAKP;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,YAAY;IAIhE;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,YAAY;IAI/C;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuB5E;;;;;;;;;;;OAWG;WACU,WAAW,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAa7B;;;;;;;;;;;;;;OAcG;WACU,cAAc,CACzB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,EACnB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,oBAAoB,CAAC;IAahC;;;;;;;;;;;OAWG;WACU,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAa7B;;;;;;;;;;;OAWG;IACG,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAgB7C;;;;;;;;;OASG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD;;;;OAIG;IACH,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAId;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,QAAQ,IAAI,MAAM;IAOlB;;OAEG;IACH,MAAM,IAAI;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAM3C"}

package/dist/primitives/null/prompts.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prompts for SemanticNull LLM operations
+ * These prompts are used to reason about null values and their semantic meaning
+ */
+/**
+ * System prompt for null interpretation tasks
+ */
+export declare const NULL_SYSTEM_PROMPT = "You are a semantic null value interpreter. Your task is to analyze and reason about null values, their meaning, and appropriate handling.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nKey concepts:\n- \"not-set\": A value that could be provided but hasn't been (e.g., optional field left blank)\n- \"not-applicable\": A value that doesn't apply to the current context (e.g., spouse name for single person)\n- \"unknown\": The reason for null is unclear or indeterminate\n\nGuidelines:\n- Consider the field name semantics when inferring reasons\n- Analyze context to determine if null is intentional or missing\n- Provide confidence scores from 0.0 to 1.0 based on clarity\n- Suggest appropriate defaults only when safe (never for sensitive data)";
+/**
+ * Prompt template for comparing two null reasons for semantic equivalence
+ */
+export declare function createSemanticallyEqualsPrompt(reason1: string, reason2: string): string;
+/**
+ * Prompt template for inferring the reason a field is null
+ */
+export declare function createInferReasonPrompt(fieldName: string, context?: Record<string, unknown>): string;
+/**
+ * Prompt template for suggesting a default value for a null field
+ */
+export declare function createSuggestDefaultPrompt(fieldName: string, schema?: {
+    type: string;
+    format?: string;
+}): string;
+/**
+ * Prompt template for checking if null is appropriate for a field
+ */
+export declare function createIsAppropriatePrompt(fieldName: string, context?: {
+    required?: boolean;
+    schema?: unknown;
+}): string;
+/**
+ * Prompt template for classifying the type of null
+ */
+export declare function createClassifyPrompt(reason: string): string;
+/**
+ * Prompt template for generating a human-readable explanation
+ */
+export declare function createExplainPrompt(fieldName: string, reason?: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/primitives/null/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/null/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB,ixBAa0C,CAAC;AAE1E;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAuBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,MAAM,CAyBR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAsBR"}

package/dist/primitives/number/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SemanticNumber module
+ * LLM-enhanced number type with semantic understanding
+ */
+export * from './number.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/number/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/number/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC"}