@polyweave/core (1.0.8)
Installation
@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/npm install @polyweave/core@1.0.8"@polyweave/core": "1.0.8"About this package
@polyweave/core
Core framework for Polyweave — push-stream based multimodal AI adapter framework. Provides frames, streams, transforms, wrappers, testing utilities, compose, and general utilities.
Synopsis
import {
createFrameDuplex, createFrameSink, createTextFrame, createStartFrame, createEndFrame,
FrameType, pipe, tee, collectFrames
} 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
Why
Core is the foundational layer of the Polyweave ecosystem. Every adapter, wrapper, tool, and harness depends on these primitives. It defines:
- Frames — typed message envelopes flowing through push-streams
- Streams — push-pull sources, sinks, and duplexes
- Transforms — frame-stream operators (map, filter, tee, join)
- Wrappers — bidirectional wrappers for cross-cutting concerns
- Testing — topology scan, send-and-collect, test harness utilities
- Utilities — ErrorCode enum, UUIDv7, functional compose
Core has zero @polyweave dependencies — it is the true root of the dependency graph.
API
Frames
| Constructor | Frame Type | Description |
|---|---|---|
createTextFrame(text) |
TEXT |
Text content from model or user |
createStartFrame() |
START |
Opens a request stream |
createEndFrame() |
END |
Closes a request stream |
createErrorFrame(code, message) |
ERROR |
Error with code and message |
createMetaFrame(content) |
META |
Metadata about routing/selection |
createParamFrame(key, value) |
PARAM |
Runtime parameter (model, budget, etc.) |
createToolCallFrame(name, args) |
TOOL_CALL |
Request to execute a tool |
createToolResultFrame(name, result) |
TOOL_RESULT |
Result from tool execution |
createBatchFrame(frames) |
BATCH |
Group of frames sent together |
createCostFrame(cost) |
COST |
Cost estimate or accumulated spend |
createCostCheckFrame(maxBudget) |
COST_CHECK |
Request cost estimate without execution |
createReceiptFrame(tokens) |
RECEIPT |
Token usage receipt from provider |
createImageFrame(data, mimeType) |
IMAGE |
Image input (base64 or URL) |
createAudioFrame(data, mimeType) |
AUDIO |
Audio input |
createEmbeddingFrame(values) |
EMBEDDING |
Vector embedding |
FrameType — Enum of all frame type constants: TEXT, META, START, END, ERROR, PARAM, TOOL_CALL, TOOL_RESULT, BATCH, COST, COST_CHECK, RECEIPT, IMAGE, AUDIO, EMBEDDING, TOPOLOGY_SCAN, TOPOLOGY_REPORT, CANCEL, ABORT, DESCRIBE, DESCRIPTION, TICK, NODE_UPDATE, TREE_COMPLETE, REFUSE_DELIVERY, FEEDBACK, INTERRUPTED.
Streams
| Function | Description |
|---|---|
createFrameSource() |
Creates a push source. Returns { pipe, resume, end, paused, ended } |
createFrameSink(handler) |
Creates a push sink. handler(frame) is called for each frame |
createFrameDuplex() |
Creates a bidirectional source+sink. Returns { source, sink } |
pipe(source, sink) |
Connect a source to a sink, returns the source |
tee(source, count) |
Duplicate a source into count sinks |
collectFrames(source, callback) |
Collect all frames from a source into an array. callback(err, frames) |
runSequence(factories) |
Run frame producers sequentially |
runParallel(factories) |
Run frame producers in parallel |
Sources and sinks implement backpressure via pause() and resume().
Transforms
| Function | Description |
|---|---|
createFrameTransform(handler) |
Create a transform function for a frame pipeline. handler(frame, push, done) |
compositionGap |
Utility for composition gap detection in transform chains |
Transforms are push-pull operators. They sit between a source and a sink, transforming frames as they pass through.
Wrappers
| Function | Description |
|---|---|
createBidirectionalWrapper(options) |
Create a bidirectional wrapper. Intercepts both source and sink |
createJoinSource(sources) |
Join multiple sources into one merged source |
createSplitSink(sinks) |
Split one sink into multiple downstream sinks |
Wrappers are the primary extensibility mechanism. They wrap an existing duplex (adapter) and add behavior without modifying the adapter code.
Testing
| Function | Description |
|---|---|
topologyScan(duplex) |
Sends TOPOLOGY_SCAN and collects TOPOLOGY_REPORT. Returns the adapter's internal state |
sendAndCollect(duplex, frames) |
Send an array of frames and collect all responses |
createTestHarness(options) |
Create a test harness with controlled source/sink pairs for integration testing |
Utilities
| Function | Description |
|---|---|
uuidv7() |
Generates a time-sortable UUID v7 |
compose(...functions) |
Right-to-left function composition. compose(f, g, h)(x) === f(g(h(x))) |
ErrorCode |
Enum of standardized error codes (see below) |
Error Codes
ErrorCode enum values:
| Code | Description |
|---|---|
RATE_LIMIT_EXCEEDED |
Provider rate limit hit |
QUEUE_TIMEOUT |
Request exceeded queue timeout |
INVALID_INPUT |
Invalid input to adapter or tool |
AUTHENTICATION_ERROR |
Missing or invalid credentials |
AUTHORIZATION_ERROR |
Insufficient permissions |
SERVICE_UNAVAILABLE |
Provider or service unavailable |
PROVIDER_ERROR |
Provider returned an error |
PROTOCOL_ERROR |
Frame protocol violation |
ADAPTER_ERROR |
Internal adapter failure |
BUDGET_EXCEEDED |
Spend budget exhausted |
CIRCUIT_OPEN |
Circuit breaker is open |
NO_VIABLE_MODEL |
No model passes viability gate |
TOOL_ERROR |
Tool execution failed |
TIMEOUT |
Operation timed out |
Re-export Packages
Core's sub-modules are available as thin re-export packages:
@polyweave/streams— re-exports@polyweave/core/streams@polyweave/middleware— re-exports transforms and pipeline utilities@polyweave/wrappers— re-exports@polyweave/core/wrappers
These convenience packages exist so consumers can install only what they need without pulling in the full core dependency tree.
Tests
npm test
214 tests across 27 test files covering frames, streams, transforms, wrappers, testing utilities, compose, ErrorCode, and UUIDv7.
Benchmarks
npm run bench
bench/frame-latency.bench.js — frame creation, pipe throughput, and duplex round-trip latency.
Requirements
Node.js 22 or later. ESM only.
Zero @polyweave dependencies. Core is the true root of the dependency graph.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @rigor/core | * |
| fast-check | ^3.23.2 |