@juspay/neurolink 12.19.1 → 12.20.0

package/CHANGELOG.md

@@ -1,8 +1,12 @@
-## [12.19.1](https://github.com/juspay/neurolink/compare/v12.19.0...v12.19.1) (2026-09-21)
+## [12.20.0](https://github.com/juspay/neurolink/compare/v12.19.2...v12.20.0) (2026-09-22)
+
+### Features
+
+- **(images):** let a caller choose the transcode output format ([f536fd0](https://github.com/juspay/neurolink/commit/f536fd0916f9e688c723cf679e05f8d995d12e9f))
 
 ### Bug Fixes
 
-- **(proxy):** pin each bridged Codex conversation to one prompt cache ([1ec34a9](https://github.com/juspay/neurolink/commit/1ec34a940ced3ba5d35ccaaee5141928ffe03e8f))
+- **(rag):** keep SVG out of the raster image path and scope the sanitized-markup claim ([0716f94](https://github.com/juspay/neurolink/commit/0716f944d097b2a8944e4036a72fccf3f7c636b6))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/README.md

@@ -39,17 +39,17 @@ const decision = await pipe.tryDecide({
 // decision?.answers.autoApprove.probability -> 0.91
 ```
 
-**[→ Docs](https://docs.neurolink.ink) · [→ Quick Start](https://docs.neurolink.ink/docs/getting-started/quick-start) · [→ npm](https://www.npmjs.com/package/@juspay/neurolink)**
+**[→ Docs](https://docs.neurolink.ink) · [→ Quick Start](https://docs.neurolink.ink/docs/getting-started/quick-start) · [→ npm](https://www.npmjs.com/package/@juspay/neurolink) · [→ Blog](https://blog.neurolink.ink)**
 
 ---
 
 ## 🧠 What is NeuroLink?
 
-**NeuroLink is the universal AI integration platform that unifies 40 AI providers under one consistent API, across three inference types: `generate`, `stream`, and `decide`.** A curated 64-model registry (7 providers, 132 aliases) backs model metadata, routing, and context-window checks out of the box, and hundreds more models are reachable through aggregator providers — 100+ via LiteLLM, 300+ via OpenRouter.
+**NeuroLink is the pipe layer of an AI nervous system.** Providers — OpenAI, Anthropic, Google, AWS, Azure, Mistral, local runtimes like Ollama, and dozens more — are the neurons: each generates a different kind of intelligence, at a different cost and latency. NeuroLink is the vascular layer that carries that intelligence, as a stream, to the applications — the organs — that consume it, across three inference types: `generate` and `stream` produce text, `decide` produces a calibrated `boolean`/`choice`/`score` judgment instead. A curated model registry (64 models, 132 aliases) backs metadata, routing, and context-window checks out of the box, and hundreds more models are reachable through aggregator providers — 100+ via LiteLLM, 300+ via OpenRouter.
 
-Extracted from production systems at Juspay, NeuroLink provides a practical, TypeScript-first way to integrate AI into any application. Whether you're building with OpenAI, Anthropic, Google, AWS Bedrock, Azure, or any of our 40 supported providers, NeuroLink gives you a single, consistent interface that works everywhere. `decide` is the third inference type — a typed, calibrated judgment instead of text — for the model-routing and gating decisions `generate`/`stream` were never meant to make.
+Extracted from production systems at Juspay, NeuroLink provides a practical, TypeScript-first way to plug any application into that nervous system. Switch which neuron answers a request with a single parameter change — OpenAI, Anthropic, Google, AWS Bedrock, Azure, a local runtime, or any provider you add. `decide` is the third inference type — a typed, calibrated judgment instead of text — for the model-routing and gating decisions `generate`/`stream` were never meant to make, powered by a purpose-built decision model (TypeSafe Jev) rather than a general-purpose LLM: routing decisions land in ~400ms for about $0.00002, instead of a full generation call.
 
-**Why NeuroLink?** Three genuine inference types, not one dressed up three ways — `generate` and `stream` produce text; `decide` produces a calibrated `boolean`/`choice`/`score` judgment, and which types a provider serves is declared per-provider via `inferenceKinds` rather than inferred from behavior. One API spans all 40 providers, including 3 fully local runtimes (Ollama, LM Studio, llama.cpp) with per-request credential overrides, and MCP support covers all 4 transports (stdio, HTTP, SSE, WebSocket). Every AI-driven optimization — model routing, context compaction, tool selection — fails open: no key configured behaves exactly like NeuroLink without it, and routing uses asymmetric confidence thresholds (upgrade at 0.3, downgrade at 0.6) rather than a single cutoff, because a wrong downgrade costs more than a wrong upgrade. Switch providers with a single parameter change, leverage built-in tools plus any MCP-compliant tool server, deploy with confidence using enterprise features like Redis memory and multi-provider failover, and optimize costs automatically with intelligent routing. Use it via our professional CLI or TypeScript SDK—whichever fits your workflow.
+**Why NeuroLink?** Three genuine inference types, not one dressed up three ways — `generate` and `stream` produce text; `decide` produces a calibrated `boolean`/`choice`/`score` judgment, and which types a provider serves is declared per-provider via `inferenceKinds` rather than inferred from behavior. Every neuron plugs into the same pipe, including 3 fully local runtimes (Ollama, LM Studio, llama.cpp) with per-request credential overrides, and MCP support covers all 4 transports (stdio, HTTP, SSE, WebSocket). Every AI-driven optimization the pipe performs — model routing, context compaction, tool selection — fails open: no key configured behaves exactly like NeuroLink without it, and routing uses asymmetric confidence thresholds (upgrade at 0.3, downgrade at 0.6) rather than a single cutoff, because a wrong downgrade costs more than a wrong upgrade. Switch providers with a single parameter change, leverage built-in tools plus any MCP-compliant tool server, deploy with confidence using enterprise features like Redis memory and multi-provider failover, and optimize costs automatically with intelligent routing. Use it via our professional CLI or TypeScript SDK—whichever fits your workflow.
 
 **Where we're headed:** We're building for the future of AI—edge-first execution and continuous streaming architectures that make AI practically free and universally available. **[Read our vision →](docs/about/vision.md)**
 
@@ -410,7 +410,7 @@ npx @juspay/neurolink --help
 
 ### Configuration
 
-NeuroLink works with 40 AI providers. You'll need at least one API key to get started:
+NeuroLink works with every major AI provider — and local runtimes that need no API key at all. You'll need at least one to get started:
 
 **Option 1: Interactive Setup (Recommended)**
 
@@ -597,7 +597,7 @@ const result = await neurolink.generate({
 ### Next Steps
 
 - **[Complete Documentation](https://docs.neurolink.ink)** - Comprehensive guides and API reference
-- **[Provider Setup Guide](docs/getting-started/provider-setup.md)** - Configure all 40 providers
+- **[Provider Setup Guide](docs/getting-started/provider-setup.md)** - Configure any provider
 - **[SDK API Reference](docs/sdk/api-reference.md)** - Full TypeScript API documentation
 - **[CLI Command Reference](docs/cli/commands.md)** - Complete CLI documentation
 - **[Example Projects](docs/examples/index.md)** - Real-world integration examples
@@ -629,7 +629,7 @@ NeuroLink is a comprehensive AI development platform. Every feature below is shi
 
 ### 🤖 AI Provider Integration
 
-**40 providers unified under one API** - Switch providers with a single parameter change. 39 serve `generate`/`stream`; 1 (TypeSafe Jev) serves `decide`. Tool support: 29 native tool-calling, 3 model-dependent, 8 that serve no tools at all (embedding-, media- and decision-only). 3 are fully local runtimes (Ollama, LM Studio, llama.cpp) and 4 need zero configuration to start (those three plus LiteLLM) — no cloud account, no API key. 9 providers (OpenAI, Google AI Studio, Google Vertex, Amazon Bedrock, Cohere, Ollama, LiteLLM, Voyage, Jina) expose `embed()`/`embedMany()` natively for RAG and custom vector search.
+**Every provider neuron behind one API** - Switch providers with a single parameter change. Nearly all serve `generate`/`stream`; TypeSafe Jev alone serves `decide`. Tool support: 29 native tool-calling, 3 model-dependent, 8 that serve no tools at all (embedding-, media- and decision-only). 3 are fully local runtimes (Ollama, LM Studio, llama.cpp) and 4 need zero configuration to start (those three plus LiteLLM) — no cloud account, no API key. 9 providers (OpenAI, Google AI Studio, Google Vertex, Amazon Bedrock, Cohere, Ollama, LiteLLM, Voyage, Jina) expose `embed()`/`embedMany()` natively for RAG and custom vector search.
 
 | Provider              | Models                                                                     | Free Tier       | Tool Support | Status        | Documentation                                                                                                                 |
 | --------------------- | -------------------------------------------------------------------------- | --------------- | ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -668,7 +668,7 @@ NeuroLink is a comprehensive AI development platform. Every feature below is shi
 **Decision-only provider:** **TypeSafe Jev** (`TYPESAFE_API_KEY`) does not appear in the table above because it does not serve `generate`/`stream` — it is the first provider for the `decide` inference type. See [Decide: Calibrated Judgments, Not Text](#decide-calibrated-judgments-not-text).
 
 **[📖 Provider Comparison Guide](docs/reference/provider-comparison.md)** - Detailed feature matrix and selection criteria
-**[🔬 Provider Feature Compatibility](docs/reference/provider-feature-compatibility.md)** - Test-based compatibility reference for all 19 features across 40 providers
+**[🔬 Provider Feature Compatibility](docs/reference/provider-feature-compatibility.md)** - Test-based compatibility reference for all 19 features across every provider
 
 ---
 
@@ -854,7 +854,7 @@ neurolink generate "Describe what happens" --file ./demo.mp4
 - **ProcessorRegistry** - Priority-based processor selection with fallback
 - **OWASP Security** - HTML/SVG sanitization prevents XSS attacks
 - **Auto-detection** - FileDetector identifies file types by extension and content
-- **Provider-agnostic** - All processors work across all 40 AI providers
+- **Provider-agnostic** - All processors work across every AI provider
 
 **[📖 File Processors Guide](docs/features/file-processors.md)** - Complete reference for all file types
 
@@ -984,7 +984,7 @@ node your-app.js
 
 ### 🤖 GitHub Action
 
-Run AI-powered workflows directly in GitHub Actions with 40 provider support and automatic PR/issue commenting.
+Run AI-powered workflows directly in GitHub Actions with support for every provider and automatic PR/issue commenting.
 
 ```yaml
 - uses: juspay/neurolink@v1
@@ -996,7 +996,7 @@ Run AI-powered workflows directly in GitHub Actions with 40 provider support and
 
 | Feature                | Description                                                                               |
 | ---------------------- | ----------------------------------------------------------------------------------------- |
-| **Multi-Provider**     | 40 providers with unified interface                                                       |
+| **Multi-Provider**     | Every provider behind one unified interface                                               |
 | **PR/Issue Comments**  | Auto-post AI responses with intelligent updates                                           |
 | **Multimodal Support** | Attach images, PDFs, CSVs, Excel, Word, JSON, YAML, XML, HTML, SVG, code files to prompts |
 | **Cost Tracking**      | Built-in analytics and quality evaluation                                                 |
@@ -1189,7 +1189,7 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 
 | Capability               | Highlights                                                                                                                                                                                                                                                                                                     |
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Provider unification** | 40 providers with automatic fallback, cost-aware routing, `providerFallback` policy, `modelChain` config.                                                                                                                                                                                                      |
+| **Provider unification** | Every provider neuron behind one API, with automatic fallback, cost-aware routing, `providerFallback` policy, `modelChain` config.                                                                                                                                                                             |
 | **Decision inference**   | Third inference type (`decide`) alongside generate/stream: calibrated `boolean`/`choice`/`score` judgments via TypeSafe Jev, ~400ms flat, ~$0.00002/decision. Used internally for model routing, context budgeting, relevance compaction and tool routing; per-query RAG planning is opt-in via `RAGPipeline`. |
 | **Multimodal pipeline**  | Stream images + CSV data + PDF documents across providers with local/remote assets. Auto-detection for mixed file types.                                                                                                                                                                                       |
 | **Voice pipeline**       | TTS (6 providers: Google, OpenAI, ElevenLabs, Azure, Fish Audio, Cartesia) + STT (4 providers) + realtime voice APIs (OpenAI Realtime, Gemini Live).                                                                                                                                                           |

package/dist/adapters/imageFormatSupport.d.ts

@@ -19,7 +19,7 @@
  *
  * @module adapters/imageFormatSupport
  */
-import type { ImageWithAltText, VisionImageConversion } from "../types/index.js";
+import type { ImageWithAltText, VisionImageConversion, VisionImageOutputFormat } from "../types/index.js";
 /**
  * MIME types every vision-capable provider accepts as-is.
  *
@@ -57,8 +57,11 @@ export declare function needsVisionTranscode(mimeType: string): boolean;
  *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
+ * @param outputFormat - Transcode target. Defaults to `"png"` — see the
+ *   module header for why that stays the default for every caller who
+ *   doesn't opt into `"jpeg"` explicitly.
  */
-export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string): Promise<VisionImageConversion>;
+export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string, outputFormat?: VisionImageOutputFormat): Promise<VisionImageConversion>;
 /**
  * Unwrap an `input.images` entry to its payload.
  *

package/dist/adapters/imageFormatSupport.js

@@ -23,7 +23,12 @@ import { extensionForMimeType } from "../processors/config/fileTypeRegistry.js";
 import { withTimeout } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
 import { tryImport } from "../utils/tryImport.js";
-import { getFfmpegPath, runFfmpeg } from "./video/ffmpegAdapter.js";
+import { getFfmpegPath, JPEG_QUALITY, runFfmpeg, } from "./video/ffmpegAdapter.js";
+/**
+ * Default transcode target, and the one every existing caller keeps getting:
+ * see the module header for why PNG rather than JPEG is the right default.
+ */
+const DEFAULT_VISION_IMAGE_OUTPUT_FORMAT = "png";
 /**
  * Per-backend ceiling for one image conversion.
  *
@@ -106,7 +111,7 @@ export function needsVisionTranscode(mimeType) {
  * only — actual HEVC-coded HEIC fails inside libheif, and BMP, ICO and
  * JPEG 2000 are not compiled in at all. Those fall through to ffmpeg below.
  */
-async function transcodeWithSharp(buffer) {
+async function transcodeWithSharp(buffer, outputFormat) {
     const sharpModule = await tryImport("sharp", "Image format conversion for vision providers");
     // A shape guard, not a crash guard: an absent or malformed sharp already
     // fails safely, because `tryImport` throws a named install error and any
@@ -115,9 +120,9 @@ async function transcodeWithSharp(buffer) {
     // failure list instead of "sharpModule.default is not a function".
     //
     // It deliberately throws rather than returning `buffer`: returning the input
-    // would report a successful conversion and relabel the original bytes as PNG,
-    // and would also skip the ffmpeg backend — the one that actually handles
-    // HEIC, BMP, ICO and JPEG 2000.
+    // would report a successful conversion and relabel the original bytes under
+    // the requested format, and would also skip the ffmpeg backend — the one
+    // that actually handles HEIC, BMP, ICO and JPEG 2000.
     if (typeof sharpModule?.default !== "function") {
         throw new Error("the installed sharp package does not expose a callable default export");
     }
@@ -125,9 +130,15 @@ async function transcodeWithSharp(buffer) {
     // a multi-page TIFF) from being flattened into one tall strip — the first
     // frame is what a vision model should receive.
     const pipeline = sharpModule.default(buffer, { pages: 1 });
-    // The instance shape is checked as well as the factory: a build that exports
-    // a callable but returns something without `.png()` would otherwise fail as
-    // an opaque TypeError inside the backend loop.
+    if (outputFormat === "jpeg") {
+        // The instance shape is checked as well as the factory: a build that
+        // exports a callable but returns something without `.jpeg()` would
+        // otherwise fail as an opaque TypeError inside the backend loop.
+        if (typeof pipeline?.jpeg !== "function") {
+            throw new Error("the installed sharp package returned a pipeline without a jpeg() encoder");
+        }
+        return pipeline.jpeg().toBuffer();
+    }
     if (typeof pipeline?.png !== "function") {
         throw new Error("the installed sharp package returned a pipeline without a png() encoder");
     }
@@ -151,7 +162,7 @@ async function transcodeWithSharp(buffer) {
  * `mkdtemp`. This whole path is server-only — nothing in a browser is going to
  * spawn ffmpeg — so the import belongs where it is used.
  */
-async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
+async function transcodeWithFfmpeg(buffer, extension, outputFormat, binaryPath) {
     const [{ randomUUID }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join },] = await Promise.all([
         import("node:crypto"),
         import("node:fs/promises"),
@@ -160,7 +171,13 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
     ]);
     const workDir = await mkdtemp(join(tmpdir(), "neurolink-img-"));
     const inputPath = join(workDir, `${randomUUID()}${extension}`);
-    const outputPath = join(workDir, `${randomUUID()}.png`);
+    // "mjpeg" is ffmpeg's codec name for a JPEG image2 stream; "png" doubles as
+    // both the codec name and the output extension.
+    const outputExtension = outputFormat === "jpeg" ? ".jpg" : ".png";
+    const codecArgs = outputFormat === "jpeg"
+        ? ["-c:v", "mjpeg", "-q:v", JPEG_QUALITY]
+        : ["-c:v", "png"];
+    const outputPath = join(workDir, `${randomUUID()}${outputExtension}`);
     try {
         await writeFile(inputPath, buffer);
         await runFfmpeg([
@@ -169,14 +186,13 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
             "error",
             "-i",
             inputPath,
-            // Take a single frame so a multi-image container yields one PNG rather
-            // than ffmpeg erroring on a missing output-sequence pattern.
+            // Take a single frame so a multi-image container yields one output
+            // image rather than ffmpeg erroring on a missing sequence pattern.
             "-frames:v",
             "1",
             "-f",
             "image2",
-            "-c:v",
-            "png",
+            ...codecArgs,
             outputPath,
         ], binaryPath ? { binaryPath } : {});
         return await readFile(outputPath);
@@ -194,17 +210,20 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
  * so when the resolved binary is not already the system one it is retried
  * explicitly rather than reporting a photo as unsupported.
  */
-async function* transcodeBackends(buffer, extension) {
-    yield { name: "sharp", run: () => transcodeWithSharp(buffer) };
+async function* transcodeBackends(buffer, extension, outputFormat) {
+    yield {
+        name: "sharp",
+        run: () => transcodeWithSharp(buffer, outputFormat),
+    };
     const resolved = await getFfmpegPath().catch(() => "ffmpeg");
     yield {
         name: "ffmpeg",
-        run: () => transcodeWithFfmpeg(buffer, extension),
+        run: () => transcodeWithFfmpeg(buffer, extension, outputFormat),
     };
     if (resolved !== "ffmpeg") {
         yield {
             name: "system ffmpeg",
-            run: () => transcodeWithFfmpeg(buffer, extension, "ffmpeg"),
+            run: () => transcodeWithFfmpeg(buffer, extension, outputFormat, "ffmpeg"),
         };
     }
 }
@@ -220,15 +239,19 @@ async function* transcodeBackends(buffer, extension) {
  *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
+ * @param outputFormat - Transcode target. Defaults to `"png"` — see the
+ *   module header for why that stays the default for every caller who
+ *   doesn't opt into `"jpeg"` explicitly.
  */
-export async function toVisionCompatibleImage(buffer, mimeType) {
+export async function toVisionCompatibleImage(buffer, mimeType, outputFormat = DEFAULT_VISION_IMAGE_OUTPUT_FORMAT) {
     if (!needsVisionTranscode(mimeType)) {
         return { buffer, mimeType, converted: false };
     }
     const normalized = mimeType.split(";")[0].trim().toLowerCase();
     const extension = extensionForMimeType(normalized) ?? ".bin";
+    const targetMimeType = outputFormat === "jpeg" ? "image/jpeg" : "image/png";
     const failures = [];
-    for await (const backend of transcodeBackends(buffer, extension)) {
+    for await (const backend of transcodeBackends(buffer, extension, outputFormat)) {
         try {
             // Both backends can stall — sharp on a malformed stream, ffmpeg on a
             // container it half-understands — and this runs inline on the request
@@ -238,16 +261,16 @@ export async function toVisionCompatibleImage(buffer, mimeType) {
             if (converted.length === 0) {
                 throw new Error("produced an empty image");
             }
-            logger.debug(`[imageFormatSupport] Transcoded ${normalized} → image/png via ${backend.name} ` +
+            logger.debug(`[imageFormatSupport] Transcoded ${normalized} → ${targetMimeType} via ${backend.name} ` +
                 `(${buffer.length} → ${converted.length} bytes) for vision compatibility`);
-            return { buffer: converted, mimeType: "image/png", converted: true };
+            return { buffer: converted, mimeType: targetMimeType, converted: true };
         }
         catch (error) {
             failures.push(`${backend.name}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
         }
     }
-    logger.warn(`[imageFormatSupport] Could not transcode ${normalized} to PNG — sending the ` +
-        `original bytes, which most vision providers will reject. Install a full ` +
+    logger.warn(`[imageFormatSupport] Could not transcode ${normalized} to ${targetMimeType} — sending ` +
+        `the original bytes, which most vision providers will reject. Install a full ` +
         `ffmpeg build (or set FFMPEG_PATH to one) to enable this format. ` +
         `Tried ${failures.join("; ")}`);
     return { buffer, mimeType, converted: false };