fascicle weekly downloads statistics

Fascicle

Compose agents out of LLM calls, tool calls, and plain functions. Everything is a Step<i, o>. Wire steps together with 23 primitives (sequence, parallel, chain, branch, retry, loop, ensemble_step, checkpoint, …) and run them as plain values. One generate surface fronts eight provider adapters: Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, Ollama, LM Studio, and a claude_cli subprocess that drives the Claude Code CLI.

No framework lifecycle. No ambient state. No decorators. Adapters are passed in per run.

Install

pnpm add fascicle

Fascicle is ESM-only and requires Node >= 24. ai, zod, and every provider SDK are optional peers — install only the ones you use. pnpm add fascicle alone builds and runs a flow against transport: 'native' or claude_cli, with no AI SDK package and no schema library installed at all; schemas accept any Standard Schema — zod, ArkType, Valibot, whichever you already use. See docs/providers.md.

No API key on hand? Several runnable examples need zero keys: examples/hello/main.ts, examples/suspend-resume/main.ts, and examples/viewer-demo/main.ts use no engine at all, and examples/newsroom/main.ts runs the full vocabulary against the bundled stub engine from fascicle/testing.

A 60-second tour

<!-- snippet: check -->

import { run, sequence, step } from 'fascicle';

const flow = sequence([
  step('add', (n: number) => n + 1),
  step('double', (n: number) => n * 2),
]);

await run(flow, 1); // 4

Add a model call:

<!-- snippet: check -->

import { create_engine, model_step, run, sequence, step } from 'fascicle';

const engine = create_engine({
  providers: {
    anthropic: { api_key: process.env.ANTHROPIC_API_KEY!, transport: 'native' },
  },
});

const flow = sequence([
  step('brief', (topic: string) => `Write a 2-sentence brief on: ${topic}`),
  model_step({ engine, model: 'claude-sonnet-4-6', system: 'No preamble.' }),
]);

try {
  console.log(await run(flow, 'Rust ownership'));
} finally {
  await engine.dispose();
}

transport: 'native' keeps the zero-peer promise above: raw HTTP against the Messages API, nothing to install beyond fascicle. Drop it to use the default ai_sdk transport, which needs pnpm add ai @ai-sdk/anthropic.

model_step returns the model's answer (a string, or the schema-validated value when schema is set), keeping flows at the step, step, model_step, step cadence. Underneath sits model_call, the only sanctioned bridge between composition and the engine: same config, but it returns the full GenerateResult envelope (usage, cost, tool calls, finish reason), with an optional project to map a slice of it at the source. Both thread ctx.abort, ctx.trajectory, and streaming chunks for you.

What's in the box

Composition primitives. Every composer takes Step<i, o> and returns Step<i, o>. Anything that fits a step fits any composition of steps. The everyday surface is small; most flows are built entirely from these nine:

Primitive	Shape
step	lift a plain function into Step<i, o>
sequence	run A then B then C, threading the value
parallel	run a named map of steps concurrently
branch	route on a predicate of the input
map	run a step per array element, optional concurrency cap
pipe	post-process an inner step's output with a plain function
retry	re-run on failure with exponential backoff
model_step	the model's answer as a step (model_call projected to its content)
chain	named steps over a typed record: .step binds, .stage concludes a phase, .output projects

The remaining primitives are specialized composers with the same contract, so they drop into any flow when the task calls for them: control flow (loop, fallback, timeout, compose), multi-model orchestration (adversarial, ensemble_step, consensus), and durability (checkpoint, suspend, gate). Behind those sits an advanced tier — the pick-best variants ensemble and tournament, the raw named-state primitives scope / stash / use underlying chain, and the self-improvement pair improve / learn — covered in docs/advanced-composition.md, each entry paired with the primary primitive to try first. One-liners for all of them live in docs/composition.md, full shapes in docs/api-reference.md, and docs/leaf-arm-spine.md is the decision guide for which layer each belongs to.

Plus run, run.stream, and describe. And inside any step body, ctx.call(step, input) runs another Step with spans, abort, and error paths intact: the direct-style counterpart to composing, for control flow too dynamic to declare.

AI engine. create_engine(config) returns one generate surface across eight providers. Two axes: model is an opaque id sent to the provider verbatim (claude-opus-4-8, gpt-4o, us.anthropic.claude-sonnet-4-20250514-v1:0), and provider names the transport (anthropic, bedrock, openrouter, claude_cli, …) — swap provider to move a call between transports. Reasoning effort ('none' through 'max') is translated per provider. Cost estimation uses a pricing table with per-engine overrides.…