@juspay/neurolink 13.2.0 → 13.4.0

package/docs-site/static/search-index.json

@@ -216,9 +216,10 @@
 {"objectID":"c63ea3a4c4aa6319f131d1f8178b30d7f3052ab09b5e6960e439ad76f9b8fa9b","title":"Role-Based Differentiation","url":"/docs/advanced/auth-architecture#role-based-differentiation","content":"roleLimits assigns per-role limits (highest limit wins for multi-role users)\nuserLimits assigns per-user overrides\nskipRoles bypasses rate limiting entirely for specified roles (e.g., super-admin)","hierarchy":{"lvl0":"Advanced","lvl1":"Authentication Architecture","lvl2":"Role-Based Differentiation","lvl3":""}},
 {"objectID":"1824c13c380df1f7461f4a8f7ce99478b257057b57adc5b2595a680ab923d094","title":"Adding a New Auth Provider","url":"/docs/advanced/auth-architecture#adding-a-new-auth-provider","content":"Create a provider class in src/lib/auth/providers/myProvider.ts that extends BaseAuthProvider\nImplement the abstract methods: authenticateToken(), createSession(), getSession(), refreshSession(), destroySession(), getUserSessions(), destroyAllUserSessions()\nRegister the provider in AuthProviderFactory.registerAll() with a dynamic import\nRegister metadata in AuthProviderRegistry.registerAll()\nAdd the type name to AuthProviderType union in src/lib/types/authTypes.ts\nAdd a typed config to src/lib/types/authTypes.ts and a discriminated union branch to NeuroLinkAuthConfig in src/lib/types/configTypes.ts\nAdd environment variable mappings to buildProviderConfig() in src/cli/commands/authProviders.ts\nExport the provider from src/lib/auth/index.ts\nAdd tests","hierarchy":{"lvl0":"Advanced","lvl1":"Authentication Architecture","lvl2":"Adding a New Auth Provider","lvl3":""}},
 {"objectID":"a63ad442a5c17bcb83737eb96e06af21ce0d91127807b57bf333100ea11535c9","title":"See Also","url":"/docs/advanced/auth-architecture#see-also","content":"Authentication Providers Guide -- user-facing guide with configuration examples\nFactory Pattern Architecture -- how NeuroLink uses factory + registry across the codebase\nMiddleware Architecture -- the broader middleware system","hierarchy":{"lvl0":"Advanced","lvl1":"Authentication Architecture","lvl2":"See Also","lvl3":""}},
-{"objectID":"4e93f12348468bad2ffb2c45eee31449794a11626f9ac799d5b5af33e79f742d","title":"Built-in Middleware Reference","url":"/docs/advanced/builtin-middleware","content":"Built-in Middleware Reference\n\nNeuroLink includes three built-in middleware components for common use cases: Analytics, Guardrails, and Auto-Evaluation. They ship ready to wire into your generate/stream calls.\n\nQuick Start\n\nEnable all built-in middleware with a single preset:\n\nOr enable specific middleware:\n\nAnalytics Middleware\n\nPurpose\n\nThe Analytics Middleware collects comprehensive usage metrics, timing data, and operational analytics for all AI operations. It's essential for monitoring production applications, tracking costs, and understanding usage patterns.\n\nKey Capabilities:\nToken usage tracking (input, output, total)\nResponse time measurement\nRequest success/failure tracking\nProvider and model information\nAutomatic metrics storage in response metadata\n\nConfiguration\n\nBasic Configuration:\n\nAdvanced Configuration:\n\nConditional Analytics (Production Only):\n\nCollected Metrics\n\n| Metric         | Type   | Description                        | Unit         |\n| -------------- | ------ | ---------------------------------- | ------------ |\n| requestId    | string | Unique identifier for this request | -            |\n| timestamp    | string | ISO 8601 timestamp                 | -            |\n| responseTime | number | Total request duration             | milliseconds |\n| usage.input  | number | Input tokens consumed              | tokens       |\n| usage.output | number | Output tokens generated            | tokens       |\n| usage.total  | number | Total tokens used                  | tokens       |\n\nOutput Format\n\nAnalytics data is automatically added to the response metadata:\n\nGenerate Response:\n\nAnalytics Object Structure:\n\nStream Response:\n\nFor streaming responses, analytics are available in the rawResponse:\n\nStream Analytics Structure:\n\nUse Cases\nCost Tracking:\nPerformance Monitoring:\nUsage Analytics Dashboard:\n\nIntegration with External Systems\n\nSend to Datadog:\n\nSend to Prometheus:\n\nGuardrails Middleware\n\nPurpose\n\nThe Guardrails Middleware provides comprehensive content filtering and policy enforcement to block or redact unsafe content, prevent prompt injection attacks, and maintain compliance with content policies.\n\nKey Capabilities:\nBad word filtering (configurable word list)\nAI model-based content safety evaluation\nPrecall evaluation (block unsafe prompts before they reach the LLM)\nStream and generate support\nConfigurable filtering actions (block, redact, log)\n\nConfiguration\n\nBasic Configuration:\n\nAdvanced Configuration with Model-Based Filtering:\n\nPrecall Evaluation (Block Unsafe Prompts):\n\nBuilt-in Filters\n\n| Filter Type            | Description                            | Action            | Configuration                     |\n| ---------------------- | -------------------------------------- | ----------------- | --------------------------------- |\n| Bad Words          | Block/redact specific words or phrases | Redact with *** | badWords: string[]              |\n| Model-Based        | Use AI to evaluate content safety      | Block if unsafe   | modelFilter.enabled: true       |\n| Precall Evaluation | Block unsafe prompts before LLM call   | Block request     | precallEvaluation.enabled: true |\n\nBad Word Filtering\n\nHow It Works:\n\nThe bad word filter scans both requests and responses for prohibited terms and replaces them with ***.\n\nExample:\n\nConfiguration:\n\nModel-Based Filtering\n\nHow It Works:\n\nUses a separate AI model to evaluate whether content is safe. The filter sends the content to the model with a safety evaluation prompt.\n\nSafety Evaluation Prompt:\n\nExample:\n\nConfiguration:\n\nPrecall Evaluation\n\nHow It Works:\n\nEvaluates the safety of the input prompt before it reaches the main LLM. If the prompt is deemed unsafe, the request is blocked entirely, saving costs and preventing unsafe content generation.\n\nEvaluation Process:\nUser submits a prompt\nGuardrails middleware intercepts in transformParams\nSafety evaluation model scores the prompt (0-1 scale)\nIf score = threshold, request proceeds to main LLM\n\nBlocked Response:\n\nConfiguration:\n\nStreaming Support\n\nGuardrails work seamlessly with streaming responses:\n\nStream Filtering:\nBad words are replaced with *** in each text delta\nModel-based filtering is not applied to streams (too slow)\nPrecall evaluation works for streams\n\nUse Cases\nContent Moderation for User-Generated Prompts:\nCompliance with Content Policies:\nProtecting Against Prompt Injection:\n\nAuto-Evaluation Middleware\n\nPurpose\n\nThe Auto-Evaluation Middleware automatically evaluates AI response quality using configurable criteria. It can trigger retries for low-quality responses and provide quality metrics for monitoring.\n\nKey Capabilities:\nAutomatic quality evaluation after each response\nConfigurable evaluation criteria (relevance, accuracy, coherence, etc.)\nBlocking and non-blocking modes\nIntegration with custom evaluation providers\nQuality score thresholds\n\nConfiguration\n\nBasic Configuration:\n\nAdvanced Configuration:\n\nEvaluation Criteria\n\nDefault evaluation criteria (can be customized):\n\n","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"","lvl3":""}},
+{"objectID":"4e93f12348468bad2ffb2c45eee31449794a11626f9ac799d5b5af33e79f742d","title":"Built-in Middleware Reference","url":"/docs/advanced/builtin-middleware","content":"Built-in Middleware Reference\n\nNeuroLink includes three built-in middleware components for common use cases: Analytics, Guardrails, and Auto-Evaluation. They ship ready to wire into your generate/stream calls.\n\nQuick Start\n\nEnable all built-in middleware with a single preset:\n\nOr enable specific middleware:\n\nDefaults for every call\n\nInstead of repeating middleware on each generate() or stream() call, set it once. From lowest to highest precedence:\n\n| Layer       | How                                                  |\n| ----------- | ---------------------------------------------------- |\n| Environment | NEUROLINK_MIDDLEWARE_PRESET=default\\|all\\|security |\n| Global      | configureGlobalMiddleware({ preset: \"all\" })       |\n| Instance    | new NeuroLink({ middleware: { preset: \"all\" } })   |\n| Per call    | generate({ middleware: { preset: \"all\" } })        |\n\nmiddlewareConfig merges per middleware id; lists and other keys set by a higher layer replace the lower layer's value. With no default set, calls are unchanged. See Guardrails: Defaults and precedence for the full rules.\n\nAnalytics Middleware\n\nPurpose\n\nThe Analytics Middleware collects comprehensive usage metrics, timing data, and operational analytics for all AI operations. It's essential for monitoring production applications, tracking costs, and understanding usage patterns.\n\nKey Capabilities:\nToken usage tracking (input, output, total)\nResponse time measurement\nRequest success/failure tracking\nProvider and model information\nAutomatic metrics storage in response metadata\n\nConfiguration\n\nBasic Configuration:\n\nAdvanced Configuration:\n\nConditional Analytics (Production Only):\n\nCollected Metrics\n\n| Metric         | Type   | Description                        | Unit         |\n| -------------- | ------ | ---------------------------------- | ------------ |\n| requestId    | string | Unique identifier for this request | -            |\n| timestamp    | string | ISO 8601 timestamp                 | -            |\n| responseTime | number | Total request duration             | milliseconds |\n| usage.input  | number | Input tokens consumed              | tokens       |\n| usage.output | number | Output tokens generated            | tokens       |\n| usage.total  | number | Total tokens used                  | tokens       |\n\nOutput Format\n\nAnalytics data is automatically added to the response metadata:\n\nGenerate Response:\n\nAnalytics Object Structure:\n\nStream Response:\n\nFor streaming responses, analytics are available in the rawResponse:\n\nStream Analytics Structure:\n\nUse Cases\nCost Tracking:\nPerformance Monitoring:\nUsage Analytics Dashboard:\n\nIntegration with External Systems\n\nSend to Datadog:\n\nSend to Prometheus:\n\nGuardrails Middleware\n\nPurpose\n\nThe Guardrails Middleware provides comprehensive content filtering and policy enforcement to block or redact unsafe content, prevent prompt injection attacks, and maintain compliance with content policies.\n\nKey Capabilities:\nBad word filtering (configurable word list)\nAI model-based content safety evaluation\nPrecall evaluation (block unsafe prompts before they reach the LLM)\nStream and generate support\nConfigurable filtering actions (block, redact, log)\n\nConfiguration\n\nBasic Configuration:\n\nAdvanced Configuration with Model-Based Filtering:\n\nPrecall Evaluation (Block Unsafe Prompts):\n\nBuilt-in Filters\n\n| Filter Type            | Description                            | Action            | Configuration                     |\n| ---------------------- | -------------------------------------- | ----------------- | --------------------------------- |\n| Bad Words          | Block/redact specific words or phrases | Redact with *** | badWords: string[]              |\n| Model-Based        | Use AI to evaluate content safety      | Block if unsafe   | modelFilter.enabled: true       |\n| Precall Evaluation | Block unsafe prompts before LLM call   | Block request     | precallEvaluation.enabled: true |\n\nBad Word Filtering\n\nHow It Works:\n\nThe bad word filter scans both requests and responses for prohibited terms and replaces them with ***.\n\nExample:\n\nConfiguration:\n\nModel-Based Filtering\n\nHow It Works:\n\nUses a separate AI model to evaluate whether content is safe. The filter sends the content to the model with a safety evaluation prompt.\n\nSafety Evaluation Prompt:\n\nExample:\n\nConfiguration:\n\nPrecall Evaluation\n\nHow It Works:\n\nEvaluates the safety of the input prompt before it reaches the main LLM. If the prompt is deemed unsafe, the request is blocked entirely, saving costs and preventing unsafe content generation.\n\nEvaluation Process:\nUser submits a prompt\nGuardrails middleware intercepts in transformParams\nSafety evaluation model scores the prompt (0-1 scale)\nIf score = threshold, request proceeds to main LLM\n\nBlocked Response:\n\nConfiguration:\n\nStreaming Support\n\nGuardrails work seamlessly with streaming responses:\n\nStream Filtering:\nBad words are replaced with *** in each text delta\nModel-based filtering is not applied to streams (too","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"","lvl3":""}},
 {"objectID":"ac9e7975939e43e8c0e52e2845fcd447f81788b86aafb183213385a1f69ee283","title":"Built-in Middleware Reference","url":"/docs/advanced/builtin-middleware#built-in-middleware-reference","content":"NeuroLink includes three built-in middleware components for common use cases: Analytics, Guardrails, and Auto-Evaluation. They ship ready to wire into your generate/stream calls.","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Built-in Middleware Reference","lvl3":""}},
 {"objectID":"63a19a2a4b7e313ef69e05e0d386ce69144f3ddae6c5022b20dc7dd0c9be5cd5","title":"Quick Start","url":"/docs/advanced/builtin-middleware#quick-start","content":"Enable all built-in middleware with a single preset:\n\nOr enable specific middleware:","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Quick Start","lvl3":""}},
+{"objectID":"a4cefe7950398abdba5bb64b133a18b0386c18ac4a6760db04a0fca5b6f99f27","title":"Defaults for every call","url":"/docs/advanced/builtin-middleware#defaults-for-every-call","content":"Instead of repeating middleware on each generate() or stream() call, set it once. From lowest to highest precedence:\n\n| Layer       | How                                                  |\n| ----------- | ---------------------------------------------------- |\n| Environment | NEUROLINK_MIDDLEWARE_PRESET=default\\|all\\|security |\n| Global      | configureGlobalMiddleware({ preset: \"all\" })       |\n| Instance    | new NeuroLink({ middleware: { preset: \"all\" } })   |\n| Per call    | generate({ middleware: { preset: \"all\" } })        |\n\nmiddlewareConfig merges per middleware id; lists and other keys set by a higher layer replace the lower layer's value. With no default set, calls are unchanged. See Guardrails: Defaults and precedence for the full rules.","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Defaults for every call","lvl3":""}},
 {"objectID":"ba5e28fcd0f3518c621fa4ff5d661252622d1d582be75671f9246ba89b846b94","title":"Purpose","url":"/docs/advanced/builtin-middleware#purpose","content":"The Analytics Middleware collects comprehensive usage metrics, timing data, and operational analytics for all AI operations. It's essential for monitoring production applications, tracking costs, and understanding usage patterns.\n\nKey Capabilities:\nToken usage tracking (input, output, total)\nResponse time measurement\nRequest success/failure tracking\nProvider and model information\nAutomatic metrics storage in response metadata","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Purpose","lvl3":""}},
 {"objectID":"f097d3aae3b2f08f80b1488048983d76d09a53d821e1249af7c8c2ef18425d68","title":"Configuration","url":"/docs/advanced/builtin-middleware#configuration","content":"Basic Configuration:\n\nAdvanced Configuration:\n\nConditional Analytics (Production Only):","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Configuration","lvl3":""}},
 {"objectID":"0ed403ca8e213ef3e9c955b807bced0bca556ca4e388f7006bd855c14a3181a5","title":"Collected Metrics","url":"/docs/advanced/builtin-middleware#collected-metrics","content":"| Metric         | Type   | Description                        | Unit         |\n| -------------- | ------ | ---------------------------------- | ------------ |\n| requestId    | string | Unique identifier for this request | -            |\n| timestamp    | string | ISO 8601 timestamp                 | -            |\n| responseTime | number | Total request duration             | milliseconds |\n| usage.input  | number | Input tokens consumed              | tokens       |\n| usage.output | number | Output tokens generated            | tokens       |\n| usage.total  | number | Total tokens used                  | tokens       |","hierarchy":{"lvl0":"Advanced","lvl1":"Built-in Middleware Reference","lvl2":"Collected Metrics","lvl3":""}},
@@ -325,7 +326,7 @@
 {"objectID":"83274029c906dfe570738346d3b0ee6d77dd8f4d2eb9dba30a0b6a8c25e1fb03","title":"Error Handling","url":"/docs/advanced/memory-integration#error-handling","content":"Memory is designed to never crash the host application:\nEvery public method is wrapped in try-catch\nget() returns null on error — the call continues without memory context\nadd() silently fails on error — the generate/stream result is not affected\nStorage initialization errors disable memory for that instance","hierarchy":{"lvl0":"Advanced","lvl1":"Memory Integration with Hippocampus","lvl2":"Error Handling","lvl3":""}},
 {"objectID":"3652380f1c43e08d5d18dfa0862f10a3a51f30f48679a7635ce026df2e7bc51a","title":"Production Checklist","url":"/docs/advanced/memory-integration#production-checklist","content":"[ ] Use S3 or Redis storage (not SQLite) in production\n[ ] Set HC_LOG_LEVEL=warn or higher in production\n[ ] Ensure userId is stable and unique per user across sessions\n[ ] For multi-tenant: use tenant-scoped prefixes or collection names\n[ ] Monitor Memory retrieval failed and Memory storage failed warnings in logs\n[ ] Verify the condensation LLM provider is configured and has sufficient quota","hierarchy":{"lvl0":"Advanced","lvl1":"Memory Integration with Hippocampus","lvl2":"Production Checklist","lvl3":""}},
 {"objectID":"417bcc8fbbc98c4053d46139d169f1e6f165888a5dceb6e2327b15c8bb8473e4","title":"See Also","url":"/docs/advanced/memory-integration#see-also","content":"Memory Guide - Quick start and configuration reference\nConversation Memory - Session-based conversation history\nContext Compaction - Automatic context window management","hierarchy":{"lvl0":"Advanced","lvl1":"Memory Integration with Hippocampus","lvl2":"See Also","lvl3":""}},
