Phase 7: AI-assisted query authoring (autocomplete, explain, fix, optimize, NL translation)

Adds a self-hosted (Ollama, qwen2.5-coder) model provider abstraction
with a pluggable opt-in cloud adapter, schema grounding, and a shared
cost/safety guard every AI-suggested query is assessed against --
compiling to and executing through the same unchanged Phase 2 IR/
compiler and Phase 4 tenant scoping as a hand-written query, no
parallel execution path.

Track A (built into the query bar): inline ghost-text autocomplete,
"Explain this query", "Fix this query" with a diff view, and a
rule-based "Optimize" suggestion. Track B: natural-language-to-query
translation, always a separate review step from execution, with
`sentryctl query --nl` requiring explicit confirmation to run.
Every accepted/dismissed translate-fix-optimize interaction is logged
into the same append-only audit_log table Phase 4 built.

Two real product bugs were found and fixed via live browser
verification (a Svelte effect re-running on every keystroke that
silently cancelled the ghost-text debounce; a ghost-text widget
positioned at document offset 0 instead of the cursor), and a real
costguard logic bug (unbounded-aggregation vs. raw-row) was caught by
its own test suite. New integration tests wire a real Ollama client
through the real HTTP handler against a mock server matching Ollama's
wire contract (hack/mock-ollama), keeping model-quality verification
out of CI as a disclosed, periodic human-run check instead.

See /docs/phase-7-ai-design.md and /docs/phase-7-runbook.md.

enterprise/cmd/enterprise-api/main.go

