fix: add deterministic mock AI provider for local/demo use

.env.example

@@ -3,7 +3,7 @@ PORT=3000
 NODE_ENV=development
 
 # AI Service Configuration
-# AI provider selection: "openrouter" (default) or "ollama"
+# AI provider selection: "openrouter" (default), "ollama", or "mock" (local/demo only)
 AI_PROVIDER=openrouter
 
 # OpenRouter Configuration (when AI_PROVIDER=openrouter)

README.md

@@ -66,7 +66,7 @@ flowchart TB
     Gateway["gateway/ Go Gin API :3000"]
     Verifier["verifier/ Rust Axum :3002"]
     Redis["Redis 7 receipt store by default\noptional response cache"]
-    AI["AI provider: OpenRouter or Ollama"]
+    AI["AI provider: OpenRouter, Ollama, or Mock"]
     Wallet["EVM wallet on configured chain\nBase Sepolia default"]
 
     Client --> Web
@@ -107,7 +107,7 @@ flowchart TB
       Summarize["POST /api/ai/summarize"]
       PaymentContext["Create PaymentContext\nrecipient, token, amount, chainId, nonce, timestamp"]
       VerifyClient["Verifier HTTP client\nVERIFIER_URL"]
-      AIClient["AI provider client\nOpenRouter or Ollama"]
+      AIClient["AI provider client\nOpenRouter, Ollama, or Mock"]
       ReceiptSigner["Receipt signer\nserver wallet key"]
       ReceiptLookup["GET /api/receipts/{id}"]
       Health["/healthz and /readyz"]
@@ -132,6 +132,7 @@ flowchart TB
     subgraph Providers["AI providers"]
       OpenRouter["OpenRouter chat completions"]
       Ollama["Local Ollama generate API"]
+      Mock["Mock offline provider"]
     end
 
     Browser --> Gin
@@ -148,6 +149,7 @@ flowchart TB
     Summarize -->|verified cache miss| AIClient
     AIClient --> OpenRouter
     AIClient --> Ollama
+    AIClient --> Mock
     Summarize --> ReceiptSigner --> Receipts
     ReceiptSigner --> MemoryStore
     Cache -->|cached response receipt| ReceiptSigner
@@ -316,7 +318,7 @@ Core local variables live in [.env.example](.env.example). Production placeholde
 
 | Variable | Service | Notes |
 | --- | --- | --- |
-| `AI_PROVIDER` | Gateway | `openrouter` by default, `ollama` for local Ollama experiments. |
+| `AI_PROVIDER` | Gateway | `openrouter` by default, `ollama` for local Ollama experiments, or `mock` for offline local/demo use. |
 | `OPENROUTER_API_KEY` | Gateway | Required when using OpenRouter. Never commit a real key. |
 | `OPENROUTER_MODEL` | Gateway | OpenRouter model name. Demo docs use `z-ai/glm-4.5-air:free` unless overridden. |
 | `OLLAMA_URL`, `OLLAMA_MODEL` | Gateway | Used only when `AI_PROVIDER=ollama`. |

docker-compose.yml

@@ -16,8 +16,13 @@ services:
       - METRICS_ENABLED=${METRICS_ENABLED:-true}
       - METRICS_PATH=${METRICS_PATH:-/metrics}
       # Pass through from .env file
