semantic-primitives 0.1.0

package/dist/types/set/set.d.ts

@@ -0,0 +1,261 @@
+/**
+ * SemanticSet
+ * A set type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<Set<T>> - Base semantic wrapper
+ * - Comparable<SemanticSet<T>> - Semantic equality comparison
+ * - Validatable - Validation against semantic rules
+ * - Summarizable - Content summarization
+ * - SemanticFilterable - Natural language filtering
+ * - SemanticGroupable - Semantic grouping
+ * - SemanticSetOperations - Intersection, union, difference
+ * - Suggestible - Related value suggestions
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult, RelatedSuggestion, ConfidenceResult } from '../../shared/types.ts';
+import type { Semantic, Comparable } from '../../shared/interfaces.ts';
+/** Result of semantic has operation */
+export interface SemanticHasResult extends ConfidenceResult {
+    exists: boolean;
+    matchedValue: unknown;
+}
+/** Result of semantic add operation */
+export interface SemanticAddResult extends ConfidenceResult {
+    added: boolean;
+    existingEquivalent: unknown;
+}
+/** Result of semantic equality with mappings */
+export interface SetSemanticEqualsResult extends SemanticEqualsResult {
+    mappings?: [unknown, unknown][];
+}
+/** Options for summarization */
+export interface SetSummarizeOptions {
+    maxLength?: number;
+    focus?: string;
+}
+/** Validation result with per-value issues */
+export interface SetValidateResult {
+    valid: boolean;
+    issues: {
+        value: unknown;
+        problems: string[];
+    }[];
+}
+/** Result of theme inference */
+export interface InferThemeResult extends ConfidenceResult {
+    theme: string;
+}
+/**
+ * SemanticSet - Set with LLM-powered semantic understanding
+ *
+ * Unlike traditional sets that only support exact value matching,
+ * semantic sets understand meaning-based membership, equivalence,
+ * and operations.
+ *
+ * @template T - The type of elements in the set
+ */
+export declare class SemanticSet<T> implements Semantic<Set<T>>, Comparable<SemanticSet<T> | Set<T>, SetSemanticEqualsResult> {
+    private readonly elements;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticSet from an existing iterable
+     */
+    static from<T>(values: Iterable<T>, client?: LLMClient): SemanticSet<T>;
+    /**
+     * Create an empty SemanticSet
+     */
+    static empty<T>(client?: LLMClient): SemanticSet<T>;
+    /**
+     * Create a SemanticSet from variadic arguments
+     */
+    static of<T>(...items: T[]): SemanticSet<T>;
+    /**
+     * Get the underlying Set value
+     */
+    valueOf(): Set<T>;
+    /**
+     * Get the values as an array (for convenience)
+     */
+    toArray(): T[];
+    /**
+     * Get the size of the set
+     */
+    get size(): number;
+    /**
+     * Check if set has an exact value (standard Set behavior)
+     */
+    has(value: T): boolean;
+    /**
+     * Check if the set contains a semantically equivalent value.
+     *
+     * @param query - Value or semantic query
+     * @returns Whether a matching value exists with details
+     *
+     * @example
+     * colors.semanticHas("crimson") // { exists: true, matchedValue: "red", confidence: 0.92 }
+     */
+    semanticHas(query: T | string): Promise<SemanticHasResult>;
+    /**
+     * Add a value only if no semantic equivalent exists.
+     *
+     * @param value - Value to add
+     * @returns Result indicating if value was added
+     *
+     * @example
+     * tags.semanticAdd("ML") // { added: false, existingEquivalent: "machine learning", confidence: 0.9 }
+     */
+    semanticAdd(value: T): Promise<{
+        result: SemanticAddResult;
+        set: SemanticSet<T>;
+    }>;
+    /**
+     * Check if two sets are semantically equivalent.
+     *
+     * @param other - Set to compare with
+     * @returns Equivalence result with mappings
+     *
+     * @example
+     * set1.semanticallyEquals(set2)
+     * // { equivalent: true, mappings: [["red", "crimson"]], confidence: 0.9 }
+     */
+    semanticallyEquals(other: SemanticSet<T> | Set<T>): Promise<SetSemanticEqualsResult>;
+    /**
+     * Get semantic intersection with another set.
+     *
+     * @param other - Set to intersect with
+     * @returns Intersection with semantic matching
+     *
+     * @example
+     * skills1.semanticIntersection(skills2)
+     * // Matches "JavaScript" with "JS", "Node.js" with "NodeJS"
+     */
+    semanticIntersection(other: SemanticSet<T> | Set<T>): Promise<SemanticSet<T>>;
+    /**
+     * Get semantic union, merging equivalent values.
+     *
+     * @param other - Set to union with
+     * @returns Union with semantic deduplication
+     *
+     * @example
+     * tags1.semanticUnion(tags2)
+     * // Combines without duplicating "ML" and "machine learning"
+     */
+    semanticUnion(other: SemanticSet<T> | Set<T>): Promise<SemanticSet<T>>;
+    /**
+     * Get semantic difference (values not in other set).
+     *
+     * @param other - Set to diff against
+     * @returns Difference with semantic matching
+     *
+     * @example
+     * allSkills.semanticDifference(requiredSkills)
+     * // Excludes "Python" if required has "Python programming"
+     */
+    semanticDifference(other: SemanticSet<T> | Set<T>): Promise<SemanticSet<T>>;
+    /**
+     * Find values matching semantic criteria.
+     *
+     * @param criteria - Natural language criteria
+     * @returns Matching values as a SemanticSet
+     *
+     * @example
+     * skills.semanticFilter("backend technologies")
+     * // SemanticSet containing ["Node.js", "PostgreSQL", "Redis"]
+     */
+    semanticFilter(criteria: string): Promise<SemanticSet<T>>;
+    /**
+     * Group set values by semantic category.
+     *
+     * @param criteria - Grouping criteria
+     * @returns Grouped values
+     *
+     * @example
+     * skills.groupBy("technology area")
+     * // Map { "frontend": SemanticSet(["React", "CSS"]), "backend": SemanticSet(["Node", "Python"]) }
+     */
+    groupBy(criteria: string): Promise<Map<string, SemanticSet<T>>>;
+    /**
+     * Summarize the set contents.
+     *
+     * @param options - Summary options
+     * @returns Human-readable summary
+     *
+     * @example
+     * permissions.summarize()
+     * // "15 permissions: 8 read, 5 write, 2 admin. Covers user and content management."
+     */
+    summarize(options?: SetSummarizeOptions): Promise<string>;
+    /**
+     * Suggest related values that might belong in this set.
+     *
+     * @returns Suggested additions
+     *
+     * @example
+     * skills.suggestRelated()
+     * // [{ value: "TypeScript", reason: "Commonly paired with JavaScript" }]
+     */
+    suggestRelated(): Promise<RelatedSuggestion[]>;
+    /**
+     * Validate all values against semantic rules.
+     *
+     * @param rules - Validation rules
+     * @returns Validation result
+     *
+     * @example
+     * tags.validate(["must be lowercase", "no special characters"])
+     */
+    validate(rules: string[]): Promise<SetValidateResult>;
+    /**
+     * Detect the semantic theme/category of this set.
+     *
+     * @returns Inferred theme
+     *
+     * @example
+     * values.inferTheme()
+     * // { theme: "programming languages", confidence: 0.92 }
+     */
+    inferTheme(): Promise<InferThemeResult>;
+    /**
+     * Add a value (standard Set behavior)
+     */
+    add(value: T): SemanticSet<T>;
+    /**
+     * Delete a value
+     */
+    delete(value: T): SemanticSet<T>;
+    /**
+     * Clear all values
+     */
+    clear(): SemanticSet<T>;
+    /**
+     * Execute a function for each value
+     */
+    forEach(fn: (value: T, value2: T, set: Set<T>) => void): void;
+    /**
+     * Get an iterator over values
+     */
+    values(): IterableIterator<T>;
+    /**
+     * Get an iterator over keys (same as values for Set)
+     */
+    keys(): IterableIterator<T>;
+    /**
+     * Get an iterator over entries
+     */
+    entries(): IterableIterator<[T, T]>;
+    /**
+     * Iterator support
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON (array representation)
+     */
+    toJSON(): T[];
+}
+//# sourceMappingURL=set.d.ts.map

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

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

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

