@sudobility/shapeshyft_engine 1.0.0

package/CLAUDE.md

@@ -0,0 +1,27 @@
+# shapeshyft_engine
+
+> **Git policy — never auto-commit or auto-push.** Run `git commit`, `git push`,
+> or publish only when the user explicitly asks in that turn.
+
+Stateless core shared by `shapeshyft_api` and `shaperouter_api` (via
+`@sudobility/shapeshyft_service`). No database, no Hono, no `process.env`.
+
+## Entry points
+
+- `@sudobility/shapeshyft_engine` — `createLLMProvider`, provider adapters,
+  provider/model catalog (`config/providers`), prompt builder, `ApiHelper`,
+  media handling, capability validation, reserved fields, output limits.
+- `@sudobility/shapeshyft_engine/types` — domain types and pure helpers. Must
+  never gain a runtime `import`; `tests/unit/types-no-runtime-imports.test.ts`
+  enforces it. Frontend packages (`shapeshyft_types`, `shaperouter_types`)
+  re-export this.
+
+## Rules
+
+- Relative imports carry `.js` (`NodeNext`). The compiler rejects them otherwise.
+- Provider SDKs and `sharp` are optional peer dependencies.
+- Provider credentials arrive in `ProviderConfig`; the engine never looks them up.
+
+## Commands
+
+    bun run verify   # typecheck + lint + test + build

package/README.md

@@ -0,0 +1,11 @@
+# @sudobility/shapeshyft_engine
+
+Stateless LLM structured-output engine used by ShapeShyft and ShapeRouter.
+
+```ts
+import { createLLMProvider } from "@sudobility/shapeshyft_engine";
+import type { LlmProvider } from "@sudobility/shapeshyft_engine/types";
+
+const provider = createLLMProvider("openai", { apiKey });
+const result = await provider.generate(request);
+```

package/dist/config/providers.d.ts

