Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(resources): reference type registry rewrite and ReferenceType model

raullopez-sandbox202703bc4c4d
diff --git a/core/switch_core/bridges/resource/__init__.py b/core/switch_core/bridges/resource/__init__.py
index 7c69dd308..8eefc24e7 100644
--- a/core/switch_core/bridges/resource/__init__.py
+++ b/core/switch_core/bridges/resource/__init__.py
@@ -4,22 +4,24 @@ from switch_core.bridges.resource.events import (
ResourceLoadResponse,
)
from switch_core.bridges.resource.registry import (
- REFERENCE_TYPES,
- list_known_types,
- serialize_used_types,
- validate_reference_type,
+ BUILTIN_REFERENCE_TYPES,
+ ReferenceTypeSpec,
+ ReferenceValue,
+ is_builtin_type,
+ validate_reference_value,
)
from switch_core.bridges.resource.service import ResourceService
from switch_core.bridges.resource.tracker import ResourceRequestTracker
__all__ = [
- "REFERENCE_TYPES",
+ "BUILTIN_REFERENCE_TYPES",
+ "ReferenceTypeSpec",
+ "ReferenceValue",
"ResourceLoadEntry",
"ResourceLoadRequest",
"ResourceLoadResponse",
"ResourceRequestTracker",
"ResourceService",
- "list_known_types",
- "serialize_used_types",
- "validate_reference_type",
+ "is_builtin_type",
+ "validate_reference_value",
]
diff --git a/core/switch_core/bridges/resource/registry.py b/core/switch_core/bridges/resource/registry.py
index 83bd25720..86f3ed124 100644
--- a/core/switch_core/bridges/resource/registry.py
+++ b/core/switch_core/bridges/resource/registry.py
@@ -1,66 +1,47 @@
-"""In-memory registry of external reference sub-types.
+"""Built-in external reference types.
-For P0 this is a static dict. A reference's ``type`` field is validated against
-this registry at create time; the per-type ``value_model`` validates the
-JSONB value bag. ``display_name`` and ``instructions`` are surfaced to UI and
-agents respectively.
+The four types defined here ship with Switch and are never database rows: their
+agent-facing ``instructions`` stay under code review. User-defined types live in
+the ``reference_types`` table and are resolved per-principal by
+``ResourceService``; a built-in wins any slug collision.
+
+Every type shares one value shape — a non-empty list of URLs — so what varies
+per type is prose: ``display_name``, ``instructions`` for agents, and
+``value_hint`` for the human filling in the form.
"""
-import builtins
-from typing import Any
+from typing import Any, Literal
from pydantic import BaseModel, Field
-class GoogleDriveValue(BaseModel):
- """Value shape for a Google Drive reference.
-
- ``urls`` may point at individual documents, folders, or a mix.
- """
-
- urls: list[str] = Field(default_factory=list, min_length=1)
-
-
-class ConfluenceValue(BaseModel):
- """Value shape for a Confluence reference. Pages, spaces, or a mix."""
-
- urls: list[str] = Field(default_factory=list, min_length=1)
-
-
-class GitHubValue(BaseModel):
- """Value shape for a GitHub reference. One or more repository URLs
- (e.g. ``https://github.com/sandbox-quantum/aq-switch``)."""
-
- urls: list[str] = Field(default_factory=list, min_length=1)
+class ReferenceValue(BaseModel):
+ """Value shape for every reference: one or more URLs identifying the material."""
-
-class JiraValue(BaseModel):
- """Value shape for a Jira reference. One or more Jira URLs — projects,
- issues, or boards, or a mix (e.g.
- ``https://your-org.atlassian.net/browse/PROJ-123``)."""
-
- urls: list[str] = Field(default_factory=list, min_length=1)
+ urls: list[str] = Field(min_length=1)
class ReferenceTypeSpec(BaseModel):
type: str
display_name: str
instructions: str
- value_model: builtins.type[BaseModel]
+ value_hint: str
def value_json_schema(self) -> dict[str, Any]:
- return self.value_model.model_json_schema()
+ return ReferenceValue.model_json_schema()
- def to_public_dict(self) -> dict[str, Any]:
+ def to_public_dict(self, *, origin: Literal["builtin", "user"]) -> dict[str, Any]:
return {
"type": self.type,
"display_name": self.display_name,
"instructions": self.instructions,
"value_schema": self.value_json_schema(),
+ "value_hint": self.value_hint,
+ "origin": origin,
}
-REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
+BUILTIN_REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
"google_drive": ReferenceTypeSpec(
type="google_drive",
display_name="Google Drive",
@@ -70,7 +51,7 @@ REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
"can fetch Drive content on your behalf. The recommended path is "
"the Glean MCP connector when available."
),
- value_model=GoogleDriveValue,
+ value_hint="Paste links to Google Drive documents or folders.",
),
"confluence": ReferenceTypeSpec(
type="confluence",
@@ -81,7 +62,7 @@ REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
"fetch Confluence content on your behalf — typically the Atlassian "
"MCP connector (e.g. getConfluencePage, searchConfluenceUsingCql)."
),
- value_model=ConfluenceValue,
+ value_hint="Paste links to Confluence pages or spaces.",
),
"github": ReferenceTypeSpec(
type="github",
@@ -95,7 +76,9 @@ REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
"URL(s) in this reference's value identify which repo(s) to "
"operate on."
),
- value_model=GitHubValue,
+ value_hint=(
+ "Paste links to GitHub repositories (e.g. https://github.com/org/repo)."
+ ),
),
"jira": ReferenceTypeSpec(
type="jira",
@@ -108,44 +91,24 @@ REFERENCE_TYPES: dict[str, ReferenceTypeSpec] = {
"getVisibleJiraProjects). The URL(s) in this reference's value "
"identify which Jira project / issue / board to operate on."
),
- value_model=JiraValue,
+ value_hint=(
+ "Paste links to Jira projects, issues, or boards "
+ "(e.g. https://your-org.atlassian.net/browse/PROJ-123)."
+ ),
),
}
-def list_known_types() -> list[str]:
- return list(REFERENCE_TYPES.keys())
-
-
-def validate_reference_type(type_: str) -> None:
- if type_ not in REFERENCE_TYPES:
- raise ValueError(
- f"Unknown reference type '{type_}'. Known: {list_known_types()}"
- )
-
-
-def validate_reference_value(type_: str, value: dict[str, Any]) -> dict[str, Any]:
- """Validate ``value`` against the type's Pydantic model. Returns the
+def validate_reference_value(value: dict[str, Any]) -> dict[str, Any]:
+ """Validate ``value`` against the shared value model. Returns the
parsed-and-redumped dict (so unknown fields are stripped). Raises
``ValueError`` on failure."""
- validate_reference_type(type_)
- spec = REFERENCE_TYPES[type_]
try:
- parsed = spec.value_model.model_validate(value)
+ parsed = ReferenceValue.model_validate(value)
except Exception as exc:
- raise ValueError(f"Invalid value for type '{type_}': {exc}") from exc
+ raise ValueError(f"Invalid reference value: {exc}") from exc
return parsed.model_dump(mode="json")
-def serialize_used_types(types: set[str]) -> dict[str, dict[str, Any]]:
- """Return the registry entries for the types actually present in a room,
- as plain dicts ready to be embedded in the on-connect payload."""
- return {
- t: {
- "type": REFERENCE_TYPES[t].type,
- "display_name": REFERENCE_TYPES[t].display_name,
- "instructions": REFERENCE_TYPES[t].instructions,
- }
- for t in types
- if t in REFERENCE_TYPES
- }
+def is_builtin_type(type_: str) -> bool:
+ return type_ in BUILTIN_REFERENCE_TYPES
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 0599a658d..5d227047c 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -414,6 +414,21 @@ class Reference(Base):
)
+class ReferenceType(Base):
+ __tablename__ = "reference_types"
+
+ type: Mapped[str] = mapped_column(Text, primary_key=True)
+ owner_id: Mapped[str] = mapped_column(Text, ForeignKey("users.id"), nullable=False)
+ read_visibility: Mapped[str] = mapped_column(Text, nullable=False)
+ write_visibility: Mapped[str] = mapped_column(Text, nullable=False)
+ display_name: Mapped[str] = mapped_column(Text, nullable=False)
+ instructions: Mapped[str] = mapped_column(Text, nullable=False)
+ value_hint: Mapped[str] = mapped_column(Text, nullable=False)
+ created_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True), server_default=func.now(), nullable=False
+ )
+
+
class Document(Base):
__tablename__ = "documents"
__table_args__ = (
diff --git a/core/tests/switch_core/bridges/resource/test_registry.py b/core/tests/switch_core/bridges/resource/test_registry.py
index 819b75b7d..9a6d6bba2 100644
--- a/core/tests/switch_core/bridges/resource/test_registry.py
+++ b/core/tests/switch_core/bridges/resource/test_registry.py
@@ -3,61 +3,75 @@ from __future__ import annotations
import pytest
from switch_core.bridges.resource.registry import (
- REFERENCE_TYPES,
- list_known_types,
- serialize_used_types,
- validate_reference_type,
+ BUILTIN_REFERENCE_TYPES,
+ is_builtin_type,
validate_reference_value,
)
-def test_jira_type_is_registered():
- assert "jira" in REFERENCE_TYPES
- assert "jira" in list_known_types()
- spec = REFERENCE_TYPES["jira"]
- assert spec.type == "jira"
- assert spec.display_name == "Jira"
- # Instructions should point agents at the Atlassian connector.
- assert "Atlassian" in spec.instructions
+ ("slug", "display_name"),
+ [
+ ("google_drive", "Google Drive"),
+ ("confluence", "Confluence"),
+ ("github", "GitHub"),
+ ("jira", "Jira"),
+ ],
+)
+def test_builtin_types_are_registered(slug: str, display_name: str):
+ spec = BUILTIN_REFERENCE_TYPES[slug]
+ assert spec.type == slug
+ assert spec.display_name == display_name
+ assert spec.instructions
+ assert spec.value_hint
+
+
+def test_jira_instructions_point_at_the_atlassian_connector():
+ assert "Atlassian" in BUILTIN_REFERENCE_TYPES["jira"].instructions
+
+
+def test_is_builtin_type():
+ assert is_builtin_type("jira")
+ assert not is_builtin_type("not_a_real_type")
-def test_jira_public_dict_carries_value_schema():
- public = REFERENCE_TYPES["jira"].to_public_dict()
+def test_public_dict_carries_schema_hint_and_origin():
+ public = BUILTIN_REFERENCE_TYPES["jira"].to_public_dict(origin="builtin")
assert public["type"] == "jira"
assert public["display_name"] == "Jira"
assert public["instructions"]
- # Mirrors confluence/github: a flat urls list with min_length=1.
- props = public["value_schema"]["properties"]
- assert "urls" in props
+ assert public["origin"] == "builtin"
+ assert public["value_hint"] == BUILTIN_REFERENCE_TYPES["jira"].value_hint
+ assert "urls" in public["value_schema"]["properties"]
-def test_jira_value_validates_url_list():
+def test_public_dict_origin_user():
+ public = BUILTIN_REFERENCE_TYPES["github"].to_public_dict(origin="user")
+ assert public["origin"] == "user"
+
+
+def test_value_validates_url_list():
normalised = validate_reference_value(
- "jira",
{"urls": ["https://your-org.atlassian.net/browse/PROJ-123"]},
)
assert normalised == {"urls": ["https://your-org.atlassian.net/browse/PROJ-123"]}
-def test_jira_value_strips_unknown_fields():
+def test_value_strips_unknown_fields():
normalised = validate_reference_value(
- "jira",
{"urls": ["https://x.atlassian.net/browse/AB-1"], "bogus": "drop me"},
)
assert normalised == {"urls": ["https://x.atlassian.net/browse/AB-1"]}
-def test_jira_empty_url_list_is_rejected():
+def test_empty_url_list_is_rejected():
with pytest.raises(ValueError):
- validate_reference_value("jira", {"urls": []})
+ validate_reference_value({"urls": []})
-def test_unknown_type_is_rejected():
+def test_missing_urls_key_is_rejected():
+ """Regression: ``urls`` used to carry ``default_factory=list``, and pydantic
+ does not validate defaults, so an empty bag silently became ``{"urls": []}``
+ instead of failing ``min_length=1``."""
with pytest.raises(ValueError):
- validate_reference_type("not_a_real_type")
-
-
-def test_serialize_used_types_includes_jira():
- used = serialize_used_types({"jira"})
- assert used["jira"]["display_name"] == "Jira"
- assert "instructions" in used["jira"]
+ validate_reference_value({})