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)

gateway/README.md

@@ -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/internal/ai/mock.go

@@ -0,0 +1,16 @@
+package ai
+
+import "context"
+
+// MockProvider implements the Provider interface for local/demo testing
+type MockProvider struct{}
+
+// NewMockProvider creates a new MockProvider instance
+func NewMockProvider() *MockProvider {
+	return &MockProvider{}
+}
+
+// Generate returns a deterministic mock summary response
+func (p *MockProvider) Generate(ctx context.Context, text string) (string, error) {
+	return "This is a deterministic mock summary of the input text for local/demo testing.", nil
+}

gateway/internal/ai/provider.go

@@ -25,6 +25,8 @@ func NewProvider() (Provider, error) {
 		return NewOpenRouterProvider(), nil
 	case "ollama":
 		return NewOllamaProvider(), nil
+	case "mock":
+		return NewMockProvider(), nil
 	default:
 		return nil, fmt.Errorf("unsupported AI provider: %s", providerType)
 	}

gateway/internal/ai/provider_test.go

@@ -1,6 +1,7 @@
 package ai
 
 import (
+	"context"
 	"testing"
 )
 
@@ -29,6 +30,12 @@ func TestNewProvider(t *testing.T) {
 			wantType:     "*ai.OllamaProvider",
 			wantErr:      false,
 		},
+		{
+			name:         "mock provider",
+			providerType: "mock",
+			wantType:     "*ai.MockProvider",
+			wantErr:      false,
+		},
 		{
 			name:         "unsupported provider",
 			providerType: "invalid",
@@ -70,6 +77,10 @@ func TestNewProvider(t *testing.T) {
 				if _, ok := provider.(*OllamaProvider); !ok {
 					t.Errorf("NewProvider() returned %T, want *OllamaProvider", provider)
 				}
+			case "*ai.MockProvider":
+				if _, ok := provider.(*MockProvider); !ok {
+					t.Errorf("NewProvider() returned %T, want *MockProvider", provider)
+				}
 			}
 		})
 	}
@@ -135,3 +146,17 @@ func TestNewOllamaProvider_Defaults(t *testing.T) {
 		t.Errorf("expected default model 'llama2', got '%s'", provider.model)
 	}
 }
+
+func TestMockProvider(t *testing.T) {
+	provider := NewMockProvider()
+	ctx := context.Background()
+	resp, err := provider.Generate(ctx, "hello world")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	expected := "This is a deterministic mock summary of the input text for local/demo testing."
+	if resp != expected {
+		t.Errorf("expected '%s', got '%s'", expected, resp)
+	}
+}

gateway/main.go

@@ -1040,6 +1040,9 @@ func handleReadyz(c *gin.Context) {
 	case "ollama":
 		aiStatus = checkOllamaHealth()
 		checks["ollama"] = aiStatus
+	case "mock":
+		aiStatus = "ok"
+		checks["mock"] = aiStatus
 	}
 	checks["ai_provider"] = gin.H{
 		"provider": providerType,

gateway/main_test.go

@@ -3,12 +3,14 @@ package main
 import (
 	"bytes"
 	"encoding/json"
+	"gateway/internal/ai"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"strconv"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"github.com/stretchr/testify/require"
@@ -616,3 +618,96 @@ func TestHandleReadyz_RedisUnreachable(t *testing.T) {
 	checks := response["checks"].(map[string]interface{})
 	require.Equal(t, "unreachable", checks["redis"])
 }
+
+func TestHandleReadyz_MockProvider(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("AI_PROVIDER", "mock")
+	t.Setenv("RECEIPT_STORE", "memory")
+	t.Setenv("CACHE_ENABLED", "false")
+
+	origVerifier := checkVerifierHealth
+	defer func() {
+		checkVerifierHealth = origVerifier
+	}()
+
+	checkVerifierHealth = func() string { return "ok" }
+
+	r := gin.Default()
+	r.GET("/readyz", handleReadyz)
+
+	req, _ := http.NewRequest(http.MethodGet, "/readyz", nil)
+	w := httptest.NewRecorder()
+
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+
+	var response map[string]interface{}
+	err := json.Unmarshal(w.Body.Bytes(), &response)
+	require.NoError(t, err)
+
+	require.Equal(t, true, response["ready"])
+
+	checks := response["checks"].(map[string]interface{})
+	require.Equal(t, "ok", checks["verifier"])
+	require.Equal(t, "ok", checks["mock"])
+
+	aiProviderCheck := checks["ai_provider"].(map[string]interface{})
+	require.Equal(t, "mock", aiProviderCheck["provider"])
+	require.Equal(t, "ok", aiProviderCheck["status"])
+}
+
+func TestHandleSummarize_MockProvider(t *testing.T) {
+	// Set up a verifier that returns valid immediately
+	verifier := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(200)
+		w.Write([]byte(`{"is_valid":true, "recovered_address":"0xabc","error":""}`))
+	}))
+	defer verifier.Close()
+
+	// Environment
+	t.Setenv("AI_PROVIDER", "mock")
+	t.Setenv("VERIFIER_URL", verifier.URL)
+	t.Setenv("SERVER_WALLET_PRIVATE_KEY", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+	t.Setenv("RECEIPT_STORE", "memory")
+	t.Setenv("CACHE_ENABLED", "false")
+
+	// Initialize AI provider for this test
+	var err error
+	aiProvider, err = ai.NewProvider()
+	require.NoError(t, err)
+
+	// Initialize receipt store for this test
+	err = initReceiptStore()
+	require.NoError(t, err)
+
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.POST("/api/ai/summarize", handleSummarize)
+
+	// Build a valid request with signature/nonce
+	reqBody := strings.NewReader(`{"text":"hello world text to summarize"}`)
+	req, _ := http.NewRequest("POST", "/api/ai/summarize", reqBody)
+	req.Header.Set("X-402-Signature", "sig")
+	req.Header.Set("X-402-Nonce", "nonce")
+	req.Header.Set("X-402-Timestamp", strconv.FormatInt(time.Now().Unix(), 10))
+	req.Header.Set("Content-Type", "application/json")
+
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+
+	var response map[string]interface{}
+	err = json.Unmarshal(w.Body.Bytes(), &response)
+	require.NoError(t, err)
+
+	// Verify deterministic response
+	expected := "This is a deterministic mock summary of the input text for local/demo testing."
+	require.Equal(t, expected, response["result"])
+
+	// Check that X-402-Receipt header is set
+	receiptHeader := w.Header().Get("X-402-Receipt")
+	require.NotEmpty(t, receiptHeader)
+}
+