-{"objectID":"16f1c17ef8c078b33ae6aa26f8107300cca478f6d88a74dab2450a7762f3a54b","title":"Middleware System Architecture","url":"/docs/advanced/middleware-architecture","content":"Middleware System Architecture\n\nOverview\n\nNeuroLink's middleware system provides a powerful and flexible way to intercept, modify, and enhance AI requests and responses. Middleware enables you to implement cross-cutting concerns like authentication, logging, analytics, content filtering, and auto-evaluation without modifying your core application logic.\n\nWhy Middleware Matters:\nRequest Interception: Modify requests before they reach the AI provider\nResponse Processing: Transform, filter, or validate AI responses\nCross-Cutting Concerns: Implement authentication, logging, rate limiting, and caching in a centralized way\nComposability: Chain multiple middleware components together\nSeparation of Concerns: Keep business logic separate from infrastructure concerns\n\nKey Benefits:\nProduction-ready middleware for common use cases (analytics, guardrails, auto-evaluation)\nFactory pattern for easy middleware management\nPriority-based execution ordering\nProvider-specific conditional execution\nBuilt on NeuroLink's own wrapLanguageModel (src/lib/middleware/wrapLanguageModel.ts), which keeps the familiar wrap-a-model shape without depending on a third-party SDK\n\nArchitecture Diagram\n\nRequest Lifecycle\n\nThe middleware system processes requests through four distinct phases:\n\nPhase 1: Pre-Request (transformParams)\n\nMiddleware in this phase runs before the AI provider call, allowing you to:\nValidate input: Check request parameters for validity\nAuthenticate/Authorize: Verify user permissions\nTransform requests: Modify or enrich request parameters\nApply guardrails: Block requests with unsafe content using precall evaluation\nRate limiting: Enforce request quotas\n\nExample Use Cases:\nPrecall guardrails evaluation (blocking unsafe prompts)\nRequest parameter validation\nAdding authentication context\nModifying prompts based on user preferences\n\nPhase 2: Provider Execution\n\nThe actual AI provider call happens between middleware phases:\nRequest sent to configured provider (OpenAI, Anthropic, Vertex, etc.)\nProvider processes the request\nResponse received from provider\n\nThis phase is not middleware - it's the core AI operation that middleware wraps around.\n\nPhase 3: Post-Response (wrapGenerate/wrapStream)\n\nMiddleware in this phase runs after the AI provider responds, allowing you to:\nCollect analytics: Track token usage, response times, costs\nFilter content: Apply guardrails to block/redact unsafe responses\nEvaluate quality: Auto-evaluate response quality and trigger retries\nTransform responses: Modify or enrich the response\nCache results: Store responses for future use\n\nExample Use Cases:\nAnalytics and metrics collection\nContent filtering and safety checks\nResponse quality evaluation\nResponse caching\nLogging and auditing\n\nPhase 4: Error Handling\n\nIf an error occurs at any stage, error handling middleware can:\nLog errors: Record error details for debugging\nTransform errors: Convert provider errors to user-friendly messages\nImplement fallbacks: Retry with different providers\nAlert monitoring: Send alerts to monitoring systems\n\nExample Use Cases:\nError logging and tracking\nProvider fallback on failure\nRetry logic with exponential backoff\nUser-friendly error messages\n\nMiddleware Chain\n\nExecution Order\n\nMiddleware executes in priority order, where higher priority values run first:\n\nImportant Notes:\ntransformParams runs before wrapGenerate/wrapStream\nWithin the same priority, registration order determines execution\nMiddleware can be conditionally enabled based on provider, model, or custom logic\n\nChain Configuration\n\nConfigure which middleware to enable and their order:\n\nAvailable Presets\n\n| Preset     | Middleware Enabled     | Use Case               |\n| ---------- | ---------------------- | ---------------------- |\n| default  | Analytics only         | Basic usage tracking   |\n| all      | Analytics + Guardrails | Production with safety |\n| security | Guardrails only        | Security-focused       |\n| Custom     | Your choice            | Define your own        |\n\nFactory Pattern\n\nMiddlewareFactory Class\n\nThe MiddlewareFactory is the central component for managing middleware:\n\nCreating Middleware Instances\n\nBasic Usage:\n\nAdvanced Configuration:\n\nRegistry System\n\nRegistering Middleware\n\nThe MiddlewareRegistry manages all registered middleware:\n\nRegistration Example:\n\nDiscovering Middleware\n\nList all registered middleware:\n\nGet specific middleware:\n\nCheck if middleware is registered:\n\nMiddleware Metadata\n\nEvery middleware must provide metadata:\n\nExample:\n\nTypeScript Interfaces\n\nNeuroLinkMiddleware\n\nThe core middleware interface, which combines the model-middleware contract with NeuroLink metadata:\n\nLanguageModelMiddleware\n\nNeuroLink declares this contract itself — it no longer comes from the Vercel AI\nSDK, which is not a dependency. The shape follows the v3 model protocol:\n\nMiddlewareContext\n\nContext information passed to middleware:\n\nMiddlewareConfig\n\nConfiguration for individual middleware:\n\nMiddlewareFactoryOptions\n\nOptions for creating and ","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"","lvl3":""}},
+{"objectID":"16f1c17ef8c078b33ae6aa26f8107300cca478f6d88a74dab2450a7762f3a54b","title":"Middleware System Architecture","url":"/docs/advanced/middleware-architecture","content":"Middleware System Architecture\n\nOverview\n\nNeuroLink's middleware system provides a powerful and flexible way to intercept, modify, and enhance AI requests and responses. Middleware enables you to implement cross-cutting concerns like authentication, logging, analytics, content filtering, and auto-evaluation without modifying your core application logic.\n\nWhy Middleware Matters:\nRequest Interception: Modify requests before they reach the AI provider\nResponse Processing: Transform, filter, or validate AI responses\nCross-Cutting Concerns: Implement authentication, logging, rate limiting, and caching in a centralized way\nComposability: Chain multiple middleware components together\nSeparation of Concerns: Keep business logic separate from infrastructure concerns\n\nKey Benefits:\nProduction-ready middleware for common use cases (analytics, guardrails, auto-evaluation)\nFactory pattern for easy middleware management\nPriority-based execution ordering\nProvider-specific conditional execution\nBuilt on NeuroLink's own wrapLanguageModel (src/lib/middleware/wrapLanguageModel.ts), which keeps the familiar wrap-a-model shape without depending on a third-party SDK\n\nArchitecture Diagram\n\nRequest Lifecycle\n\nThe middleware system processes requests through four distinct phases:\n\nPhase 1: Pre-Request (transformParams)\n\nMiddleware in this phase runs before the AI provider call, allowing you to:\nValidate input: Check request parameters for validity\nAuthenticate/Authorize: Verify user permissions\nTransform requests: Modify or enrich request parameters\nApply guardrails: Block requests with unsafe content using precall evaluation\nRate limiting: Enforce request quotas\n\nExample Use Cases:\nPrecall guardrails evaluation (blocking unsafe prompts)\nRequest parameter validation\nAdding authentication context\nModifying prompts based on user preferences\n\nPhase 2: Provider Execution\n\nThe actual AI provider call happens between middleware phases:\nRequest sent to configured provider (OpenAI, Anthropic, Vertex, etc.)\nProvider processes the request\nResponse received from provider\n\nThis phase is not middleware - it's the core AI operation that middleware wraps around.\n\nPhase 3: Post-Response (wrapGenerate/wrapStream)\n\nMiddleware in this phase runs after the AI provider responds, allowing you to:\nCollect analytics: Track token usage, response times, costs\nFilter content: Apply guardrails to block/redact unsafe responses\nEvaluate quality: Auto-evaluate response quality and trigger retries\nTransform responses: Modify or enrich the response\nCache results: Store responses for future use\n\nExample Use Cases:\nAnalytics and metrics collection\nContent filtering and safety checks\nResponse quality evaluation\nResponse caching\nLogging and auditing\n\nPhase 4: Error Handling\n\nIf an error occurs at any stage, error handling middleware can:\nLog errors: Record error details for debugging\nTransform errors: Convert provider errors to user-friendly messages\nImplement fallbacks: Retry with different providers\nAlert monitoring: Send alerts to monitoring systems\n\nExample Use Cases:\nError logging and tracking\nProvider fallback on failure\nRetry logic with exponential backoff\nUser-friendly error messages\n\nMiddleware Chain\n\nExecution Order\n\nMiddleware executes in priority order, where higher priority values run first:\n\nImportant Notes:\ntransformParams runs before wrapGenerate/wrapStream\nWithin the same priority, registration order determines execution\nMiddleware can be conditionally enabled based on provider, model, or custom logic\n\nChain Configuration\n\nConfigure which middleware to enable and their order:\n\nAvailable Presets\n\n| Preset     | Middleware Enabled     | Use Case               |\n| ---------- | ---------------------- | ---------------------- |\n| default  | Analytics only         | Basic usage tracking   |\n| all      | Analytics + Guardrails | Production with safety |\n| security | Guardrails only        | Security-focused       |\n| Custom     | Your choice            | Define your own        |\n\nsecurity switches guardrails on and nothing more: it ships no word list and no model filter, so it redacts nothing until badWords, modelFilter or precallEvaluation is configured. A preset, and any other MiddlewareFactoryOptions, can also be set as a default for every call: NEUROLINK_MIDDLEWARE_PRESET (a preset name only), configureGlobalMiddleware() and new NeuroLink({ middleware }), each overridden by the next and finally by the call's own middleware. See Guardrails: Defaults and precedence.\n\nFactory Pattern\n\nMiddlewareFactory Class\n\nThe MiddlewareFactory is the central component for managing middleware:\n\nCreating Middleware Instances\n\nBasic Usage:\n\nAdvanced Configuration:\n\nRegistry System\n\nRegistering Middleware\n\nThe MiddlewareRegistry manages all registered middleware:\n\nRegistration Example:\n\nDiscovering Middleware\n\nList all registered middleware:\n\nGet specific middleware:\n\nCheck if middleware is registered:\n\nMiddleware Metadata\n\nEvery middleware must provide metadata:\n\nExample:\n","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"","lvl3":""}},
 {"objectID":"f59113cc43afb8aa74ec51f97fb491b40e5ac27d3bbdaecf1a226437ab0d13a4","title":"Overview","url":"/docs/advanced/middleware-architecture#overview","content":"NeuroLink's middleware system provides a powerful and flexible way to intercept, modify, and enhance AI requests and responses. Middleware enables you to implement cross-cutting concerns like authentication, logging, analytics, content filtering, and auto-evaluation without modifying your core application logic.\n\nWhy Middleware Matters:\nRequest Interception: Modify requests before they reach the AI provider\nResponse Processing: Transform, filter, or validate AI responses\nCross-Cutting Concerns: Implement authentication, logging, rate limiting, and caching in a centralized way\nComposability: Chain multiple middleware components together\nSeparation of Concerns: Keep business logic separate from infrastructure concerns\n\nKey Benefits:\nProduction-ready middleware for common use cases (analytics, guardrails, auto-evaluation)\nFactory pattern for easy middleware management\nPriority-based execution ordering\nProvider-specific conditional execution\nBuilt on NeuroLink's own wrapLanguageModel (src/lib/middleware/wrapLanguageModel.ts), which keeps the familiar wrap-a-model shape without depending on a third-party SDK","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Overview","lvl3":""}},
 {"objectID":"60b4f50d9fe9e6299393c3a0d190cf5968e65731a535c66e5b17280f20b6bb4f","title":"Request Lifecycle","url":"/docs/advanced/middleware-architecture#request-lifecycle","content":"The middleware system processes requests through four distinct phases:","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Request Lifecycle","lvl3":""}},
 {"objectID":"d6648ed23071b3b4eaeeb161e0191b57f0aa1d3b718a1ea33c4472f4a822f91a","title":"Phase 1: Pre-Request (transformParams)","url":"/docs/advanced/middleware-architecture#phase-1-pre-request-transformparams","content":"Middleware in this phase runs before the AI provider call, allowing you to:\nValidate input: Check request parameters for validity\nAuthenticate/Authorize: Verify user permissions\nTransform requests: Modify or enrich request parameters\nApply guardrails: Block requests with unsafe content using precall evaluation\nRate limiting: Enforce request quotas\n\nExample Use Cases:\nPrecall guardrails evaluation (blocking unsafe prompts)\nRequest parameter validation\nAdding authentication context\nModifying prompts based on user preferences","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Phase 1: Pre-Request (transformParams)","lvl3":""}},
@@ -334,7 +335,7 @@
 {"objectID":"20bf1eb219ac6b555aede3c4b1d49ae31ca8ce6f88ab65833ea58f0d563c68e0","title":"Phase 4: Error Handling","url":"/docs/advanced/middleware-architecture#phase-4-error-handling","content":"If an error occurs at any stage, error handling middleware can:\nLog errors: Record error details for debugging\nTransform errors: Convert provider errors to user-friendly messages\nImplement fallbacks: Retry with different providers\nAlert monitoring: Send alerts to monitoring systems\n\nExample Use Cases:\nError logging and tracking\nProvider fallback on failure\nRetry logic with exponential backoff\nUser-friendly error messages","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Phase 4: Error Handling","lvl3":""}},
 {"objectID":"c1aab1346883c17f6e9da3cf125b3b05a5260dc96ec275774ec50e5e4e0f8671","title":"Execution Order","url":"/docs/advanced/middleware-architecture#execution-order","content":"Middleware executes in priority order, where higher priority values run first:\n\nImportant Notes:\ntransformParams runs before wrapGenerate/wrapStream\nWithin the same priority, registration order determines execution\nMiddleware can be conditionally enabled based on provider, model, or custom logic","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Execution Order","lvl3":""}},
 {"objectID":"a8f35bb4df1cb02433a72127e19d70d13e65c37f39e82efcf3bcf6e8f87e527e","title":"Chain Configuration","url":"/docs/advanced/middleware-architecture#chain-configuration","content":"Configure which middleware to enable and their order:","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Chain Configuration","lvl3":""}},
-{"objectID":"4e2d305d305f23f07317c55ef429af7e4f49de1c6b555bf06943a1b82125ecfb","title":"Available Presets","url":"/docs/advanced/middleware-architecture#available-presets","content":"| Preset     | Middleware Enabled     | Use Case               |\n| ---------- | ---------------------- | ---------------------- |\n| default  | Analytics only         | Basic usage tracking   |\n| all      | Analytics + Guardrails | Production with safety |\n| security | Guardrails only        | Security-focused       |\n| Custom     | Your choice            | Define your own        |","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Available Presets","lvl3":""}},
+{"objectID":"4e2d305d305f23f07317c55ef429af7e4f49de1c6b555bf06943a1b82125ecfb","title":"Available Presets","url":"/docs/advanced/middleware-architecture#available-presets","content":"| Preset     | Middleware Enabled     | Use Case               |\n| ---------- | ---------------------- | ---------------------- |\n| default  | Analytics only         | Basic usage tracking   |\n| all      | Analytics + Guardrails | Production with safety |\n| security | Guardrails only        | Security-focused       |\n| Custom     | Your choice            | Define your own        |\n\nsecurity switches guardrails on and nothing more: it ships no word list and no model filter, so it redacts nothing until badWords, modelFilter or precallEvaluation is configured. A preset, and any other MiddlewareFactoryOptions, can also be set as a default for every call: NEUROLINK_MIDDLEWARE_PRESET (a preset name only), configureGlobalMiddleware() and new NeuroLink({ middleware }), each overridden by the next and finally by the call's own middleware. See Guardrails: Defaults and precedence.","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Available Presets","lvl3":""}},
 {"objectID":"2ca1866088d786b0302554707dd19943bda8284588e3608359014cd37df2535b","title":"MiddlewareFactory Class","url":"/docs/advanced/middleware-architecture#middlewarefactory-class","content":"The MiddlewareFactory is the central component for managing middleware:","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"MiddlewareFactory Class","lvl3":""}},
 {"objectID":"1a9035a2cc3954f641addd49e21328c92c7328d84ffeea0eba439766fac54125","title":"Creating Middleware Instances","url":"/docs/advanced/middleware-architecture#creating-middleware-instances","content":"Basic Usage:\n\nAdvanced Configuration:","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Creating Middleware Instances","lvl3":""}},
 {"objectID":"b03a3da8a1b53b12b3c7e81e18e58528c3b4b32a517187311051c1ce954947c7","title":"Registering Middleware","url":"/docs/advanced/middleware-architecture#registering-middleware","content":"The MiddlewareRegistry manages all registered middleware:\n\nRegistration Example:","hierarchy":{"lvl0":"Advanced","lvl1":"Middleware System Architecture","lvl2":"Registering Middleware","lvl3":""}},
@@ -953,7 +954,7 @@
 {"objectID":"e8f772ab075392c0b4ddf2d907da1d9691928dbdc2c4c0961a603f145aec02f3","title":"Start docs server with stdio transport (default)","url":"/docs/cli/commands#start-docs-server-with-stdio-transport-default","content":"npx @juspay/neurolink docs","hierarchy":{"lvl0":"Cli","lvl1":"CLI Command Reference","lvl2":"Start docs server with stdio transport (default)","lvl3":""}},
 {"objectID":"2688bf05daed20b355836574a11f3879c32211de4b4d79c87d1da17c01d2f361","title":"Start docs server with HTTP transport on custom port","url":"/docs/cli/commands#start-docs-server-with-http-transport-on-custom-port","content":"npx @juspay/neurolink docs --transport http --port 3001\n\n\n| Option        | Alias | Type   | Default | Description                                            |\n| ------------- | ----- | ------ | ------- | ------------------------------------------------------ |\n| --transport | -t  | string | stdio | Transport protocol: stdio (local) or http (remote) |\n| --port      | -p  | number | 3001  | Port for HTTP transport (ignored for stdio)            |\n\n**Note:** Requires the docs site to be built first (cd docs-site && pnpm build`). The server exposes documentation search and retrieval tools via MCP.","hierarchy":{"lvl0":"Cli","lvl1":"CLI Command Reference","lvl2":"Start docs server with HTTP transport on custom port","lvl3":""}},
 {"objectID":"8f49c1467f8e816d39e710ef8143f9ea82f0fb6b7207923b038f16088921ecb5","title":"Troubleshooting","url":"/docs/cli/commands#troubleshooting","content":"| Issue                              | Tip                                                                                                      |\n| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| Unknown argument                 | Check spelling; run command --help for the latest options.                                             |\n| CLI exits immediately              | Upgrade to the newest release or clear old neurolink binaries on PATH.                                 |\n| Provider shows as not-configured | Run neurolink setup --provider <name> or populate .env.                                              |\n| Analytics/evaluation missing       | Ensure both --enableAnalytics/--enableEvaluation and provider credentials for the judge model exist. |\n\nFor advanced workflows (batching, tooling, configuration management) see the relevant guides in the documentation sidebar.","hierarchy":{"lvl0":"Cli","lvl1":"CLI Command Reference","lvl2":"Troubleshooting","lvl3":""}},
-{"objectID":"8119c15fb9af553003230d175f4a2ee502a36966c92c48486de6bae793ea7d1d","title":"Related Features","url":"/docs/cli/commands#related-features","content":"Q4 2025:\nCLI Loop Sessions – Persistent interactive mode with session management\nRedis Conversation Export – Export session history via memory export\nGuardrails Middleware – Content filtering (use --middleware-preset security)\n\nQ3 2025:\nMultimodal Chat – Use --image flag with generate or stream\nAuto Evaluation – Enable with --enableEvaluation\nProvider Orchestration – Automatic fallback and routing\n\nDocumentation:\nSDK API Reference – TypeScript API equivalents\nConfiguration Guide – Environment variables and config files\nTroubleshooting – Detailed error solutions","hierarchy":{"lvl0":"Cli","lvl1":"CLI Command Reference","lvl2":"Related Features","lvl3":""}},
+{"objectID":"8119c15fb9af553003230d175f4a2ee502a36966c92c48486de6bae793ea7d1d","title":"Related Features","url":"/docs/cli/commands#related-features","content":"Q4 2025:\nCLI Loop Sessions – Persistent interactive mode with session management\nRedis Conversation Export – Export session history via memory export\nGuardrails Middleware – Content filtering (the CLI reads NEUROLINK_MIDDLEWARE_PRESET; it has no word-list option)\n\nQ3 2025:\nMultimodal Chat – Use --image flag with generate or stream\nAuto Evaluation – Enable with --enableEvaluation\nProvider Orchestration – Automatic fallback and routing\n\nDocumentation:\nSDK API Reference – TypeScript API equivalents\nConfiguration Guide – Environment variables and config files\nTroubleshooting – Detailed error solutions","hierarchy":{"lvl0":"Cli","lvl1":"CLI Command Reference","lvl2":"Related Features","lvl3":""}},
 {"objectID":"e0f8ded613d2bfce135ac507d9d6d72d0714035e5a4619ae7522926d6929fe66","title":"CLI Examples","url":"/docs/cli/examples","content":"CLI Examples\n\nPractical examples and usage patterns for the NeuroLink CLI.\n\n🚀 Quick Start Examples\n\nBasic Text Generation\n\nProvider Testing\n\n🔧 Development Workflows\n\nCode Generation\n\nDocumentation Generation\n\n📊 Business Use Cases\n\nContent Creation\n\nBusiness Analysis\n\n🔄 Batch Processing\n\nContent Pipeline\n\nCode Review Automation\n\n🎯 Advanced Features\n\nAnalytics and Evaluation\n\nCustom Context\n\n🔍 Debugging and Monitoring\n\nProvider Diagnostics\n\nPerformance Testing\n\n🔧 Integration Examples\n\nShell Scripts\n\nPackage.json Scripts\n\nGitHub Actions\n\n🌐 Production Workflows\n\nContent Management\n\nCode Review Pipeline\n\nMonitoring and Alerts\n\n📈 Performance Optimization\n\nProvider Selection\n\nBatch Optimization\n\n🚨 Error Handling\n\nRobust Scripts\n\nTimeout Handling\n\n📚 Learning and Experimentation\n\nA/B Testing\n\nTemperature Experiments\n\nToken Limit Testing\n\n🔗 Related Resources\nCLI Commands Reference - Complete command documentation\nAdvanced Usage - Power user features\nInstallation Guide - Setup instructions\nEnvironment Variables - Configuration\nTroubleshooting - Common issues","hierarchy":{"lvl0":"Cli","lvl1":"CLI Examples","lvl2":"","lvl3":""}},
 {"objectID":"03625aa61bb31e6c0ba861895a08bad39ca4b9494198f5fceb841ad8bd5cbf84","title":"CLI Examples","url":"/docs/cli/examples#cli-examples","content":"Practical examples and usage patterns for the NeuroLink CLI.","hierarchy":{"lvl0":"Cli","lvl1":"CLI Examples","lvl2":"CLI Examples","lvl3":""}},
 {"objectID":"cbaa79c5e583835d23dcaab7a2e23df19c9e3ec43b92ce0878117717f67f0c5e","title":"Basic Text Generation","url":"/docs/cli/examples#basic-text-generation","content":"`bash","hierarchy":{"lvl0":"Cli","lvl1":"CLI Examples","lvl2":"Basic Text Generation","lvl3":""}},