@@ -0,0 +1,8 @@
+/**
+ * Semantic Streams
+ * LLM-enhanced stream types with semantic understanding
+ */
+export { SemanticReadableStream, type DetectContentTypeResult, type StreamSemanticEqualsResult, type DetectPatternsResult, type InferSchemaResult, type StreamValidationItem, } from './readable-stream.ts';
+export { SemanticWritableStream, type WriteStats, } from './writable-stream.ts';
+export { SemanticTransformStream } from './transform-stream.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/streams/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,sBAAsB,EACtB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,53 @@
+/**
+ * Prompts for Semantic Stream LLM operations
+ * These prompts enable intelligent content analysis, pattern detection, and stream processing
+ */
+/**
+ * System prompt for stream analysis tasks
+ */
+export declare const STREAM_SYSTEM_PROMPT = "You are an expert at analyzing streaming data, understanding content types, detecting patterns, and providing semantic insights about data flows.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nGuidelines:\n- Analyze stream content to understand its structure and meaning\n- Detect patterns, anomalies, and data quality issues\n- Consider common data formats: JSON, NDJSON, CSV, XML, binary, text\n- Provide meaningful, contextual responses about stream content\n- Be precise with confidence scores (0.0 to 1.0)";
+/**
+ * Prompt for detecting content type of stream data
+ */
+export declare function createDetectContentTypePrompt(sample: string, description?: string): string;
+/**
+ * Prompt for summarizing stream contents
+ */
+export declare function createSummarizePrompt(content: string, description?: string): string;
+/**
+ * Prompt for checking semantic equivalence between two streams
+ */
+export declare function createSemanticEqualsPrompt(content1: string, content2: string, description?: string): string;
+/**
+ * Prompt for filtering stream data based on criteria
+ */
+export declare function createSemanticFilterPrompt(item: string, criteria: string, description?: string): string;
+/**
+ * Prompt for transforming stream data
+ */
+export declare function createSemanticTransformPrompt(item: string, instruction: string, description?: string): string;
+/**
+ * Prompt for validating stream data against rules
+ */
+export declare function createValidatePrompt(item: string, rules: string[], description?: string): string;
+/**
+ * Prompt for explaining stream contents
+ */
+export declare function createExplainPrompt(sample: string, description?: string): string;
+/**
+ * Prompt for detecting patterns in stream data
+ */
+export declare function createDetectPatternsPrompt(content: string, description?: string): string;
+/**
+ * Prompt for inferring schema from stream data
+ */
+export declare function createInferSchemaPrompt(sample: string, description?: string): string;
+/**
+ * Prompt for explaining a transform operation
+ */
+export declare function createExplainTransformPrompt(instruction: string): string;
+/**
+ * Prompt for validating data before writing to a stream
+ */
+export declare function createWriteValidationPrompt(data: string, rules: string[]): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/streams/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,oiBASgB,CAAC;AAElD;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EAAE,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgBxE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAkBR"}

