aviasoletechnologies/shapecraft

Purpose and Public Entry Points

Shapecraft is a Node.js/TypeScript library for LLM structured-output generation: it normalizes schema inputs, invokes provider-specific models, validates output, and retries failures. Root exports are in src/index.ts; the CLI entry is src/cli.ts. Tree-shakeable domain entry points include agent orchestration in src/agentic/index.ts and FHIR presets in src/fhir/index.ts.

Model Abstraction and Backend Adapters

Core operations target a common model interface/types defined in src/types.ts. Provider factories in src/backends/index.ts adapt OpenAI-compatible APIs, Anthropic, Gemini, Ollama, and local llama.cpp to that interface. Representative implementations are src/backends/openai.ts, src/backends/anthropic.ts, and src/backends/llamaCpp.ts. Backends expose capabilities and enforce structured output natively, through token constraints, or best-effort prompting depending on provider support.

Generation and Validation Pipeline

src/core/generate.ts is the primary control path: construct schema-aware instructions, call the model, parse output, structurally validate it, then retry schema failures within timeout/cancellation boundaries. Validation is centralized in src/core/validate.ts; schema normalization and Zod/JSON Schema handling are in src/core/schema.ts. The pipeline supports optional semantic validation, confidence scoring, and post-processing after structural acceptance.

Schema and Format Boundaries

Schema input dispatch supports Zod, raw JSON Schema, regex/custom validators, XML templates, and GBNF. Parsing is isolated in src/core/parse.ts; XML template construction/validation is in src/core/xml.ts; the bundled grammar parser/matcher is src/core/gbnf.ts. This boundary distinguishes deterministic structural checks from semantic truthfulness, which callers must supply via validators.

Streaming, Retries, and Lifecycle

src/core/stream.ts provides the streaming variant while preserving the same final validation semantics as one-shot generation. Its subpipeline in src/core/streaming/incremental-parser.ts, src/core/streaming/validator.ts, and src/core/streaming/emitter.ts tokenizes streamed JSON, validates completed top-level fields early where possible, emits lifecycle events, and aborts/retries invalid attempts. src/core/timeout.ts enforces per-attempt timeout and AbortSignal behavior independent of backend cooperation.

Client, Parallelism, and Higher-Level Execution

src/core/client.ts creates configured clients with defaults; src/core/middleware.ts wraps non-streaming generation with Koa-style middleware. src/core/batch.ts runs independent requests with bounded concurrency and all-settled ordered results. src/core/skills.ts implements schema-driven skill selection and iterative handler execution, while src/core/tools.ts normalizes native provider tool calls and validates arguments before handler invocation. src/core/turnaround.ts supports conversational multi-turn completion before final structured extraction.

Agentic and Healthcare Extensions

src/agentic/agent.ts defines an agent as model, schema, role, and optional prompt builder; src/agentic/orchestrator.ts executes caller-routed sequential agent steps using ordinary generation and validated handoffs. FHIR R4 extraction presets are separate schemas under src/fhir/patient.ts, src/fhir/observation.ts, and related files, keeping healthcare types optional and tree-shakeable.

Runtime and External Services

The package runs on Node.js and is distributed through npm. Backend integrations require optional provider SDKs or HTTP services: OpenAI-compatible services (OpenAI, Groq, Fireworks, Mistral, OpenRouter, DeepSeek), Anthropic, Google Gemini, Ollama, and local GGUF inference through node-llama-cpp. GitHub Actions CI/publishing workflows reside in .github/workflows/ci.yml and .github/workflows/publish.yml.