@@ -3471,12 +3472,12 @@
 {"objectID":"acc039ba50dd533ebee67d761c7060a470341050b0e74b617d8a2ecd2ee58d3a","title":"File Size Limits","url":"/docs/features/file-processors#file-size-limits","content":"Default size limits prevent denial-of-service attacks:\n\n| Category     | Default Limit | Configurable     |\n| ------------ | ------------- | ---------------- |\n| Documents    | 50 MB         | Yes              |\n| Data files   | 10 MB         | Yes              |\n| Code files   | 5 MB          | Yes              |\n| Config files | 1 MB          | Yes              |\n| Images       | 10 MB         | No — fixed limit |\n\nThe image limit (SIZE_LIMITS_BYTES.IMAGE_MAX, 10 MB) is enforced: an oversized image buffer, file, or download throws a descriptive error before any base64 conversion, so a large image can no longer exhaust process memory. This applies to both entry points — images passed via generate({ files }) (routed through FileDetector → ImageProcessor) and via generate({ images }) (routed through the message builder). The internal image helpers that convert buffers/files/URLs accept an optional size override, but it is not exposed through generate() or any other public API — the 10 MB limit is fixed for SDK callers.","hierarchy":{"lvl0":"Features","lvl1":"File Processors Guide","lvl2":"File Size Limits","lvl3":""}},
 {"objectID":"65a3ceb133215b2453584713522686169451f444788d78d330508879d050037d","title":"Provider Compatibility","url":"/docs/features/file-processors#provider-compatibility","content":"All file processors work across NeuroLink's text- and multimodal-capable providers. The processed content is formatted as text that any such provider can understand:\n\n| Provider          | Documents | Data | Markup | Code | Config |\n| ----------------- | --------- | ---- | ------ | ---- | ------ |\n| OpenAI            | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Anthropic         | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Google AI Studio  | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Google Vertex     | ✅        | ✅   | ✅     | ✅   | ✅     |\n| AWS Bedrock       | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Azure OpenAI      | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Mistral           | ✅        | ✅   | ✅     | ✅   | ✅     |\n| LiteLLM           | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Ollama            | ✅        | ✅   | ✅     | ✅   | ✅     |\n| Hugging Face      | ✅        | ✅   | ✅     | ✅   | ✅     |\n| SageMaker         | ✅        | ✅   | ✅     | ✅   | ✅     |\n| OpenAI Compatible | ✅        | ✅   | ✅     | ✅   | ✅     |\n| OpenRouter        | ✅        | ✅   | ✅     | ✅   | ✅     |\n\nNote: For binary files like images and PDFs, provider-specific adapters handle the formatting. See PDF Support and Multimodal Chat.","hierarchy":{"lvl0":"Features","lvl1":"File Processors Guide","lvl2":"Provider Compatibility","lvl3":""}},
 {"objectID":"be7374d46193897235391ecd13b89a01971bdeb07cbb2205f0018d0d64f9d1bc","title":"Related Documentation","url":"/docs/features/file-processors#related-documentation","content":"Multimodal Chat - Image and media handling\nPDF Support - PDF-specific features\nCSV Support - CSV processing details\nCLI Commands - CLI file options\nSDK API Reference - Full API documentation","hierarchy":{"lvl0":"Features","lvl1":"File Processors Guide","lvl2":"Related Documentation","lvl3":""}},
-{"objectID":"b8b45370e9a5ddcc4d97fb6cfd40ec293136c5e986be4e0870e843a780c93877","title":"Guardrails AI Integration with Middleware","url":"/docs/features/guardrails-ai","content":"Guardrails AI Integration with Middleware\n\nThis document outlines the modern, simplified approach to integrating Guardrails AI with the NeuroLink platform using the new MiddlewareFactory. This enhances the safety, reliability, and security of your AI applications in a modular and maintainable way.\n\nOverview\n\nGuardrails AI is an open-source library that provides a framework for creating and managing guardrails for large language models (LLMs). By integrating Guardrails AI as middleware, you can enforce specific rules and policies on the inputs and outputs of your models, ensuring they adhere to your safety guidelines and quality standards.\n\nKey Benefits\nRisk Mitigation: Protect against common AI risks such as hallucinations, toxic language, and data leakage.\nQuality Assurance: Ensure that model outputs are accurate, relevant, and meet predefined quality criteria.\nCompliance: Enforce industry-specific regulations and compliance requirements.\nCustomization: Create custom guardrails tailored to specific use cases and business needs.\n\nMiddleware-based Guardrail Implementation\n\nWith the new MiddlewareFactory, integrating guardrails is easier than ever. The factory automatically handles the registration and application of the guardrails middleware when you use a relevant preset.\n\nUsing the security Preset\n\nThe easiest way to enable guardrails is to use the security preset when creating your MiddlewareFactory. This preset is specifically designed to enable the guardrails middleware with a default configuration.\n\nUsing the all Preset\n\nIf you want to use guardrails in combination with other built-in middleware like analytics, you can use the all preset.\n\nCustomizing Guardrails\n\nWhile presets provide a great starting point, you can also customize the behavior of the guardrails middleware by providing a custom configuration.\n\nThis new, streamlined approach provides a clean and scalable way to add safety and other enhancements to your AI models within the NeuroLink ecosystem.\n\nSee Also\n\nFor configuration examples, best practices, and troubleshooting, see the Guardrails Middleware Feature Guide.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"","lvl3":""}},
+{"objectID":"b8b45370e9a5ddcc4d97fb6cfd40ec293136c5e986be4e0870e843a780c93877","title":"Guardrails AI Integration with Middleware","url":"/docs/features/guardrails-ai","content":"Guardrails AI Integration with Middleware\n\nThis document outlines the modern, simplified approach to integrating Guardrails AI with the NeuroLink platform using the new MiddlewareFactory. This enhances the safety, reliability, and security of your AI applications in a modular and maintainable way.\n\nOverview\n\nGuardrails AI is an open-source library that provides a framework for creating and managing guardrails for large language models (LLMs). By integrating Guardrails AI as middleware, you can enforce specific rules and policies on the inputs and outputs of your models, ensuring they adhere to your safety guidelines and quality standards.\n\nKey Benefits\nRisk Mitigation: Protect against common AI risks such as hallucinations, toxic language, and data leakage.\nQuality Assurance: Ensure that model outputs are accurate, relevant, and meet predefined quality criteria.\nCompliance: Enforce industry-specific regulations and compliance requirements.\nCustomization: Create custom guardrails tailored to specific use cases and business needs.\n\nMiddleware-based Guardrail Implementation\n\nWith the new MiddlewareFactory, integrating guardrails is easier than ever. The factory automatically handles the registration and application of the guardrails middleware when you use a relevant preset.\n\nUsing the security Preset\n\nThe easiest way to enable guardrails is to use the security preset when creating your MiddlewareFactory. This preset enables the guardrails middleware with an empty configuration: it filters nothing until you add badWords, modelFilter or precallEvaluation (see Customizing Guardrails). To apply a preset to every call without building a factory, use new NeuroLink({ middleware }), configureGlobalMiddleware() or NEUROLINK_MIDDLEWARE_PRESET.\n\nUsing the all Preset\n\nIf you want to use guardrails in combination with other built-in middleware like analytics, you can use the all preset.\n\nCustomizing Guardrails\n\nWhile presets provide a great starting point, you can also customize the behavior of the guardrails middleware by providing a custom configuration.\n\nThis new, streamlined approach provides a clean and scalable way to add safety and other enhancements to your AI models within the NeuroLink ecosystem.\n\nSee Also\n\nFor configuration examples, best practices, and troubleshooting, see the Guardrails Middleware Feature Guide.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"","lvl3":""}},
 {"objectID":"2887e2921f080ab2b5f9cce892d0e5b231097704dada610addc7dba968ac2b2b","title":"Guardrails AI Integration with Middleware","url":"/docs/features/guardrails-ai#guardrails-ai-integration-with-middleware","content":"This document outlines the modern, simplified approach to integrating Guardrails AI with the NeuroLink platform using the new MiddlewareFactory. This enhances the safety, reliability, and security of your AI applications in a modular and maintainable way.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Guardrails AI Integration with Middleware","lvl3":""}},
 {"objectID":"656e3b1f93c26cedaeb4820d59bb33c0baf4c1d74f567b5e9903a4476b6df911","title":"Overview","url":"/docs/features/guardrails-ai#overview","content":"Guardrails AI is an open-source library that provides a framework for creating and managing guardrails for large language models (LLMs). By integrating Guardrails AI as middleware, you can enforce specific rules and policies on the inputs and outputs of your models, ensuring they adhere to your safety guidelines and quality standards.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Overview","lvl3":""}},
 {"objectID":"f2d2b26f599eb151126c2317daa9412449d66cc6b8b4d0f1327c8954b01c504a","title":"Key Benefits","url":"/docs/features/guardrails-ai#key-benefits","content":"Risk Mitigation: Protect against common AI risks such as hallucinations, toxic language, and data leakage.\nQuality Assurance: Ensure that model outputs are accurate, relevant, and meet predefined quality criteria.\nCompliance: Enforce industry-specific regulations and compliance requirements.\nCustomization: Create custom guardrails tailored to specific use cases and business needs.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Key Benefits","lvl3":""}},
 {"objectID":"26097f53ddbdab41d7341e08c5c758cbe1a3b95bbbbeae5dd96e9658aa979f2f","title":"Middleware-based Guardrail Implementation","url":"/docs/features/guardrails-ai#middleware-based-guardrail-implementation","content":"With the new MiddlewareFactory, integrating guardrails is easier than ever. The factory automatically handles the registration and application of the guardrails middleware when you use a relevant preset.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Middleware-based Guardrail Implementation","lvl3":""}},
-{"objectID":"5383993ee99d15ab0a7af3261df2e30969572d1867439cae6e2e66892657655a","title":"Using the security Preset","url":"/docs/features/guardrails-ai#using-the-security-preset","content":"The easiest way to enable guardrails is to use the security preset when creating your MiddlewareFactory. This preset is specifically designed to enable the guardrails middleware with a default configuration.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Using the security Preset","lvl3":""}},
+{"objectID":"5383993ee99d15ab0a7af3261df2e30969572d1867439cae6e2e66892657655a","title":"Using the security Preset","url":"/docs/features/guardrails-ai#using-the-security-preset","content":"The easiest way to enable guardrails is to use the security preset when creating your MiddlewareFactory. This preset enables the guardrails middleware with an empty configuration: it filters nothing until you add badWords, modelFilter or precallEvaluation (see Customizing Guardrails). To apply a preset to every call without building a factory, use new NeuroLink({ middleware }), configureGlobalMiddleware() or NEUROLINK_MIDDLEWARE_PRESET.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Using the security Preset","lvl3":""}},
 {"objectID":"422196a1c2e1508dcd31ea7fb0c1dba130bfbeb917925ceb9f6c80a762fcfd30","title":"Using the all Preset","url":"/docs/features/guardrails-ai#using-the-all-preset","content":"If you want to use guardrails in combination with other built-in middleware like analytics, you can use the all preset.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Using the all Preset","lvl3":""}},
 {"objectID":"4b7a1fe97ea0f23a386d90548d3214e8e24a6f36ffcff4df7d5859a78e6f9271","title":"Customizing Guardrails","url":"/docs/features/guardrails-ai#customizing-guardrails","content":"While presets provide a great starting point, you can also customize the behavior of the guardrails middleware by providing a custom configuration.\n\nThis new, streamlined approach provides a clean and scalable way to add safety and other enhancements to your AI models within the NeuroLink ecosystem.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"Customizing Guardrails","lvl3":""}},
 {"objectID":"1c07c45bcdcf7be8441182379a01af46db12b22af1ce3115ca29218979bd43bb","title":"See Also","url":"/docs/features/guardrails-ai#see-also","content":"For configuration examples, best practices, and troubleshooting, see the Guardrails Middleware Feature Guide.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails AI Integration with Middleware","lvl2":"See Also","lvl3":""}},
@@ -3507,32 +3508,34 @@
 {"objectID":"062ba86ed5fa937d989ef36219f6bc4d2673654750f6c4fbfee623527282bc03","title":"From Previous Implementations","url":"/docs/features/guardrails-implementation#from-previous-implementations","content":"If upgrading from older guardrail implementations:\nUpdate configuration format to new interfaces\nReplace deprecated methods with new utility functions\nTest evaluation thresholds and adjust as needed\nUpdate error handling to use new patterns","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Implementation Guide","lvl2":"From Previous Implementations","lvl3":""}},
 {"objectID":"1d4cfe18f157b91540119afedbf464d626c2c320e56551b69d5b3f853541e3c4","title":"Breaking Changes","url":"/docs/features/guardrails-implementation#breaking-changes","content":"Configuration structure has been updated for better organization\nSome utility function signatures have changed\nError handling patterns have been improved","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Implementation Guide","lvl2":"Breaking Changes","lvl3":""}},
 {"objectID":"214fe14d9f320f468b5ed10d5b5cf315a7aa2a0fcb1a32598f42a622570e177d","title":"Conclusion","url":"/docs/features/guardrails-implementation#conclusion","content":"The NeuroLink guardrails implementation provides comprehensive content safety and filtering capabilities with:\n✅ AI-powered pre-call evaluation\n✅ Flexible content filtering options\n✅ Configurable response actions\n✅ Visual proof and demonstrations\n✅ High performance and scalability\n✅ Comprehensive error handling\n✅ TypeScript support throughout\n\nFor additional support or questions, refer to the main NeuroLink documentation or create an issue in the repository.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Implementation Guide","lvl2":"Conclusion","lvl3":""}},