package/dist/types/streams/readable-stream.d.ts

@@ -0,0 +1,148 @@
+/**
+ * SemanticReadableStream
+ * A ReadableStream wrapper with LLM-powered semantic understanding
+ *
+ * Enables content analysis, intelligent transformations, and pattern detection on streaming data.
+ */
+import type { LLMClient } from '../../llm/client.ts';
+/** Result of content type detection */
+export interface DetectContentTypeResult {
+    type: string;
+    format?: string;
+    confidence: number;
+}
+/** Result of semantic equality comparison */
+export interface StreamSemanticEqualsResult {
+    equivalent: boolean;
+    confidence: number;
+    reason?: string;
+}
+/** Result of pattern detection */
+export interface DetectPatternsResult {
+    patterns: string[];
+    anomalies: {
+        index: number;
+        reason: string;
+    }[];
+}
+/** Result of schema inference */
+export interface InferSchemaResult {
+    type: string;
+    properties?: Record<string, string>;
+    confidence: number;
+}
+/** Validation result for stream items */
+export interface StreamValidationItem<T> {
+    data: T;
+    valid: boolean;
+    issues: string[];
+}
+/**
+ * SemanticReadableStream - ReadableStream with LLM-powered semantic understanding
+ *
+ * Wraps a native ReadableStream and adds intelligent content analysis,
+ * pattern detection, and transformation capabilities.
+ */
+export declare class SemanticReadableStream<T> {
+    readonly [Symbol.toStringTag] = "SemanticReadableStream";
+    private _stream;
+    private readonly _description?;
+    private readonly _client;
+    private constructor();
+    /**
+     * Wrap a ReadableStream with semantic capabilities.
+     *
+     * @param stream - ReadableStream to wrap
+     * @param description - Optional description of stream contents
+     * @param client - Optional LLM client
+     * @returns SemanticReadableStream instance
+     *
+     * @example
+     * SemanticReadableStream.from(fetch(url).then(r => r.body), "API response")
+     */
+    static from<T>(stream: ReadableStream<T>, description?: string, client?: LLMClient): SemanticReadableStream<T>;
+    /**
+     * Get the underlying ReadableStream.
+     */
+    get stream(): ReadableStream<T>;
+    /**
+     * Get the description.
+     */
+    get description(): string | undefined;
+    /**
+     * Get a reader for the underlying stream.
+     */
+    getReader(): ReadableStreamDefaultReader<T>;
+    /**
+     * Tee the stream into two branches.
+     */
+    tee(): [SemanticReadableStream<T>, SemanticReadableStream<T>];
+    /**
+     * Check if two streams are semantically equivalent.
+     * Note: This consumes both streams.
+     *
+     * @param other - Stream to compare
+     * @returns Equivalence result
+     */
+    semanticallyEquals(other: ReadableStream<T>): Promise<StreamSemanticEqualsResult>;
+    /**
+     * Detect the content type of the stream data.
+     *
+     * @param sampleSize - Bytes to sample for detection
+     * @returns Content type detection result
+     */
+    detectContentType(sampleSize?: number): Promise<DetectContentTypeResult>;
+    /**
+     * Summarize the stream contents.
+     * Note: This consumes the stream.
+     *
+     * @returns Content summary
+     */
+    summarize(): Promise<string>;
+    /**
+     * Filter stream data using semantic criteria.
+     *
+     * @param criteria - Natural language filter
+     * @returns Filtered stream
+     */
+    semanticFilter(criteria: string): SemanticReadableStream<T>;
+    /**
+     * Transform stream using natural language instructions.
+     *
+     * @param instruction - Transformation instruction
+     * @returns Transformed stream
+     */
+    semanticTransform<U>(instruction: string): SemanticReadableStream<U>;
+    /**
+     * Validate stream data against semantic rules.
+     *
+     * @param rules - Validation rules
+     * @returns Validation stream
+     */
+    validate(rules: string[]): SemanticReadableStream<StreamValidationItem<T>>;
+    /**
+     * Explain what this stream contains.
+     *
+     * @param sampleSize - Data to sample for explanation
+     * @returns Human-readable explanation
+     */
+    explain(sampleSize?: number): Promise<string>;
+    /**
+     * Detect patterns in stream data.
+     * Note: This consumes the stream.
+     *
+     * @returns Detected patterns
+     */
+    detectPatterns(): Promise<DetectPatternsResult>;
+    /**
+     * Infer the schema of stream elements.
+     *
+     * @returns Inferred schema
+     */
+    inferSchema(): Promise<InferSchemaResult>;
+    /**
+     * Consume the entire stream as a string.
+     */
+    private consumeAsString;
+}
+//# sourceMappingURL=readable-stream.d.ts.map

