feat(llm): add mock LLM provider and improve caching

Added MockProvider for testing LLM interactions with expectation-based responses. Enhanced caching middleware to store full token metrics (input, output, reasoning, cache read/write). New mock backend supports condition-based prompt matching for flexible test scenarios.

Author: moshloop

go.mod

@@ -33,6 +33,10 @@ func NewClientWithModel(model string, options ...middleware.Option) (Client, err
 		return nil, fmt.Errorf("model cannot be empty")
 	}
 
+	if os.Getenv("MOCK") != "false" {
+		return &directClient{provider: NewMockProvider(model)}, nil
+	}
+
 	// Infer provider backend from model name
 	backend, err := inferBackendFromModel(model)
 	if err != nil {

go.sum

@@ -10,6 +10,13 @@ import (
 	"github.com/flanksource/commons/logger"
 )
 
+func valueOrZero(v *int) int {
+	if v == nil {
+		return 0
+	}
+	return *v
+}
+
 // CacheConfig holds configuration for caching middleware
 type CacheConfig struct {
 	Cache *cache.Cache // Cache instance (required)
@@ -87,7 +94,7 @@ func (c *cachingProvider) Execute(sess *Session, req ProviderRequest) (ProviderR
 		// Cache error
 		return ProviderResponse{}, fmt.Errorf("failed to get cache: %w", err)
 	}
-	logger.Infof("[%s/%s] cache miss", req.Model)
+	logger.Infof("[%s/%s] cache miss", c.GetBackend(), req.Model)
 
 	// Cache miss - execute request
 	startTime := time.Now()
@@ -113,6 +120,22 @@ func (c *cachingProvider) Execute(sess *Session, req ProviderRequest) (ProviderR
 		return resp, execErr
 	}
 
+	cacheEntry.Response = resp.Text
+	cacheEntry.TokensInput = resp.InputTokens
+	cacheEntry.TokensOutput = resp.OutputTokens
+	cacheEntry.TokensReasoning = valueOrZero(resp.ReasoningTokens)
+	cacheEntry.TokensCacheRead = valueOrZero(resp.CacheReadTokens)
+	cacheEntry.TokensCacheWrite = valueOrZero(resp.CacheWriteTokens)
+	cacheEntry.TokensTotal = resp.InputTokens +
+		resp.OutputTokens +
+		valueOrZero(resp.ReasoningTokens) +
+		valueOrZero(resp.CacheReadTokens) +
+		valueOrZero(resp.CacheWriteTokens)
+	cacheEntry.Provider = string(c.GetBackend())
+	if req.MaxTokens != nil {
+		cacheEntry.MaxTokens = *req.MaxTokens
+	}
+
 	// Store in cache
 	if err := c.cache.Set(cacheEntry); err != nil {
 		return resp, fmt.Errorf("failed to set cache: %w", err)

llm/client.go

@@ -0,0 +1,60 @@
+package llm
+
+import (
+	"strings"
+	"sync"
+
+	. "github.com/flanksource/commons-db/llm/types"
+)
+
+// MockExpectation defines a prompt match rule and its canned response.
+type MockExpectation struct {
+	Contains string
+	Response string
+}
+
+var (
+	mockExpectations []MockExpectation
+	mockMu           sync.RWMutex
+)
+
+// MockWhen registers an expectation: when a prompt contains the given
+// substring, return the specified response text.
+func MockWhen(contains, response string) {
+	mockMu.Lock()
+	defer mockMu.Unlock()
+	mockExpectations = append(mockExpectations, MockExpectation{Contains: contains, Response: response})
+}
+
+// MockReset clears all registered mock expectations.
+func MockReset() {
+	mockMu.Lock()
+	defer mockMu.Unlock()
+	mockExpectations = nil
+}
+
+type mockProvider struct {
+	model string
+}
+
+// NewMockProvider creates a mock provider that returns canned responses.
+func NewMockProvider(model string) Provider {
+	return &mockProvider{model: model}
+}
+
+func (p *mockProvider) Execute(_ *Session, req ProviderRequest) (ProviderResponse, error) {
+	mockMu.RLock()
+	defer mockMu.RUnlock()
+
+	for _, exp := range mockExpectations {
+		if strings.Contains(req.Prompt, exp.Contains) {
+			return ProviderResponse{Text: exp.Response, Model: p.model}, nil
+		}
+	}
+
+	return ProviderResponse{Text: "mock response", Model: p.model}, nil
+}
+
+func (p *mockProvider) GetModel() string            { return p.model }
+func (p *mockProvider) GetBackend() LLMBackend       { return LLMBackendMock }
+func (p *mockProvider) GetOpenRouterModelID() string { return "" }

llm/middleware/caching.go

@@ -0,0 +1,67 @@
+package llm
+
+import (
+	"testing"
+
+	. "github.com/flanksource/commons-db/llm/types"
+)
+
+func TestMockProvider_DefaultResponse(t *testing.T) {
+	p := NewMockProvider("test-model")
+	resp, err := p.Execute(&Session{}, ProviderRequest{Prompt: "anything"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.Text != "mock response" {
+		t.Errorf("got %q, want %q", resp.Text, "mock response")
+	}
+	if resp.Model != "test-model" {
+		t.Errorf("model = %q, want %q", resp.Model, "test-model")
+	}
+}
+
+func TestMockProvider_Expectations(t *testing.T) {
+	MockReset()
+	defer MockReset()
+
+	MockWhen("analyze commit", "type: feat\nscope: test\nsubject: mock commit")
+	MockWhen("summarize", "name: Summary\ndescription: Mock summary")
+
+	p := NewMockProvider("test-model")
+
+	resp, _ := p.Execute(&Session{}, ProviderRequest{Prompt: "please analyze commit abc123"})
+	if resp.Text != "type: feat\nscope: test\nsubject: mock commit" {
+		t.Errorf("got %q", resp.Text)
+	}
+
+	resp, _ = p.Execute(&Session{}, ProviderRequest{Prompt: "summarize the changes"})
+	if resp.Text != "name: Summary\ndescription: Mock summary" {
+		t.Errorf("got %q", resp.Text)
+	}
+
+	resp, _ = p.Execute(&Session{}, ProviderRequest{Prompt: "no match here"})
+	if resp.Text != "mock response" {
+		t.Errorf("unmatched should return default, got %q", resp.Text)
+	}
+}
+
+func TestMockReset(t *testing.T) {
+	MockWhen("test", "response")
+	MockReset()
+
+	p := NewMockProvider("m")
+	resp, _ := p.Execute(&Session{}, ProviderRequest{Prompt: "test"})
+	if resp.Text != "mock response" {
+		t.Errorf("after reset, expected default response, got %q", resp.Text)
+	}
+}
+
+func TestMockProvider_Backend(t *testing.T) {
+	p := NewMockProvider("m")
+	if p.GetBackend() != LLMBackendMock {
+		t.Errorf("backend = %q, want %q", p.GetBackend(), LLMBackendMock)
+	}
+	if p.GetOpenRouterModelID() != "" {
+		t.Errorf("OpenRouter ID should be empty")
+	}
+}

llm/provider_mock.go

@@ -12,6 +12,7 @@ const (
 	LLMBackendAnthropic  LLMBackend = "anthropic"
 	LLMBackendGemini     LLMBackend = "gemini"
 	LLMBackendClaudeCode LLMBackend = "claude-code"
+	LLMBackendMock       LLMBackend = "mock"
 )
 
 // Provider is the interface that all LLM provider implementations must satisfy.