-{"objectID":"540c47bd7c6e059a9673d6acb056728c913d14a87db9e96c85e9ad17847af52d","title":"Guardrails Middleware","url":"/docs/features/guardrails","content":"Guardrails Middleware\n\nSince: v7.42.0 | Status: Stable | Availability: SDK (CLI + SDK)\n\nOverview\n\nWhat it does: Guardrails middleware provides real-time content filtering and policy enforcement for AI model outputs, blocking profanity, PII, unsafe content, and custom-defined terms.\n\nWhy use it: Protect your application from generating harmful, inappropriate, or non-compliant content. Ensures AI responses meet safety standards and regulatory requirements.\n\nCommon use cases:\nContent moderation for user-facing applications\nPII (Personally Identifiable Information) redaction\nProfanity filtering for family-friendly apps\nCompliance with industry regulations (COPPA, GDPR, etc.)\nBrand safety and reputation management\n\nQuick Start\n\nGuardrails work out of the box with the security preset. No custom configuration required for basic content filtering.\n\nSDK Example with Security Preset\nEnables guardrails middleware with default configuration\nPass middleware on every call that should be filtered; the NeuroLink constructor does not take this option\nContent is already filtered - safe to display to users\n\nCustom Guardrails Configuration\nMaster switch for guardrails middleware\nEnable keyword-based filtering (fast, regex-based)\nCustom terms to filter/redact from outputs\nEnable AI-powered content safety check (slower, more accurate)\nUse fast, cheap model for safety evaluation\n\nCLI Usage\n\nConfiguration\n\n| Option                    | Type       | Default | Required | Description                          |\n| ------------------------- | ---------- | ------- | -------- | ------------------------------------ |\n| enabled                 | boolean  | true  | No       | Enable/disable guardrails middleware |\n| badWords.enabled        | boolean  | false | No       | Enable keyword-based filtering       |\n| badWords.list           | string[] | []    | No       | List of terms to filter/redact       |\n| badWords.regexPatterns  | string[] | []    | No       | Regular expressions to redact        |\n| modelFilter.enabled     | boolean  | false | No       | Enable AI-based content safety check |\n| modelFilter.filterModel | string   | -       | No       | Model to use for safety evaluation   |\n\nEnvironment Variables\n\nConfig File\n\nHow It Works\n\nFiltering Pipeline\nUser prompt → Sent to AI model\nAI generates response → Initial content created\nGuardrails middleware intercepts:\nBad word filtering: Regex-based term replacement\nModel-based filtering: AI evaluates content safety\nFiltered response → Delivered to user\n\nBad Word Filtering\n\nSimple regex-based replacement:\nCase-insensitive matching\nReplaces each match with a fixed string, [REDACTED] by default (not length-preserving asterisks) — override it with badWords.replacementText\nWorks in both generate and stream modes\n\nRegex Patterns\n\nbadWords.regexPatterns takes regular expressions, each applied with the gi flags. When it is set it takes priority over list:\n\nPatterns run synchronously against the whole response, so one that backtracks catastrophically would stall every request in the process. The cost comes from input that can be split between the parts of a pattern in many ways: a variable-length part (+, *, ?, {n,m}) that can match the same text as whatever follows it. A pattern is refused when it:\nis longer than 1000 characters;\nrepeats a group in which such a part can match the same text as what follows it, including the next iteration of the group: (a+)+, (\\w+\\s*)*, (.*a){10}, (a?a?)+, (a{1,30}){1,30};\nrepeats a group whose alternatives may overlap, such as (a|aa)+ or (\\w|\\d)+;\nchains too many overlapping variable-length parts: more than 8 optional parts in a row (a?a?a?a?a?a?a?a?a?), or more than 4 open-ended ones (.*a.*b.*c.*d.*e.*f);\nuses a repetition bound above 500, such as a{1,1000}.\n\nA repeated group is fine when each variable-length part is followed by something it cannot match. These all run: (\\d{1,3}\\.){3}, ([a-z0-9-]+\\.)+[a-z]{2,}, (?:\\d{4}[- ]?)+, \\b(?:\\d[ -]*?){13,16}\\b, (?:\\w+\\s+)+.\n\nA refused pattern is skipped and logged as an error (Refusing regex pattern ...), the same way an invalid regex is. It is never thrown at the caller, and the other patterns in the list still run. Fail-open is the trade: a skipped pattern filters nothing, so check the logs after you change a pattern. The same limits apply to precallEvaluation.sanitizationPatterns (Refusing sanitization pattern ...).\n\nThe check reads the pattern; it does not run it, so it is conservative and not a proof:\nIt refuses some safe patterns, such as a small fixed count of an ambiguous part ((a{1,3}){3}). Flatten it (a{1,9}) or split it.\nIt compares character classes on a fixed sample of characters (Latin text plus a few other scripts), so a class that only overlaps outside the sample can look disjoint. A back-reference is assumed to overlap with everything.\nExponential shapes built from optional parts are only partly covered: loops and long chains are refused, but the check is a model of the engine, not the engine. Open-ende","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"","lvl3":""}},
-{"objectID":"ad4c8c0e011c259d8f444afec90c94a3c939d9f14e65491e8044a8417430b54c","title":"Guardrails Middleware","url":"/docs/features/guardrails#guardrails-middleware","content":"Since: v7.42.0 | Status: Stable | Availability: SDK (CLI + SDK)","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Guardrails Middleware","lvl3":""}},
-{"objectID":"1ecba9f0cdb3586cf8ad53bba31fb80cabab7aed2aba88050b4f98078dd2bec9","title":"Overview","url":"/docs/features/guardrails#overview","content":"What it does: Guardrails middleware provides real-time content filtering and policy enforcement for AI model outputs, blocking profanity, PII, unsafe content, and custom-defined terms.\n\nWhy use it: Protect your application from generating harmful, inappropriate, or non-compliant content. Ensures AI responses meet safety standards and regulatory requirements.\n\nCommon use cases:\nContent moderation for user-facing applications\nPII (Personally Identifiable Information) redaction\nProfanity filtering for family-friendly apps\nCompliance with industry regulations (COPPA, GDPR, etc.)\nBrand safety and reputation management","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Overview","lvl3":""}},
-{"objectID":"064824951ceeb2f827852673ce43e1d5b0a4776cda59dec766413ea3ea1a41ae","title":"Quick Start","url":"/docs/features/guardrails#quick-start","content":"Guardrails work out of the box with the security preset. No custom configuration required for basic content filtering.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Quick Start","lvl3":""}},
-{"objectID":"95afe6ceda57115c0508134d07f22b3d8ca5fa5f064adacafde697b1e97a1f49","title":"SDK Example with Security Preset","url":"/docs/features/guardrails#sdk-example-with-security-preset","content":"Enables guardrails middleware with default configuration\nPass middleware on every call that should be filtered; the NeuroLink constructor does not take this option\nContent is already filtered - safe to display to users","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"SDK Example with Security Preset","lvl3":""}},
-{"objectID":"b4fbe7f14d6486c89e71170dde75c0aac0a463e7146d3505542a389e27177987","title":"Custom Guardrails Configuration","url":"/docs/features/guardrails#custom-guardrails-configuration","content":"Master switch for guardrails middleware\nEnable keyword-based filtering (fast, regex-based)\nCustom terms to filter/redact from outputs\nEnable AI-powered content safety check (slower, more accurate)\nUse fast, cheap model for safety evaluation","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Custom Guardrails Configuration","lvl3":""}},
-{"objectID":"c8521792297f968b1ed06d4d84924590f9453bb688d0511d82b24e8cb807d1d4","title":"CLI Usage","url":"/docs/features/guardrails#cli-usage","content":"`bash","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"CLI Usage","lvl3":""}},
-{"objectID":"db6d627e8bf12acc503a42180b82237d38b98a34bf4b5c6427110388ba783598","title":"Enable guardrails via environment variable","url":"/docs/features/guardrails#enable-guardrails-via-environment-variable","content":"npx @juspay/neurolink generate \"Write a product description\" --enable-analytics","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Enable guardrails via environment variable","lvl3":""}},
-{"objectID":"0968c358bc16ec092d8eafc1875703e50dd25b900e6a64d8f9a1356ac3e143f8","title":"Guardrails are automatically applied to all generations","url":"/docs/features/guardrails#guardrails-are-automatically-applied-to-all-generations","content":"`","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Guardrails are automatically applied to all generations","lvl3":""}},
-{"objectID":"5b562e23dda525ed54a3fbcd8d86fd0b6b8aba8bc84bb34bc52b2cd028cf0178","title":"Configuration","url":"/docs/features/guardrails#configuration","content":"| Option                    | Type       | Default | Required | Description                          |\n| ------------------------- | ---------- | ------- | -------- | ------------------------------------ |\n| enabled                 | boolean  | true  | No       | Enable/disable guardrails middleware |\n| badWords.enabled        | boolean  | false | No       | Enable keyword-based filtering       |\n| badWords.list           | string[] | []    | No       | List of terms to filter/redact       |\n| badWords.regexPatterns  | string[] | []    | No       | Regular expressions to redact        |\n| modelFilter.enabled     | boolean  | false | No       | Enable AI-based content safety check |\n| modelFilter.filterModel | string   | -       | No       | Model to use for safety evaluation   |","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Configuration","lvl3":""}},
-{"objectID":"2406e4412d40d6ab610c334f551ae73529304f50a559b6fdf180d616d7536174","title":"Environment Variables","url":"/docs/features/guardrails#environment-variables","content":"`bash","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Environment Variables","lvl3":""}},
-{"objectID":"946b41af2f888ce1a40149ea8123d2c4584292d7a22fe88549f0b7c23671f951","title":"Or enable all middleware (includes guardrails + analytics)","url":"/docs/features/guardrails#or-enable-all-middleware-includes-guardrails-analytics","content":"`","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Or enable all middleware (includes guardrails + analytics)","lvl3":""}},
-{"objectID":"70cbcd4ca56befe769c6ddb6128a5ab280c75a48edc8e9b4141dfce607bc2c1e","title":"Filtering Pipeline","url":"/docs/features/guardrails#filtering-pipeline","content":"User prompt → Sent to AI model\nAI generates response → Initial content created\nGuardrails middleware intercepts:\nBad word filtering: Regex-based term replacement\nModel-based filtering: AI evaluates content safety\nFiltered response → Delivered to user","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Filtering Pipeline","lvl3":""}},
-{"objectID":"3af7a22581a93723a5045560d7c0026a6fc3f1bca903dd47c28e0dfa5707e350","title":"Bad Word Filtering","url":"/docs/features/guardrails#bad-word-filtering","content":"Simple regex-based replacement:\nCase-insensitive matching\nReplaces each match with a fixed string, [REDACTED] by default (not length-preserving asterisks) — override it with badWords.replacementText\nWorks in both generate and stream modes","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Bad Word Filtering","lvl3":""}},
+{"objectID":"540c47bd7c6e059a9673d6acb056728c913d14a87db9e96c85e9ad17847af52d","title":"Guardrails Middleware","url":"/docs/features/guardrails","content":"Guardrails Middleware\n\nSince: v7.29.0 | Status: Stable | Availability: SDK; the CLI reads NEUROLINK_MIDDLEWARE_PRESET\n\nOverview\n\nWhat it does: Guardrails is a built-in language-model middleware (id guardrails) that checks what a model returns, and optionally what a user sends. It has three mechanisms. Each is off until you configure it:\nBad-word filtering replaces matches of terms or regular expressions you list with a fixed string. Works in generate() and stream().\nModel-based filtering asks a second model whether the reply is safe and replaces the whole reply if the answer is unsafe. generate() only.\nPre-call evaluation asks a model to judge the user's input before the request is sent, and answers a blocked request with a fixed refusal. Works in generate() and stream().\n\nWhat it does not do: Guardrails ships no word list, no profanity list and no PII patterns. With nothing configured it changes nothing, including under preset: \"security\". It is a text filter, not a compliance control: a term that is not in your list passes through, and a model-based check can miss unsafe content or be unavailable (see Model-Based Filtering). Built-in PII detection is a separate piiDetection option on generate() and stream(), not part of guardrails.\n\nCommon use cases:\nRedacting a known set of terms (brand names, internal codenames, banned words) from model output\nA second-opinion safety check on replies from generate()\nRefusing requests that an evaluator model judges unsafe before they reach the main model\n\nQuick Start\n\nRedact terms on one call\n\nBoth middlewareConfig.guardrails.enabled and badWords.enabled must be true, and list or regexPatterns must be non-empty. Missing any one of them filters nothing.\n\nSet it once for an instance\n\nThe preset: \"security\" line is what switches guardrails on here; the word list is what makes it filter.\n\nSet it once for the process\n\nTurn a preset on from the environment\n\npreset: \"security\" only enables the guardrails middleware. It adds no badWords and no modelFilter, so until one of the layers below supplies them, a reply passes through unchanged. That is true of NEUROLINK_MIDDLEWARE_PRESET=security too. There is deliberately no default word list: a generic list gives false assurance and false positives.\n\nDefaults and precedence\n\nA call resolves its middleware from four layers. A higher layer overrides a lower one.\n\n| Order       | Layer       | How you set it                       | Scope                                                                                                            |\n| ----------- | ----------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |\n| 1 (lowest)  | Environment | NEUROLINK_MIDDLEWARE_PRESET        | Read when each NeuroLink instance is constructed. A preset name only: default, all or security           |\n| 2           | Global      | configureGlobalMiddleware(options) | The whole process. Read on every call, so existing instances pick it up. A later call replaces the earlier one   |\n| 3           | Instance    | new NeuroLink({ middleware })      | That instance. Snapshotted at construction: later edits to your object's word lists or strings are not picked up |\n| 4 (highest) | Per call    | generate({ middleware }) and so on | That call                                                                                                        |\n\nThe defaults apply to generate(), stream() and generateText(). With no default set, a call behaves exactly as it did before: only its own middleware counts.\n\nThe classifier router's model strategy and the probe call in checkCredentials() run through generate() on your own instance, so all of that instance's defaults apply to them. The SDK also creates separate NeuroLink instances for the file summariser, the conversation-memory condenser, the Redis conversation title generator and the image-generation service. Those see the environment layer, which every instance reads, and the global layer, which is read on every call, but not your instance's middleware option. A global badWords list therefore redacts file summaries and titles, and a global precallEvaluation sends whole file contents to the evaluator model.\n\nAn unrecognised NEUROLINK_MIDDLEWARE_PRESET is ignored. A message naming the value is written to stderr, once per distinct value, whether or not debugging is on. A preset in a constructor or global default that is not default, all or security throws a TypeError at new NeuroLink() or configureGlobalMiddleware(), so a typo cannot silently replace a valid preset from a lower layer and leave guardrails off.\n\nHow layers combine\n\n| Option                                                          | Rule                                                                                                                                |\n| --------------------------------------------------------------- | ----------------","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"","lvl3":""}},
+{"objectID":"ad4c8c0e011c259d8f444afec90c94a3c939d9f14e65491e8044a8417430b54c","title":"Guardrails Middleware","url":"/docs/features/guardrails#guardrails-middleware","content":"Since: v7.29.0 | Status: Stable | Availability: SDK; the CLI reads NEUROLINK_MIDDLEWARE_PRESET","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Guardrails Middleware","lvl3":""}},
+{"objectID":"1ecba9f0cdb3586cf8ad53bba31fb80cabab7aed2aba88050b4f98078dd2bec9","title":"Overview","url":"/docs/features/guardrails#overview","content":"What it does: Guardrails is a built-in language-model middleware (id guardrails) that checks what a model returns, and optionally what a user sends. It has three mechanisms. Each is off until you configure it:\nBad-word filtering replaces matches of terms or regular expressions you list with a fixed string. Works in generate() and stream().\nModel-based filtering asks a second model whether the reply is safe and replaces the whole reply if the answer is unsafe. generate() only.\nPre-call evaluation asks a model to judge the user's input before the request is sent, and answers a blocked request with a fixed refusal. Works in generate() and stream().\n\nWhat it does not do: Guardrails ships no word list, no profanity list and no PII patterns. With nothing configured it changes nothing, including under preset: \"security\". It is a text filter, not a compliance control: a term that is not in your list passes through, and a model-based check can miss unsafe content or be unavailable (see Model-Based Filtering). Built-in PII detection is a separate piiDetection option on generate() and stream(), not part of guardrails.\n\nCommon use cases:\nRedacting a known set of terms (brand names, internal codenames, banned words) from model output\nA second-opinion safety check on replies from generate()\nRefusing requests that an evaluator model judges unsafe before they reach the main model","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Overview","lvl3":""}},
+{"objectID":"6215004e045d98a4935173857d1228a9c7699746998c801501ac8f9b9de0dfef","title":"Redact terms on one call","url":"/docs/features/guardrails#redact-terms-on-one-call","content":"Both middlewareConfig.guardrails.enabled and badWords.enabled must be true, and list or regexPatterns must be non-empty. Missing any one of them filters nothing.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Redact terms on one call","lvl3":""}},
+{"objectID":"dd7d7f1a5d3cff8d00a5d56133e0a8345ff1eb7873a6a7b12239af036a7f828e","title":"Set it once for an instance","url":"/docs/features/guardrails#set-it-once-for-an-instance","content":"The preset: \"security\" line is what switches guardrails on here; the word list is what makes it filter.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Set it once for an instance","lvl3":""}},
+{"objectID":"3cd4c72a4af5c6c901a4261fd6506c27591d7b3d3f7b5ee6875af27182613eac","title":"Turn a preset on from the environment","url":"/docs/features/guardrails#turn-a-preset-on-from-the-environment","content":"preset: \"security\" only enables the guardrails middleware. It adds no badWords and no modelFilter, so until one of the layers below supplies them, a reply passes through unchanged. That is true of NEUROLINK_MIDDLEWARE_PRESET=security too. There is deliberately no default word list: a generic list gives false assurance and false positives.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Turn a preset on from the environment","lvl3":""}},
+{"objectID":"b704c7417bcc49bb43075e7000d652885dd9d1ffb780f82dd398fef4861c6584","title":"Defaults and precedence","url":"/docs/features/guardrails#defaults-and-precedence","content":"A call resolves its middleware from four layers. A higher layer overrides a lower one.\n\n| Order       | Layer       | How you set it                       | Scope                                                                                                            |\n| ----------- | ----------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |\n| 1 (lowest)  | Environment | NEUROLINK_MIDDLEWARE_PRESET        | Read when each NeuroLink instance is constructed. A preset name only: default, all or security           |\n| 2           | Global      | configureGlobalMiddleware(options) | The whole process. Read on every call, so existing instances pick it up. A later call replaces the earlier one   |\n| 3           | Instance    | new NeuroLink({ middleware })      | That instance. Snapshotted at construction: later edits to your object's word lists or strings are not picked up |\n| 4 (highest) | Per call    | generate({ middleware }) and so on | That call                                                                                                        |\n\nThe defaults apply to generate(), stream() and generateText(). With no default set, a call behaves exactly as it did before: only its own middleware counts.\n\nThe classifier router's model strategy and the probe call in checkCredentials() run through generate() on your own instance, so all of that instance's defaults apply to them. The SDK also creates separate NeuroLink instances for the file summariser, the conversation-memory condenser, the Redis conversation title generator and the image-generation service. Those see the environment layer, which every instance reads, and the global layer, which is read on every call, but not your instance's middleware option. A global badWords list therefore redacts file summaries and titles, and a global precallEvaluation sends whole file contents to the evaluator model.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Defaults and precedence","lvl3":""}},
+{"objectID":"1166b98bef204d316c02e3d1088946a13fe15472dbe6e89fbbe3d069fc80cd9b","title":"How layers combine","url":"/docs/features/guardrails#how-layers-combine","content":"| Option                                                          | Rule                                                                                                                                |\n| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| preset                                                        | The highest layer that sets one wins                                                                                                |\n| middlewareConfig                                              | Merged per middleware id. Within an id, enabled and conditions come from the highest layer that sets them                       |\n| middlewareConfig.<id>.config                                  | Merged key by key. A key set by a higher layer replaces the lower layer's value for that key as a whole: badWords is not combined |\n| middleware, enabledMiddleware, disabledMiddleware (lists) | The highest layer that sets the list replaces it. Lists are never concatenated. An explicit [] clears an inherited list           |\n| global                                                        | Merged key by key                                                                                                                   |\n\nThe factory applies disabledMiddleware after enabledMiddleware, so a lower layer's disabled list could out-vote a call that asked for the opposite. The merge prevents that: an id that a higher layer switches on, by enabledMiddleware or by middlewareConfig.<id>.enabled: true, is removed from a disabled list it would inherit, and the reverse.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"How layers combine","lvl3":""}},
+{"objectID":"5b562e23dda525ed54a3fbcd8d86fd0b6b8aba8bc84bb34bc52b2cd028cf0178","title":"Configuration","url":"/docs/features/guardrails#configuration","content":"These go under middlewareConfig.guardrails.config, except the first row.\n\n| Option                                | Type              | Default                             | Description                                                                                                         |\n| ------------------------------------- | ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| middlewareConfig.guardrails.enabled | boolean         | false, unless a preset enables it | Master switch. preset: \"security\" and preset: \"all\" set it to true                                            |\n| badWords.enabled                    | boolean         | false                             | Turn on term filtering                                                                                              |\n| badWords.list                       | string[]        | none                                | Terms to redact. Case-insensitive, matched as substrings (no word boundaries), so ass also matches inside class |\n| badWords.regexPatterns              | string[]        | none                                | Case-insensitive regular expressions. When both this and list are set, list is ignored and a warning is logged  |\n| badWords.replacementText            | string          | [REDACTED]                        | What each match is replaced with. The replacement is a fixed string, not length-preserving                          |\n| modelFilter.enabled                 | boolean         | false                             | Turn on the model-based check (generate() only)                                                                   |\n| modelFilter.filterModel             | string or model | none                                | \"provider:model\", a bare model id, or a model handle.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Configuration","lvl3":""}},
+{"objectID":"2406e4412d40d6ab610c334f551ae73529304f50a559b6fdf180d616d7536174","title":"Environment variables","url":"/docs/features/guardrails#environment-variables","content":"| Variable                      | Values                       | Effect                                                                                                                         |\n| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| NEUROLINK_MIDDLEWARE_PRESET | default, all, security | Lowest-precedence default preset for every NeuroLink instance. Blank is ignored; unknown is ignored with a message on stderr |\n\n| Preset     | Turns on              | Notes                                                                         |\n| ---------- | --------------------- | ----------------------------------------------------------------------------- |\n| default  | analytics             |                                                                               |\n| all      | analytics, guardrails | Not everything: auto-evaluation and lifecycle are opt-in per call             |\n| security | guardrails            | Filters nothing until badWords, modelFilter or precallEvaluation is set |\n\nThere is no config-file setting for middleware. Use the constructor option, configureGlobalMiddleware() or the environment variable.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Environment variables","lvl3":""}},
+{"objectID":"71eea9da1fd111fc54519592dbdef82d137cfc893048f58a83e18650fb783ffb","title":"CLI","url":"/docs/features/guardrails#cli","content":"The CLI builds a NeuroLink instance, so NEUROLINK_MIDDLEWARE_PRESET applies to CLI runs too:\n\nThe CLI has no option for a word list or a model filter, so this enables guardrails and filters nothing. Use the SDK to choose what is filtered.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"CLI","lvl3":""}},
+{"objectID":"70cbcd4ca56befe769c6ddb6128a5ab280c75a48edc8e9b4141dfce607bc2c1e","title":"Filtering Pipeline","url":"/docs/features/guardrails#filtering-pipeline","content":"Your request is sent to the model. With precallEvaluation on, an evaluator model sees the input first and an unsafe request is answered with Request contains inappropriate content and has been blocked. without reaching the main model.\nThe model replies.\nThe guardrails middleware filters the reply:\nBad words: the configured terms or patterns are replaced.\nModel filter (generate() only): a second model classifies the reply.\nThe filtered reply is delivered.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Filtering Pipeline","lvl3":""}},
+{"objectID":"3af7a22581a93723a5045560d7c0026a6fc3f1bca903dd47c28e0dfa5707e350","title":"Bad Word Filtering","url":"/docs/features/guardrails#bad-word-filtering","content":"Case-insensitive\nReplaces each match with a fixed string, [REDACTED] by default; override it with badWords.replacementText\nA term matches anywhere inside a word. Use regexPatterns with \\b when you need word boundaries\nWorks in both generate() and stream()","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Bad Word Filtering","lvl3":""}},
 {"objectID":"4be9b0134609c0a5ccba707be47bfc7c5708940e325c69550c196de6060f48a0","title":"Regex Patterns","url":"/docs/features/guardrails#regex-patterns","content":"badWords.regexPatterns takes regular expressions, each applied with the gi flags. When it is set it takes priority over list:\n\nPatterns run synchronously against the whole response, so one that backtracks catastrophically would stall every request in the process. The cost comes from input that can be split between the parts of a pattern in many ways: a variable-length part (+, *, ?, {n,m}) that can match the same text as whatever follows it. A pattern is refused when it:\nis longer than 1000 characters;\nrepeats a group in which such a part can match the same text as what follows it, including the next iteration of the group: (a+)+, (\\w+\\s*)*, (.*a){10}, (a?a?)+, (a{1,30}){1,30};\nrepeats a group whose alternatives may overlap, such as (a|aa)+ or (\\w|\\d)+;\nchains too many overlapping variable-length parts: more than 8 optional parts in a row (a?a?a?a?a?a?a?a?a?), or more than 4 open-ended ones (.*a.*b.*c.*d.*e.*f);\nuses a repetition bound above 500, such as a{1,1000}.\n\nA repeated group is fine when each variable-length part is followed by something it cannot match. These all run: (\\d{1,3}\\.){3}, ([a-z0-9-]+\\.)+[a-z]{2,}, (?:\\d{4}[- ]?)+, \\b(?:\\d[ -]*?){13,16}\\b, (?:\\w+\\s+)+.\n\nA refused pattern is skipped and logged as an error (Refusing regex pattern ...), the same way an invalid regex is. It is never thrown at the caller, and the other patterns in the list still run. Fail-open is the trade: a skipped pattern filters nothing, so check the logs after you change a pattern. The same limits apply to precallEvaluation.sanitizationPatterns (Refusing sanitization pattern ...).\n\nThe check reads the pattern; it does not run it, so it is conservative and not a proof:\nIt refuses some safe patterns, such as a small fixed count of an ambiguous part ((a{1,3}){3}). Flatten it (a{1,9}) or split it.\nIt compares character classes on a fixed sample of characters (Latin text plus a few other scripts), so a class that only overlaps outside the sample can look disjoint.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Regex Patterns","lvl3":""}},
