feat(investigations): add investigation schema

Author: arslnb

migrations_lockfile.txt

@@ -19,6 +19,8 @@ hybridcloud: 0033_drop_webhookpayload_schedule_for_index
 
 insights: 0001_squashed_0002_backfill_team_starred
 
+investigations: 0001_initial
+
 monitors: 0001_squashed_0013_delete_monitor_is_muted_field
 
 nodestore: 0001_squashed_0002_nodestore_no_dictfield

src/sentry/conf/server.py

@@ -494,6 +494,7 @@ def env(
     "sentry.data_secrecy",
     "sentry.workflow_engine",
     "sentry.explore",
+    "sentry.investigations.apps.InvestigationsConfig",
     "sentry.insights",
     "sentry.preprod",
     "sentry.releases",

src/sentry/investigations/__init__.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class InvestigationsConfig(AppConfig):
+    name = "sentry.investigations"

src/sentry/investigations/apps.py

@@ -0,0 +1,4 @@
+from .cell import *  # NOQA
+from .execution import *  # NOQA
+from .investigation import *  # NOQA
+from .parameter import *  # NOQA

src/sentry/investigations/migrations/0001_initial.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import models
+from django.db.models import F, Q
+
+from sentry.backup.scopes import RelocationScope
+from sentry.db.models import FlexibleForeignKey, cell_silo_model, sane_repr
+from sentry.db.models.base import DefaultFieldsModel
+from sentry.db.models.fields.bounded import BoundedPositiveIntegerField
+from sentry.db.models.fields.hybrid_cloud_foreign_key import HybridCloudForeignKey
+
+
+class InvestigationCellKind(models.TextChoices):
+    TEXT = "text", "Text"
+    QUERY = "query", "Query"
+
+
+@cell_silo_model
+class InvestigationCell(DefaultFieldsModel):
+    """A user-composed cell whose content may be produced by a Seer execution."""
+
+    __relocation_scope__ = RelocationScope.Excluded
+
+    investigation = FlexibleForeignKey(
+        "investigations.Investigation", on_delete=models.CASCADE, related_name="cells"
+    )
+    created_by_id = HybridCloudForeignKey("sentry.User", null=True, on_delete="SET_NULL")
+    last_edited_by_id = HybridCloudForeignKey("sentry.User", null=True, on_delete="SET_NULL")
+
+    position = BoundedPositiveIntegerField()
+    kind = models.CharField(max_length=32, choices=InvestigationCellKind.choices)
+    title = models.CharField(max_length=255, default="", blank=True, db_default="")
+    # The canonical, editable body rendered or evaluated by this cell.
+    content = models.TextField(default="", blank=True, db_default="")
+    # The latest prompt used to generate content. This remains editable so a
+    # future execution can regenerate the cell.
+    prompt = models.TextField(default="", blank=True, db_default="")
+    # The unedited output of the latest generation. Human edits update content
+    # without erasing the generated source.
+    generated_content = models.TextField(default="", blank=True, db_default="")
+
+    # Kind-specific execution and authoring behavior, such as automatic execution
+    # or a dataset hint. Presentation-only state belongs in `display`.
+    config: models.Field[dict[str, Any], dict[str, Any]] = models.JSONField(
+        default=dict, db_default={}
+    )
+    # Versioned presentation state, such as table/chart selection or whether a
+    # prompt is collapsed. It must not affect how a cell executes.
+    display: models.Field[dict[str, Any], dict[str, Any]] = models.JSONField(
+        default=dict, db_default={}
+    )
+
+    version = BoundedPositiveIntegerField(default=1, db_default=1)
+    current_execution = FlexibleForeignKey(
+        "investigations.InvestigationCellExecution",
+        null=True,
+        on_delete=models.SET_NULL,
+        related_name="+",
+    )
+    # The successful execution that produced the currently rendered text body.
+    # This remains stable while a newer generation is pending or fails so the
+    # existing Markdown keeps its original project-access requirements.
+    content_execution = FlexibleForeignKey(
+        "investigations.InvestigationCellExecution",
+        null=True,
+        on_delete=models.SET_NULL,
+        related_name="+",
+    )
+    # The latest successful execution that produced a query result. It remains
+    # stable while a replacement run is pending, stopped, or fails.
+    result_execution = FlexibleForeignKey(
+        "investigations.InvestigationCellExecution",
+        null=True,
+        on_delete=models.SET_NULL,
+        related_name="+",
+    )
+    # Set when an input changes so the UI can distinguish a valid old output
+    # from a current one before a replacement execution finishes.
+    stale_at = models.DateTimeField(null=True)
+
+    # Cells are hidden rather than hard-deleted so execution history remains
+    # inspectable and stale references retain a stable target.
+    deleted_at = models.DateTimeField(null=True)
+
+    class Meta:
+        app_label = "investigations"
+        db_table = "investigations_investigationcell"
+        indexes = [
+            models.Index(fields=["investigation", "deleted_at", "position"]),
+            models.Index(fields=["investigation", "-date_updated"]),
+        ]
+
+    __repr__ = sane_repr("investigation_id", "kind", "position")
+
+
+@cell_silo_model
+class InvestigationCellDependency(DefaultFieldsModel):
+    """A directed edge from a cell to one of its upstream dependencies."""
+
+    __relocation_scope__ = RelocationScope.Excluded
+
+    cell = FlexibleForeignKey(
+        "investigations.InvestigationCell",
+        on_delete=models.CASCADE,
+        related_name="dependency_links",
+    )
+    depends_on = FlexibleForeignKey(
+        "investigations.InvestigationCell",
+        on_delete=models.CASCADE,
+        related_name="dependent_links",
+    )
+
+    class Meta:
+        app_label = "investigations"
+        db_table = "investigations_investigationcelldependency"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["cell", "depends_on"], name="investigation_unique_cell_dependency"
+            ),
+            models.CheckConstraint(
+                condition=~Q(cell=F("depends_on")), name="investigation_no_self_dependency"
+            ),
+        ]

