From a20ace1b2dafafc357c5e63fd6f5cd034119c2b9 Mon Sep 17 00:00:00 2001 From: Stackbilt Date: Thu, 7 May 2026 11:51:27 -0500 Subject: [PATCH] deprecation(#59): mark ImageProvider, ImageProviderConfig, IMAGE_MODELS as @deprecated (v1.6.1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit img-forge is the org's canonical image generation service. ImageProvider is a frozen snapshot of img-forge internals that will not track new models or providers as img-forge's registry grows. Phase 1 (this PR): JSDoc @deprecated on ImageProvider, ImageProviderConfig, IMAGE_MODELS. Exports retained — no breaking change. normalizeAiResponse left undeprecated pending Phase 2 audit. Phase 2 (next major): remove src/image/ entirely. Closes #59 Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 5 +++++ README.md | 10 ++++++++-- package.json | 2 +- src/image/provider.ts | 14 ++++++++++++++ src/image/types.ts | 2 ++ 5 files changed, 30 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8132765..5e6e7c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,11 @@ All notable changes to `@stackbilt/llm-providers` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/). Versions use [Semantic Versioning](https://semver.org/). +## [1.6.2] — 2026-05-07 + +### Deprecated +- **`ImageProvider`, `ImageProviderConfig`, `IMAGE_MODELS`** — marked `@deprecated`. img-forge is the org's canonical image generation service; `ImageProvider` is a frozen snapshot of img-forge internals and will not track new models or providers. Use the img-forge API or MCP tools for image generation. Exports are retained for backward compatibility and will be removed in the next major version. `normalizeAiResponse` is not yet deprecated (under audit). + ## [1.6.1] — 2026-05-06 ### Added diff --git a/README.md b/README.md index 578c1e5..8451923 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,17 @@ A multi-provider LLM abstraction layer with automatic failover, graduated circui - **Provider-agnostic cache hints** -- `LLMRequest.cache` translates to provider-native caching (Anthropic `cache_control` breakpoints; automatic on OpenAI/Groq/Cerebras); cached token counts normalized into `TokenUsage` - **Schema drift detection** -- envelope validation on every provider response; streaming frames validated per-chunk; `SchemaDriftError` routes through fallback chain and fires `onSchemaDrift` hook - **Schema canary** -- `runCanaryCheck` / `extractShape` / `compareShapes` for comparing live response shapes against committed golden fixtures -- **Image generation** -- Cloudflare Workers AI (SDXL, FLUX) and Google Gemini +- **Image generation** -- `ImageProvider` is deprecated; use [img-forge](https://github.com/Stackbilt-dev/img-forge) instead - **Health monitoring** -- per-provider health checks, metrics, and circuit breaker state - **Structured logging** -- injectable `Logger` interface; silent by default, opt-in to console or custom loggers - **Zero runtime dependencies** -- no transitive dependency tree to audit +## Deprecated APIs + +**`ImageProvider` is deprecated.** It was extracted from img-forge during an earlier phase when llm-providers and img-forge were more tightly coupled. img-forge is now the dedicated imagegen service with a full quality-tier registry, async orchestration, and quota metering. Use the [img-forge API](https://github.com/Stackbilt-dev/img-forge) or MCP tools for image generation. llm-providers handles text inference and vision understanding only. + +`ImageProvider`, `ImageProviderConfig`, and `IMAGE_MODELS` will be removed in the next major version. The `normalizeAiResponse` utility is under audit and may be retained as a standalone export. + ## Installation ```bash @@ -409,7 +415,7 @@ fs.writeFileSync('fixtures/openai.json', JSON.stringify(shape, null, 2)); | `CreditLedger` | Monthly budgets, rate limits, burn rate projection, threshold events | | `CostOptimizer` | Static methods for optimal provider selection | | `MODEL_CATALOG` | Declarative model metadata for routing and recommendation | -| `ImageProvider` | Multi-provider image generation (Cloudflare SDXL/FLUX, Google Gemini) | +| `ImageProvider` | **[Deprecated]** Multi-provider image generation — use [img-forge](https://github.com/Stackbilt-dev/img-forge) instead | | `extractShape` | Walk a raw API response into a flat `path → type` shape map | | `compareShapes` | Diff two shape maps into `{ added, removed, changed }` | | `runCanaryCheck` | One-shot canary: extract live shape, compare against golden, return `CanaryReport` | diff --git a/package.json b/package.json index 9cc98a1..07d7e23 100755 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@stackbilt/llm-providers", - "version": "1.6.1", + "version": "1.6.2", "description": "Multi-LLM failover with circuit breakers, cost tracking, and intelligent retry. Cloudflare Workers native.", "author": "Stackbilt ", "license": "Apache-2.0", diff --git a/src/image/provider.ts b/src/image/provider.ts index 533790f..0d5f3e2 100644 --- a/src/image/provider.ts +++ b/src/image/provider.ts @@ -7,11 +7,19 @@ * - Google Gemini (Flash Image, Flash Image Preview) * * Extracted from img-forge production codebase. Battle-tested. + * + * @deprecated Use the img-forge service or the img-forge MCP tools instead. + * ImageProvider is a frozen snapshot of img-forge's internals and will not + * track new models or providers. For image generation from within a Worker, + * call the img-forge gateway via fetch or the GATEWAY service binding. */ import type { ImageRequest, ImageResponse, ImageModelConfig } from './types.js'; import { IMAGE_MODELS, getImageModel } from './types.js'; +/** + * @deprecated Use img-forge instead. See ImageProvider deprecation notice. + */ export interface ImageProviderConfig { /** Cloudflare Workers AI binding (env.AI) */ cloudflareAi?: unknown; @@ -23,6 +31,12 @@ export interface ImageProviderConfig { models?: Record; } +/** + * @deprecated Use the img-forge service or the img-forge MCP tools instead. + * ImageProvider is a frozen snapshot of img-forge's internals and will not + * track new models or providers. For image generation from within a Worker, + * call the img-forge gateway via fetch or the GATEWAY service binding. + */ export class ImageProvider { private cloudflareAi: unknown; private geminiApiKey: string | null; diff --git a/src/image/types.ts b/src/image/types.ts index cc6c4c1..b78bad5 100644 --- a/src/image/types.ts +++ b/src/image/types.ts @@ -44,6 +44,8 @@ export interface ImageResponse { /** * Built-in image model registry. * Quality tiers map to specific provider + model combinations. + * + * @deprecated Use img-forge instead. See ImageProvider deprecation notice. */ export const IMAGE_MODELS: Record = { // Cloudflare Workers AI — fast, included in free tier