-{"objectID":"5c5b50314493905262b204dbb73bacc7c6ab8a60fa3124469df9e6c1706e47a5","title":"Model-Based Filtering","url":"/docs/features/guardrails#model-based-filtering","content":"While guardrails filter common PII patterns, always review critical outputs manually. False negatives can occur with obfuscated data or uncommon PII formats. For high-stakes compliance, combine with dedicated PII detection services.\n\nAI-powered safety check:\nUses separate, lightweight model (e.g., gpt-4o-mini)\nBinary safe/unsafe classification\nFull redaction on unsafe detection","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Model-Based Filtering","lvl3":""}},
-{"objectID":"dbfe7ff9f27039591c8f98fc3b03c705f22f7b36b689e5f0de95241ae3fb71ee","title":"Middleware Configuration","url":"/docs/features/guardrails#middleware-configuration","content":"preset: \"security\" → Enables guardrails with defaults\npreset: \"all\" → Enables guardrails + all other middleware\nmiddlewareConfig.guardrails → Custom guardrails configuration\n\nSee guardrails-ai-integration.md for complete integration guide.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Middleware Configuration","lvl3":""}},
-{"objectID":"85995a92035eb64e3e92878f16c818aa6b02432dfcdf8a2c1b7d0ec93efb0ceb","title":"Problem: Guardrails not filtering content","url":"/docs/features/guardrails#problem-guardrails-not-filtering-content","content":"Cause: Middleware not enabled or preset not configured\nSolution:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Guardrails not filtering content","lvl3":""}},
-{"objectID":"69697f2c3191cc2ac3f2d5a0a1e9295a7c6df79603d7a54068a65420afd69858","title":"Problem: Too many false positives (legitimate content filtered)","url":"/docs/features/guardrails#problem-too-many-false-positives-legitimate-content-filtered","content":"Cause: Overly aggressive bad word list\nSolution:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Too many false positives (legitimate content filtered)","lvl3":""}},
+{"objectID":"03371e64b1c11c9930bf187a72312fff1e1954628c7da4981da6c3507dfa150b","title":"Streaming","url":"/docs/features/guardrails#streaming","content":"With badWords.enabled: true, stream() holds each run of text and filters it as one string, so a term split across chunks is still caught. The run is released when a non-text part arrives or the stream ends. Filtering therefore costs incremental delivery: you may receive a long reply in one piece at the end rather than as it is generated. With bad-word filtering off, chunks pass through unbuffered.\n\nneurolink.streamText(prompt, options?) is the older string-only form: it takes the prompt as its first argument and yields plain strings, not objects with a content field.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Streaming","lvl3":""}},
+{"objectID":"5c5b50314493905262b204dbb73bacc7c6ab8a60fa3124469df9e6c1706e47a5","title":"Model-Based Filtering","url":"/docs/features/guardrails#model-based-filtering","content":"After the main model replies, the text is sent to the filter model with the prompt Is the following text safe? Respond with only \"safe\" or \"unsafe\". If the answer, trimmed and lower-cased, is exactly unsafe, each text part of the reply is replaced by <REDACTED BY AI GUARDRAIL>. Any other answer leaves the reply alone.\ngenerate() only. stream() does not run the model filter.\nfilterModel as a string is \"provider:model\". A bare model id such as gpt-4o-mini is created on the default provider (NEUROLINK_PROVIDER, then AI_PROVIDER, then vertex), so name the provider unless that is what you want.\nIt fails open. If the filter model cannot be created or the call fails, an error is logged and the reply is returned unfiltered.\nThe reply text leaves for another model. The filter model's provider sees what the main model said.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Model-Based Filtering","lvl3":""}},
+{"objectID":"7ff25d1d098f3d16de4560efbe63e65954883804b47cb56ebc73307b7582f6e3","title":"Pre-Call Evaluation","url":"/docs/features/guardrails#pre-call-evaluation","content":"With precallEvaluation.enabled: true, the user's input is sent to an evaluator model (google-ai with gemini-2.5-flash unless you set provider and evaluationModel). An input it judges unsafe is blocked by default; if the evaluator errors, the request is allowed. This needs credentials for the evaluator's provider.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Pre-Call Evaluation","lvl3":""}},
+{"objectID":"5db7566aedf90d539390892389df697a9ba96c4880f17fa840e40608ea86d19b","title":"Dynamic Guardrails","url":"/docs/features/guardrails#dynamic-guardrails","content":"A per-call middleware can carry a list you load at request time. It replaces the list from any default, because lists are replaced rather than combined.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Dynamic Guardrails","lvl3":""}},
+{"objectID":"1f76b8a28577849750e76dd464d6646aa9bdefe8523d12f311037f919fe24305","title":"API Reference","url":"/docs/features/guardrails#api-reference","content":"new NeuroLink({ middleware }): instance default, a MiddlewareFactoryOptions object\nconfigureGlobalMiddleware(options): process-wide default; replaces the previous one and throws a TypeError if options is not an object\nclearGlobalMiddleware(): remove the process-wide default\ngenerate({ middleware }), stream({ middleware }), generateText({ middleware }): per-call, highest precedence\npreset: \"security\": guardrails on, nothing configured\npreset: \"all\": analytics and guardrails\nmiddlewareConfig.guardrails: the configuration described above\n\nSee guardrails-ai-integration.md for pre-call evaluation in depth.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"API Reference","lvl3":""}},
+{"objectID":"85995a92035eb64e3e92878f16c818aa6b02432dfcdf8a2c1b7d0ec93efb0ceb","title":"Problem: Guardrails not filtering content","url":"/docs/features/guardrails#problem-guardrails-not-filtering-content","content":"Cause: One of the switches is missing, or only a preset is set. preset: \"security\" enables guardrails but gives them nothing to filter.\nSolution: Set all of these, on the call, the instance or the global default:\n\nIf a default is set but a call still passes through, check whether the call's own middleware switches guardrails off (disabledMiddleware or enabled: false) or replaces the list.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Guardrails not filtering content","lvl3":""}},
+{"objectID":"69697f2c3191cc2ac3f2d5a0a1e9295a7c6df79603d7a54068a65420afd69858","title":"Problem: Too many false positives (legitimate content filtered)","url":"/docs/features/guardrails#problem-too-many-false-positives-legitimate-content-filtered","content":"Cause: Terms match anywhere inside a word, so a short or common term catches unrelated words.\nSolution: Use specific terms, or a regular expression with word boundaries:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Too many false positives (legitimate content filtered)","lvl3":""}},
 {"objectID":"eee2fe44ae3284cb63eec8fb3919e61415d44d01645db00a942193e14955f189","title":"Problem: A regex pattern is not filtering anything","url":"/docs/features/guardrails#problem-a-regex-pattern-is-not-filtering-anything","content":"Cause: The pattern was refused for its length or its shape, or it is not valid regex. Both are skipped, and the log says which\nSolution: Look for Refusing regex pattern (or Invalid regex pattern) in the error log. A refusal names the reason, for example a repeated group whose variable-length part can match the same text as what follows it. Separate the parts with a character they cannot match (([\\w-]+\\.)+ instead of ([\\w-]+)+), split a long pattern into several, or move plain terms to badWords.list","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: A regex pattern is not filtering anything","lvl3":""}},
-{"objectID":"203e91cc171e445ffc3872091866a6a6da27809cb879259d7c595e54cf02b29f","title":"Problem: Model-based filter is slow","url":"/docs/features/guardrails#problem-model-based-filter-is-slow","content":"Cause: Using large/expensive model for filtering\nSolution:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Model-based filter is slow","lvl3":""}},
-{"objectID":"3d6cce90a89ac6dc76fe42611ab3d172032a8879982db277948a0f6982c57923","title":"Problem: Guardrails not working in streaming mode","url":"/docs/features/guardrails#problem-guardrails-not-working-in-streaming-mode","content":"Cause: Streaming guardrails only support bad word filtering (not model-based)\nSolution:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Guardrails not working in streaming mode","lvl3":""}},
-{"objectID":"95ef73f0ed68f3ce81ba9c25d863438aae71096384fc37cf1d5b3ee3e6219c69","title":"Content Filtering Strategy","url":"/docs/features/guardrails#content-filtering-strategy","content":"Start with presets - Use preset: \"security\" as baseline\nLayer protections - Combine bad words + model filtering\nUse lightweight filter models - gpt-4o-mini for speed\nTest thoroughly - Verify filtering doesn't break legitimate content\nMonitor and iterate - Track false positives/negatives","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Content Filtering Strategy","lvl3":""}},
-{"objectID":"a900aa88102d3e7f32205bee5665bb0732bca6cfe575bcdca0ca993a3590f28e","title":"Bad Word List Curation","url":"/docs/features/guardrails#bad-word-list-curation","content":"✅ Do:\nInclude specific harmful terms\nUse exact phrases, not single characters\nRegularly update based on user reports\nConsider context-specific terms for your domain\n\n❌ Don't:\nAdd common English words (high false positive rate)\nInclude single letters or short words\nRely solely on bad words (use model filter too)","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Bad Word List Curation","lvl3":""}},
-{"objectID":"8380babcbfc88033aac779943fa372013989ce1cd79ebbc9f1803af06cf2e27e","title":"Related Features","url":"/docs/features/guardrails#related-features","content":"HITL Workflows - User approval for risky actions\nMiddleware Architecture - Custom middleware development\nAnalytics Integration - Track filtered content metrics","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Related Features","lvl3":""}},
-{"objectID":"4dcd9d3f7dd025aac5e11ee4820832266eed4420348ba5f439bac3b9035737ae","title":"Migration Notes","url":"/docs/features/guardrails#migration-notes","content":"If upgrading from versions before v7.42.0:\nGuardrails are now enabled via middleware presets\nOld guardrailsConfig option deprecated - use middlewareConfig.guardrails\nNo breaking changes - existing configs still work\nRecommended: Switch to preset: \"security\" for simplified setup\n\nFor complete technical documentation and advanced integration patterns, see guardrails-ai-integration.md.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Migration Notes","lvl3":""}},
+{"objectID":"4678be93ebd07a49cf125f8b350254ac320ee6245be6e4d77746e5ebbebdee86","title":"Problem: Model-based filter is slow or does nothing","url":"/docs/features/guardrails#problem-model-based-filter-is-slow-or-does-nothing","content":"Cause: A large filter model adds a second round trip to every generate(). If the filter model cannot be created, for example a bare id that does not exist on the default provider, the failure is logged and the reply is returned unfiltered.\nSolution: Use a small model and name its provider:","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Model-based filter is slow or does nothing","lvl3":""}},
+{"objectID":"3d6cce90a89ac6dc76fe42611ab3d172032a8879982db277948a0f6982c57923","title":"Problem: Guardrails not working in streaming mode","url":"/docs/features/guardrails#problem-guardrails-not-working-in-streaming-mode","content":"Cause: stream() supports bad-word filtering and pre-call evaluation but not the model filter.\nSolution: Use badWords for streams, or use generate() when you need the model filter.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: Guardrails not working in streaming mode","lvl3":""}},
+{"objectID":"54dd2e05fca81d0523db814f1329fd7f6c77c3bd34b65e43ef4b5afe5e0f7838","title":"Problem: NEUROLINK_MIDDLEWARE_PRESET has no effect","url":"/docs/features/guardrails#problem-neurolink_middleware_preset-has-no-effect","content":"Cause: The name is not default, all or security (it is then ignored, with a message on stderr), the variable was set after the NeuroLink instance was constructed, or a higher layer sets its own preset.\nSolution: Export it before the process starts, and check the layer order in Defaults and precedence.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Problem: NEUROLINK_MIDDLEWARE_PRESET has no effect","lvl3":""}},
+{"objectID":"a7e9e7181f3c4e419e083e152c274ddaf929b0240ee057ece97504c909ccc8f2","title":"Best Practices","url":"/docs/features/guardrails#best-practices","content":"Name what you filter. The presets enable guardrails; your word list or filter model does the filtering.\nSet a default for every call you cannot audit. An instance or global default is applied even where a call site forgot middleware.\nPrefer specific terms or word-boundary patterns to short common words.\nTest with a real reply. Run a call that should be filtered and one that should not, and check both.\nTreat the model filter as best effort. It fails open and sees only text parts.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Best Practices","lvl3":""}},
+{"objectID":"8380babcbfc88033aac779943fa372013989ce1cd79ebbc9f1803af06cf2e27e","title":"Related Features","url":"/docs/features/guardrails#related-features","content":"HITL Workflows - User approval for risky actions\nMiddleware Architecture - How the middleware chain is built\nBuilt-in Middleware - Analytics, guardrails and auto-evaluation\nGuardrails AI Integration - Pre-call evaluation and MiddlewareFactory usage","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Related Features","lvl3":""}},
+{"objectID":"4dcd9d3f7dd025aac5e11ee4820832266eed4420348ba5f439bac3b9035737ae","title":"Migration Notes","url":"/docs/features/guardrails#migration-notes","content":"Instance, global and environment defaults were added after guardrails were first released. They are optional: a call that passes its own middleware and sets no default behaves as it always did.","hierarchy":{"lvl0":"Features","lvl1":"Guardrails Middleware","lvl2":"Migration Notes","lvl3":""}},
 {"objectID":"4360e3d584ae161b59c6d6c3d6c7fe074f475883b020805602930215117fd0d7","title":"Human-in-the-Loop (HITL) Workflows","url":"/docs/features/hitl","content":"Human-in-the-Loop (HITL) Workflows\n\nSince: v7.39.0 | Status: Stable | Availability: SDK\n\nOverview\n\nWhat it does: HITL pauses AI tool execution to request explicit user approval before performing risky operations like deleting files, modifying databases, or making expensive API calls.\n\nWhy use it: Prevent costly mistakes and give users control over potentially dangerous AI actions. Think of it as an \"Are you sure?\" dialog for AI assistant operations.\n\nOnly use HITL for truly risky operations. Overusing confirmation prompts degrades user experience and can lead to \"confirmation fatigue\" where users approve actions without reading them.\n\nCommon use cases:\nFile deletion or modification operations\nDatabase write/delete operations\nExpensive third-party API calls\nIrreversible actions (sending emails, posting to social media)\nOperations accessing sensitive data\n\nQuick Start\n\nSDK Example\nTool identifier used by the AI to invoke this function\nDescribes tool purpose to the LLM for proper selection\nTriggers HITL checkpoint before execution\nActual implementation only runs after user approval\n\nHandling Confirmation in Your UI\n\nHITL uses an event-based workflow where the SDK emits confirmation requests and your app responds with user decisions.\nGet the event emitter - NeuroLink is not itself an emitter, so requests and responses both go through getEventEmitter()\nSubscribe to confirmation requests - NeuroLink emits one before running a tool that needs approval\nShow your confirmation UI with the tool name, arguments and remaining time\nReply on the same emitter, echoing the request's confirmationId so the response is matched to its request\nApproval decision determines if tool executes\nOptional: Handle cases where user doesn't respond in time\n\nConfiguration\n\n| Option                 | Type      | Default | Required | Description                          |\n| ---------------------- | --------- | ------- | -------- | ------------------------------------ |\n| requiresConfirmation | boolean | false | No       | Mark tool as requiring user approval |\n\nTool Registration\n\nHow It Works\n\nExecution Flow\nAI requests tool execution → Tool executor checks if tool requires confirmation\nConfirmation required? → Returns USER_CONFIRMATION_REQUIRED error to LLM\nLLM asks user → \"I need to [action]. Is that okay?\"\nUser responds:\nApprove → UI sets confirmation_received = true and retries tool execution\nDeny → UI sends \"User cancelled\" message back to LLM\nTool executes → Permission flag immediately resets to false\n\nSecurity Features\nOne-time permissions: Each approval works for exactly one action\nNo reuse: AI cannot reuse old permissions for new actions\nAutomatic reset: Permission flag clears immediately after use\nFail-safe: Defaults to requiring permission when in doubt\n\nAPI Reference\n\nEvent Types\n\nAll HITL events ride the SDK emitter returned by\nneurolink.getEventEmitter(); emitter below is that object.\n\nConfirmation Request Event (hitl:confirmation-request):\n\nConfirmation Response (emit from your app):\n\nTimeout Event (hitl:timeout):\n\nTroubleshooting\n\nProblem: Tool executes without asking for permission\n\nCause: Tool not marked with requiresConfirmation: true\nSolution:\nAdd this boolean flag to any tool that performs risky operations\n\nProblem: AI keeps asking for confirmation repeatedly\n\nCause: Confirmation responses not being sent or sent with wrong confirmationId\nSolution:\nExtract confirmation ID from the request event\nAlways respond to every confirmation request\nCritical: Use the same confirmationId from the request\n\nProblem: Confirmation dialog doesn't show\n\nCause: Not listening to hitl:confirmation-request event\nSolution:\nRegister the event handler early in your application startup\nAll subsequent tool executions will trigger confirmations when needed\n\nBest Practices\n\nStore user confirmation preferences to avoid repeated prompts for the same action type. For example, if a user approves \"delete temporary files\" once, cache that preference for similar low-risk deletions in the same session.\n\nFor Developers\nMark tools conservatively - If an operation could cause problems, require confirmation\nClear prompts - Ensure users understand exactly what will happen\nTest confirmation flow - Verify it works smoothly in your UI\nLog approvals - Keep audit trail of user decisions\nHandle denials gracefully - Allow users to try alternative approaches\n\nWhat to Mark as Requiring Confirmation\n\n✅ Do require confirmation:\nFile deletions\nDatabase writes/deletes\nSending emails or messages\nMaking purchases or payments\nModifying production systems\n\n❌ Don't require confirmation:\nRead-only operations\nAnswering questions\nGenerating content\nSearching/fetching data\n\nRelated Features\nGuardrails Middleware - Content filtering and safety checks\nCustom Tools - Building your own tools with HITL\nMiddleware Architecture - Advanced request interception\n\nMigration Notes\n\nIf upgrading from versions before v7.39.0:\nReview all existing tools for risk assessment\nAdd requiresConfirmation: tr","hierarchy":{"lvl0":"Features","lvl1":"Human-in-the-Loop (HITL) Workflows","lvl2":"","lvl3":""}},
 {"objectID":"d85931f065438b4475cf5fc7e7854d68dda75d45b96963229ea7accb7f456a86","title":"Human-in-the-Loop (HITL) Workflows","url":"/docs/features/hitl#human-in-the-loop-hitl-workflows","content":"Since: v7.39.0 | Status: Stable | Availability: SDK","hierarchy":{"lvl0":"Features","lvl1":"Human-in-the-Loop (HITL) Workflows","lvl2":"Human-in-the-Loop (HITL) Workflows","lvl3":""}},
 {"objectID":"f1d18bf2b10a871a2c1ba24625cfdba4ced0186612c32e21ff05afa4d8c614b5","title":"Overview","url":"/docs/features/hitl#overview","content":"What it does: HITL pauses AI tool execution to request explicit user approval before performing risky operations like deleting files, modifying databases, or making expensive API calls.\n\nWhy use it: Prevent costly mistakes and give users control over potentially dangerous AI actions. Think of it as an \"Are you sure?\" dialog for AI assistant operations.\n\nOnly use HITL for truly risky operations. Overusing confirmation prompts degrades user experience and can lead to \"confirmation fatigue\" where users approve actions without reading them.\n\nCommon use cases:\nFile deletion or modification operations\nDatabase write/delete operations\nExpensive third-party API calls\nIrreversible actions (sending emails, posting to social media)\nOperations accessing sensitive data","hierarchy":{"lvl0":"Features","lvl1":"Human-in-the-Loop (HITL) Workflows","lvl2":"Overview","lvl3":""}},
