semantic-primitives 0.1.0

package/dist/llm/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Unified LLM Client
+ * Provides a single interface to interact with multiple LLM providers
+ */
+import type { ChatOptions, CompletionOptions, LLMProvider, LLMResponse } from './types.ts';
+/**
+ * LLM Client - Unified interface for LLM operations
+ *
+ * Uses environment variables for configuration:
+ * - LLM_PROVIDER: Which provider to use (openai, anthropic, google)
+ * - Provider-specific API keys and models
+ */
+export declare class LLMClient {
+    private defaultProvider;
+    private apiKeys;
+    constructor(config?: {
+        provider?: LLMProvider;
+        apiKeys?: Partial<Record<LLMProvider, string>>;
+    });
+    /** Get the API key for a provider */
+    private getApiKey;
+    /** Resolve the provider from options or default */
+    private resolveProvider;
+    /**
+     * Generate a completion from a prompt
+     *
+     * @example
+     * ```ts
+     * const client = new LLMClient();
+     * const response = await client.complete({
+     *   prompt: "What is the capital of France?",
+     *   systemPrompt: "You are a helpful geography assistant."
+     * });
+     * console.log(response.content);
+     * ```
+     */
+    complete(options: CompletionOptions): Promise<LLMResponse>;
+    /**
+     * Generate a response in a chat conversation
+     *
+     * @example
+     * ```ts
+     * const client = new LLMClient();
+     * const response = await client.chat({
+     *   messages: [
+     *     { role: "user", content: "Hello!" },
+     *     { role: "assistant", content: "Hi there! How can I help?" },
+     *     { role: "user", content: "What's the weather like?" }
+     *   ]
+     * });
+     * console.log(response.content);
+     * ```
+     */
+    chat(options: ChatOptions): Promise<LLMResponse>;
+    /**
+     * Switch to a different provider
+     */
+    withProvider(provider: LLMProvider): LLMClient;
+}
+/**
+ * Get the default LLM client (singleton)
+ */
+export declare function getClient(): LLMClient;
+/**
+ * Convenience function for simple completions
+ *
+ * @example
+ * ```ts
+ * const response = await complete("What is 2 + 2?");
+ * console.log(response.content); // "4"
+ * ```
+ */
+export declare function complete(prompt: string, options?: Omit<CompletionOptions, 'prompt'>): Promise<LLMResponse>;
+/**
+ * Convenience function for simple chat completions
+ */
+export declare function chat(options: ChatOptions): Promise<LLMResponse>;
+/**
+ * Clear the provider cache (useful for testing or reconfiguration)
+ */
+export declare function clearProviderCache(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/llm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/llm/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAEjB,WAAW,EAEX,WAAW,EACZ,MAAM,YAAY,CAAC;AAkCpB;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,OAAO,CAAuC;gBAE1C,MAAM,CAAC,EAAE;QACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;QACvB,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;KAChD;IAMD,qCAAqC;IACrC,OAAO,CAAC,SAAS;IAIjB,mDAAmD;IACnD,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAMhE;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAMtD;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS;CAM/C;AAKD;;GAEG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAKrC;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,CAEtB;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAErE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/llm/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * LLM Module Exports
+ * Unified API for interacting with multiple LLM providers
+ */
+export type { LLMProvider, MessageRole, Message, LLMConfig, CompletionOptions, ChatOptions, LLMResponse, LLMProviderInterface, LLMEnvironment, } from './types.ts';
+export { getEnvConfig } from './types.ts';
+export { LLMClient, getClient, complete, chat, clearProviderCache, } from './client.ts';
+export { OpenAIProvider } from './providers/openai.ts';
+export { AnthropicProvider } from './providers/anthropic.ts';
+export { GoogleProvider } from './providers/google.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EACL,SAAS,EACT,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/llm/providers/anthropic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Anthropic Provider Implementation
+ */
+import type { ChatOptions, CompletionOptions, LLMProviderInterface, LLMResponse } from '../types.ts';
+export declare class AnthropicProvider implements LLMProviderInterface {
+    readonly provider: "anthropic";
+    private client;
+    private defaultModel;
+    constructor(apiKey?: string, model?: string);
+    complete(options: CompletionOptions): Promise<LLMResponse>;
+    chat(options: ChatOptions): Promise<LLMResponse>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/llm/providers/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/anthropic.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EAEZ,MAAM,aAAa,CAAC;AAuBrB,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,QAAQ,CAAC,QAAQ,EAAG,WAAW,CAAU;IACzC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAYrC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IA8B1D,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAgCvD"}

package/dist/llm/providers/google.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Google Generative AI (Gemini) Provider Implementation
+ */
+import type { ChatOptions, CompletionOptions, LLMProviderInterface, LLMResponse } from '../types.ts';
+export declare class GoogleProvider implements LLMProviderInterface {
+    readonly provider: "google";
+    private client;
+    private defaultModel;
+    constructor(apiKey?: string, model?: string);
+    complete(options: CompletionOptions): Promise<LLMResponse>;
+    chat(options: ChatOptions): Promise<LLMResponse>;
+}
+//# sourceMappingURL=google.d.ts.map

package/dist/llm/providers/google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/google.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EAEZ,MAAM,aAAa,CAAC;AAqBrB,qBAAa,cAAe,YAAW,oBAAoB;IACzD,QAAQ,CAAC,QAAQ,EAAG,QAAQ,CAAU;IACtC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAYrC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoC1D,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAwCvD"}

package/dist/llm/providers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * LLM Provider Exports
+ */
+export { OpenAIProvider } from './openai.ts';
+export { AnthropicProvider } from './anthropic.ts';
+export { GoogleProvider } from './google.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/llm/providers/openai.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenAI Provider Implementation
+ */
+import type { ChatOptions, CompletionOptions, LLMProviderInterface, LLMResponse } from '../types.ts';
+export declare class OpenAIProvider implements LLMProviderInterface {
+    readonly provider: "openai";
+    private client;
+    private defaultModel;
+    constructor(apiKey?: string, model?: string);
+    complete(options: CompletionOptions): Promise<LLMResponse>;
+    chat(options: ChatOptions): Promise<LLMResponse>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/llm/providers/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/openai.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EAEZ,MAAM,aAAa,CAAC;AAoBrB,qBAAa,cAAe,YAAW,oBAAoB;IACzD,QAAQ,CAAC,QAAQ,EAAG,QAAQ,CAAU;IACtC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAYrC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoC1D,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAgCvD"}

package/dist/llm/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * LLM Provider Types and Interfaces
+ * Provides a universal API for interacting with different LLM providers
+ */
+/** Supported LLM providers */
+export type LLMProvider = 'openai' | 'anthropic' | 'google';
+/** Role in a conversation message */
+export type MessageRole = 'system' | 'user' | 'assistant';
+/** A single message in a conversation */
+export interface Message {
+    role: MessageRole;
+    content: string;
+}
+/** Configuration for LLM requests */
+export interface LLMConfig {
+    /** The provider to use (defaults to LLM_PROVIDER env var) */
+    provider?: LLMProvider;
+    /** Model identifier (uses provider-specific default if not set) */
+    model?: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for response randomness (0-2) */
+    temperature?: number;
+    /** Top-p sampling parameter */
+    topP?: number;
+    /** Stop sequences to end generation */
+    stopSequences?: string[];
+}
+/** Options for a completion request */
+export interface CompletionOptions extends LLMConfig {
+    /** The prompt to send to the model */
+    prompt: string;
+    /** Optional system message to set context */
+    systemPrompt?: string;
+}
+/** Options for a chat request */
+export interface ChatOptions extends LLMConfig {
+    /** Array of messages in the conversation */
+    messages: Message[];
+    /** Optional system message (prepended to messages) */
+    systemPrompt?: string;
+}
+/** Standard response from an LLM request */
+export interface LLMResponse {
+    /** The generated text content */
+    content: string;
+    /** The provider that generated the response */
+    provider: LLMProvider;
+    /** The model that was used */
+    model: string;
+    /** Token usage statistics (if available) */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** The raw response from the provider (for advanced use) */
+    raw?: unknown;
+}
+/** Interface that all LLM provider implementations must follow */
+export interface LLMProviderInterface {
+    /** Provider identifier */
+    readonly provider: LLMProvider;
+    /** Generate a completion from a prompt */
+    complete(options: CompletionOptions): Promise<LLMResponse>;
+    /** Generate a response in a chat conversation */
+    chat(options: ChatOptions): Promise<LLMResponse>;
+}
+/** Environment configuration for LLM */
+export interface LLMEnvironment {
+    provider: LLMProvider;
+    openai: {
+        apiKey?: string;
+        model: string;
+    };
+    anthropic: {
+        apiKey?: string;
+        model: string;
+    };
+    google: {
+        apiKey?: string;
+        model: string;
+    };
+    defaults: {
+        maxTokens: number;
+        temperature: number;
+    };
+}
+/** Get environment configuration */
+export declare function getEnvConfig(): LLMEnvironment;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8BAA8B;AAC9B,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE5D,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE1D,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,uCAAuC;AACvC,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,WAAW,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,4DAA4D;IAC5D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE3D,iDAAiD;IACjD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,SAAS,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,MAAM,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,oCAAoC;AACpC,wBAAgB,YAAY,IAAI,cAAc,CAoB7C"}

package/dist/primitives/bigint/bigint.d.ts

@@ -0,0 +1,197 @@
+/**
+ * SemanticBigInt
+ * A BigInt type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<bigint> - Base semantic wrapper
+ * - Comparable<bigint | SemanticBigInt> - Semantic equality comparison
+ * - ContextValidatable - Domain-specific validation
+ * - Describable - Human-readable descriptions
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult, ReasonableResult, InferDomainResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, ContextValidatable, Describable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResult, ReasonableResult, InferDomainResult } from '../../shared/types.ts';
+/** Format style options for BigInt display */
+export type FormatStyle = 'words' | 'compact' | 'scientific' | 'full';
+/** Options for formatting BigInt values */
+export interface FormatOptions {
+    style?: FormatStyle;
+    locale?: string;
+}
+/** Result of scale/magnitude analysis */
+export interface ScaleResult {
+    magnitude: number;
+    name: string;
+    scientificNotation: string;
+}
+/** Common mathematical patterns */
+export type MatchPattern = 'power-of-two' | 'prime' | 'perfect-square' | 'factorial' | 'fibonacci' | 'even' | 'odd';
+/**
+ * SemanticBigInt - BigInt with LLM-powered semantic understanding
+ *
+ * Unlike traditional BigInts that are just large integers,
+ * semantic BigInts can interpret natural language, understand domain context,
+ * and provide human-readable representations.
+ */
+export declare class SemanticBigInt implements Semantic<bigint>, Comparable<bigint | SemanticBigInt>, ContextValidatable, Describable {
+    private readonly _value;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticBigInt from a raw bigint value
+     */
+    static fromBigInt(value: bigint, client?: LLMClient): SemanticBigInt;
+    /**
+     * Create a SemanticBigInt from a number
+     */
+    static fromNumber(value: number, client?: LLMClient): SemanticBigInt;
+    /**
+     * Parse a BigInt from natural language or formatted string.
+     * Understands scientific notation, word forms, and abbreviations.
+     *
+     * @param input - Natural language or formatted BigInt string, number, or bigint
+     * @param client - Optional LLM client to use
+     * @returns Promise resolving to SemanticBigInt instance
+     *
+     * @example
+     * await SemanticBigInt.from("1 trillion") // 1000000000000n
+     * await SemanticBigInt.from("10^18") // 1000000000000000000n
+     * await SemanticBigInt.from("5.2e15") // 5200000000000000n
+     */
+    static from(input: string | number | bigint, client?: LLMClient): Promise<SemanticBigInt>;
+    /**
+     * Check if two BigInts are semantically equivalent.
+     * Considers approximate values for very large numbers.
+     *
+     * @param other - BigInt to compare with
+     * @param options - Comparison options
+     * @returns Promise resolving to equivalence result with confidence
+     *
+     * @example
+     * const trillion = await SemanticBigInt.from("1 trillion");
+     * await trillion.semanticallyEquals(1000000000000n)
+     * // { equivalent: true, confidence: 1.0 }
+     */
+    semanticallyEquals(other: bigint | SemanticBigInt, options?: {
+        tolerance?: 'exact' | 'approximate';
+    }): Promise<SemanticEqualsResult>;
+    /**
+     * Validate if the BigInt is reasonable for a given domain.
+     *
+     * @param domain - Domain context (e.g., "database-id", "cryptocurrency-amount")
+     * @returns Promise resolving to validation result with explanation
+     *
+     * @example
+     * const negative = SemanticBigInt.fromBigInt(-1n);
+     * await negative.isReasonable("database-id")
+     * // { reasonable: false, explanation: "Database IDs are typically positive" }
+     */
+    isReasonable(domain: string): Promise<ReasonableResult>;
+    /**
+     * Format the BigInt in a human-readable way.
+     *
+     * @param options - Formatting options
+     * @returns Promise resolving to formatted string
+     *
+     * @example
+     * const big = SemanticBigInt.fromBigInt(1234567890123n);
+     * await big.format({ style: "words" }) // "1.23 trillion"
+     * await big.format({ style: "scientific" }) // "1.23 × 10^12"
+     */
+    format(options?: FormatOptions): Promise<string>;
+    /**
+     * Format with thousands separators (full style)
+     */
+    private formatFull;
+    /**
+     * Generate a human-readable explanation of this BigInt.
+     * Implements Explainable interface.
+     *
+     * @param context - Optional context for more relevant explanation
+     * @returns Promise resolving to human-readable explanation
+     *
+     * @example
+     * const big = SemanticBigInt.fromBigInt(1000000000000n);
+     * await big.explain() // "A 12-digit number in the trillions"
+     */
+    explain(context?: string): Promise<string>;
+    /**
+     * Get a human-friendly description of the magnitude.
+     *
+     * @param context - Optional context for more relevant comparison
+     * @returns Promise resolving to human-readable description with relatable comparisons
+     *
+     * @example
+     * const population = SemanticBigInt.fromBigInt(7900000000n);
+     * await population.describe("population")
+     * // "about 7.9 billion (roughly the world population)"
+     */
+    describe(context?: string): Promise<string>;
+    /**
+     * Infer what domain or type this BigInt likely represents.
+     *
+     * @returns Promise resolving to inferred domain with confidence
+     *
+     * @example
+     * const timestamp = SemanticBigInt.fromBigInt(1609459200000n);
+     * await timestamp.inferDomain()
+     * // { domain: "unix-timestamp-ms", confidence: 0.87 }
+     */
+    inferDomain(): Promise<InferDomainResult>;
+    /**
+     * Check if this BigInt matches common patterns.
+     * Uses local computation for efficiency when possible.
+     *
+     * @param pattern - Pattern to check
+     * @returns Promise resolving to whether the BigInt matches the pattern
+     *
+     * @example
+     * const power = SemanticBigInt.fromBigInt(1024n);
+     * await power.matches("power-of-two") // true
+     * const prime = SemanticBigInt.fromBigInt(13n);
+     * await prime.matches("prime") // true
+     */
+    matches(pattern: string): Promise<boolean>;
+    /**
+     * Check if value is a power of two (local computation)
+     */
+    private isPowerOfTwo;
+    /**
+     * Check if value is a perfect square (local computation)
+     */
+    private isPerfectSquare;
+    /**
+     * Check if value is prime (local computation for small numbers)
+     */
+    private isPrimeLocal;
+    /**
+     * Get the scale/order of magnitude.
+     *
+     * @returns Scale description with magnitude, name, and scientific notation
+     *
+     * @example
+     * const trillion = SemanticBigInt.fromBigInt(1000000000000n);
+     * trillion.scale()
+     * // { magnitude: 12, name: "trillion", scientificNotation: "10^12" }
+     */
+    scale(): ScaleResult;
+    /**
+     * Get the raw BigInt value.
+     *
+     * @returns The underlying BigInt
+     */
+    valueOf(): bigint;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        value: string;
+        scale: ScaleResult;
+    };
+}
+//# sourceMappingURL=bigint.d.ts.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * SemanticBigInt Module
+ * Exports all SemanticBigInt types and utilities
+ */
+export { SemanticBigInt, type FormatStyle, type FormatOptions, type ScaleResult, type MatchPattern, } from './bigint.ts';
+export type { SemanticEqualsResult, ReasonableResult, InferDomainResult, } from '../../shared/types.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/bigint/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,37 @@
+/**
+ * Prompts for SemanticBigInt LLM operations
+ * These prompts are used to interpret, analyze, and describe large integers
+ */
+/**
+ * System prompt for BigInt interpretation and analysis tasks
+ */
+export declare const BIGINT_SYSTEM_PROMPT = "You are a semantic BigInt interpreter. Your task is to analyze large integers, understand their context, and provide meaningful interpretations.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Interpret natural language representations of large numbers (billions, trillions, scientific notation)\n- Recognize common BigInt domains: timestamps, database IDs, cryptocurrency amounts, cryptographic values\n- Provide confidence scores from 0.0 to 1.0 based on clarity and certainty\n- Consider the magnitude and context when making domain inferences\n- Use appropriate scale names: thousand, million, billion, trillion, quadrillion, etc.";
+/**
+ * Prompt template for parsing natural language to BigInt
+ */
+export declare function createFromPrompt(input: string): string;
+/**
+ * Prompt template for semantic equality comparison
+ */
+export declare function createSemanticallyEqualsPrompt(value1: string, value2: string, tolerance: 'exact' | 'approximate'): string;
+/**
+ * Prompt template for domain reasonableness validation
+ */
+export declare function createIsReasonablePrompt(value: string, domain: string): string;
+/**
+ * Prompt template for human-readable formatting
+ */
+export declare function createFormatPrompt(value: string, style: 'words' | 'compact' | 'scientific' | 'full', locale?: string): string;
+/**
+ * Prompt template for describing magnitude with context
+ */
+export declare function createDescribePrompt(value: string, context?: string): string;
+/**
+ * Prompt template for domain inference
+ */
+export declare function createInferDomainPrompt(value: string): string;
+/**
+ * Prompt template for pattern matching
+ */
+export declare function createMatchesPatternPrompt(value: string, pattern: string): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/bigint/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,8qBASsD,CAAC;AAExF;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBtD;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,GAAG,aAAa,GACjC,MAAM,CAcR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,EAClD,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAoB7D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,CAsBR"}