v0.1.0-alpha.21 — Structured-output reliability + OTel observability hooks (additive)

[baabakk]

Released 2026-06-18. Install: pnpm add @llm-ports/core@alpha @llm-ports/adapter-openai@alpha @llm-ports/capabilities@alpha

Two coordinated themes. All additive, no breaking changes.

1. Structured-output reliability batch

Driven by ADW's 2026-06-18 LLM Provider Test Report. The 8-call-per-provider sweep showed DeepInfra + Parasail were the only cheap-tier providers dropping required fields on the first attempt — empirically grounded in three numbers: deepseek-flash 2/8 retries, gemma-31b 8/8 retries (one on every call), mimo-parasail 3/8 retries. All three drop to 0/8 retries with strict mode.

What shipped

• Per-call strict?: boolean on GenerateStructuredOptions / StreamStructuredOptions. Adapters that don't implement strict mode silently ignore the hint. Plumbed through 5 capability factories.
• Strict-mode allowlist extended to api.deepinfra.com and api.parasail.io. Joins the existing list (OpenAI native, Cerebras, Groq, SambaNova).
• Bundled pricing for deepseek-ai/DeepSeek-V4-Flash, google/gemma-4-31B-it, XiaomiMiMo/MiMo-V2.5. No more parallel pricingOverrides for these.
• isJsonModeRejection matcher fix from adapter-openai: strict-schema-rejection rescue trigger doesn't match OpenAI native's error pattern #46 (already in main as 9cb9a82; bundled here too).

Closes

• adapter-openai: strict-schema-rejection rescue trigger doesn't match OpenAI native's error pattern #46 — per-call strict opt-out + adapter-openai strict-schema-rejection rescue
• adapter-openai: expand strict-mode allowlist to include DeepInfra and Parasail (empirically verified) #47 — DeepInfra + Parasail allowlist expansion
• adapter-openai: add pricing entries for DeepInfra (DeepSeek-V4-Flash, Gemma-4-31B-it) and Parasail (MiMo-V2.5) #48 — pricing entries for 3 compat models

2. OTel-aligned observability hooks

Five hooks on RegistryOptions.observability, aligned with OpenTelemetry's gen_ai.* semantic conventions so downstream pipelines (Honeycomb, Datadog, OTel Collector, OTLP exporters) map them onto spans + metrics without re-deriving fields:

const registry = createRegistryFromEnv({
  // ...existing options...
  observability: {
    onCost:        (e) => { /* per-call USD breakdown */ },
    onTokenUsage:  (e) => { /* per-call token counts */ },
    onFallback:    (e) => { /* fired when chain advances */ },
    onCacheHit:    (e) => { /* fired when cached_tokens > 0 */ },
    onValidationRetry: (e) => { /* type-only in alpha.21 */ },
  },
});

All hooks sync OR async, errors swallowed (observability instrumentation can't break inference).

Emission coverage

Hook	alpha.21	Where it fires
onCost	✅	Every successful generateText / generateStructured / runAgent
onTokenUsage	✅	Every successful generateText / generateStructured / runAgent
onCacheHit	✅	When the response reports cacheReadTokens > 0
onFallback	✅	When walkChain advances from one alias to the next
onValidationRetry	Type only	Emission deferred to alpha.22

For onValidationRetry today: use the adapter onRetry hook and filter on reason === "validation-feedback". Stream methods don't emit cost yet (alpha.22 follow-up).

Backwards compatibility

All additions are additive. Calls without strict, registries without observability, adapters against allowlisted baseURLs unchanged.

Tests

• 14 new adapter-openai tests
• 22 new core observability-hooks tests
• All existing 505 unit tests pass

What's next (alpha.22)

• onValidationRetry Registry-level emission
• Streamed cost surfacing for onCost / onTokenUsage
• Cerebras pricing entries (pending rate confirmation)
• LP-REQ-01 resilient fallback preset (carried over from alpha.20.1)

Full release notes.