@@ -3632,9 +3635,9 @@
 {"objectID":"ca876274dff5d751bc09c60e4de804f44917d9e0599697c2cd17362e3e6148bd","title":"Advanced Integrations","url":"/docs/features#advanced-integrations","content":"| Integration                                                    | Description                                                                                         |\n| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| LiteLLM Integration           | Access 100+ models across a broad range of AI providers via LiteLLM routing with unified interface. |\n| SageMaker Integration       | Deploy and call custom endpoints directly from NeuroLink CLI/SDK with full control.                 |\n| Memory                                        | Per-user condensed memory with S3/Redis/SQLite storage and LLM-powered condensation.                |\n| Enterprise Proxy           | Configure outbound policies and compliance posture for corporate environments.                      |\n| Configuration Management | Manage environments, regions, and credentials safely across deployments.                            |","hierarchy":{"lvl0":"Features","lvl1":"Feature Guides","lvl2":"Advanced Integrations","lvl3":""}},
 {"objectID":"0d74f47963b8a59cf58901d344f8d1e987d3bb286cb012ed22278f415c051d3f","title":"Advanced Features","url":"/docs/features#advanced-features","content":"| Feature                                                                                   | Description                                                                        |\n| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| 🏭 Factory Pattern Architecture | Unified provider interface with automatic fallbacks and type-safe implementations. |\n| 🗄️ Conversation Memory              | Deep dive into memory management and Redis integration.                            |\n| 🔧 Custom Middleware              | Build request/response hooks for logging, filtering, and custom processing.        |\n| ⚡ Performance Optimization     | Caching, connection pooling, and latency optimization strategies.                  |\n| 📊 Telemetry & Observability               | OpenTelemetry integration for distributed tracing and monitoring.                  |\n| 🧪 Testing Guide                                   | Provider-agnostic testing, mocking, and quality assurance strategies.              |\n| 📊 Analytics & Evaluation               | Usage tracking, cost monitoring, and quality scoring for AI responses.             |\n| ⚡ Streaming                                | Real-time token streaming with provider-specific optimizations.                    |\n|  Thinking Configuration               | Configure extended thinking levels for supported models (Anthropic, Gemini 2.5+).  |\n|  Structured Output                        | JSON schema-based structured output with provider-specific formatting.             |\n|  Text-to-Speech (TTS)                              | Basic TTS support via Google Cloud TTS (Neural2, Wavenet, Standard voices).        |","hierarchy":{"lvl0":"Features","lvl1":"Feature Guides","lvl2":"Advanced Features","lvl3":""}},
 {"objectID":"9c1dd453df8293552c84f52e9dd08ca4cd003afe799a2561dc4101aa9c2a304a","title":"See Also","url":"/docs/features#see-also","content":"Getting Started - Quick start and installation\nCLI Reference - Command-line interface documentation\nSDK Reference - TypeScript API documentation\nEnterprise Guides - Production deployment patterns\nTutorials - Step-by-step implementation guides\nExamples - Real-world code samples","hierarchy":{"lvl0":"Features","lvl1":"Feature Guides","lvl2":"See Also","lvl3":""}},
-{"objectID":"83f5b0de036a8a17898acf6e57b876b24b8eab4db20af614b766816e4da47913","title":"LiveKit Voice Agent — Real-Time Voice over WebRTC","url":"/docs/features/livekit-voice-agent","content":"LiveKit Voice Agent — Real-Time Voice over WebRTC\n\nA WebRTC voice agent that uses LiveKit for the real-time media loop and NeuroLink as the brain (LLM, tools, memory).\n\nTable of Contents\nProblem Statement & Solution\nArchitecture Overview\nDeployment Topologies (Cloud & Self-Hosted)\nCore Components\nHow NeuroLink Owns the Brain\nRuntime Flow\nUsage Example\nSource Layout\nConfiguration\nTuning the Voice Loop (VAD, Turn Detection, Interruption, Language)\nConversation Memory\nImplementation Plan\nOperational Behavior\nError Handling & Troubleshooting\nExtensibility Roadmap\n\nProblem Statement & Solution\n\nThe Challenge\n\nThe original NeuroLink voice agent (see voice-agent.md) runs a browser-to-server loop over a WebSocket. That design works, but a WebSocket transport carries structural limits for real-time audio:\nTCP head-of-line blocking and no jitter buffer cause choppy audio on lossy networks\nno built-in acoustic echo cancellation — the assistant can be transcribed by its own mic input\nraw PCM is ~8–10× the bandwidth of a compressed codec, and all of it flows through the application server\nvoice-activity detection runs on the application server's event loop, capping per-process concurrency\nSvelteKit and similar frameworks cannot accept the WebSocket upgrade without a custom server entry\n\nThe Solution\n\nThe LiveKit voice agent moves the transport to WebRTC via LiveKit, while keeping NeuroLink as the brain. LiveKit (an open-source WebRTC platform with a managed cloud and a self-hostable server) provides the parts that are hard to build correctly:\nWebRTC transport with echo cancellation, jitter buffering, packet-loss concealment, and Opus compression\nvoice-activity detection, turn detection, and interruption handling\na worker/job model that runs each call in its own process for isolation and horizontal scaling\n\nNeuroLink remains responsible for the conversation itself:\nthe LLM (any NeuroLink provider — Bedrock/Claude, OpenAI, Gemini, etc.)\ntool calling (MCP and registered tools), decided and executed inside neurolink.stream()\nconversation memory, keyed by a stable conversationId\n\nKey Benefits\nProduction-grade real-time audio without building media plumbing\nNeuroLink stays the brain — generate()/stream(), tools, and memory are unchanged\nWorker-per-call scaling provided by the LiveKit Agents runtime\nCloud or self-hosted with identical application code\nProvider-agnostic brain layer that can later back other transports\n\nArchitecture Overview\n\nSystem Flow Diagram\n\nDivision of Responsibility\n\n| Concern                                     | Owner                               |\n| ------------------------------------------- | ----------------------------------- |\n| WebRTC transport, AEC, jitter, Opus         | LiveKit                             |\n| VAD, turn detection, interruption           | LiveKit Agents                      |\n| Worker-per-call process isolation & scaling | LiveKit Agents                      |\n| STT / TTS                                   | LiveKit plugins (configurable)      |\n| LLM, tool-calling, memory                   | NeuroLink                           |\n| Conversation history source of truth        | NeuroLink memory (conversationId) |\n\nDeployment Topologies (Cloud & Self-Hosted)\n\nThe application code is identical across topologies; only LIVEKIT_URL and credentials change.\n\nTopology A — LiveKit Cloud (managed)\nRooms are created automatically on LiveKit's servers on first join.\nThe worker connects outbound to Cloud and receives dispatched Jobs over that connection — no inbound exposure or tunneling is required, even in local development.\nBilling is per participant-minute (a free Build tier is suitable for development).\nUse when: fastest setup, minimal media ops, dev/staging, or production without running media infrastructure.\n\nTopology B — Self-Hosted LiveKit (in-house)\nThe livekit-server (open source) runs on your own infrastructure (for example, Kubernetes behind your ingress/service mesh).\nMedia stays inside your network; there is no per-minute media fee — you pay only for compute and bandwidth.\nUse when: cost control at scale, data-residency/compliance requirements, or full control over the media path.\n\nLocal Development\nConsole mode: the worker runs standalone using the host machine's microphone and speakers — no LiveKit server and no browser required. Best for iterating on the brain loop.\nLocal server: livekit-server --dev (placeholder credentials, no external dependencies) with the browser and worker on localhost.\nCloud from local: point local LIVEKIT_URL at a Cloud project. Because the worker connects outbound, Cloud can dispatch Jobs to a locally-running worker without tunneling.\n\nCore Components\nLiveKit Agents Worker\n\nA long-lived Node process built on @livekit/agents. It registers with the LiveKit server under an agentName (for example, neurolink-voice). For each room, LiveKit dispatches a Job, which the runtime runs in its own process — this is the worker-per-call isolation that bounds the ","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"","lvl3":""}},
+{"objectID":"83f5b0de036a8a17898acf6e57b876b24b8eab4db20af614b766816e4da47913","title":"LiveKit Voice Agent — Real-Time Voice over WebRTC","url":"/docs/features/livekit-voice-agent","content":"LiveKit Voice Agent — Real-Time Voice over WebRTC\n\nA WebRTC voice agent that uses LiveKit for the real-time media loop and NeuroLink as the brain (LLM, tools, memory).\n\nTable of Contents\nProblem Statement & Solution\nArchitecture Overview\nDeployment Topologies (Cloud & Self-Hosted)\nCore Components\nHow NeuroLink Owns the Brain\nRuntime Flow\nUsage Example\nSource Layout\nConfiguration\nTuning the Voice Loop (VAD, Turn Detection, Interruption, Language)\nConversation Memory\nRealtime Speech-to-Speech Backends (Gemini Live and xAI Grok Voice)\nImplementation Plan\nOperational Behavior\nError Handling & Troubleshooting\nExtensibility Roadmap\n\nProblem Statement & Solution\n\nThe Challenge\n\nThe original NeuroLink voice agent (see voice-agent.md) runs a browser-to-server loop over a WebSocket. That design works, but a WebSocket transport carries structural limits for real-time audio:\nTCP head-of-line blocking and no jitter buffer cause choppy audio on lossy networks\nno built-in acoustic echo cancellation — the assistant can be transcribed by its own mic input\nraw PCM is ~8–10× the bandwidth of a compressed codec, and all of it flows through the application server\nvoice-activity detection runs on the application server's event loop, capping per-process concurrency\nSvelteKit and similar frameworks cannot accept the WebSocket upgrade without a custom server entry\n\nThe Solution\n\nThe LiveKit voice agent moves the transport to WebRTC via LiveKit, while keeping NeuroLink as the brain. LiveKit (an open-source WebRTC platform with a managed cloud and a self-hostable server) provides the parts that are hard to build correctly:\nWebRTC transport with echo cancellation, jitter buffering, packet-loss concealment, and Opus compression\nvoice-activity detection, turn detection, and interruption handling\na worker/job model that runs each call in its own process for isolation and horizontal scaling\n\nNeuroLink remains responsible for the conversation itself:\nthe LLM (any NeuroLink provider — Bedrock/Claude, OpenAI, Gemini, etc.)\ntool calling (MCP and registered tools), decided and executed inside neurolink.stream()\nconversation memory, keyed by a stable conversationId\n\nKey Benefits\nProduction-grade real-time audio without building media plumbing\nNeuroLink stays the brain — generate()/stream(), tools, and memory are unchanged\nWorker-per-call scaling provided by the LiveKit Agents runtime\nCloud or self-hosted with identical application code\nProvider-agnostic brain layer that can later back other transports\n\nArchitecture Overview\n\nSystem Flow Diagram\n\nDivision of Responsibility\n\n| Concern                                     | Owner                               |\n| ------------------------------------------- | ----------------------------------- |\n| WebRTC transport, AEC, jitter, Opus         | LiveKit                             |\n| VAD, turn detection, interruption           | LiveKit Agents                      |\n| Worker-per-call process isolation & scaling | LiveKit Agents                      |\n| STT / TTS                                   | LiveKit plugins (configurable)      |\n| LLM, tool-calling, memory                   | NeuroLink                           |\n| Conversation history source of truth        | NeuroLink memory (conversationId) |\n\nDeployment Topologies (Cloud & Self-Hosted)\n\nThe application code is identical across topologies; only LIVEKIT_URL and credentials change.\n\nTopology A — LiveKit Cloud (managed)\nRooms are created automatically on LiveKit's servers on first join.\nThe worker connects outbound to Cloud and receives dispatched Jobs over that connection — no inbound exposure or tunneling is required, even in local development.\nBilling is per participant-minute (a free Build tier is suitable for development).\nUse when: fastest setup, minimal media ops, dev/staging, or production without running media infrastructure.\n\nTopology B — Self-Hosted LiveKit (in-house)\nThe livekit-server (open source) runs on your own infrastructure (for example, Kubernetes behind your ingress/service mesh).\nMedia stays inside your network; there is no per-minute media fee — you pay only for compute and bandwidth.\nUse when: cost control at scale, data-residency/compliance requirements, or full control over the media path.\n\nLocal Development\nConsole mode: the worker runs standalone using the host machine's microphone and speakers — no LiveKit server and no browser required. Best for iterating on the brain loop.\nLocal server: livekit-server --dev (placeholder credentials, no external dependencies) with the browser and worker on localhost.\nCloud from local: point local LIVEKIT_URL at a Cloud project. Because the worker connects outbound, Cloud can dispatch Jobs to a locally-running worker without tunneling.\n\nCore Components\nLiveKit Agents Worker\n\nA long-lived Node process built on @livekit/agents. It registers with the LiveKit server under an agentName (for example, neurolink-voice). For each room, LiveKit dispatches a Job, which the runtime runs in its ","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"","lvl3":""}},
 {"objectID":"18162c78ef8435753a2a960c9aaacf301d553ede68ef97184f924649726c9b59","title":"LiveKit Voice Agent — Real-Time Voice over WebRTC","url":"/docs/features/livekit-voice-agent#livekit-voice-agent-real-time-voice-over-webrtc","content":"A WebRTC voice agent that uses LiveKit for the real-time media loop and NeuroLink as the brain (LLM, tools, memory).","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl3":""}},
-{"objectID":"1f733cc14879f19626ff1c687558c535be79cba162237c90533f45426f7d98cc","title":"Table of Contents","url":"/docs/features/livekit-voice-agent#table-of-contents","content":"Problem Statement & Solution\nArchitecture Overview\nDeployment Topologies (Cloud & Self-Hosted)\nCore Components\nHow NeuroLink Owns the Brain\nRuntime Flow\nUsage Example\nSource Layout\nConfiguration\nTuning the Voice Loop (VAD, Turn Detection, Interruption, Language)\nConversation Memory\nImplementation Plan\nOperational Behavior\nError Handling & Troubleshooting\nExtensibility Roadmap","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Table of Contents","lvl3":""}},
+{"objectID":"1f733cc14879f19626ff1c687558c535be79cba162237c90533f45426f7d98cc","title":"Table of Contents","url":"/docs/features/livekit-voice-agent#table-of-contents","content":"Problem Statement & Solution\nArchitecture Overview\nDeployment Topologies (Cloud & Self-Hosted)\nCore Components\nHow NeuroLink Owns the Brain\nRuntime Flow\nUsage Example\nSource Layout\nConfiguration\nTuning the Voice Loop (VAD, Turn Detection, Interruption, Language)\nConversation Memory\nRealtime Speech-to-Speech Backends (Gemini Live and xAI Grok Voice)\nImplementation Plan\nOperational Behavior\nError Handling & Troubleshooting\nExtensibility Roadmap","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Table of Contents","lvl3":""}},
 {"objectID":"91eb3bc5f2e53ccf0662d056db82c3261cd9995803814a4bd489a21b509d5ac8","title":"The Challenge","url":"/docs/features/livekit-voice-agent#the-challenge","content":"The original NeuroLink voice agent (see voice-agent.md) runs a browser-to-server loop over a WebSocket. That design works, but a WebSocket transport carries structural limits for real-time audio:\nTCP head-of-line blocking and no jitter buffer cause choppy audio on lossy networks\nno built-in acoustic echo cancellation — the assistant can be transcribed by its own mic input\nraw PCM is ~8–10× the bandwidth of a compressed codec, and all of it flows through the application server\nvoice-activity detection runs on the application server's event loop, capping per-process concurrency\nSvelteKit and similar frameworks cannot accept the WebSocket upgrade without a custom server entry","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"The Challenge","lvl3":""}},
 {"objectID":"1cb9d49f576a65ba650f409acd589e1409d749a9e793c8007fcdd653049227cd","title":"The Solution","url":"/docs/features/livekit-voice-agent#the-solution","content":"The LiveKit voice agent moves the transport to WebRTC via LiveKit, while keeping NeuroLink as the brain. LiveKit (an open-source WebRTC platform with a managed cloud and a self-hostable server) provides the parts that are hard to build correctly:\nWebRTC transport with echo cancellation, jitter buffering, packet-loss concealment, and Opus compression\nvoice-activity detection, turn detection, and interruption handling\na worker/job model that runs each call in its own process for isolation and horizontal scaling\n\nNeuroLink remains responsible for the conversation itself:\nthe LLM (any NeuroLink provider — Bedrock/Claude, OpenAI, Gemini, etc.)\ntool calling (MCP and registered tools), decided and executed inside neurolink.stream()\nconversation memory, keyed by a stable conversationId","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"The Solution","lvl3":""}},
 {"objectID":"8c89b1ddf6fdca318ba346bdddbd0dc7a7d0e750cf4eeffdde705f11e43e7dc7","title":"Key Benefits","url":"/docs/features/livekit-voice-agent#key-benefits","content":"Production-grade real-time audio without building media plumbing\nNeuroLink stays the brain — generate()/stream(), tools, and memory are unchanged\nWorker-per-call scaling provided by the LiveKit Agents runtime\nCloud or self-hosted with identical application code\nProvider-agnostic brain layer that can later back other transports","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Key Benefits","lvl3":""}},
@@ -3673,6 +3676,14 @@
 {"objectID":"804a64dd17c69cb8d4af469682d01d12f00bec2d6869a5faef30865da99f176d","title":"Speech provider selection","url":"/docs/features/livekit-voice-agent#speech-provider-selection","content":"STT and TTS plugins are chosen per agent and configured by environment credentials.\nSTT: soniox, deepgram. TTS: cartesia, elevenlabs.\nOnly set voice / model if your account supports them; otherwise omit those\n  fields to use the plugin's own defaults.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Speech provider selection","lvl3":""}},
 {"objectID":"5589375c3b5b8ee71271f32386ef6b0f878bc88f7097a13ee7d8ef03b694655e","title":"Conversation Memory","url":"/docs/features/livekit-voice-agent#conversation-memory","content":"The agent remembers earlier turns automatically when the NeuroLink instance you\nbuild inside createNeuroLink has conversation memory enabled. History is the\nagent's source of truth — LiveKit's own transcript context is not used for\ngeneration.\n\nHow it behaves:\nKeyed per call. Each room/call is an isolated conversation; the id is\n  derived from the room name. Override the prefix with conversationIdPrefix\n  (default \"voice\").\nIn-memory by default; Redis for persistence. Set REDIS_URL to use a\n  shared store that survives worker restarts and is shared across worker\n  replicas — important because each call runs in its own job process.\nWorks across turns within the session. The user can say \"my name is Alex\"\n  and later ask \"what's my name?\" and the agent recalls it.\n\nMemory persists only when the instance is configured with\nconversationMemory.enabled. Without it, each turn is independent.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Conversation Memory","lvl3":""}},
 {"objectID":"e6ef692117fe2ad968f2bb5bd1692e50783a069a189d3dbfd6ac49f71ef84c73","title":"Remembering a realtime call in the user's own conversation","url":"/docs/features/livekit-voice-agent#remembering-a-realtime-call-in-the-users-own-conversation","content":"A speech-to-speech call (defineRealtimeVoiceAgent) never goes through\nstream() or generate(), so by default nothing it says is stored. Opt in with\nmemory and the call's turns are written, through\nNeuroLink.recordConversationTurn, to the same conversation memory typed chat\nuses, appended to the conversation the person already has open. The model is\nalso seeded with that conversation's recent history when the call starts, so it\nknows what was said before.\n\nWhose conversation is never taken from the client. The host that creates\nthe room signs a binding and puts it in the room metadata next to authToken\nand mcpContext. The worker stores nothing unless it verifies.\nThe signature is HMAC-SHA256 over [\"neurolink.voice.memory.v1\", room,\nuserId, sessionId, exp] (a JSON array, so no choice of values can make two\n  bindings collide), base64url-encoded. It covers the room name, so a binding\n  copied into another room does not verify. exp is Unix seconds; the default\n  lifetime is two hours, the cap 24 hours.\nThe shared secret is at least 16 characters, read from\n  NEUROLINK_VOICE_MEMORY_SECRET unless memory.secret is set on the worker.\nsessionId matches ^[A-Za-z0-9_-]{1,128}$ (no :, which is part of the\n  stored key). userId is 1 to 256 characters with no whitespace or control\n  characters; : is allowed because chat user ids contain it.\nFail closed. No secret, no binding, a malformed or expired binding, or a\n  bad signature: the call runs normally, nothing is stored, and a warning\n  names the reason (never the ids).\nA client may name the conversation to append to. The host accepts the name\n  only when neurolink.conversationExists({ sessionId, userId }) is true for\n  the verified user. Otherwise it mints a new voice-<uuid>.\n\nWhat is stored. Each finished exchange becomes a user message and an\nassistant message with the ids ${turnId}:user and ${turnId}:assistant, where\nturnId is the realtime session's assistant message id, and\nmetadata.modality: \"voice\".","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Remembering a realtime call in the user's own conversation","lvl3":""}},