package/dist/types/streams/readable-stream.d.ts.map

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

package/dist/types/streams/transform-stream.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SemanticTransformStream
+ * A TransformStream wrapper with LLM-powered semantic understanding
+ *
+ * Enables intelligent transformations based on natural language instructions.
+ */
+import type { LLMClient } from '../../llm/client.ts';
+/**
+ * SemanticTransformStream - TransformStream with LLM-powered semantic understanding
+ *
+ * Creates a transform stream from natural language instructions.
+ */
+export declare class SemanticTransformStream<I, O> {
+    readonly [Symbol.toStringTag] = "SemanticTransformStream";
+    private readonly _transformStream;
+    private readonly _instruction;
+    private readonly _client;
+    private _explanation;
+    private constructor();
+    /**
+     * Create a transform stream from natural language instruction.
+     *
+     * @param instruction - What transformation to perform
+     * @param client - Optional LLM client
+     * @returns Transform stream
+     *
+     * @example
+     * SemanticTransformStream.from("parse JSON and extract names")
+     */
+    static from<I, O>(instruction: string, client?: LLMClient): SemanticTransformStream<I, O>;
+    /**
+     * Get the underlying TransformStream.
+     */
+    get transformStream(): TransformStream<I, O>;
+    /**
+     * Get the instruction.
+     */
+    get instruction(): string;
+    /**
+     * Get the readable side of the transform stream.
+     */
+    get readable(): ReadableStream<O>;
+    /**
+     * Get the writable side of the transform stream.
+     */
+    get writable(): WritableStream<I>;
+    /**
+     * Explain what this transform does.
+     *
+     * @returns Transformation description
+     */
+    explain(): string;
+    /**
+     * Explain what this transform does using LLM.
+     *
+     * @returns Transformation description
+     */
+    explainAsync(): Promise<string>;
+    /**
+     * Pipe a readable stream through this transform.
+     *
+     * @param source - Source readable stream
+     * @returns Transformed readable stream
+     */
+    pipeFrom(source: ReadableStream<I>): ReadableStream<O>;
+}
+//# sourceMappingURL=transform-stream.d.ts.map

