Understanding the Translation Compatibility Setting in WorkWeave Router: Three Modes Explained

WorkWeave Router provides three translation compatibility modes—Off, Shadow, and Enforce—that control whether and how the router applies compatibility constraints between upstream AI providers and its internal model catalog.

The translation compatibility setting in WorkWeave Router determines how strictly the system enforces compatibility matrices when translating requests between different AI provider APIs. Defined by the TranslationCompatibilityMode type in internal/proxy/translation_plan.go, this setting allows operators to balance experimental flexibility against production safety when routing AI workloads.

The Three Translation Compatibility Modes

WorkWeave Router supports three distinct operating modes for translation compatibility, each suited to different deployment scenarios.

Off Mode

Off mode (off) completely disables compatibility filtering. When this mode is active, the router attempts to translate requests without applying any compatibility matrix constraints between the upstream provider and the target model.

This mode is ideal for full-feature experimentation where you want the router to ignore compatibility rules and attempt translation regardless of provider-model mismatches. However, it provides no safety guarantees against incompatible API feature combinations.

Shadow Mode

Shadow mode (shadow) evaluates compatibility filters without failing requests. When incompatibilities are detected, the router logs the issue (typically at debug level) but continues processing the request normally.

This mode lets you monitor compatibility issues in production environments without impacting request success rates. It serves as a "dry run" for compatibility enforcement, allowing operators to identify problematic request patterns before enabling strict validation.

Enforce Mode

Enforce mode (enforce) strictly applies compatibility constraints. If a request does not satisfy the compatibility matrix defined in the router's model catalog, the router returns a 400-level error response and rejects the translation.

This is the recommended setting for production environments where you want to guarantee that only compatible routes are used, preventing runtime errors downstream in the provider API.

Configuring the Translation Compatibility Setting

The translation compatibility setting is injected at startup through the proxy service configuration and remains constant for the process lifetime.

Service Initialization

Configure the mode using the WithTranslationCompatibilityMode option when constructing the proxy service in internal/proxy/service.go:

proxySvc := proxy.NewService().
    WithTranslationCompatibilityMode(proxy.TranslationCompatibilityEnforce)

Environment Variable Configuration

The router typically reads the mode from environment variables during boot in cmd/router/main.go. Parse the string value and convert it to the appropriate enum type:

modeStr := config.GetOr("TRANSLATION_COMPATIBILITY_MODE", "off")
mode := proxy.TranslationCompatibilityMode(modeStr)
proxySvc := proxy.NewService().WithTranslationCompatibilityMode(mode)

Valid string values are "off", "shadow", and "enforce". The router validates and logs the chosen mode at startup.

Runtime Request Handling

Inside request-handling functions, the router checks the configured mode when building a TranslationPlan. The following pattern from internal/proxy/translation_plan.go demonstrates how each mode affects request processing:

func (s *Service) applyTranslationPlan(ctx context.Context, req router.Request) (router.Request, error) {
    // ... other logic ...

    switch s.translationCompatibilityMode {
    case proxy.TranslationCompatibilityEnforce:
        // Fail fast on incompatibility
        if incompatibilityDetected {
            return req, errors.New("incompatible request")
        }
    case proxy.TranslationCompatibilityShadow:
        // Log but continue
        if incompatibilityDetected {
            logger.Debug("compatibility issue (shadow mode)", "req", req.ID)
        }
    case proxy.TranslationCompatibilityOff:
        // No compatibility checks
    }
    // ... continue processing ...
}

Source Code Implementation

According to the WorkWeave Router source code, three key files implement the translation compatibility setting:

• internal/proxy/translation_plan.go – Defines the TranslationCompatibilityMode enum and contains the compatibility matrix evaluation logic.
• internal/proxy/service.go – Provides the WithTranslationCompatibilityMode configuration method for the proxy service builder.
• cmd/router/main.go – Parses the mode from configuration at startup, validates the input, and logs the active setting during boot.

Summary

• Translation compatibility settings control how WorkWeave Router handles mismatches between provider capabilities and model requirements.
• Off mode disables all compatibility checks for unrestricted experimentation.
• Shadow mode logs incompatibilities without failing requests, enabling safe monitoring in production.
• Enforce mode strictly validates compatibility, returning 400-level errors for incompatible requests.
• The setting is configured at startup via WithTranslationCompatibilityMode and cannot be changed without restarting the router.

Frequently Asked Questions

What happens if I set the translation compatibility mode to Off?

The router will attempt to translate all requests without checking whether the upstream provider supports the requested features for the target model. This bypasses the compatibility matrix entirely, which may lead to runtime API errors if the provider does not support specific parameters or capabilities.

How does Shadow mode differ from Enforce mode?

Shadow mode evaluates compatibility constraints but only logs violations without affecting the request outcome, while Enforce mode immediately rejects requests that violate compatibility constraints with a 400-level error. Shadow mode is used for monitoring and gradual rollout, whereas Enforce mode provides strict production safety.

Where is the translation compatibility mode configured in WorkWeave Router?

The mode is configured in cmd/router/main.go during application startup, where it is parsed from environment variables or configuration files. It is then passed to the proxy service constructor in internal/proxy/service.go using the WithTranslationCompatibilityMode method.

Can I change the translation compatibility mode without restarting the router?

No. The translation compatibility setting is injected at startup and stored as a static field in the proxy service structure. Changing the mode requires updating the configuration and restarting the router process, as the setting is read once during initialization in cmd/router/main.go and remains immutable for the process lifetime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}