+{"objectID":"2b5f572d39aad7e08324d267d06f5dcbc4e90af9c0c31f1d536c84cc4243c5c1","title":"Realtime Speech-to-Speech Backends (Gemini Live and xAI Grok Voice)","url":"/docs/features/livekit-voice-agent#realtime-speech-to-speech-backends-gemini-live-and-xai-grok-voice","content":"defineRealtimeVoiceAgent runs one realtime model that does speech-to-text,\nreasoning, text-to-speech and turn detection over a single connection. Gemini\nLive on Vertex is the default. xAI's Grok Voice is a second backend, reached\nthrough LiveKit's xAI plugin.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Realtime Speech-to-Speech Backends (Gemini Live and xAI Grok Voice)","lvl3":""}},
+{"objectID":"3ea0de3512723dda2eba65763b09a6e3eff2ded8a4d0aa2fa41581d46b88e6c7","title":"Status","url":"/docs/features/livekit-voice-agent#status","content":"Tested against a stub WebSocket server only. The stub listens on\n  127.0.0.1. It shows what the LiveKit xAI plugin sends to whatever it is\n  pointed at, and how this package reads the OpenAI-style events it is given.\n  It shows nothing about how xAI answers.\nNo request has been made to xAI by this project. No xAI key was available\n  when the backend was written.\nNot established here: behaviour against the live service, latency,\n  accuracy, and every xAI benchmark. Nothing in this section says the xai\n  backend works with the real service. Treat it as untested against xAI until\n  someone runs a call with a real key.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Status","lvl3":""}},
+{"objectID":"6676179c44d375115fe98161f9377ba40357b82eebf4a99b7b330ede9721e8c3","title":"Choosing the backend","url":"/docs/features/livekit-voice-agent#choosing-the-backend","content":"| Variable                                                                          | Backend | Meaning                                                                                                                                                                                                                                                                                                                                                                            |\n| --------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| VOICE_REALTIME_BACKEND                                                          | both    | gemini or xai. Any other value throws at startup, naming the variable and the two choices and repeating nothing from the environment.                                                                                                                                                                                                                                          |\n| VOICE_LIVE_MODEL                                                                | both    | Realtime model id. Default gemini-live-2.5-flash for gemini, grok-voice-3.0 for xai.                                                                                                                                                                                                                                                                                           |\n| VOICE_S2S_VOICE                                                                 | both    | Voice name.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Choosing the backend","lvl3":""}},
+{"objectID":"632f3752058fa7c7c6d48b02af1e8d5212b7daa55001e8cc931227404009278f","title":"Dependencies","url":"/docs/features/livekit-voice-agent#dependencies","content":"The xai backend needs @livekit/agents-plugin-xai and\n@livekit/agents-plugin-openai. Both are optional dependencies of this package,\nso they are installed with its other optional dependencies (an install that\nomits optional dependencies has to add them by hand), and both resolved to\n1.4.6 in its lockfile. The xAI plugin asks for @livekit/agents 1.4.6 exactly,\nwhich is why that package moved from 1.4.5 to 1.4.6 with it. The options the\nGemini backend builds are unchanged by the move, but no live Gemini call was\nrun after it.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Dependencies","lvl3":""}},
+{"objectID":"a890643483526cae888fdc083535c83d5313ddef29c4a24f6d2771e94dcf3f71","title":"What the xai backend does","url":"/docs/features/livekit-voice-agent#what-the-xai-backend-does","content":"The LiveKit xAI plugin extends the OpenAI realtime model. Against a stub it\nconnects to <base URL>/realtime?model=<id> with Authorization: Bearer\n<XAI_API_KEY> (the key is never put in the URL) and its first event is a\nsession.update that carries the model, the voice, output_modalities:\n[\"audio\"], server-side voice-activity detection (threshold 0.5, 300 ms prefix\npadding, 200 ms silence, response creation and interruption on) and an input\ntranscription setting. The plugin's default endpoint is wss://api.x.ai/v1.\n\nTwo things in that list are the plugin's and are not verified against xAI:\nthe plugin sends gpt-4o-mini-transcribe, an OpenAI model name, as the input\n  transcription model;\nthe plugin's own default model is grok-voice-think-fast-1.0. NeuroLink\n  defaults to grok-voice-3.0, the flagship id xAI's documentation lists\n  (together with the alias grok-voice-latest and a deprecated\n  grok-voice-2.0). The plugin passes the id through; whether the service\n  accepts it through the plugin has not been tested.\n\nA missing key stops the call before it connects. If XAI_API_KEY is unset\nthe plugin falls back to OPENAI_API_KEY, and a stub server showed that\nfallback sending the OpenAI key as the Bearer token to the configured xAI URL.\n(An empty value does not fall back: the plugin throws its own OpenAI API key is\nrequired error. A whitespace-only value is sent as the key.) NeuroLink\ntherefore refuses an unset, empty or whitespace-only key: it throws\nXAI_API_KEY is not set ... when the agent starts and again in\ncreateRealtimeLlm, and no connection is made.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"What the xai backend does","lvl3":""}},
+{"objectID":"b4b0a14667e072deb333f9771c062361a617e33da9a0142087c0ba9502d3e4f7","title":"How each part of the agent behaves on xai","url":"/docs/features/livekit-voice-agent#how-each-part-of-the-agent-behaves-on-xai","content":"| Part                                                               | On xai                                                                                                                                                                                                                            |\n| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Vertex ADC and GEMINI_API_KEY clearing                           | Not run. The xai backend never touches the Gemini environment.                                                                                                                                                                    |\n| Data-channel event bridge, HITL, room context                      | Unchanged. They work on the LiveKit room and the agent session, not on a model.                                                                                                                                                   |\n| Session events (user transcript, assistant text, turn done, usage) | Unchanged code. Against a stub, OpenAI-style transcript and usage events reach the shapes the agent reads.                                                                                                                        |\n| MCP tool bridge and schema sanitizer                               | Unchanged. The sanitizer produces plain JSON Schema (the OpenAI-style API takes full JSON Schema), and the plugin forwards it as is. Keeping it is the safer choice: it drops $ref and unions that xAI has not been tried with. |\n| Conversation memory (recording and seeding)                        | Recording is shared by both backends.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"How each part of the agent behaves on xai","lvl3":""}},
+{"objectID":"f2c4f00431a110b4ec6b67653e157a21d79cc3d52751253260a13758eec90e66","title":"Still unknown without a real key","url":"/docs/features/livekit-voice-agent#still-unknown-without-a-real-key","content":"Whether xAI accepts the model ids above through the plugin; whether it accepts\nthe input transcription setting; whether it accepts the sanitized tool schemas\nand underscore tool names; the event names and ordering xAI really sends (the\nplugin line pinned here, 1.4.6, predates later xAI-specific handling in newer\nplugin releases); whether the seeded history is accepted; and how interruption,\ntruncation and tool calls behave. A live smoke test with a key supplied by the\nowner is the missing step.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Still unknown without a real key","lvl3":""}},
+{"objectID":"9eb38592a55bd3da33ee8a936b4648d18645a49909579f1fccb19844c8263ac7","title":"Troubleshooting","url":"/docs/features/livekit-voice-agent#troubleshooting","content":"VOICE_REALTIME_BACKEND must be \"gemini\" or \"xai\": fix the value, or unset it\n  for gemini.\nXAI_API_KEY is not set: set it in the worker's environment. The check also\n  rejects a whitespace-only value.\nXAI_REALTIME_BASE_URL must be a ws:// or wss:// URL: use a WebSocket URL,\n  not an https:// one.\nA call that will not start on the xai backend: confirm that VOICE_LIVE_MODEL\n  and VOICE_S2S_VOICE hold xAI values and not leftover Gemini ones, since both\n  variables are shared.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Troubleshooting","lvl3":""}},
 {"objectID":"7ffe7e32a7c2baea6c491d743617448eb70eeb4afe439960050efdc3ead18c48","title":"Implementation Plan","url":"/docs/features/livekit-voice-agent#implementation-plan","content":"The integration is built and validated in phases. Each phase is independently testable.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Implementation Plan","lvl3":""}},
 {"objectID":"d4c9885eea3272e250fa1a0dbc1af9503b1a24f0217a82dd0c30d93bf6c5df31","title":"Phase 0 — Console-mode spike (no infrastructure)","url":"/docs/features/livekit-voice-agent#phase-0-console-mode-spike-no-infrastructure","content":"Build a minimal agent (Silero VAD + Deepgram STT + ElevenLabs TTS + llmNode → neurolink.stream()) and run it in console mode using the host machine's mic/speakers. Validates the NeuroLink brain loop, conversationId history, and a tool call — with no LiveKit server and no browser. Requires only STT/TTS and LLM credentials.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Phase 0 — Console-mode spike (no infrastructure)","lvl3":""}},
 {"objectID":"9dddf98f952af643b5357bdefbcb5554a3ff2d9c33a16b0c432243fd68db5569","title":"Phase 1 — NeuroLink LiveKit module","url":"/docs/features/livekit-voice-agent#phase-1-neurolink-livekit-module","content":"Implement brain.ts, voiceAgent.ts, voiceAgentWorker.ts, tokens.ts, config.ts; add the @juspay/neurolink/livekit export and optional/peer dependencies. The worker factory accepts an external NeuroLink instance so a host application's registered tools are available. Wire abort-on-interrupt. Verify build, type-check, and lint.","hierarchy":{"lvl0":"Features","lvl1":"LiveKit Voice Agent — Real-Time Voice over WebRTC","lvl2":"Phase 1 — NeuroLink LiveKit module","lvl3":""}},
@@ -3984,7 +3995,7 @@
 {"objectID":"2f01481e1bd920ff04b7d26da5bc86efababd09cbd1f763a1f119fb7d1443582","title":"Serverless and short-lived processes","url":"/docs/features/observability#serverless-and-short-lived-processes","content":"Spans are batched. Flush before the process freezes or exits:\n\nOr send each span as it ends:\n\nshutdownOpenTelemetry() is terminal for the process: telemetry cannot restart afterwards. While other NeuroLink instances are still alive it only flushes.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Serverless and short-lived processes","lvl3":""}},
 {"objectID":"721428a68bdcef28a5437443fe5a57565c6aa3b324a48ccc39728e5d7ff25e2d","title":"Health","url":"/docs/features/observability#health","content":"isHealthy and hasProcessor are true only while a Langfuse exporter is registered, whether NeuroLink owns the provider or runs beside a host provider. With a host provider, the exporter still needs createExporterSpanProcessor() on that provider to receive spans.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Health","lvl3":""}},
 {"objectID":"68b0ab87bc1ff79e31454e9550e76c174e5a1a4628f3c9de0e74a7dc6e07bdd2","title":"Proxy","url":"/docs/features/observability#proxy","content":"The proxy records the pool account label (not an email address), sets userId and sessionId from x-neurolink-user-id and x-neurolink-session-id, names traces proxy:<model>, and records request and response bodies, usage, cost and time to first token. See the Telemetry Guide and Claude Proxy Observability.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Proxy","lvl3":""}},
-{"objectID":"818b18185bdd4b8b7003f170da3113452c78895619ec762279322c8b2b587801","title":"Voice (LiveKit)","url":"/docs/features/observability#voice-livekit","content":"Pipeline mode traces through stream() and carries the voice tag. Realtime mode records one trace per conversation turn, with transcripts as input and output and tool calls as tool records, and only when voice memory is enabled. Full transcripts are sent to Langfuse by default; use mask for sensitive data.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Voice (LiveKit)","lvl3":""}},
+{"objectID":"818b18185bdd4b8b7003f170da3113452c78895619ec762279322c8b2b587801","title":"Voice (LiveKit)","url":"/docs/features/observability#voice-livekit","content":"Pipeline mode traces through stream() and carries the voice tag. Realtime mode records one trace per conversation turn, with transcripts as input and output and tool calls as tool records, and only when voice memory is enabled. The realtime generation record carries the model id and the provider of the realtime backend (vertex for Gemini Live, xai for Grok Voice). Full transcripts are sent to Langfuse by default; use mask for sensitive data.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Voice (LiveKit)","lvl3":""}},
 {"objectID":"6ddae5fd4f96e8c2a1c9d924054685440eb46353183984ff0b8d3167e12071b8","title":"Troubleshooting","url":"/docs/features/observability#troubleshooting","content":"| Symptom                           | Check                                                                                                                                                                                                                              |\n| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Nothing reaches Langfuse          | Both keys set and langfuse not false; getLangfuseHealthStatus(); call flushOpenTelemetry() on exit                                                                                                                         |\n| Spans missing with own OTEL setup | Add createExporterSpanProcessor() to your provider and pass the Langfuse keys to NeuroLink (or set LANGFUSE_*), or use new LangfuseSpanProcessor() with its own keys; register the processor before the first NeuroLink call |\n| Wrong host                        | Variable is LANGFUSE_BASE_URL, not LANGFUSE_BASEURL                                                                                                                                                                            |\n| Traces stop after shutdown        | shutdownOpenTelemetry() cannot be undone in the same process; use flushOpenTelemetry()                                                                                                                                         |","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Troubleshooting","lvl3":""}},
 {"objectID":"c26071897c848ba9cf00651234ebd459171008740460f6075451e866420e5881","title":"Migrating from the previous version","url":"/docs/features/observability#migrating-from-the-previous-version","content":"This release is breaking.","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Migrating from the previous version","lvl3":""}},
 {"objectID":"310e635468902de6eca8789d9ce5905c4ecb08a665b802119f33a6ae78a6f429","title":"Configuration fields","url":"/docs/features/observability#configuration-fields","content":"| Removed                                                       | Replacement                                                             |\n| ------------------------------------------------------------- | ----------------------------------------------------------------------- |\n| langfuse.enabled                                            | Set the keys to enable; langfuse: false disables                      |\n| langfuse.userId, langfuse.sessionId                       | Per-call context.userId, context.sessionId, or setLangfuseContext |\n| useExternalTracerProvider, autoDetectExternalProvider     | Automatic: a registered global provider is detected                     |\n| skipLangfuseSpanProcessor                                   | Register your own provider; NeuroLink then adds nothing                 |\n| mediaUploadEnabled, LANGFUSE_MEDIA_UPLOAD_ENABLED         | Removed; the exporter does not upload media                             |\n| autoDetectOperationName, operationName, traceNameFormat | context.traceName                                                     |\n| customAttributes                                            | context.metadata                                                      |\n| conversationId, requestId on the config                   | context.conversationId, context.requestId (stored as metadata)      |\n| NEUROLINK_TELEMETRY_ENABLED                                 | Removed; the LANGFUSE_* keys enable tracing                           |\n| LANGFUSE_BASEURL hint                                       | LANGFUSE_BASE_URL                                                     |","hierarchy":{"lvl0":"Features","lvl1":"Observability Guide","lvl2":"Configuration fields","lvl3":""}},
@@ -10555,7 +10566,7 @@
 {"objectID":"ca34f307c204381b1904fe62e5762d2451f439c5f2c8d47083804d9e9ca1f361","title":"Factory Functions","url":"/docs/reference/server-configuration#factory-functions","content":"For quick OpenAPI generation without instantiating the class:","hierarchy":{"lvl0":"Reference","lvl1":"Srvr Cofiguratio Rfrc []","lvl2":"Factory Functions","lvl3":""}},
 {"objectID":"8e5b75ed2dd85636a125c03319a725a2c10669870a925448135351aa81e49df9","title":"All Available Schemas","url":"/docs/reference/server-configuration#all-available-schemas","content":"The OpenAPISchemas registry provides access to all built-in schemas:","hierarchy":{"lvl0":"Reference","lvl1":"Srvr Cofiguratio Rfrc []","lvl2":"All Available Schemas","lvl3":""}},
 {"objectID":"50b633e0ff979961fac99435d14bff5b692d058757f69642edd9efc0db8c050f","title":"Related Documentation","url":"/docs/reference/server-configuration#related-documentation","content":"Server Adapters Overview - Introduction to server adapters\nSecurity Guide - Security best practices\nDeployment Guide - Deployment strategies and configurations","hierarchy":{"lvl0":"Reference","lvl1":"Srvr Cofiguratio Rfrc []","lvl2":"Related Documentation","lvl3":""}},
-{"objectID":"efd7e891fd4b311148a6006fb8a03a36f7702832577266f8e750ec6d79d4dd25","title":"NeuroLink Troubleshooting Guide","url":"/docs/reference/troubleshooting","content":"NeuroLink Troubleshooting Guide\n\nVersion: v9.26.1\nLast Updated: March 2026\n\nOverview\n\nThis guide helps diagnose and resolve common issues with NeuroLink, including AI provider connectivity, MCP integration, CLI usage problems, streaming issues, and the generate function migration.\n\nQuick Diagnostics\n\nBefore diving into specific issues, try these quick diagnostics:\n\nQuick Fixes\n\n| Symptom                                | Resolution                                                                                                                     |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Image not found when using --image | Provide an absolute path or run the command from the directory containing the asset. URLs must be HTTPS.                       |\n| Evaluation model not configured      | Set NEUROLINK_EVALUATION_PROVIDER/NEUROLINK_EVALUATION_MODEL, or disable --enableEvaluation until credentials are added. |\n| Redis connection failed in loop mode | Export REDIS_URL before running neurolink loop or start the session with --no-auto-redis.                                |\n| Model not available in region        | Confirm the model supports the requested region and update AWS_REGION / GOOGLE_VERTEX_LOCATION accordingly.                |\n| CLI exits after error inside loop      | Upgrade to latest @juspay/neurolink and restart the loop; new builds catch errors without exiting.                           |\n\nQ4 2025 Features -- Common Issues\n\nHuman-in-the-Loop (HITL)\n\n| Issue                                   | Solution                                                                                                    |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Tool executes without asking permission | Add requiresConfirmation: true to tool definition. See HITL Guide    |\n| Confirmation dialog doesn't appear      | Handle USER_CONFIRMATION_REQUIRED error in your UI. See HITL Guide |\n| Permission flag not resetting           | Call setUserConfirmation(false) after tool execution. See HITL Guide  |\n\nGuardrails Middleware\n\n| Issue                      | Solution                                                                                                               |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| Content not being filtered | Ensure preset: \"security\" is set in middleware config. See Guardrails Guide |\n| Too many false positives   | Review bad word list, remove common words. See Guardrails Guide            |\n| Model-based filter is slow | Switch to gpt-4o-mini for faster filtering. See Guardrails Guide        |\n\nRedis Conversation Export\n\n| Issue                                        | Solution                                                                                                                                     |\n| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| Export returns empty history                 | Verify Redis connection and session ID exists. See Conversation History Guide         |\n| getConversationHistory returns empty array | Ensure conversationMemory.enabled: true is configured. See Conversation History Guide |\n| Missing metadata in export                   | Set includeMetadata: true in export options. See Conversation History Guide          |\n\nVideo Generation (Veo 3.1)\n\n| Issue                                  | Solution                                                                                                                                                        |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| PROVIDER_NOT_CONFIGURED error        | Set GOOGLE_APPLICATION_CREDENTIALS to your service account JSON path. See Video Generation Guide             |\n| VIDEO_POLL_TIMEOUT after 3 minutes   | Video generation can take 1-2 minutes; increase timeout or check Vertex AI quota. See Video Generation Guide |\n| VIDEO_INVALID_INPUT for image format | Ensure image is PNG, JPEG, or WebP under 20MB; check aspect ratio compatibility. See Video Generation Guide      |\n| Video generation uses wrong provider   | Video gen only supports Vertex AI; provider auto-switches to vertex when output.mode: \"video\"                                                               |\n| Project not found error              | Set GOOGLE_VERTEX_PROJECT or GOOGLE_CLOUD_PROJECT environment variable                                                ","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"","lvl3":""}},
+{"objectID":"efd7e891fd4b311148a6006fb8a03a36f7702832577266f8e750ec6d79d4dd25","title":"NeuroLink Troubleshooting Guide","url":"/docs/reference/troubleshooting","content":"NeuroLink Troubleshooting Guide\n\nVersion: v9.26.1\nLast Updated: March 2026\n\nOverview\n\nThis guide helps diagnose and resolve common issues with NeuroLink, including AI provider connectivity, MCP integration, CLI usage problems, streaming issues, and the generate function migration.\n\nQuick Diagnostics\n\nBefore diving into specific issues, try these quick diagnostics:\n\nQuick Fixes\n\n| Symptom                                | Resolution                                                                                                                     |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Image not found when using --image | Provide an absolute path or run the command from the directory containing the asset. URLs must be HTTPS.                       |\n| Evaluation model not configured      | Set NEUROLINK_EVALUATION_PROVIDER/NEUROLINK_EVALUATION_MODEL, or disable --enableEvaluation until credentials are added. |\n| Redis connection failed in loop mode | Export REDIS_URL before running neurolink loop or start the session with --no-auto-redis.                                |\n| Model not available in region        | Confirm the model supports the requested region and update AWS_REGION / GOOGLE_VERTEX_LOCATION accordingly.                |\n| CLI exits after error inside loop      | Upgrade to latest @juspay/neurolink and restart the loop; new builds catch errors without exiting.                           |\n\nQ4 2025 Features -- Common Issues\n\nHuman-in-the-Loop (HITL)\n\n| Issue                                   | Solution                                                                                                    |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Tool executes without asking permission | Add requiresConfirmation: true to tool definition. See HITL Guide    |\n| Confirmation dialog doesn't appear      | Handle USER_CONFIRMATION_REQUIRED error in your UI. See HITL Guide |\n| Permission flag not resetting           | Call setUserConfirmation(false) after tool execution. See HITL Guide  |\n\nGuardrails Middleware\n\n| Issue                      | Solution                                                                                                                                                                                                            |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Content not being filtered | preset: \"security\" only turns guardrails on; also set badWords (with enabled: true and a list) or modelFilter. See Guardrails Guide |\n| Too many false positives   | Review bad word list, remove common words. See Guardrails Guide                                                                                                         |\n| Model-based filter is slow | Switch to openai:gpt-4o-mini for faster filtering. See Guardrails Guide                                                                                              |\n\nRedis Conversation Export\n\n| Issue                                        | Solution                                                                                                                                     |\n| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| Export returns empty history                 | Verify Redis connection and session ID exists. See Conversation History Guide         |\n| getConversationHistory returns empty array | Ensure conversationMemory.enabled: true is configured. See Conversation History Guide |\n| Missing metadata in export                   | Set includeMetadata: true in export options. See Conversation History Guide          |\n\nVideo Generation (Veo 3.1)\n\n| Issue                                  | Solution                                                                                                                                                        |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| PROVIDER_NOT_CONFIGURED error        | Set GOOGLE_APPLICATION_CREDENTIALS to your service account JSON path. See Video Generation Guide             |\n| VIDEO_POLL_TIMEOUT after 3 minutes   | Video generation can take 1-2 minutes; increase timeout or check Vertex AI quota. See Video Generation Guide |\n| VIDEO_INVALID_INPUT for image format | Ensure image is PNG, JPEG, or WebP under 20MB; ","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"","lvl3":""}},
 {"objectID":"f18cd128c5fcffdd4422033accb929756a0ed04e990d54c0915a2270fc99b7bb","title":"NeuroLink Troubleshooting Guide","url":"/docs/reference/troubleshooting#neurolink-troubleshooting-guide","content":"Version: v9.26.1\nLast Updated: March 2026","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"NeuroLink Troubleshooting Guide","lvl3":""}},
 {"objectID":"16da6024adabd6a43133f9085cea031c955dbe961369e449b1e36739585501f9","title":"Overview","url":"/docs/reference/troubleshooting#overview","content":"This guide helps diagnose and resolve common issues with NeuroLink, including AI provider connectivity, MCP integration, CLI usage problems, streaming issues, and the generate function migration.","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Overview","lvl3":""}},
 {"objectID":"989cb831fb47ad94f3f9469ca199da828c0d637b2acc3d200ffea2a2a3ae563a","title":"Quick Diagnostics","url":"/docs/reference/troubleshooting#quick-diagnostics","content":"Before diving into specific issues, try these quick diagnostics:\n\n`bash","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Quick Diagnostics","lvl3":""}},
@@ -10567,7 +10578,7 @@
 {"objectID":"21f39a157951a67d608fc7cdf36c85389d8ff578c25e8d2293ab7cf5a9942e3b","title":"6. Enable debug logging","url":"/docs/reference/troubleshooting#6-enable-debug-logging","content":"npx @juspay/neurolink generate \"Test\" --debug\n`","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"6. Enable debug logging","lvl3":""}},
 {"objectID":"9875cf71575de93b4835f39b84e856f4a94df8899571e70f3dfc8336d16f69d7","title":"Quick Fixes","url":"/docs/reference/troubleshooting#quick-fixes","content":"| Symptom                                | Resolution                                                                                                                     |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Image not found when using --image | Provide an absolute path or run the command from the directory containing the asset. URLs must be HTTPS.                       |\n| Evaluation model not configured      | Set NEUROLINK_EVALUATION_PROVIDER/NEUROLINK_EVALUATION_MODEL, or disable --enableEvaluation until credentials are added. |\n| Redis connection failed in loop mode | Export REDIS_URL before running neurolink loop or start the session with --no-auto-redis.                                |\n| Model not available in region        | Confirm the model supports the requested region and update AWS_REGION / GOOGLE_VERTEX_LOCATION accordingly.                |\n| CLI exits after error inside loop      | Upgrade to latest @juspay/neurolink and restart the loop; new builds catch errors without exiting.                           |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Quick Fixes","lvl3":""}},
 {"objectID":"519835175f0f4ba411dbe92426eeb603aa23a38ec149913ac19bca7682b3adec","title":"Human-in-the-Loop (HITL)","url":"/docs/reference/troubleshooting#human-in-the-loop-hitl","content":"| Issue                                   | Solution                                                                                                    |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Tool executes without asking permission | Add requiresConfirmation: true to tool definition. See HITL Guide    |\n| Confirmation dialog doesn't appear      | Handle USER_CONFIRMATION_REQUIRED error in your UI. See HITL Guide |\n| Permission flag not resetting           | Call setUserConfirmation(false) after tool execution. See HITL Guide  |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Human-in-the-Loop (HITL)","lvl3":""}},