src/sentry/investigations/migrations/__init__.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from django.db import models
+
+from sentry.backup.scopes import RelocationScope
+from sentry.db.models import FlexibleForeignKey, cell_silo_model, sane_repr
+from sentry.db.models.base import DefaultFieldsModel
+from sentry.db.models.fields.bounded import BoundedPositiveIntegerField
+from sentry.db.models.fields.hybrid_cloud_foreign_key import HybridCloudForeignKey
+
+
+class InvestigationCellExecutor(models.TextChoices):
+    # Content persisted without an automated runner.
+    MANUAL = "manual", "Manual"
+    # Content or query results produced by the Seer code-mode runner.
+    CODE_MODE = "code_mode", "Code mode"
+    # Text content produced by the Seer text-generation runner.
+    TEXT_GENERATION = "text_generation", "Text generation"
+
+
+class InvestigationCellExecutionStatus(models.TextChoices):
+    PENDING = "pending", "Pending"
+    RUNNING = "running", "Running"
+    AWAITING_INPUT = "awaiting_input", "Awaiting input"
+    STOPPING = "stopping", "Stopping"
+    COMPLETED = "completed", "Completed"
+    FAILED = "failed", "Failed"
+    CANCELLED = "cancelled", "Cancelled"
+
+
+@cell_silo_model
+class InvestigationCellExecution(DefaultFieldsModel):
+    """An immutable attempt to produce a cell's content or query result."""
+
+    __relocation_scope__ = RelocationScope.Excluded
+
+    # Idempotency identity supplied by, or returned to, execution callers.
+    request_id = models.UUIDField(default=uuid4, editable=False, unique=True)
+    cell = FlexibleForeignKey(
+        "investigations.InvestigationCell", on_delete=models.CASCADE, related_name="executions"
+    )
+    triggered_by_id = HybridCloudForeignKey("sentry.User", null=True, on_delete="SET_NULL")
+    seer_run = FlexibleForeignKey(
+        "seer.SeerRun", null=True, on_delete=models.SET_NULL, related_name="cell_executions"
+    )
+
+    executor = models.CharField(max_length=32, choices=InvestigationCellExecutor.choices)
+    status = models.CharField(
+        max_length=32,
+        choices=InvestigationCellExecutionStatus.choices,
+        default=InvestigationCellExecutionStatus.PENDING,
+        db_default=InvestigationCellExecutionStatus.PENDING,
+    )
+    cell_version = BoundedPositiveIntegerField()
+
+    # Immutable resolved inputs: parameter values plus exact upstream execution
+    # execution IDs/hashes. This makes reruns reproducible even after the notebook changes.
+    input_snapshot: models.Field[dict[str, Any], dict[str, Any]] = models.JSONField(
+        default=dict, db_default={}
+    )
+    input_fingerprint = models.CharField(max_length=64)
+
+    result_schema_version = BoundedPositiveIntegerField(default=1, db_default=1)
+    result = models.JSONField(null=True)
+    error = models.JSONField(null=True)
+    transcript = models.JSONField(default=list, db_default=[])
+    transcript_truncated = models.BooleanField(default=False, db_default=False)
+    started_at = models.DateTimeField(null=True)
+    completed_at = models.DateTimeField(null=True)
+
+    # Immutable provenance for projects whose data contributed to this output.
+    # Unlike an investigation's mutable project selection, these links are used
+    # when enforcing access to already-persisted results.
+    data_projects = models.ManyToManyField(
+        "sentry.Project", through="investigations.InvestigationCellExecutionProject", blank=True
+    )
+
+    class Meta:
+        app_label = "investigations"
+        db_table = "investigations_investigationcellexecution"
+        indexes = [
+            models.Index(fields=["cell", "-date_added"]),
+            models.Index(fields=["cell", "status"]),
+        ]
+
+    __repr__ = sane_repr("cell_id", "executor", "status")
+
+
+@cell_silo_model
+class InvestigationCellExecutionProject(DefaultFieldsModel):
+    """A project whose data contributed to one persisted cell output."""
+
+    __relocation_scope__ = RelocationScope.Excluded
+
+    execution = FlexibleForeignKey(
+        "investigations.InvestigationCellExecution",
+        on_delete=models.CASCADE,
+        related_name="data_project_links",
+    )
+    project = FlexibleForeignKey("sentry.Project", on_delete=models.CASCADE)
+
+    class Meta:
+        app_label = "investigations"
+        db_table = "investigations_investigationcellexecutionproject"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["execution", "project"],
+                name="investigation_unique_execution_project",
+            )
+        ]