references: models

surfsense_backend/app/agents/chat/runtime/references/models.py

@@ -0,0 +1,29 @@
+"""Data shapes for a resolved ``@``-reference."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ReferenceKind(str, Enum):
+    """What the user pointed at; the value is the label shown to the model."""
+
+    DOCUMENT = "document"
+    FOLDER = "folder"
+    CONNECTOR = "connector"
+    CHAT = "chat"
+
+
+@dataclass(frozen=True)
+class ResolvedReference:
+    """A resolved reference: identity plus the bits a pointer line needs."""
+
+    kind: ReferenceKind
+    entity_id: int
+    label: str
+    path: str | None = None  # document/folder virtual path
+    provider: str | None = None  # connector provider, e.g. "Gmail"
+
+
+__all__ = ["ReferenceKind", "ResolvedReference"]