-{"objectID":"3e08d9134df8755f7ff0cd9382ee0a4151ff1a1ff6c13f60494e8b5206dea416","title":"Guardrails Middleware","url":"/docs/reference/troubleshooting#guardrails-middleware","content":"| Issue                      | Solution                                                                                                               |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| Content not being filtered | Ensure preset: \"security\" is set in middleware config. See Guardrails Guide |\n| Too many false positives   | Review bad word list, remove common words. See Guardrails Guide            |\n| Model-based filter is slow | Switch to gpt-4o-mini for faster filtering. See Guardrails Guide        |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Guardrails Middleware","lvl3":""}},
+{"objectID":"3e08d9134df8755f7ff0cd9382ee0a4151ff1a1ff6c13f60494e8b5206dea416","title":"Guardrails Middleware","url":"/docs/reference/troubleshooting#guardrails-middleware","content":"| Issue                      | Solution                                                                                                                                                                                                            |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Content not being filtered | preset: \"security\" only turns guardrails on; also set badWords (with enabled: true and a list) or modelFilter. See Guardrails Guide |\n| Too many false positives   | Review bad word list, remove common words. See Guardrails Guide                                                                                                         |\n| Model-based filter is slow | Switch to openai:gpt-4o-mini for faster filtering. See Guardrails Guide                                                                                              |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Guardrails Middleware","lvl3":""}},
 {"objectID":"13407b41e672f252dd093443b23887d95a5d464a743ab992713dc63bbcf42cc2","title":"Redis Conversation Export","url":"/docs/reference/troubleshooting#redis-conversation-export","content":"| Issue                                        | Solution                                                                                                                                     |\n| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| Export returns empty history                 | Verify Redis connection and session ID exists. See Conversation History Guide         |\n| getConversationHistory returns empty array | Ensure conversationMemory.enabled: true is configured. See Conversation History Guide |\n| Missing metadata in export                   | Set includeMetadata: true in export options. See Conversation History Guide          |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Redis Conversation Export","lvl3":""}},
 {"objectID":"6cf2bc5f5079c8e4490e3d9a2b8d687e06ef94abedb94924e0e92788ed85256a","title":"Video Generation (Veo 3.1)","url":"/docs/reference/troubleshooting#video-generation-veo-31","content":"| Issue                                  | Solution                                                                                                                                                        |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| PROVIDER_NOT_CONFIGURED error        | Set GOOGLE_APPLICATION_CREDENTIALS to your service account JSON path. See Video Generation Guide             |\n| VIDEO_POLL_TIMEOUT after 3 minutes   | Video generation can take 1-2 minutes; increase timeout or check Vertex AI quota. See Video Generation Guide |\n| VIDEO_INVALID_INPUT for image format | Ensure image is PNG, JPEG, or WebP under 20MB; check aspect ratio compatibility. See Video Generation Guide      |\n| Video generation uses wrong provider   | Video gen only supports Vertex AI; provider auto-switches to vertex when output.mode: \"video\"                                                               |\n| Project not found error              | Set GOOGLE_VERTEX_PROJECT or GOOGLE_CLOUD_PROJECT environment variable                                                                                      |\n| Audio missing from generated video     | Set output.video.audio: true (enabled by default) and ensure Veo 3.1 model is used                                                                            |","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"Video Generation (Veo 3.1)","lvl3":""}},
 {"objectID":"a92a4e02183ff63c57c4e6477e15e48f9bc4b2ae17fd61849e537bd592dad0d9","title":"PPT Generation (PowerPoint Presentations)","url":"/docs/reference/troubleshooting#ppt-generation-powerpoint-presentations","content":"PPT_PLANNING_FAILED -- Check AI provider connection and ensure valid prompt. See PPT Generation Guide\nPPT_INVALID_AI_RESPONSE during generation -- Simplify prompt/topic and retry. See PPT Generation Guide\nPPT_FILE_WRITE_FAILED -- Check write permissions for output directory and disk space. See PPT Generation Guide\nEmpty slides in presentation -- Ensure content plan has enough detail; try more specific prompts\nImages not generating -- Set generateAIImages: true in output.ppt (SDK) or avoid --pptNoImages (CLI), and configure VERTEX_IMAGE_MODEL. See PPT Generation Guide\nTheme not applying correctly -- Verify theme name: modern, corporate, creative, minimal, or dark","hierarchy":{"lvl0":"Reference","lvl1":"NeuroLink Troubleshooting Guide","lvl2":"PPT Generation (PowerPoint Presentations)","lvl3":""}},
@@ -11033,7 +11044,7 @@
 {"objectID":"357bbb718f458d764e00524826a1d42a64da83167df93a52c04d9ddec3651764","title":"Core Events","url":"/docs/sdk/api-reference#core-events","content":"| Event              | Emitted When                         |\n| ------------------ | ------------------------------------ |\n| generation:start | A generate() call begins           |\n| generation:end   | A generate() call completes        |\n| stream:start     | A stream() call begins             |\n| stream:chunk     | A new chunk arrives during streaming |\n| stream:end       | Streaming completes normally         |\n| stream:complete  | Stream fully consumed                |\n| stream:error     | An error occurs during streaming     |\n| tool:start       | A tool execution begins              |\n| tool:end         | A tool execution completes           |\n| response:start   | A provider response begins           |\n| response:end     | A provider response completes        |","hierarchy":{"lvl0":"Sdk","lvl1":"API Reference","lvl2":"Core Events","lvl3":""}},
 {"objectID":"efcf19aa651c13dbc72ef4b3d0f83986ee180008a076c0db030509880e4d4b1a","title":"MCP Server Events","url":"/docs/sdk/api-reference#mcp-server-events","content":"| Event                            | Emitted When                              |\n| -------------------------------- | ----------------------------------------- |\n| externalMCP:serverConnected    | An external MCP server connects           |\n| externalMCP:serverDisconnected | An external MCP server disconnects        |\n| externalMCP:serverFailed       | An external MCP server connection fails   |\n| externalMCP:toolDiscovered     | A new tool is discovered on an MCP server |\n| externalMCP:toolRemoved        | A tool is removed from an MCP server      |\n| externalMCP:serverAdded        | A new MCP server registration is added    |\n| externalMCP:serverRemoved      | An MCP server registration is removed     |","hierarchy":{"lvl0":"Sdk","lvl1":"API Reference","lvl2":"MCP Server Events","lvl3":""}},
 {"objectID":"c4d157804d0d96f1d8571e6aabeff4305aca0c07c151894dee3804d611331de6","title":"Other Events","url":"/docs/sdk/api-reference#other-events","content":"| Event                  | Emitted When                        |\n| ---------------------- | ----------------------------------- |\n| tools-register:start | Tool registration process begins    |\n| tools-register:end   | Tool registration process completes |\n| connected            | Connection established              |\n| message              | General message event               |\n| error                | An error occurs                     |\n| log                  | A log message is emitted            |\n| log-event            | A structured log event is emitted   |\n\nTypedEventEmitter Interface:","hierarchy":{"lvl0":"Sdk","lvl1":"API Reference","lvl2":"Other Events","lvl3":""}},
-{"objectID":"7ff1b31f163c4928ce88a79da3c279d1c1c6351ccf3cc5ad2464d2a03174f308","title":"Related Features","url":"/docs/sdk/api-reference#related-features","content":"Human-in-the-Loop (HITL) - Mark tools with requiresConfirmation: true\nGuardrails Middleware - Enable with middleware: { preset: 'security' }\nConversation History - Use getConversationHistory() method\nMultimodal Chat - Use images array in generate() options\nAuto Evaluation - Enable with enableEvaluation: true\nCLI Loop Sessions - Interactive mode with persistent state\nProvider Orchestration - Set enableOrchestration: true\nRegional Streaming - Use region parameter in generate()\nOffice Documents - Use officeFiles array for DOCX, PPTX, XLSX\nPDF Support - Use pdfFiles array for PDF documents\nCSV Support - Use csvFiles array for spreadsheet data\nCLI Commands Reference - CLI equivalents for all SDK methods\nConfiguration Guide - Environment variables and config files\nTroubleshooting - Common SDK issues and solutions\n\nBack to Main README | Next: Visual Demos","hierarchy":{"lvl0":"Sdk","lvl1":"API Reference","lvl2":"Related Features","lvl3":""}},
+{"objectID":"7ff1b31f163c4928ce88a79da3c279d1c1c6351ccf3cc5ad2464d2a03174f308","title":"Related Features","url":"/docs/sdk/api-reference#related-features","content":"Human-in-the-Loop (HITL) - Mark tools with requiresConfirmation: true\nGuardrails Middleware - Set middleware per call, in new NeuroLink({ middleware }) or with configureGlobalMiddleware(); add badWords or modelFilter to filter\nConversation History - Use getConversationHistory() method\nMultimodal Chat - Use images array in generate() options\nAuto Evaluation - Enable with enableEvaluation: true\nCLI Loop Sessions - Interactive mode with persistent state\nProvider Orchestration - Set enableOrchestration: true\nRegional Streaming - Use region parameter in generate()\nOffice Documents - Use officeFiles array for DOCX, PPTX, XLSX\nPDF Support - Use pdfFiles array for PDF documents\nCSV Support - Use csvFiles array for spreadsheet data\nCLI Commands Reference - CLI equivalents for all SDK methods\nConfiguration Guide - Environment variables and config files\nTroubleshooting - Common SDK issues and solutions\n\nBack to Main README | Next: Visual Demos","hierarchy":{"lvl0":"Sdk","lvl1":"API Reference","lvl2":"Related Features","lvl3":""}},
 {"objectID":"72ff7213f71cd3e590c196c5a1a39a7ab2af152776936e1a647f228cae34de6e","title":"🔧 SDK Custom Tools Guide","url":"/docs/sdk/custom-tools-guide","content":"🔧 SDK Custom Tools Guide\n\nBuild powerful AI applications by extending NeuroLink with your own custom tools.\n\n📋 Overview\n\nNeuroLink's SDK allows you to register custom tools programmatically, giving your AI assistants access to any functionality you need. All registered tools work seamlessly with the built-in tool system across all supported providers.\n\nKey Features\n✅ Type-Safe: Full TypeScript support with Zod schema validation\n✅ Provider Agnostic: Works with all providers that support tools\n✅ Easy Integration: Simple API for tool registration\n✅ Async Support: All tools run asynchronously\n✅ Error Handling: Graceful error handling built-in\n\n🚀 Quick Start\n\nBasic Tool Registration\n\n⚠️ Common Mistakes\n\n❌ Using schema instead of parameters\n\n❌ Using plain JSON schema as parameters\n\n✅ Correct Zod Schema Format\n\n📖 SimpleTool Interface\n\nAll custom tools implement the SimpleTool interface:\n\nInterface Components\ndescription: Clear, actionable description that helps the AI understand when to use the tool\nparameters: Optional Zod schema for validating inputs (highly recommended)\nexecute: Async function that implements the tool's logic\n\n🛠️ Registration Methods\n\nRegister Single Tool\n\nRegister Multiple Tools\n\nGet Custom Tools\n\n💡 Common Use Cases\nAPI Integration\nDatabase Operations\nData Processing\nFile Operations\nExternal Service Integration\n\n🎯 Best Practices\nClear Descriptions\n\nMake tool descriptions specific and actionable:\nParameter Validation\n\nAlways use Zod schemas for type safety:\nError Handling\n\nHandle errors gracefully:\n\nA returned error is classified as a failure everywhere the SDK reports one,\nexactly as a thrown error is. A result is error-shaped when it carries\nisError: true (the MCP convention), a non-null error field ({ error:\n\"User not found\" }), or a status of \"error\" / \"failed\" / \"failure\" /\n\"fail\". Such a call emits tool:end with success: false and the error\ntext, is stored in session memory as success: false, replays on later turns\nas [called <tool> → error], and is reported with isError: true in\nresult.toolExecutions. The model still receives the full object you\nreturned — classification only affects telemetry and memory, never what the\nmodel sees.\nAsync Operations\n\nAll execute functions must return promises:\nTool Naming\n\nUse clear, consistent naming:\n\n🧪 Testing Your Tools\n\nUnit Testing\n\nIntegration Testing\n\n🔍 Debugging Tools\n\nEnable Debug Mode\n\nLog Tool Execution\n\n🚀 Advanced Patterns\n\nTool Composition\n\nTool Middleware\n\nDynamic Tool Registration\n\nForcing a Tool Call\n\ntoolChoice tells the model whether it must call a tool on a step:\n\n| Value                             | Effect                                           |\n| --------------------------------- | ------------------------------------------------ |\n| \"auto\" (default)                | The model decides whether and which tool to call |\n| \"none\"                          | No tool calls on any step                        |\n| \"required\"                      | The model must call at least one tool            |\n| { type: \"tool\", toolName: \"x\" } | The model must call the named tool               |\n\nA forced choice (\"required\" or a named tool) is applied only to the first\ntoolChoiceSteps steps of the tool loop — default 1 — after which the\nmodel is free to answer. Holding a forced choice on every step would compel\na tool call on every step, and the turn could only end when maxSteps ran\nout. \"auto\" and \"none\" are applied unchanged on every step.\n\nFor anything finer, prepareStep runs before every step and may return a\ntoolChoice for that step, which takes precedence over toolChoiceSteps:\n\nprepareStep receives { stepNumber, steps, maxSteps, model }, where steps\nholds one record per completed step (its text, tool calls — with input\nalready parsed into an object — tool results, finish reason and usage,\nincluding prompt-cache tokens where the provider reports them). Only the\nreturned toolChoice is honoured; the legacy model and\nexperimental_activeTools / activeTools fields are accepted for source\ncompatibility but ignored, and their presence is logged once as a warning —\nuse toolFilter / excludeTools to scope tools. A hook that throws is\nlogged and that step falls back to the toolChoice / toolChoiceSteps rule;\na hook still pending when the turn is aborted or times out is released with\nthe abort. Both toolChoice and prepareStep apply to stream() as well.\n\nVertex, Google AI Studio and Bedrock do not honour toolChoice at all today.\nSageMaker honours tools, toolChoice and prepareStep on generate()\nonly: its stream() sends the prompt without tools.\n\n📊 Performance Considerations\nTimeout Handling\nCaching\nBatch Operations\n\n🔒 Security Considerations\n\nInput Sanitization\n\nPermission Checking\n\nRate Limiting\n\n🎉 Complete Example\n\nHere's a complete example combining multiple concepts:\n\n🌐 MCP Server Integration\n\nBeyond simple tool registration, NeuroLink SDK supports adding complete MCP (Model Context Protocol) servers for more complex tool ecosystems.\n\nAdding I","hierarchy":{"lvl0":"Sdk","lvl1":"🔧 SDK Custom Tools Guide","lvl2":"","lvl3":""}},
 {"objectID":"fe570104af53b04cac97749a24ce61018428abe7df180a14a7285ebf6fda6fca","title":"🔧 SDK Custom Tools Guide","url":"/docs/sdk/custom-tools-guide#-sdk-custom-tools-guide","content":"Build powerful AI applications by extending NeuroLink with your own custom tools.","hierarchy":{"lvl0":"Sdk","lvl1":"🔧 SDK Custom Tools Guide","lvl2":"🔧 SDK Custom Tools Guide","lvl3":""}},
 {"objectID":"4c744b8358a0761297815b9e1244bad43bebb4ece00ddac4cb24b186dbae5647","title":"📋 Overview","url":"/docs/sdk/custom-tools-guide#-overview","content":"NeuroLink's SDK allows you to register custom tools programmatically, giving your AI assistants access to any functionality you need. All registered tools work seamlessly with the built-in tool system across all supported providers.","hierarchy":{"lvl0":"Sdk","lvl1":"🔧 SDK Custom Tools Guide","lvl2":"📋 Overview","lvl3":""}},