Merge pull request #390 from NguyenSiTrung/main

feat(amp): add model mapping support for routing unavailable models to alternatives

Author: luispater

README.md

@@ -56,6 +56,7 @@ CLIProxyAPI includes integrated support for [Amp CLI](https://ampcode.com) and A
 - Provider route aliases for Amp's API patterns (`/api/provider/{provider}/v1...`)
 - Management proxy for OAuth authentication and account features
 - Smart model fallback with automatic routing
+- **Model mapping** to route unavailable models to alternatives (e.g., `claude-opus-4.5` → `claude-sonnet-4`)
 - Security-first design with localhost-only management endpoints
 
 **→ [Complete Amp CLI Integration Guide](docs/amp-cli-integration.md)**

config.example.yaml

@@ -55,6 +55,28 @@ quota-exceeded:
 # When true, enable authentication for the WebSocket API (/v1/ws).
 ws-auth: false
 
+# Amp CLI Integration
+# Configure upstream URL for Amp CLI OAuth and management features
+#amp-upstream-url: "https://ampcode.com"
+
+# Optional: Override API key for Amp upstream (otherwise uses env or file)
+#amp-upstream-api-key: ""
+
+# Restrict Amp management routes (/api/auth, /api/user, etc.) to localhost only (recommended)
+#amp-restrict-management-to-localhost: true
+
+# Amp Model Mappings
+# Route unavailable Amp models to alternative models available in your local proxy.
+# Useful when Amp CLI requests models you don't have access to (e.g., Claude Opus 4.5)
+# but you have a similar model available (e.g., Claude Sonnet 4).
+#amp-model-mappings:
+#  - from: "claude-opus-4.5"       # Model requested by Amp CLI
+#    to: "claude-sonnet-4"         # Route to this available model instead
+#  - from: "gpt-5"
+#    to: "gemini-2.5-pro"
+#  - from: "claude-3-opus-20240229"
+#    to: "claude-3-5-sonnet-20241022"
+
 # Gemini API keys (preferred)
 #gemini-api-key:
 #  - api-key: "AIzaSy...01"

docs/amp-cli-integration.md

@@ -8,6 +8,7 @@ This guide explains how to use CLIProxyAPI with Amp CLI and Amp IDE extensions,
   - [Which Providers Should You Authenticate?](#which-providers-should-you-authenticate)
 - [Architecture](#architecture)
 - [Configuration](#configuration)
+  - [Model Mapping Configuration](#model-mapping-configuration)
 - [Setup](#setup)
 - [Usage](#usage)
 - [Troubleshooting](#troubleshooting)
@@ -21,6 +22,7 @@ The Amp CLI integration adds specialized routing to support Amp's API patterns w
 - **Provider route aliases**: Maps Amp's `/api/provider/{provider}/v1...` patterns to CLIProxyAPI handlers
 - **Management proxy**: Forwards OAuth and account management requests to Amp's control plane
 - **Smart fallback**: Automatically routes unconfigured models to ampcode.com
+- **Model mapping**: Route unavailable models to alternatives you have access to (e.g., `claude-opus-4.5` → `claude-sonnet-4`)
 - **Secret management**: Configurable precedence (config > env > file) with 5-minute caching
 - **Security-first**: Management routes restricted to localhost by default
 - **Automatic gzip handling**: Decompresses responses from Amp upstream
@@ -75,7 +77,10 @@ Amp CLI/IDE
   │   ↓
   │   ├─ Model configured locally?
   │   │   YES → Use local OAuth tokens (OpenAI/Claude/Gemini handlers)
-  │   │   NO  → Forward to ampcode.com (reverse proxy)
+  │   │   NO  ↓
+  │   │       ├─ Model mapping configured?
+  │   │       │   YES → Rewrite model → Use local handler (free)
+  │   │       │   NO  → Forward to ampcode.com (uses Amp credits)
   │   ↓
   │   Response
   │
@@ -115,6 +120,49 @@ amp-upstream-url: "https://ampcode.com"
 amp-restrict-management-to-localhost: true
 ```
 
+### Model Mapping Configuration
+
+When Amp CLI requests a model that you don't have access to, you can configure mappings to route those requests to alternative models that you DO have available. This avoids consuming Amp credits for models you could handle locally.
+
+```yaml
+# Route unavailable models to alternatives
+amp-model-mappings:
+  # Example: Route Claude Opus 4.5 requests to Claude Sonnet 4
+  - from: "claude-opus-4.5"
+    to: "claude-sonnet-4"
+  
+  # Example: Route GPT-5 requests to Gemini 2.5 Pro
+  - from: "gpt-5"
+    to: "gemini-2.5-pro"
+  
+  # Example: Map older model names to newer versions
+  - from: "claude-3-opus-20240229"
+    to: "claude-3-5-sonnet-20241022"
+```
+
+**How it works:**
+
+1. Amp CLI requests a model (e.g., `claude-opus-4.5`)
+2. CLIProxyAPI checks if a local provider is available for that model
+3. If not available, it checks the model mappings
+4. If a mapping exists, the request is rewritten to use the target model
+5. The request is then handled locally (free, using your OAuth subscription)
+
+**Benefits:**
+- **Save Amp credits**: Use your local subscriptions instead of forwarding to ampcode.com
+- **Hot-reload**: Mappings can be updated without restarting the proxy
+- **Structured logging**: Clear logs show when mappings are applied
+
+**Routing Decision Logs:**
+
+The proxy logs each routing decision with structured fields:
+
+```
+[AMP] Using local provider for model: gemini-2.5-pro          # Local provider (free)
+[AMP] Model mapped: claude-opus-4.5 -> claude-sonnet-4        # Mapping applied (free)
+[AMP] Forwarding to ampcode.com (uses Amp credits) - model_id: gpt-5  # Fallback (costs credits)
+```
+
 ### Secret Resolution Precedence
 
 The Amp module resolves API keys using this precedence order:
@@ -301,11 +349,14 @@ When Amp requests a model:
 
 1. **Check local configuration**: Does CLIProxyAPI have OAuth tokens for this model's provider?
 2. **If YES**: Route to local handler (use your OAuth subscription)
-3. **If NO**: Forward to ampcode.com (use Amp's default routing)
+3. **If NO**: Check if a model mapping exists
+4. **If mapping exists**: Rewrite request to mapped model → Route to local handler (free)
+5. **If no mapping**: Forward to ampcode.com (uses Amp credits)
 
 This enables seamless mixed usage:
 - Models you've configured (Gemini, ChatGPT, Claude) → Your OAuth subscriptions
-- Models you haven't configured → Amp's default providers
+- Models with mappings configured → Routed to alternative local models (free)
+- Models you haven't configured and have no mapping → Amp's default providers (uses credits)
 
 ### Example API Calls
 

internal/api/modules/amp/amp.go

@@ -23,11 +23,13 @@ type Option func(*AmpModule)
 //   - Reverse proxy to Amp control plane for OAuth/management
 //   - Provider-specific route aliases (/api/provider/{provider}/...)
 //   - Automatic gzip decompression for misconfigured upstreams
+//   - Model mapping for routing unavailable models to alternatives
 type AmpModule struct {
 	secretSource    SecretSource
 	proxy           *httputil.ReverseProxy
 	accessManager   *sdkaccess.Manager
 	authMiddleware_ gin.HandlerFunc
+	modelMapper     *DefaultModelMapper
 	enabled         bool
 	registerOnce    sync.Once
 }
@@ -101,6 +103,9 @@ func (m *AmpModule) Register(ctx modules.Context) error {
 	// Use registerOnce to ensure routes are only registered once
 	var regErr error
 	m.registerOnce.Do(func() {
+		// Initialize model mapper from config (for routing unavailable models to alternatives)
+		m.modelMapper = NewModelMapper(ctx.Config.AmpModelMappings)
+
 		// Always register provider aliases - these work without an upstream
 		m.registerProviderAliases(ctx.Engine, ctx.BaseHandler, auth)
 
@@ -159,8 +164,16 @@ func (m *AmpModule) getAuthMiddleware(ctx modules.Context) gin.HandlerFunc {
 // OnConfigUpdated handles configuration updates.
 // Currently requires restart for URL changes (could be enhanced for dynamic updates).
 func (m *AmpModule) OnConfigUpdated(cfg *config.Config) error {
+	// Update model mappings (hot-reload supported)
+	if m.modelMapper != nil {
+		log.Infof("amp config updated: reloading %d model mapping(s)", len(cfg.AmpModelMappings))
+		m.modelMapper.UpdateMappings(cfg.AmpModelMappings)
+	} else {
+		log.Warnf("amp model mapper not initialized, skipping model mapping update")
+	}
+
 	if !m.enabled {
-		log.Debug("Amp routing not enabled, skipping config update")
+		log.Debug("Amp routing not enabled, skipping other config updates")
 		return nil
 	}
 
@@ -181,3 +194,8 @@ func (m *AmpModule) OnConfigUpdated(cfg *config.Config) error {
 	log.Debug("Amp config updated (restart required for URL changes)")
 	return nil
 }
+
+// GetModelMapper returns the model mapper instance (for testing/debugging).
+func (m *AmpModule) GetModelMapper() *DefaultModelMapper {
+	return m.modelMapper
+}

internal/api/modules/amp/fallback_handlers.go

@@ -6,16 +6,75 @@ import (
 	"io"
 	"net/http/httputil"
 	"strings"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/util"
 	log "github.com/sirupsen/logrus"
 )
 
+// AmpRouteType represents the type of routing decision made for an Amp request
+type AmpRouteType string
+
+const (
+	// RouteTypeLocalProvider indicates the request is handled by a local OAuth provider (free)
+	RouteTypeLocalProvider AmpRouteType = "LOCAL_PROVIDER"
+	// RouteTypeModelMapping indicates the request was remapped to another available model (free)
+	RouteTypeModelMapping AmpRouteType = "MODEL_MAPPING"
+	// RouteTypeAmpCredits indicates the request is forwarded to ampcode.com (uses Amp credits)
+	RouteTypeAmpCredits AmpRouteType = "AMP_CREDITS"
+	// RouteTypeNoProvider indicates no provider or fallback available
+	RouteTypeNoProvider AmpRouteType = "NO_PROVIDER"
+)
+
+// logAmpRouting logs the routing decision for an Amp request with structured fields
+func logAmpRouting(routeType AmpRouteType, requestedModel, resolvedModel, provider, path string) {
+	fields := log.Fields{
+		"component":       "amp-routing",
+		"route_type":      string(routeType),
+		"requested_model": requestedModel,
+		"path":            path,
+		"timestamp":       time.Now().Format(time.RFC3339),
+	}
+
+	if resolvedModel != "" && resolvedModel != requestedModel {
+		fields["resolved_model"] = resolvedModel
+	}
+	if provider != "" {
+		fields["provider"] = provider
+	}
+
+	switch routeType {
+	case RouteTypeLocalProvider:
+		fields["cost"] = "free"
+		fields["source"] = "local_oauth"
+		log.WithFields(fields).Infof("[AMP] Using local provider for model: %s", requestedModel)
+
+	case RouteTypeModelMapping:
+		fields["cost"] = "free"
+		fields["source"] = "local_oauth"
+		fields["mapping"] = requestedModel + " -> " + resolvedModel
+		log.WithFields(fields).Infof("[AMP] Model mapped: %s -> %s", requestedModel, resolvedModel)
+
+	case RouteTypeAmpCredits:
+		fields["cost"] = "amp_credits"
+		fields["source"] = "ampcode.com"
+		fields["model_id"] = requestedModel // Explicit model_id for easy config reference
+		log.WithFields(fields).Warnf("[AMP] Forwarding to ampcode.com (uses Amp credits) - model_id: %s | To use local proxy, add to config: amp-model-mappings: [{from: \"%s\", to: \"<your-local-model>\"}]", requestedModel, requestedModel)
+
+	case RouteTypeNoProvider:
+		fields["cost"] = "none"
+		fields["source"] = "error"
+		fields["model_id"] = requestedModel // Explicit model_id for easy config reference
+		log.WithFields(fields).Warnf("[AMP] No provider available for model_id: %s", requestedModel)
+	}
+}
+
 // FallbackHandler wraps a standard handler with fallback logic to ampcode.com
 // when the model's provider is not available in CLIProxyAPI
 type FallbackHandler struct {
-	getProxy func() *httputil.ReverseProxy
+	getProxy    func() *httputil.ReverseProxy
+	modelMapper ModelMapper
 }
 
 // NewFallbackHandler creates a new fallback handler wrapper
@@ -26,10 +85,25 @@ func NewFallbackHandler(getProxy func() *httputil.ReverseProxy) *FallbackHandler
 	}
 }
 
+// NewFallbackHandlerWithMapper creates a new fallback handler with model mapping support
+func NewFallbackHandlerWithMapper(getProxy func() *httputil.ReverseProxy, mapper ModelMapper) *FallbackHandler {
+	return &FallbackHandler{
+		getProxy:    getProxy,
+		modelMapper: mapper,
+	}
+}
+
+// SetModelMapper sets the model mapper for this handler (allows late binding)
+func (fh *FallbackHandler) SetModelMapper(mapper ModelMapper) {
+	fh.modelMapper = mapper
+}
+
 // WrapHandler wraps a gin.HandlerFunc with fallback logic
 // If the model's provider is not configured in CLIProxyAPI, it forwards to ampcode.com
 func (fh *FallbackHandler) WrapHandler(handler gin.HandlerFunc) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		requestPath := c.Request.URL.Path
+
 		// Read the request body to extract the model name
 		bodyBytes, err := io.ReadAll(c.Request.Body)
 		if err != nil {
@@ -55,12 +129,33 @@ func (fh *FallbackHandler) WrapHandler(handler gin.HandlerFunc) gin.HandlerFunc
 		// Check if we have providers for this model
 		providers := util.GetProviderName(normalizedModel)
 
+		// Track resolved model for logging (may change if mapping is applied)
+		resolvedModel := normalizedModel
+		usedMapping := false
+
 		if len(providers) == 0 {
-			// No providers configured - check if we have a proxy for fallback
+			// No providers configured - check if we have a model mapping
+			if fh.modelMapper != nil {
+				if mappedModel := fh.modelMapper.MapModel(normalizedModel); mappedModel != "" {
+					// Mapping found - rewrite the model in request body
+					bodyBytes = rewriteModelInBody(bodyBytes, mappedModel)
+					c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes))
+					resolvedModel = mappedModel
+					usedMapping = true
+
+					// Get providers for the mapped model
+					providers = util.GetProviderName(mappedModel)
+
+					// Continue to handler with remapped model
+					goto handleRequest
+				}
+			}
+
+			// No mapping found - check if we have a proxy for fallback
 			proxy := fh.getProxy()
 			if proxy != nil {
-				// Fallback to ampcode.com
-				log.Infof("amp fallback: model %s has no configured provider, forwarding to ampcode.com", modelName)
+				// Log: Forwarding to ampcode.com (uses Amp credits)
+				logAmpRouting(RouteTypeAmpCredits, modelName, "", "", requestPath)
 
 				// Restore body again for the proxy
 				c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes))
@@ -71,7 +166,23 @@ func (fh *FallbackHandler) WrapHandler(handler gin.HandlerFunc) gin.HandlerFunc
 			}
 
 			// No proxy available, let the normal handler return the error
-			log.Debugf("amp fallback: model %s has no configured provider and no proxy available", modelName)
+			logAmpRouting(RouteTypeNoProvider, modelName, "", "", requestPath)
+		}
+
+	handleRequest:
+
+		// Log the routing decision
+		providerName := ""
+		if len(providers) > 0 {
+			providerName = providers[0]
+		}
+
+		if usedMapping {
+			// Log: Model was mapped to another model
+			logAmpRouting(RouteTypeModelMapping, modelName, resolvedModel, providerName, requestPath)
+		} else if len(providers) > 0 {
+			// Log: Using local provider (free)
+			logAmpRouting(RouteTypeLocalProvider, modelName, resolvedModel, providerName, requestPath)
 		}
 
 		// Providers available or no proxy for fallback, restore body and use normal handler
@@ -91,6 +202,27 @@ func (fh *FallbackHandler) WrapHandler(handler gin.HandlerFunc) gin.HandlerFunc
 	}
 }
 
+// rewriteModelInBody replaces the model name in a JSON request body
+func rewriteModelInBody(body []byte, newModel string) []byte {
+	var payload map[string]interface{}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		log.Warnf("amp model mapping: failed to parse body for rewrite: %v", err)
+		return body
+	}
+
+	if _, exists := payload["model"]; exists {
+		payload["model"] = newModel
+		newBody, err := json.Marshal(payload)
+		if err != nil {
+			log.Warnf("amp model mapping: failed to marshal rewritten body: %v", err)
+			return body
+		}
+		return newBody
+	}
+
+	return body
+}
+
 // extractModelFromRequest attempts to extract the model name from various request formats
 func extractModelFromRequest(body []byte, c *gin.Context) string {
 	// First try to parse from JSON body (OpenAI, Claude, etc.)