@@ -42,6 +42,9 @@ import (
 	chdriver "github.com/ClickHouse/clickhouse-go/v2"
 	"github.com/jackc/pgx/v5/pgxpool"
 
+	"github.com/sentry/sentry/api/ai/aiapi"
+	"github.com/sentry/sentry/api/ai/provider/ollama"
+	"github.com/sentry/sentry/api/ai/router"
 	"github.com/sentry/sentry/api/authz"
 	"github.com/sentry/sentry/api/dashboards"
 	"github.com/sentry/sentry/api/httpserver"
@@ -50,12 +53,17 @@ import (
 	"github.com/sentry/sentry/enterprise/internal/apiconfig"
 	"github.com/sentry/sentry/enterprise/internal/audit"
 	"github.com/sentry/sentry/enterprise/internal/chrunner"
+	"github.com/sentry/sentry/enterprise/internal/groundingregistry"
 	"github.com/sentry/sentry/enterprise/internal/rbacstore"
 	"github.com/sentry/sentry/enterprise/internal/searchclient"
 	"github.com/sentry/sentry/enterprise/internal/tenantcrd"
 	"github.com/sentry/sentry/enterprise/internal/tenantprovision"
 )
 
+// groundingRefreshInterval matches api/cmd/api's own constant of the
+// same name and reasoning -- see that file's doc comment.
+const groundingRefreshInterval = time.Minute
+
 func main() {
 	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
 
@@ -161,6 +169,27 @@ func main() {
 	queryHandler.RegisterRoutes(mux) // also registers GET /healthz
 	dashboardsHandler.RegisterRoutes(mux)
 
+	// Same "off unless OLLAMA_BASE_URL is set" gate as api/cmd/api --
+	// see that file's doc comment.
+	if cfg.AI.OllamaBaseURL != "" {
+		groundingReg := groundingregistry.New(registry)
+		groundingReg.StartRefreshing(ctx, rbac.ListActiveTenantIDs, groundingRefreshInterval, logger)
+
+		defaultProvider := ollama.New(cfg.AI.OllamaBaseURL, cfg.AI.OllamaModel)
+		aiRouter := router.New(defaultProvider)
+		if cfg.AI.OllamaFastModel != "" && cfg.AI.OllamaFastModel != cfg.AI.OllamaModel {
+			aiRouter.SetOperation(router.OpComplete, ollama.New(cfg.AI.OllamaBaseURL, cfg.AI.OllamaFastModel))
+		}
+
+		// Reuses the same audit_writer-role pool/store auditLogger above
+		// writes through -- same append-only audit_log table, new
+		// event_type (see metadata/migrations/0036).
+		interactionLogger := audit.NewAIInteractionLogger(audit.NewStore(auditPool), audit.SourceAPI)
+		aiHandler := aiapi.NewHandler(logger, aiRouter, groundingReg, authorizer, interactionLogger)
+		aiHandler.RegisterRoutes(mux)
+		logger.Info("ai routes enabled", "ollama_base_url", cfg.AI.OllamaBaseURL, "model", cfg.AI.OllamaModel)
+	}
+
 	srv := &http.Server{
 		Addr:    cfg.HTTPListenAddr,
 		Handler: httpserver.WithCORS(mux, cfg.CORSAllowedOrigin),

enterprise/cmd/enterprise-auth/main.go

@@ -1,5 +1,6 @@
 // Command enterprise-auth is Sentry's SSO/tenant-provisioning/RBAC
-// service (commercial license, not AGPL) -- see
+// service (AGPLv3, same as core -- see
+// /docs/compliance/license-audit-report.md) -- see
 // /docs/phase-4-isolation-design.md and /docs/phase-4-rbac-design.md.
 //
 // Wires session issuance/validation (internal/session), the

enterprise/internal/apiconfig/apiconfig.go

@@ -48,6 +48,23 @@ type Config struct {
 	// Deployments with no Kubernetes cluster at all (docker-compose)
 	// never set this.
 	TenantCRDNamespace string
+	// AI gates Phase 7's AI-assisted query features, same shape and same
+	// env var names as api/internal/config.AIConfig -- duplicated rather
+	// than imported (that package is under api/internal/, which Go's
+	// internal/ visibility rule blocks a separate module like this one
+	// from importing at all, the same constraint that already moved
+	// querylang/executor and dashboards out of internal/ in earlier
+	// phases) -- matches this file's own existing pattern of
+	// independently defining every field even where it overlaps with
+	// api/internal/config's (Postgres, SearchGRPCAddr, and so on), not a
+	// new inconsistency introduced here.
+	AI AIConfig
+}
+
+type AIConfig struct {
+	OllamaBaseURL   string
+	OllamaModel     string
+	OllamaFastModel string
 }
 
 type ClickHouseAdminConfig struct {
@@ -84,6 +101,11 @@ func Load() (Config, error) {
 			Username: getenv("POSTGRES_USERNAME", "sentry"),
 			Password: getenv("POSTGRES_PASSWORD", ""),
 		},
+		AI: AIConfig{
+			OllamaBaseURL:   getenv("OLLAMA_BASE_URL", ""),
+			OllamaModel:     getenv("OLLAMA_MODEL", "qwen2.5-coder:7b"),
+			OllamaFastModel: getenv("OLLAMA_FAST_MODEL", "qwen2.5-coder:1.5b"),
+		},
 		AuditWriter: AuditWriterConfig{
 			Username: getenv("AUDIT_WRITER_USERNAME", "audit_writer"),
 			Password: getenv("AUDIT_WRITER_PASSWORD", ""),

enterprise/internal/audit/ai_interaction_adapter.go

@@ -0,0 +1,79 @@
+// Adapts *Store to api/ai/aiapi.InteractionLogger -- same shape as
+// queryapi_adapter.go's QueryAPILogger, wired in by
+// enterprise/cmd/enterprise-api alongside it (Phase 7 task 12).
+package audit
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/sentry/sentry/api/ai/aiapi"
+	"github.com/sentry/sentry/api/authz"
+)
+
+// AIInteractionLogger implements aiapi.InteractionLogger by translating
+// its InteractionEntry into this package's Entry, reading tenant/user
+// identity from ctx -- same "read identity from ctx rather than the
+// interface growing tenant-awareness" shape as QueryAPILogger.
+type AIInteractionLogger struct {
+	store  *Store
+	source Source
+}
+
+func NewAIInteractionLogger(store *Store, source Source) *AIInteractionLogger {
+	return &AIInteractionLogger{store: store, source: source}
+}
+
+// aiInteractionDetail is what Detail carries -- Operation/Confidence/
+// Accepted/Edited don't have dedicated audit_log columns (same reasoning
+// as role_change/grant_change already using Detail instead of
+// query_text/row_count/duration_ms), only QueryText (FinalQuery) does.
+type aiInteractionDetail struct {
+	Operation  string `json:"operation"`
+	Input      string `json:"input"`
+	Output     string `json:"output"`
+	Confidence string `json:"confidence,omitempty"`
+	Accepted   bool   `json:"accepted"`
+	Edited     bool   `json:"edited"`
+}
+
+func (l *AIInteractionLogger) LogInteraction(ctx context.Context, entry aiapi.InteractionEntry) error {
+	identity, ok := authz.IdentityFromContext(ctx)
+	if !ok || identity.TenantID == "" {
+		return fmt.Errorf("audit: no tenant identity in context, refusing to write an unattributable audit entry")
+	}
+
+	var userID *string
+	if identity.UserID != "" {
+		userID = &identity.UserID
+	}
+
+	detail, err := json.Marshal(aiInteractionDetail{
+		Operation:  entry.Operation,
+		Input:      entry.Input,
+		Output:     entry.Output,
+		Confidence: entry.Confidence,
+		Accepted:   entry.Accepted,
+		Edited:     entry.Edited,
+	})
+	if err != nil {
+		return fmt.Errorf("audit: marshaling ai interaction detail: %w", err)
+	}
+
+	var queryText *string
+	if entry.FinalQuery != "" {
+		queryText = &entry.FinalQuery
+	}
+
+	_, err = l.store.Append(ctx, Entry{
+		TenantID:  identity.TenantID,
+		UserID:    userID,
+		Source:    l.source,
+		EventType: EventAIInteraction,
+		QueryText: queryText,
+		Status:    StatusSuccess,
+		Detail:    detail,
+	})
+	return err
+}

enterprise/internal/audit/audit.go

@@ -47,6 +47,12 @@ const (
 	EventGrantChange     EventType = "grant_change"
 	EventSSOConfigChange EventType = "sso_config_change"
 	EventSecretReveal    EventType = "secret_reveal"
+	// EventAIInteraction (Phase 7 task 12): a translate/fix/optimize
+	// suggestion's accept-or-dismiss outcome. QueryText carries the
+	// resulting query (if any); Detail carries the operation, the
+	// original input, confidence, and whether the user edited the
+	// suggestion before using it -- see ai_interaction_adapter.go.
+	EventAIInteraction EventType = "ai_interaction"
 )
 
 type Status string

enterprise/internal/audit/integration_test.go

@@ -13,6 +13,7 @@ package audit
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -22,6 +23,7 @@ import (
 
 	"github.com/jackc/pgx/v5/pgxpool"
 
+	"github.com/sentry/sentry/api/ai/aiapi"
 	"github.com/sentry/sentry/api/authz"
 	"github.com/sentry/sentry/api/queryapi"
 )
@@ -140,6 +142,74 @@ func TestQueryAPILoggerRefusesWithoutIdentity(t *testing.T) {
 	}
 }
 
+// TestAIInteractionLoggerWritesAttributedToContextIdentity is
+// AIInteractionLogger's counterpart to TestQueryAPILoggerWritesAttributedToContextIdentity
+// above (Phase 7 task 12) -- same "reads identity from ctx" contract,
+// plus a check that Detail actually round-trips the operation/
+// confidence/accepted/edited fields that don't have dedicated columns.
+func TestAIInteractionLoggerWritesAttributedToContextIdentity(t *testing.T) {
+	writerPool := testPool(t, "audit_writer", os.Getenv("AUDIT_TEST_POSTGRES_PASSWORD"))
+	adminPool := testPool(t, "sentry", os.Getenv("AUDIT_TEST_ADMIN_PASSWORD"))
+	cleanupAuditLog(t, adminPool)
+	defer cleanupAuditLog(t, adminPool)
+
+	logger := NewAIInteractionLogger(NewStore(writerPool), SourceAPI)
+	ctx := authz.WithIdentity(context.Background(), authz.Identity{TenantID: "acme", UserID: "22222222-2222-2222-2222-222222222222", Role: authz.RoleViewer})
+
+	err := logger.LogInteraction(ctx, aiapi.InteractionEntry{
+		Operation:  "translate",
+		Input:      "errors in the last hour",
+		Output:     "earliest=-1h severity=ERROR",
+		Confidence: "high",
+		Accepted:   true,
+		Edited:     false,
+		FinalQuery: "earliest=-1h severity=ERROR",
+	})
+	if err != nil {
+		t.Fatalf("LogInteraction: %v", err)
+	}
+
+	var tenantID, userID, eventType, queryText string
+	var detail []byte
+	row := adminPool.QueryRow(context.Background(),
+		`SELECT tenant_id, user_id, event_type, query_text, detail FROM audit_log ORDER BY id DESC LIMIT 1`)
+	if err := row.Scan(&tenantID, &userID, &eventType, &queryText, &detail); err != nil {
+		t.Fatalf("reading back the written row: %v", err)
+	}
+	if tenantID != "acme" || userID != "22222222-2222-2222-2222-222222222222" {
+		t.Fatalf("got tenant_id=%q user_id=%q, want acme/22222222-...", tenantID, userID)
+	}
+	if eventType != "ai_interaction" {
+		t.Fatalf("event_type = %q, want ai_interaction", eventType)
+	}
+	if queryText != "earliest=-1h severity=ERROR" {
+		t.Fatalf("query_text = %q, want the final query", queryText)
+	}
+	var parsed struct {
+		Operation string `json:"operation"`
+		Accepted  bool   `json:"accepted"`
+	}
+	if err := json.Unmarshal(detail, &parsed); err != nil {
+		t.Fatalf("unmarshaling detail: %v", err)
+	}
+	if parsed.Operation != "translate" || !parsed.Accepted {
+		t.Fatalf("detail = %+v, want operation=translate accepted=true", parsed)
+	}
+}
+
+func TestAIInteractionLoggerRefusesWithoutIdentity(t *testing.T) {
+	writerPool := testPool(t, "audit_writer", os.Getenv("AUDIT_TEST_POSTGRES_PASSWORD"))
+	adminPool := testPool(t, "sentry", os.Getenv("AUDIT_TEST_ADMIN_PASSWORD"))
+	cleanupAuditLog(t, adminPool)
+	defer cleanupAuditLog(t, adminPool)
+
+	logger := NewAIInteractionLogger(NewStore(writerPool), SourceAPI)
+	err := logger.LogInteraction(context.Background(), aiapi.InteractionEntry{Operation: "fix", Accepted: false})
+	if err == nil {
+		t.Fatal("expected LogInteraction to refuse writing an entry with no tenant identity in context")
+	}
+}
+
 // TestVerifyChainDetectsTampering proves the chain actually catches an
 // in-place row modification -- not just that VerifyChain runs without
 // erroring on untampered data, which a bug returning OK unconditionally

enterprise/internal/groundingregistry/registry.go

@@ -0,0 +1,144 @@
+// Package groundingregistry gives each active tenant its own schema-
+// grounding snapshot (Phase 7 task 3) in a multi-tenant deployment,
+// mirroring enterprise/internal/chwriter.Registry's per-tenant-instance
+// shape. It exists because api/ai/grounding.Service is deliberately
+// tenant-agnostic (it just wraps whatever executor.SQLRunner it's given
+// and caches one snapshot) -- a multi-tenant deployment needs many
+// snapshots, one per tenant, refreshed independently.
+//
+// The underlying SQLRunner every tenant's Service samples through is the
+// *same* chrunner.Registry instance shared across all of them: chrunner
+// resolves which tenant's actual ClickHouse connection to use from the
+// context.Context passed to RunSQL, not from anything this package
+// stores per tenant -- see chrunner.Registry.RunSQL's doc comment. So
+// "one grounding.Service per tenant" doesn't mean one ClickHouse
+// connection per tenant here (chrunner already owns that); it means one
+// cached snapshot per tenant, refreshed by calling that tenant's
+// Service.Refresh with a context stamped with that tenant's identity via
+// api/authz.WithIdentity -- the same "construct our own request context
+// outside an HTTP handler" pattern that function's doc comment names
+// this exact kind of caller as being for.
+package groundingregistry
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/sentry/sentry/api/ai/grounding"
+	"github.com/sentry/sentry/api/ai/provider"
+	"github.com/sentry/sentry/api/authz"
+	"github.com/sentry/sentry/api/querylang/executor"
+)
+
+// TenantLister returns the currently-active tenant IDs to sample --
+// a narrow function type rather than an rbacstore dependency, same
+// reasoning chwriter.Registry's SourceLister gives: this package
+// shouldn't need to import rbacstore just to know its return type.
+// enterprise-api's main.go supplies one backed by
+// rbacstore.ListProvisionedDataSources, the same source chrunner/
+// chwriter's own registries already refresh from.
+type TenantLister func(ctx context.Context) ([]string, error)
+
+// Registry holds one grounding.Service per active tenant, all sharing
+// the same underlying SQLRunner (chrunner.Registry).
+type Registry struct {
+	runner executor.SQLRunner
+
+	mu       sync.RWMutex
+	services map[string]*grounding.Service
+}
+
+func New(runner executor.SQLRunner) *Registry {
+	return &Registry{runner: runner, services: make(map[string]*grounding.Service)}
+}
+
+// SchemaContextFor returns tenant's cached grounding snapshot, or a
+// zero-valued SchemaContext if that tenant hasn't been sampled yet (new
+// tenant, not yet seen by a refresh cycle) -- same "absence is normal,
+// not an error" posture grounding.Service.Current documents.
+func (r *Registry) SchemaContextFor(tenantID string) provider.SchemaContext {
+	r.mu.RLock()
+	svc, ok := r.services[tenantID]
+	r.mu.RUnlock()
+	if !ok {
+		return provider.SchemaContext{}
+	}
+	return svc.Current()
+}
+
+// SchemaContext implements aiapi.SchemaContextSource, resolving the
+// tenant from ctx the same way chrunner.RunSQL does -- the multi-tenant
+// counterpart to grounding.Service's own same-named method, which has
+// no tenant to resolve in a single-tenant deployment. An unauthenticated
+// or tenant-less context (shouldn't happen behind aiapi's RoleViewer
+// auth wrapper, but handled rather than assumed) returns a zero-valued
+// SchemaContext, same as an unseen tenant -- absence is normal here, not
+// worth a panic or a swallowed error over.
+func (r *Registry) SchemaContext(ctx context.Context) provider.SchemaContext {
+	id, ok := authz.IdentityFromContext(ctx)
+	if !ok || id.TenantID == "" {
+		return provider.SchemaContext{}
+	}
+	return r.SchemaContextFor(id.TenantID)
+}
+
+// StartRefreshing lists active tenants and refreshes each one's
+// grounding snapshot, immediately and then on interval, until ctx is
+// cancelled -- same shape as chwriter.Registry.StartRefreshing. A
+// newly-active tenant gets a Service the first time it appears in
+// lister's output; a tenant that's no longer listed keeps its last
+// snapshot rather than being torn down (grounding data going briefly
+// stale for a deprovisioned tenant is harmless -- unlike a ClickHouse
+// writer connection, there's no credential to leak or clean up here).
+func (r *Registry) StartRefreshing(ctx context.Context, lister TenantLister, interval time.Duration, logger *slog.Logger) {
+	r.refreshAll(ctx, lister, logger)
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				r.refreshAll(ctx, lister, logger)
+			}
+		}
+	}()
+}
+
+func (r *Registry) refreshAll(ctx context.Context, lister TenantLister, logger *slog.Logger) {
+	tenantIDs, err := lister(ctx)
+	if err != nil {
+		if logger != nil {
+			logger.Error("groundingregistry: listing active tenants", "error", err)
+		}
+		return
+	}
+	for _, tenantID := range tenantIDs {
+		svc := r.serviceFor(tenantID)
+		tenantCtx := authz.WithIdentity(ctx, authz.Identity{TenantID: tenantID, Role: authz.RoleService})
+		if err := svc.Refresh(tenantCtx); err != nil && logger != nil {
+			logger.Error("groundingregistry: refreshing tenant", "tenant", tenantID, "error", err)
+		}
+	}
+}
+
+func (r *Registry) serviceFor(tenantID string) *grounding.Service {
+	r.mu.RLock()
+	svc, ok := r.services[tenantID]
+	r.mu.RUnlock()
+	if ok {
+		return svc
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if svc, ok := r.services[tenantID]; ok { // re-check under write lock
+		return svc
+	}
+	svc = grounding.New(r.runner)
+	r.services[tenantID] = svc
+	return svc
+}

enterprise/internal/groundingregistry/registry_test.go

@@ -0,0 +1,74 @@
+package groundingregistry
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sentry/sentry/api/authz"
+	"github.com/sentry/sentry/api/querylang/executor"
+)
+
+// tenantAwareFakeRunner returns a service list keyed by the tenant
+// identity RunSQL is called with -- confirms groundingregistry actually
+// stamps a different tenant per Service.Refresh call, not the same
+// context reused for everyone (chrunner.Registry's real RunSQL resolves
+// tenant from ctx the same way, so this fake exercises the same
+// contract).
+type tenantAwareFakeRunner struct {
+	byTenant map[string][]string
+}
+
+func (f *tenantAwareFakeRunner) RunSQL(ctx context.Context, sql string) (*executor.Result, error) {
+	id, ok := authz.IdentityFromContext(ctx)
+	if !ok {
+		return &executor.Result{Columns: []string{"service"}, Rows: nil}, nil
+	}
+	services := f.byTenant[id.TenantID]
+	rows := make([][]any, len(services))
+	for i, s := range services {
+		rows[i] = []any{s}
+	}
+	return &executor.Result{Columns: []string{"service"}, Rows: rows}, nil
+}
+
+func TestRefreshAllScopesEachTenantIndependently(t *testing.T) {
+	runner := &tenantAwareFakeRunner{byTenant: map[string][]string{
+		"tenant-a": {"api-a"},
+		"tenant-b": {"api-b", "worker-b"},
+	}}
+	reg := New(runner)
+	lister := func(context.Context) ([]string, error) {
+		return []string{"tenant-a", "tenant-b"}, nil
+	}
+
+	reg.refreshAll(context.Background(), lister, nil)
+
+	a := reg.SchemaContextFor("tenant-a")
+	if len(a.Services) != 1 || a.Services[0] != "api-a" {
+		t.Errorf("tenant-a grounding = %v, want [api-a]", a.Services)
+	}
+	b := reg.SchemaContextFor("tenant-b")
+	if len(b.Services) != 2 {
+		t.Errorf("tenant-b grounding = %v, want 2 services", b.Services)
+	}
+
+	unknown := reg.SchemaContextFor("tenant-never-seen")
+	if len(unknown.Services) != 0 || len(unknown.Fields) != 0 {
+		t.Errorf("unseen tenant should get a zero-valued SchemaContext, got %+v", unknown)
+	}
+}
+
+func TestRefreshAllListerErrorLeavesExistingSnapshots(t *testing.T) {
+	runner := &tenantAwareFakeRunner{byTenant: map[string][]string{"tenant-a": {"api-a"}}}
+	reg := New(runner)
+	good := func(context.Context) ([]string, error) { return []string{"tenant-a"}, nil }
+	reg.refreshAll(context.Background(), good, nil)
+
+	failing := func(context.Context) ([]string, error) { return nil, context.DeadlineExceeded }
+	reg.refreshAll(context.Background(), failing, nil)
+
+	a := reg.SchemaContextFor("tenant-a")
+	if len(a.Services) != 1 {
+		t.Errorf("tenant-a grounding after a failed lister call = %v, want unchanged [api-a]", a.Services)
+	}
+}