@@ -0,0 +1,111 @@
+/**
+ * LLM Provider and Model Configuration
+ *
+ * This configuration is served via API endpoints so it can be updated
+ * without requiring frontend package updates.
+ *
+ * ## Supported Providers
+ *
+ * Catalog verified against provider documentation on 2026-08-18.
+ *
+ * - **openai**: GPT-5.6 (Sol/Terra/Luna), GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, GPT-4o
+ * - **anthropic**: Claude Fable 5, Opus 5, Sonnet 5, Haiku 4.5 (+ Opus 4.8/4.7/4.6, Sonnet 4.6)
+ * - **gemini**: Gemini 3.7/3.6/3.5/3.1 and 2.5, Nano Banana image models, Veo 3.1 video
+ * - **mistral**: Mistral Large 3, Medium 3.5, Small 4, Ministral 3, Codestral, OCR
+ * - **cohere**: Command A+, Command A (reasoning/vision/translate), Command R
+ * - **groq**: GPT-OSS, Qwen3.6, MiniMax M2.7, Compound, Whisper
+ * - **xai**: Grok 4.6, 4.5, 4.3, Grok 4.20 variants, Grok Build
+ * - **deepseek**: DeepSeek V4 Pro and V4 Flash
+ * - **perplexity**: Sonar models with live web search grounding
+ * - **lm_studio**: Local LLM server (LM Studio or any OpenAI-compatible endpoint)
+ *
+ * ## Keeping this current
+ *
+ * Model lineups turn over every few weeks and retired IDs fail at the provider,
+ * not here -- `MODEL_CAPABILITIES` and `MODEL_PRICING` fall back to permissive
+ * defaults for anything unknown, so a stale entry surfaces as a runtime error in
+ * a user's endpoint. When updating, work from each provider's own model and
+ * pricing pages (linked above each section below), and check the provider's
+ * deprecation page for retirements: Groq retired `llama-3.3-70b-versatile` and
+ * `llama-3.1-8b-instant` on 2026-08-16, and both were listed here until then.
+ *
+ * Pricing is in **cents per 1M tokens** (image per image, audio/video per minute).
+ *
+ * ## LM Studio Model Identifiers
+ *
+ * LM Studio uses the OpenAI-compatible API format. When specifying models:
+ *
+ * - **API requests** use just the model name (e.g., `"qwen2.5-vl-7b-instruct"`)
+ * - **Downloading models** uses publisher/name format (e.g., `lmstudio-community/Qwen2.5-VL-7B-Instruct-GGUF`)
+ *
+ * The model identifier in API requests matches what's returned by `GET /v1/models`.
+ * Example response:
+ * ```json
+ * { "id": "qwen2.5-vl-7b-instruct", "object": "model" }
+ * ```
+ *
+ * To discover available models on a running LM Studio server:
+ * ```bash
+ * curl http://localhost:1234/v1/models
+ * ```
+ *
+ * For multi-variant models, you can specify quantization with `@`:
+ * ```
+ * google/gemma-3-12b@q3_k_l
+ * google/gemma-3-12b@4bit
+ * ```
+ *
+ * ## Vision Models
+ *
+ * Vision-capable models can process images in addition to text:
+ * - Qwen2.5-VL series: Excellent object recognition, 128k context window
+ * - Gemma 3 series: Google's multimodal models
+ * - GLM-4V: Optimized for local deployment
+ * - Pixtral: Mistral's vision model
+ * - olmOCR: Specialized for OCR tasks
+ * - Janus-Pro: Visual QA and scene interpretation
+ *
+ * Note: Vision models are not optimal for text-only tasks. For text-only
+ * workloads, use dedicated text models like Qwen3 or Mistral.
+ *
+ * @see https://lmstudio.ai/docs/developer/openai-compat
+ * @see https://lmstudio.ai/docs/developer/openai-compat/models
+ */
+import type { LlmProvider, ModelCapabilities, ModelPricing, ProviderConfig } from "../types/index.js";
+export declare const PROVIDERS: ProviderConfig[];
+export declare const PROVIDER_MODELS: Record<LlmProvider, string[]>;
+export declare const MODEL_CAPABILITIES: Record<string, ModelCapabilities>;
+export declare const MODEL_PRICING: Record<string, ModelPricing>;
+export declare const DEFAULT_MODEL_PRICING: ModelPricing;
+/**
+ * Get provider configuration by ID.
+ * @param providerId - The provider identifier (e.g., "openai", "anthropic")
+ * @returns The provider config or undefined if not found
+ */
+export declare function getProviderById(providerId: LlmProvider): ProviderConfig | undefined;
+/**
+ * Get the list of model IDs for a given provider.
+ * @param providerId - The provider identifier
+ * @returns Array of model ID strings
+ */
+export declare function getModelsForProvider(providerId: LlmProvider): string[];
+/**
+ * Get capabilities for a specific model (vision, audio, video I/O).
+ * Returns empty object for unknown models (permissive by default).
+ * @param model - The model identifier
+ * @returns Model capabilities
+ */
+export declare function getModelCapabilities(model: string): ModelCapabilities;
+/**
+ * Get pricing for a specific model (cents per 1M tokens).
+ * Returns DEFAULT_MODEL_PRICING for unknown models.
+ * @param model - The model identifier
+ * @returns Model pricing
+ */
+export declare function getModelPricing(model: string): ModelPricing;
+/**
+ * Get the provider for a given model name.
+ * Searches through PROVIDER_MODELS to find which provider owns this model.
+ */
+export declare function getProviderForModel(model: string): LlmProvider;
+//# sourceMappingURL=providers.d.ts.map

package/dist/config/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/config/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAM3B,eAAO,MAAM,SAAS,EAAE,cAAc,EAoFrC,CAAC;AAMF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,CA2JzD,CAAC;AAMF,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAs8BhE,CAAC;AAMF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA6MtD,CAAC;AAGF,eAAO,MAAM,qBAAqB,EAAE,YAA0C,CAAC;AAM/E;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,WAAW,GACtB,cAAc,GAAG,SAAS,CAE5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,WAAW,GAAG,MAAM,EAAE,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAK3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAQ9D"}