package/dist/types/streams/transform-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-stream.d.ts","sourceRoot":"","sources":["../../../src/types/streams/transform-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAQrD;;;;GAIG;AACH,qBAAa,uBAAuB,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,6BAA6B;IAE1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,YAAY,CAAuB;IAE3C,OAAO;IAyCP;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,SAAS,GACjB,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC;IAIhC;;OAEG;IACH,IAAI,eAAe,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAE3C;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC,CAEhC;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC,CAEhC;IAED;;;;OAIG;IACH,OAAO,IAAI,MAAM;IASjB;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAsBrC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;CAGvD"}

package/dist/types/streams/writable-stream.d.ts

@@ -0,0 +1,111 @@
+/**
+ * SemanticWritableStream
+ * A WritableStream wrapper with LLM-powered semantic understanding
+ *
+ * Enables intelligent validation and statistics tracking for written data.
+ */
+import type { LLMClient } from '../../llm/client.ts';
+/** Statistics about written data */
+export interface WriteStats {
+    chunksWritten: number;
+    bytesWritten: number;
+    errorCount: number;
+}
+/**
+ * SemanticWritableStream - WritableStream with LLM-powered semantic understanding
+ *
+ * Wraps a native WritableStream and adds intelligent validation
+ * and statistics tracking capabilities.
+ *
+ * Note: When using withValidation(), the original instance becomes unusable.
+ * Only the returned wrapper should be used for subsequent operations.
+ */
+export declare class SemanticWritableStream<T> {
+    readonly [Symbol.toStringTag] = "SemanticWritableStream";
+    private readonly _stream;
+    private readonly _client;
+    private readonly _validationRules;
+    private readonly _sharedState;
+    private _transferred;
+    private constructor();
+    /**
+     * Wrap a WritableStream with semantic capabilities.
+     *
+     * @param stream - WritableStream to wrap
+     * @param client - Optional LLM client
+     * @returns SemanticWritableStream instance
+     *
+     * @example
+     * SemanticWritableStream.from(new WritableStream({ write(chunk) { ... } }))
+     */
+    static from<T>(stream: WritableStream<T>, client?: LLMClient): SemanticWritableStream<T>;
+    /**
+     * Get the underlying WritableStream.
+     */
+    get stream(): WritableStream<T>;
+    /**
+     * Check if this instance has been transferred to a validation wrapper.
+     */
+    get isTransferred(): boolean;
+    /**
+     * Throws if this instance has been transferred.
+     */
+    private assertNotTransferred;
+    /**
+     * Get a writer for the underlying stream.
+     */
+    getWriter(): WritableStreamDefaultWriter<T>;
+    /**
+     * Write a chunk to the stream.
+     *
+     * @param chunk - Data to write
+     */
+    write(chunk: T): Promise<void>;
+    /**
+     * Close the stream.
+     */
+    close(): Promise<void>;
+    /**
+     * Abort the stream.
+     */
+    abort(reason?: unknown): Promise<void>;
+    /**
+     * Release the writer lock.
+     */
+    releaseLock(): void;
+    /**
+     * Create a new SemanticWritableStream with validation rules.
+     *
+     * IMPORTANT: After calling this method, the current instance becomes unusable.
+     * Only the returned wrapper should be used for subsequent operations.
+     * Statistics are shared between all wrappers.
+     *
+     * @param rules - Validation rules
+     * @returns Validating writable stream
+     */
+    withValidation(rules: string[]): SemanticWritableStream<T>;
+    /**
+     * Get statistics about written data.
+     * Statistics are shared across all validation wrappers of the same stream.
+     *
+     * @returns Write statistics
+     */
+    getStats(): Promise<WriteStats>;
+    /**
+     * Validate a chunk against the validation rules.
+     */
+    private validateChunk;
+    /**
+     * Basic validation without LLM.
+     */
+    private basicValidation;
+    /**
+     * Get the byte size of a chunk.
+     */
+    private getChunkSize;
+    /**
+     * Convert a chunk to string for validation.
+     */
+    private stringifyChunk;
+}
+//# sourceMappingURL=writable-stream.d.ts.map

package/dist/types/streams/writable-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writable-stream.d.ts","sourceRoot":"","sources":["../../../src/types/streams/writable-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD;;;;;;;;GAQG;AACH,qBAAa,sBAAsB,CAAC,CAAC;IACnC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,4BAA4B;IAEzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO;IAeP;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EACX,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,MAAM,CAAC,EAAE,SAAS,GACjB,sBAAsB,CAAC,CAAC,CAAC;IAO5B;;OAEG;IACH,IAAI,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,CAE9B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,SAAS,IAAI,2BAA2B,CAAC,CAAC,CAAC;IAQ3C;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBpC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C;;OAEG;IACH,WAAW,IAAI,IAAI;IAOnB;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,sBAAsB,CAAC,CAAC,CAAC;IAe1D;;;;;OAKG;IACH,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAQ/B;;OAEG;YACW,aAAa;IA2B3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,OAAO,CAAC,cAAc;CASvB"}