From ee9b9af8d3c75ab9ba1a7b5ad2a3177a3106c5ac Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Wed, 24 Jun 2026 21:41:27 +0200
Subject: [PATCH] references: models

---
 .../agents/chat/runtime/references/models.py  | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 surfsense_backend/app/agents/chat/runtime/references/models.py

diff --git a/surfsense_backend/app/agents/chat/runtime/references/models.py b/surfsense_backend/app/agents/chat/runtime/references/models.py
new file mode 100644
index 000000000..c61198eca
--- /dev/null
+++ b/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"]