# aviasoletechnologies/shapecraft architecture

> Architecture diagram of the GitHub repository aviasoletechnologies/shapecraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aviasoletechnologies/shapecraft
- Repository: https://github.com/aviasoletechnologies/shapecraft

## Overview

#### 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`.

Main entry points: [`src/core/generate.ts`](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/generate.ts) (Generate pipeline), [`src/core/stream.ts`](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/stream.ts) (Streaming generation), [`src/index.ts`](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/index.ts) (Library exports), [`src/core/client.ts`](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/client.ts) (Configured client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Public APIs"]
  node_root_exports["Library exports<br/>TypeScript entry<br/>[index.ts]"]
  node_cli["CLI<br/>TypeScript entry<br/>[cli.ts]"]
  node_agentic_exports["Agentic exports<br/>TypeScript entry<br/>[index.ts]"]
  node_fhir_exports["FHIR presets<br/>TypeScript entry<br/>[index.ts]"]
end

subgraph group_core["Generation Core"]
  node_model_types["Model interface<br/>shared types<br/>[types.ts]"]
  node_client["Configured client<br/>client factory<br/>[client.ts]"]
  node_generate["Generate pipeline<br/>generation control<br/>[generate.ts]"]
  node_schema["Schema normalization<br/>schema boundary<br/>[schema.ts]"]
  node_parse_validate["Parse &amp; structural validation<br/>[validate.ts]"]
  node_format_engines["XML &amp; GBNF<br/>format engines<br/>[xml.ts]"]
  node_timeout["Timeout &amp; cancellation<br/>lifecycle control<br/>[timeout.ts]"]
end

subgraph group_streaming["Streaming Pipeline"]
  node_stream["Streaming generation<br/>stream control<br/>[stream.ts]"]
  node_incremental_streaming["Incremental stream processing"]
end

subgraph group_extensions["Higher-Level Extensions"]
  node_execution_features["Batch, middleware &amp; tools<br/>execution features<br/>[batch.ts]"]
  node_agent_orchestrator["Agent orchestrator<br/>agent workflow<br/>[orchestrator.ts]"]
end

subgraph group_backends["Model Backends"]
  node_backend_factories["Backend factories<br/>provider adapters<br/>[index.ts]"]
  node_provider_adapters["Provider implementations<br/>[openai.ts]"]
end

subgraph group_runtime["Runtime &amp; Delivery"]
  node_provider_services{{"Provider SDKs &amp; inference<br/>external services"}}
  node_node_npm{{"Node.js &amp; npm<br/>runtime / distribution"}}
  node_ci_publish["CI &amp; publishing<br/>GitHub Actions<br/>[publish.yml]"]
end

node_root_exports -->|"exports"| node_client
node_root_exports -->|"exports"| node_generate
node_cli -->|"configures"| node_client
node_client -->|"invokes"| node_generate
node_generate -->|"normalizes input"| node_schema
node_schema -->|"delegates XML / GBNF"| node_format_engines
node_generate -->|"parses and validates"| node_parse_validate
node_generate -->|"bounds attempts"| node_timeout
node_generate -->|"uses model contract"| node_model_types
node_backend_factories -->|"implements"| node_model_types
node_backend_factories -->|"selects"| node_provider_adapters
node_provider_adapters -->|"calls"| node_provider_services
node_stream -->|"processes tokens"| node_incremental_streaming
node_stream -->|"final validation"| node_parse_validate
node_stream -->|"abort / retry"| node_timeout
node_execution_features -->|"composes"| node_generate
node_agentic_exports -->|"exports"| node_agent_orchestrator
node_agent_orchestrator -->|"runs agent steps"| node_generate
node_fhir_exports -->|"supplies schemas"| node_schema
node_node_npm -->|"runs / distributes"| node_root_exports
node_ci_publish -->|"publishes package"| node_node_npm

click node_root_exports "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/index.ts"
click node_cli "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/cli.ts"
click node_agentic_exports "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/agentic/index.ts"
click node_fhir_exports "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/fhir/index.ts"
click node_model_types "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/types.ts"
click node_client "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/client.ts"
click node_generate "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/generate.ts"
click node_schema "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/schema.ts"
click node_parse_validate "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/validate.ts"
click node_format_engines "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/xml.ts"
click node_timeout "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/timeout.ts"
click node_stream "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/stream.ts"
click node_incremental_streaming "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/streaming/incremental-parser.ts"
click node_execution_features "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/batch.ts"
click node_agent_orchestrator "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/agentic/orchestrator.ts"
click node_backend_factories "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/backends/index.ts"
click node_provider_adapters "https://github.com/aviasoletechnologies/shapecraft/blob/main/src/backends/openai.ts"
click node_ci_publish "https://github.com/aviasoletechnologies/shapecraft/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_exports,node_cli,node_agentic_exports,node_fhir_exports toneBlue
class node_model_types,node_client,node_generate,node_schema,node_parse_validate,node_format_engines,node_timeout toneAmber
class node_stream,node_incremental_streaming toneMint
class node_execution_features,node_agent_orchestrator toneRose
class node_backend_factories,node_provider_adapters toneIndigo
class node_provider_services,node_node_npm,node_ci_publish toneTeal
```

## Components

### Public APIs

- [Library exports](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/index.ts): TypeScript entry · `src/index.ts`
- [CLI](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/cli.ts): TypeScript entry · `src/cli.ts`
- [Agentic exports](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/agentic/index.ts): TypeScript entry · `src/agentic/index.ts`
- [FHIR presets](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/fhir/index.ts): TypeScript entry · Tree-shakeable FHIR R4 schema presets. · `src/fhir/index.ts`

### Generation Core

- [Model interface](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/types.ts): shared types · Common model contract and capability types. · `src/types.ts`
- [Configured client](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/client.ts): client factory · `src/core/client.ts`
- [Generate pipeline](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/generate.ts): generation control · Instructions, invocation, parsing, validation, and retries. · `src/core/generate.ts`
- [Schema normalization](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/schema.ts): schema boundary · Dispatches Zod, JSON Schema, custom, XML, and GBNF inputs. · `src/core/schema.ts`
- [Parse & structural validation](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/validate.ts): validation · `src/core/validate.ts`
- [XML & GBNF](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/xml.ts): format engines · Template validation and bundled grammar matching. · `src/core/xml.ts`
- [Timeout & cancellation](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/timeout.ts): lifecycle control · Per-attempt timeout and AbortSignal enforcement. · `src/core/timeout.ts`

### Streaming Pipeline

- [Streaming generation](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/stream.ts): stream control · Retains final validation and retry semantics. · `src/core/stream.ts`
- [Incremental stream processing](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/streaming/incremental-parser.ts): parser / validator / emitter · Parses tokens, validates completed fields, and emits lifecycle events. · `src/core/streaming/incremental-parser.ts`

### Higher-Level Extensions

- [Batch, middleware & tools](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/core/batch.ts): execution features · Bounded parallelism, middleware, skills, tools, and multi-turn completion. · `src/core/batch.ts`
- [Agent orchestrator](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/agentic/orchestrator.ts): agent workflow · Runs sequential agents with validated handoffs. · `src/agentic/orchestrator.ts`

### Model Backends

- [Backend factories](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/backends/index.ts): provider adapters · Adapts provider APIs to the common model interface. · `src/backends/index.ts`
- [Provider implementations](https://github.com/aviasoletechnologies/shapecraft/blob/main/src/backends/openai.ts): OpenAI / Anthropic / llama.cpp · Native constraints, token constraints, or prompting by capability. · `src/backends/openai.ts`

### Runtime & Delivery

- **Provider SDKs & inference**: external services · OpenAI-compatible, Anthropic, Gemini, Ollama, and local GGUF inference.
- **Node.js & npm**: runtime / distribution
- [CI & publishing](https://github.com/aviasoletechnologies/shapecraft/blob/main/.github/workflows/publish.yml): GitHub Actions · `.github/workflows/publish.yml`

## Connections

- Library exports → Configured client: exports
- Library exports → Generate pipeline: exports
- CLI → Configured client: configures
- Configured client → Generate pipeline: invokes
- Generate pipeline → Schema normalization: normalizes input
- Schema normalization → XML & GBNF: delegates XML / GBNF
- Generate pipeline → Parse & structural validation: parses and validates
- Generate pipeline → Timeout & cancellation: bounds attempts
- Generate pipeline → Model interface: uses model contract
- Backend factories → Model interface: implements
- Backend factories → Provider implementations: selects
- Provider implementations → Provider SDKs & inference: calls
- Streaming generation → Incremental stream processing: processes tokens
- Streaming generation → Parse & structural validation: final validation
- Streaming generation → Timeout & cancellation: abort / retry
- Batch, middleware & tools → Generate pipeline: composes
- Agentic exports → Agent orchestrator: exports
- Agent orchestrator → Generate pipeline: runs agent steps
- FHIR presets → Schema normalization: supplies schemas
- Node.js & npm → Library exports: runs / distributes
- CI & publishing → Node.js & npm: publishes package