+      - AI_PROVIDER
+      - OLLAMA_URL=${OLLAMA_URL:-http://host.docker.internal:11434}
+      - OLLAMA_MODEL
       - OPENROUTER_API_KEY
       - OPENROUTER_MODEL
+      - OPENROUTER_URL
+      - RUNNING_IN_DOCKER=true
       - SERVER_WALLET_PRIVATE_KEY
       - RECIPIENT_ADDRESS
       - PAYMENT_AMOUNT
@@ -37,6 +42,8 @@ services:
       start_period: 10s
     networks:
       - microai-net
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
 
   verifier:
     build: ./verifier

gateway/README.md

@@ -70,7 +70,7 @@ The verifier route `POST /verify` is not a gateway route. It belongs to the inte
 | `ratelimit.go` | Token bucket implementation. |
 | `metrics.go` | Prometheus metric definitions and metrics endpoint config helpers. |
 | `middleware.go` | Request timeout, correlation ID, and request metrics middleware. |
-| `internal/ai/` | OpenRouter and Ollama provider implementations. |
+| `internal/ai/` | OpenRouter, Ollama, and Mock provider implementations. |
 | `openapi.yaml` | Public gateway API contract. |
 
 ## Configuration
@@ -88,7 +88,7 @@ Common optional variables:
 | Variable | Default | Notes |
 | --- | --- | --- |
 | `PORT` | `3000` | Gateway listen port. |
-| `AI_PROVIDER` | `openrouter` | Supported values: `openrouter`, `ollama`. |
+| `AI_PROVIDER` | `openrouter` | Supported values: `openrouter`, `ollama`, `mock` (local/demo only). |
 | `OPENROUTER_MODEL` | `z-ai/glm-4.5-air:free` in code/docs unless overridden | OpenRouter model. |
 | `OPENROUTER_URL` | `https://openrouter.ai/api/v1/chat/completions` provider default | Used by tests and custom OpenRouter-compatible endpoints. |
 | `OLLAMA_URL` | `http://localhost:11434` | Used when `AI_PROVIDER=ollama`. |
@@ -129,7 +129,7 @@ cd gateway
 RECEIPT_STORE=memory CACHE_ENABLED=false go run .
 ```
 
-The verifier must be reachable at `VERIFIER_URL` for signed requests. OpenRouter startup requires `OPENROUTER_API_KEY` unless `AI_PROVIDER=ollama`.
+The verifier must be reachable at `VERIFIER_URL` for signed requests. OpenRouter startup requires `OPENROUTER_API_KEY` unless `AI_PROVIDER` is set to `ollama` or `mock`.
 
 ## Testing
 

gateway/cache.go

@@ -108,6 +108,8 @@ func CacheMiddleware() gin.HandlerFunc {
 			if model == "" {
 				model = "llama2"
 			}
+		} else if os.Getenv("AI_PROVIDER") == "mock" {
+			model = "mock"
 		} else if model == "" {
 			model = "z-ai/glm-4.5-air:free"
 		}

gateway/config_test.go

@@ -474,3 +474,76 @@ func TestGetReceiptTTL(t *testing.T) {
 func stringPtr(value string) *string {
 	return &value
 }
+
+func TestValidateConfig_MockProvider(t *testing.T) {
+	t.Run("allowed in dev environment", func(t *testing.T) {
+		t.Setenv("AI_PROVIDER", "mock")
+		t.Setenv("NODE_ENV", "development")
+		t.Setenv("APP_ENV", "")
+		t.Setenv("ALLOW_MOCK_PROVIDER", "")
+		t.Setenv("CACHE_ENABLED", "false")
+		t.Setenv("RECIPIENT_ADDRESS", "")
+		t.Setenv("SERVER_WALLET_PRIVATE_KEY", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+		t.Setenv("VERIFIER_URL", "http://127.0.0.1:3002")
+		t.Setenv("RECEIPT_STORE", "memory")
+
+		err := validateConfig()
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+
+	t.Run("allowed with ALLOW_MOCK_PROVIDER", func(t *testing.T) {
+		t.Setenv("AI_PROVIDER", "mock")
+		t.Setenv("NODE_ENV", "")
+		t.Setenv("APP_ENV", "")
+		t.Setenv("ALLOW_MOCK_PROVIDER", "true")
+		t.Setenv("CACHE_ENABLED", "false")
+		t.Setenv("RECIPIENT_ADDRESS", "")
+		t.Setenv("SERVER_WALLET_PRIVATE_KEY", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+		t.Setenv("VERIFIER_URL", "http://127.0.0.1:3002")
+		t.Setenv("RECEIPT_STORE", "memory")
+
+		err := validateConfig()
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+
+	t.Run("rejected in production", func(t *testing.T) {
+		t.Setenv("AI_PROVIDER", "mock")
+		t.Setenv("NODE_ENV", "production")
+		t.Setenv("APP_ENV", "")
+		t.Setenv("ALLOW_MOCK_PROVIDER", "true")
+		t.Setenv("CACHE_ENABLED", "false")
+		t.Setenv("RECIPIENT_ADDRESS", "")
+		t.Setenv("SERVER_WALLET_PRIVATE_KEY", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+		t.Setenv("VERIFIER_URL", "http://127.0.0.1:3002")
+		t.Setenv("RECEIPT_STORE", "memory")
+
+		err := validateConfig()
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		if !strings.Contains(err.Error(), "disabled in production") {
+			t.Fatalf("expected error to mention disabled in production, got %v", err)
+		}
+	})
+
+	t.Run("rejected outside allowed env", func(t *testing.T) {
+		t.Setenv("AI_PROVIDER", "mock")
+		t.Setenv("NODE_ENV", "")
+		t.Setenv("APP_ENV", "")
+		t.Setenv("ALLOW_MOCK_PROVIDER", "")
+		t.Setenv("CACHE_ENABLED", "false")
+		t.Setenv("RECIPIENT_ADDRESS", "")
+		t.Setenv("SERVER_WALLET_PRIVATE_KEY", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+		t.Setenv("VERIFIER_URL", "http://127.0.0.1:3002")
+		t.Setenv("RECEIPT_STORE", "memory")
+
+		err := validateConfig()
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+	})
+}

gateway/internal/ai/mock.go

@@ -0,0 +1,18 @@
+package ai
+
+import "context"
+
+type MockProvider struct {
+	Name string
+}
+
+func NewMockProvider() *MockProvider {
+	return &MockProvider{Name: "Mock"}
+}
+
+func (m *MockProvider) Generate(ctx context.Context, text string) (string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", err
+	}
+	return "This is a deterministic mock summary of the input text for local/demo testing.", nil
+}

gateway/internal/ai/ollama.go

@@ -24,6 +24,13 @@ func NewOllamaProvider() *OllamaProvider {
 		url = "http://localhost:11434"
 	}
 
+	if os.Getenv("RUNNING_IN_DOCKER") == "true" {
+		if url == "http://localhost:11434" || url == "http://localhost:11434/" ||
+			url == "http://127.0.0.1:11434" || url == "http://127.0.0.1:11434/" {
+			url = "http://host.docker.internal:11434"
+		}
+	}
+
 	model := os.Getenv("OLLAMA_MODEL")
 	if model == "" {
 		model = "llama2"

gateway/internal/ai/provider.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"strings"
 )
 
 // Provider defines the interface for AI service providers
@@ -25,7 +26,37 @@ func NewProvider() (Provider, error) {
 		return NewOpenRouterProvider(), nil
 	case "ollama":
 		return NewOllamaProvider(), nil
+	case "mock":
+		if err := IsMockAllowed(os.Getenv("NODE_ENV"), os.Getenv("APP_ENV"), os.Getenv("ALLOW_MOCK_PROVIDER")); err != nil {
+			return nil, err
+		}
+		return NewMockProvider(), nil
 	default:
 		return nil, fmt.Errorf("unsupported AI provider: %s", providerType)
 	}
 }
+
+// IsMockAllowed evaluates NODE_ENV, APP_ENV, and ALLOW_MOCK_PROVIDER to see if the mock provider can be run.
+// It normalizes checks by lowercasing and trimming spaces, evaluating production prefixes,
+// and treating truthy values for ALLOW_MOCK_PROVIDER.
+func IsMockAllowed(nodeEnv, appEnv, allowMock string) error {
+	nodeEnv = strings.ToLower(strings.TrimSpace(nodeEnv))
+	appEnv = strings.ToLower(strings.TrimSpace(appEnv))
+	allowMock = strings.ToLower(strings.TrimSpace(allowMock))
+
+	isProd := strings.HasPrefix(nodeEnv, "prod") || strings.HasPrefix(appEnv, "prod")
+	if isProd {
+		return fmt.Errorf("mock AI provider is disabled in production environments")
+	}
+
+	isAllowedEnv := nodeEnv == "development" || nodeEnv == "local" || nodeEnv == "demo" || nodeEnv == "test" || nodeEnv == "dev" ||
+		appEnv == "development" || appEnv == "local" || appEnv == "demo" || appEnv == "test" || appEnv == "dev"
+
+	isExplicitlyAllowed := allowMock == "true" || allowMock == "1" || allowMock == "yes"
+
+	if !isAllowedEnv && !isExplicitlyAllowed {
+		return fmt.Errorf("mock AI provider is disabled. Enable it by setting ALLOW_MOCK_PROVIDER=true, or set NODE_ENV/APP_ENV to development/local/demo/test")
+	}
+
+	return nil
+}