@polyweave/core (1.0.0)
Installation
@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/npm install @polyweave/core@1.0.0"@polyweave/core": "1.0.0"About this package
Core
Core framework for Polyweave - push-stream based multimodal AI adapter framework.
Synopsis
import {
createFrameDuplex,
createFrameSink,
createTextFrame,
createStartFrame,
createEndFrame,
FrameType,
pipe
} from '@polyweave/core';
const duplex = createFrameDuplex();
duplex.source.pipe(createFrameSink((frame) => {
if (frame.type === FrameType.TEXT) {
console.log('Response:', frame.content.text);
}
}));
duplex.sink.write(createStartFrame());
duplex.sink.write(createTextFrame('Hello, world!'));
duplex.sink.write(createEndFrame());
Install
npm install @polyweave/core
Description
Core provides the foundational push-stream primitives for the Polyweave ecosystem: frame types, stream sources/sinks, transforms, wrappers, middleware, durability, cost estimation, and test harnesses.
Key concepts:
- Frames: typed data units flowing through push-streams (TEXT, META, START, END, ERROR, PARAM, etc.)
- Sinks: frame consumers with
write()andend()methods - Sources: frame producers that emit through registered callbacks
- Transforms: push-pull stream operators between sources and sinks
- Wrappers: bidirectional wrappers combining source and sink into a duplex adapter
- Durability: WAL-based checkpointing and recovery with FileWALStore and MemoryWALStore
- Costs: per-provider token counting, cost estimation, adaptive budget tracking with anytime-valid statistical guarantees, and rolling-hash cache estimation
API
Frames
createTextFrame(text), createStartFrame(), createEndFrame(), createErrorFrame(code, message), createMetaFrame(content), createParamFrame(key, value), createToolResultFrame(name, result), createBatchFrame(frames), createCostFrame(cost), createCostCheckFrame(maxBudget) - Frame constructors.
FrameType - Enum of all frame types (TEXT, META, START, END, ERROR, PARAM, TOOL_RESULT, BATCH, COST, COST_CHECK, ESTIMATED_TEXT, etc.).
Streams
createFrameSource(), createFrameSink(handler), createFrameDuplex() - Stream primitives.
pipe(source, sink) - Connect a source to a sink, returning the source.
tee(source, count) - Duplicate a source into multiple sinks.
collectFrames(source) - Collect all frames from a source into an array.
runSequence(factories) / runParallel(factories) - Run frame producers sequentially or in parallel.
Transforms
createFrameTransform(handler) - Create a transform function for a frame pipeline.
compositionGap - Available in transforms module.
Wrappers
createBidirectionalWrapper(options) - Create a bidirectional wrapper with source and sink.
createJoinSource(sources) - Join multiple sources into one.
createSplitSink(sinks) - Split one sink into multiple.
Middleware
createMiddlewarePipeline(middleware) - Chain middleware for frame processing.
Durability
FileWALStore, MemoryWALStore - Write-ahead log stores for checkpointing.
createCheckpointManager, createRecoveryManager, createDurablePipeline - Recovery primitives.
Testing
topologyScan, sendAndCollect, createTestHarness - Test utilities for frame-based systems.
Utils
uuidv7(), ErrorCode, compose(...functions) - General utilities.
Costs
calculateTokenCost(model, tokens), getModelCost(provider, model) — Per-provider cost calculation.
createCostEstimator(provider) — Create a provider-specific cost estimator.
createCostTracker(innerDuplex, options) — Frame-protocol budget wrapper. Set budget via PARAM, query totals via DESCRIBE, get predictions via COST_CHECK, block TEXT frames on overage. Uses an anytime-valid Bayesian ratio e-process that learns the output/input token ratio from RECEIPT frames and provides statistical guarantees on false-block probability.
createRatioEProcess(options) — Gaussian conjugate e-process for the output/input token ratio. Methods: update(totalInput, output) from RECEIPT frames, estimate(inputTokens, mode) with alpha-cut conservation bounds, tailProbability(theta) for posterior tail, testBudgetExceeded(thetaDanger) for anytime-valid budget gating.
createRollingHash(options) — Sliding window polynomial hash for cache-hit estimation. Tracks which text windows have been seen before to estimate KV-cache reuse across conversation turns.
setCustomPricing(overrides) — Override default provider pricing.
Tests
npm test
Tests cover frames, streams, transforms, wrappers, cost estimation, durability/WAL, durable router, and integration scenarios.
Requirements
Node.js 18 or later. ESM only.
License
MIT
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @rigor/core | * |
| fast-check | ^3.23.2 |