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(rooms-yaml): typed params block with {var} interpolation (#402)

Abel Dantasb25fd23a3ac4
diff --git a/core/switch_core/gateway/rooms.py b/core/switch_core/gateway/rooms.py
index 0e81d45c0..061b6faeb 100644
--- a/core/switch_core/gateway/rooms.py
+++ b/core/switch_core/gateway/rooms.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import json
import logging
from typing import Annotated, cast
@@ -373,13 +374,31 @@ async def create_room_from_yaml(
rooms_yaml: Annotated[RoomYamlService, Depends(get_room_yaml_service)],
user: Annotated[User, Depends(get_current_user)],
) -> ProvisionResult:
- """Provision a single room and its attachments from a YAML spec. The body
- is the raw YAML text. Best-effort: the room is created first (fail-loud on
- bad config), then inline references/docs are attached, with post-creation
- failures surfaced in ``failed_attachments`` rather than dropped."""
- text = (await request.body()).decode("utf-8")
+ """Provision a single room and its attachments from a YAML spec.
+
+ Two content types are accepted:
+
+ * **Raw YAML** (``text/yaml``, ``text/plain``, or any non-JSON type): the
+ body is the template text. Only defaults-only templates work here
+ (no way to pass inputs).
+ * **JSON** (``application/json``): ``{"yaml": "<template text>",
+ "inputs": {...}}`` where ``inputs`` supplies values for declared
+ ``params:``.
+ """
+ content_type = request.headers.get("content-type", "")
try:
- spec = rooms_yaml.parse(text)
+ if "application/json" in content_type:
+ payload = json.loads(await request.body())
+ if not isinstance(payload, dict) or "yaml" not in payload:
+ raise ValueError("JSON body must have a 'yaml' key")
+ text = payload["yaml"]
+ if not isinstance(text, str):
+ raise ValueError("'yaml' must be a string")
+ inputs = payload.get("inputs")
+ else:
+ text = (await request.body()).decode("utf-8")
+ inputs = None
+ spec = rooms_yaml.parse(text, inputs=inputs)
return await rooms_yaml.provision(
spec, user_id=user.id, is_admin=user.role == "admin"
)
diff --git a/core/switch_core/rooms_yaml.py b/core/switch_core/rooms_yaml.py
index c3c28defe..2ef5eb0da 100644
--- a/core/switch_core/rooms_yaml.py
+++ b/core/switch_core/rooms_yaml.py
@@ -1,21 +1,27 @@
"""Declarative provisioning of a single room from YAML, and export back.
-This is the first step toward configurable room-network packages.
-v1 is deliberately a single-room bootstrap tool: one ``room:`` mapping is parsed
-into a fully-resolved :class:`RoomSpec` (no parameters / no templating), then
-provisioned in one shot on top of the existing :class:`RoomService.create_room`
-primitive. Export is the inverse: a live room is read back into the same
-surface so it round-trips.
+v0 supports a ``params:`` block beside ``room:`` that declares typed,
+defaultable placeholders. ``parse(text, inputs)`` resolves them and
+interpolates ``{name}`` throughout the ``room:`` tree before validation, so
+one file can stamp out many rooms with different inputs. A literal
+``{word}`` that collides with a declared param name *is* substituted — this
+is accepted for v0; ``sensitive: true`` is deferred to a later version.
+
+An optional top-level ``version:`` key (default ``0``) is accepted and
+validated as an integer, but not acted on yet.
Provisioning is room-first and best-effort: the room is created first (which
fails loud on bad agents / refs / config), then inline references and docs are
attached, with any post-creation failures collected into ``failed_attachments``
rather than silently dropped.
+
+Export emits resolved rooms and never emits ``params:``.
"""
from __future__ import annotations
import logging
+import re
from typing import TYPE_CHECKING, Any, Literal, cast
import yaml
@@ -40,6 +46,108 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
+# ── Template parameters (v0) ─────────────────────────────────────────────
+
+PLACEHOLDER_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class ParamSpec(BaseModel):
+ model_config = {"extra": "forbid"}
+ type: Literal["string", "number", "boolean", "enum"] = "string"
+ description: str | None = None
+ default: str | int | float | bool | None = None
+ enum: list[str] | None = None
+
+
+def _coerce(value: Any, spec: ParamSpec, name: str) -> str | int | float | bool:
+ """Coerce a raw input value to the declared type."""
+ t = spec.type
+ if t == "string":
+ return str(value)
+ if t == "number":
+ if isinstance(value, bool):
+ raise ValueError(f"param {name!r}: expected a number, got {value!r}")
+ if isinstance(value, int):
+ return value # keep int as int; no float roundtrip, no precision loss
+ try:
+ f = float(value)
+ return int(f) if f == int(f) else f
+ except (ValueError, TypeError, OverflowError) as e:
+ raise ValueError(f"param {name!r}: expected a number, got {value!r}") from e
+ if t == "boolean":
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, str):
+ low = value.lower()
+ if low in ("true", "1", "yes"):
+ return True
+ if low in ("false", "0", "no"):
+ return False
+ raise ValueError(f"param {name!r}: expected a boolean, got {value!r}")
+ # enum
+ s = str(value)
+ if spec.enum and s not in spec.enum:
+ raise ValueError(f"param {name!r}: {s!r} is not one of {spec.enum}")
+ return s
+
+
+def resolve_params(
+ declared: dict[str, ParamSpec],
+ inputs: dict[str, Any] | None,
+) -> dict[str, str | int | float | bool]:
+ """Merge inputs over defaults, enforce required, coerce types."""
+ if inputs is not None and not isinstance(inputs, dict):
+ raise ValueError("'inputs' must be a mapping of param name to value")
+ inputs = inputs or {}
+ undeclared = set(inputs) - set(declared)
+ if undeclared:
+ raise ValueError(f"Undeclared input(s): {', '.join(sorted(undeclared))}")
+ resolved: dict[str, str | int | float | bool] = {}
+ missing: list[str] = []
+ for name, spec in declared.items():
+ if name in inputs:
+ resolved[name] = _coerce(inputs[name], spec, name)
+ elif spec.default is not None:
+ resolved[name] = _coerce(spec.default, spec, name)
+ else:
+ missing.append(name)
+ if missing:
+ raise ValueError(f"Missing required param(s): {', '.join(missing)}")
+ return resolved
+
+
+def interpolate(
+ node: Any,
+ values: dict[str, str | int | float | bool],
+) -> Any:
+ """Recursively substitute ``{name}`` placeholders in *node*.
+
+ If an entire string is exactly one placeholder for a declared param the
+ typed value is returned unchanged (so a boolean/enum param can fill a
+ non-string field). Otherwise each declared placeholder in the string is
+ replaced with ``str(value)``. Undeclared ``{word}`` patterns are left
+ untouched so that JSON braces and other non-param patterns survive.
+ """
+ if isinstance(node, str):
+ # Whole-field substitution: the entire string is one placeholder.
+ m = PLACEHOLDER_RE.fullmatch(node)
+ if m and m.group(1) in values:
+ return values[m.group(1)]
+
+ # Partial substitution within the string.
+ def _replace(m: re.Match[str]) -> str:
+ key = m.group(1)
+ if key in values:
+ return str(values[key])
+ return m.group(0) # leave undeclared placeholders intact
+
+ return PLACEHOLDER_RE.sub(_replace, node)
+ if isinstance(node, dict):
+ return {k: interpolate(v, values) for k, v in node.items()}
+ if isinstance(node, list):
+ return [interpolate(item, values) for item in node]
+ return node
+
# ── Spec models ───────────────────────────────────────────────────────────
#
@@ -167,15 +275,50 @@ class RoomYamlService:
# ── Parse ─────────────────────────────────────────────────────────────
- def parse(self, text: str) -> RoomSpec:
+ def parse(self, text: str, inputs: dict[str, Any] | None = None) -> RoomSpec:
try:
data = yaml.safe_load(text)
except yaml.YAMLError as e:
raise ValueError(f"Invalid YAML: {e}") from e
if not isinstance(data, dict) or "room" not in data:
raise ValueError("YAML must have a single top-level 'room:' mapping")
+
+ allowed_keys = {"room", "params", "version"}
+ extra = set(data) - allowed_keys
+ if extra:
+ raise ValueError(f"Unknown top-level key(s): {', '.join(sorted(extra))}")
+
+ # version: accepted, not acted on yet.
+ version = data.get("version", 0)
+ if not isinstance(version, int):
+ raise ValueError(
+ f"'version' must be an integer, got {type(version).__name__}"
+ )
+
+ raw_params = data.get("params")
+ if raw_params is not None:
+ if not isinstance(raw_params, dict):
+ raise ValueError("'params' must be a mapping")
+ try:
+ declared = {
+ k: ParamSpec.model_validate(v) for k, v in raw_params.items()
+ }
+ except ValidationError as e:
+ raise ValueError(f"Invalid param spec: {e}") from e
+ else:
+ declared = {}
+
+ if inputs and not declared:
+ raise ValueError("Inputs supplied but the template declares no params")
+
+ if declared:
+ values = resolve_params(declared, inputs)
+ room_data = interpolate(data["room"], values)
+ else:
+ room_data = data["room"]
+
try:
- return RoomSpec.model_validate(data["room"])
+ return RoomSpec.model_validate(room_data)
except ValidationError as e:
raise ValueError(f"Invalid room spec: {e}") from e
diff --git a/core/tests/switch_core/test_rooms_yaml.py b/core/tests/switch_core/test_rooms_yaml.py
index c4b49ace3..064c5f461 100644
--- a/core/tests/switch_core/test_rooms_yaml.py
+++ b/core/tests/switch_core/test_rooms_yaml.py
@@ -44,7 +44,13 @@ from switch_core.db.stores.room_link_store import RoomLinkStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.room_service import RoomCreateConfig, RoomCreateResult
-from switch_core.rooms_yaml import ExistingReferenceById, RoomYamlService
+from switch_core.rooms_yaml import (
+ ExistingReferenceById,
+ ParamSpec,
+ RoomYamlService,
+ interpolate,
+ resolve_params,
+)
class FakeRoomService:
@@ -645,3 +651,432 @@ async def test_export_includes_users_from_bridge(env):
assert reparsed.name == "Bridged"
assert reparsed.bridge == "Mattermost"
assert reparsed.users == ["bob"]
+
+
+# ── resolve_params ──────────────────────────────────────────────────────────
+
+
+def test_resolve_params_defaults_only():
+ declared = {
+ "owner": ParamSpec(type="string"),
+ "repo": ParamSpec(type="string", default="sandbox-quantum/switch"),
+ }
+ values = resolve_params(declared, {"owner": "alice"})
+ assert values == {"owner": "alice", "repo": "sandbox-quantum/switch"}
+
+
+def test_resolve_params_override_default():
+ declared = {
+ "repo": ParamSpec(type="string", default="sandbox-quantum/switch"),
+ }
+ values = resolve_params(declared, {"repo": "other/repo"})
+ assert values == {"repo": "other/repo"}
+
+
+def test_resolve_params_missing_required():
+ declared = {"owner": ParamSpec(type="string")}
+ with pytest.raises(ValueError, match="Missing required param.*owner"):
+ resolve_params(declared, {})
+
+
+def test_resolve_params_undeclared_input():
+ declared = {"owner": ParamSpec(type="string")}
+ with pytest.raises(ValueError, match="Undeclared input.*extra"):
+ resolve_params(declared, {"owner": "a", "extra": "b"})
+
+
+def test_resolve_params_enum_valid():
+ declared = {
+ "vis": ParamSpec(type="enum", enum=["channel_public", "channel_private"]),
+ }
+ values = resolve_params(declared, {"vis": "channel_public"})
+ assert values == {"vis": "channel_public"}
+
+
+def test_resolve_params_enum_invalid():
+ declared = {
+ "vis": ParamSpec(type="enum", enum=["channel_public", "channel_private"]),
+ }
+ with pytest.raises(ValueError, match="not one of"):
+ resolve_params(declared, {"vis": "direct"})
+
+
+def test_resolve_params_boolean_coercion():
+ declared = {"flag": ParamSpec(type="boolean")}
+ assert resolve_params(declared, {"flag": True}) == {"flag": True}
+ assert resolve_params(declared, {"flag": "false"}) == {"flag": False}
+
+
+def test_resolve_params_number_coercion():
+ declared = {"count": ParamSpec(type="number")}
+ assert resolve_params(declared, {"count": "42"}) == {"count": 42}
+ assert resolve_params(declared, {"count": 3.14}) == {"count": 3.14}
+
+
+def test_resolve_params_number_bad():
+ declared = {"count": ParamSpec(type="number")}
+ with pytest.raises(ValueError, match="expected a number"):
+ resolve_params(declared, {"count": "abc"})
+
+
+def test_resolve_params_number_rejects_bool():
+ declared = {"count": ParamSpec(type="number")}
+ with pytest.raises(ValueError, match="expected a number"):
+ resolve_params(declared, {"count": True})
+
+
+def test_resolve_params_number_preserves_large_int():
+ declared = {"n": ParamSpec(type="number")}
+ big = 10**18 + 1 # loses precision if routed through float
+ assert resolve_params(declared, {"n": big}) == {"n": big}
+
+
+def test_resolve_params_rejects_non_dict_inputs():
+ declared = {"owner": ParamSpec(type="string")}
+ with pytest.raises(ValueError, match="'inputs' must be a mapping"):
+ resolve_params(declared, [1, 2, 3])
+
+
+# ── interpolate ─────────────────────────────────────────────────────────────
+
+
+def test_interpolate_whole_field_typed():
+ """A whole-field placeholder returns the typed value, not a string."""
+ result = interpolate("{flag}", {"flag": True})
+ assert result is True
+
+
+def test_interpolate_partial_string():
+ result = interpolate("hello {name}!", {"name": "world"})
+ assert result == "hello world!"
+
+
+def test_interpolate_undeclared_left_intact():
+ result = interpolate("{unknown} stays", {})
+ assert result == "{unknown} stays"
+
+
+def test_interpolate_nested_dict_and_list():
+ node = {
+ "a": "{x}",
+ "b": ["{y}", "literal"],
+ "c": {"nested": "prefix-{x}"},
+ }
+ values = {"x": "X", "y": "Y"}
+ result = interpolate(node, values)
+ assert result == {
+ "a": "X",
+ "b": ["Y", "literal"],
+ "c": {"nested": "prefix-X"},
+ }
+
+
+def test_interpolate_non_string_passthrough():
+ assert interpolate(42, {"x": "y"}) == 42
+ assert interpolate(None, {"x": "y"}) is None
+
+
+# ── parse with params ──────────────────────────────────────────────────────
+
+
+def test_parse_with_params_defaults_only(env):
+ spec = _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ default: "alice"
+ room:
+ name: "{owner} local-deploy"
+ description: "{owner}'s room"
+ """
+ )
+ assert spec.name == "alice local-deploy"
+ assert spec.description == "alice's room"
+
+
+def test_parse_with_params_override(env):
+ spec = _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ default: "alice"
+ room:
+ name: "{owner} local-deploy"
+ description: "{owner}'s room"
+ """,
+ inputs={"owner": "bob"},
+ )
+ assert spec.name == "bob local-deploy"
+
+
+def test_parse_with_params_missing_required_raises(env):
+ with pytest.raises(ValueError, match="Missing required param.*owner"):
+ _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ room:
+ name: "{owner} room"
+ description: "d"
+ """
+ )
+
+
+def test_parse_with_params_undeclared_input_raises(env):
+ with pytest.raises(ValueError, match="Undeclared input.*extra"):
+ _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ room:
+ name: "{owner} room"
+ description: "d"
+ """,
+ inputs={"owner": "a", "extra": "b"},
+ )
+
+
+def test_parse_inputs_against_paramless_file_raises(env):
+ with pytest.raises(ValueError, match="no params"):
+ _svc(env).parse(
+ """
+ room:
+ name: "R"
+ description: "d"
+ """,
+ inputs={"owner": "a"},
+ )
+
+
+def test_parse_unknown_placeholder_left_intact(env):
+ spec = _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ room:
+ name: "{owner} room"
+ description: "JSON brace {not_a_param} survives"
+ """,
+ inputs={"owner": "alice"},
+ )
+ assert spec.description == "JSON brace {not_a_param} survives"
+
+
+def test_parse_whole_field_typed_substitution(env):
+ """An enum param used as the whole value of channel_type stays valid."""
+ spec = _svc(env).parse(
+ """
+ params:
+ visibility:
+ type: enum
+ enum: [channel_public, channel_private]
+ default: channel_private
+ room:
+ name: "R"
+ description: "d"
+ channel_type: "{visibility}"
+ """
+ )
+ assert spec.channel_type == "channel_private"
+
+
+def test_parse_interpolation_into_docs_content(env):
+ spec = _svc(env).parse(
+ """
+ params:
+ owner:
+ type: string
+ room:
+ name: "R"
+ description: "d"
+ docs:
+ - name: "Guide"
+ description: "d"
+ instructions: "i"
+ content: "Welcome, {owner}."
+ """,
+ inputs={"owner": "alice"},
+ )
+ assert spec.docs[0].content == "Welcome, alice."
+
+
+def test_parse_interpolation_into_references_value(env):
+ spec = _svc(env).parse(
+ """
+ params:
+ repo:
+ type: string
+ room:
+ name: "R"
+ description: "d"
+ references:
+ - type: github
+ name: "Repo"
+ description: "d"
+ instructions: "i"
+ value:
+ urls: ["https://github.com/{repo}"]
+ """,
+ inputs={"repo": "org/project"},
+ )
+ assert spec.references[0].value == {"urls": ["https://github.com/org/project"]} # type: ignore[union-attr]
+
+
+def test_parse_version_key_accepted(env):
+ spec = _svc(env).parse(
+ """
+ version: 0
+ room:
+ name: "R"
+ description: "d"
+ """
+ )
+ assert spec.name == "R"
+
+
+def test_parse_version_non_integer_rejected(env):
+ with pytest.raises(ValueError, match="integer"):
+ _svc(env).parse(
+ """
+ version: "one"
+ room:
+ name: "R"
+ description: "d"
+ """
+ )
+
+
+def test_parse_unknown_top_level_key_rejected(env):
+ with pytest.raises(ValueError, match="Unknown top-level key"):
+ _svc(env).parse(
+ """
+ room:
+ name: "R"
+ description: "d"
+ extra_key: bad
+ """
+ )
+
+
+# ── provision with params (integration) ────────────────────────────────────
+
+
+TEMPLATE = """\
+params:
+ owner:
+ type: string
+ description: Whose room this is
+ deploy_agent:
+ type: string
+ description: The agent that runs deployments
+ repo:
+ type: string
+ default: "sandbox-quantum/switch"
+ visibility:
+ type: enum
+ enum: [channel_public, channel_private]
+ default: channel_private
+room:
+ name: "{owner} local-deploy"
+ description: "{owner}'s local deployment room for {repo}"
+ channel_type: "{visibility}"
+ agents: ["{deploy_agent}"]
+ instructions: |
+ You run local deployments of {repo} for {owner}.
+"""
+
+
+async def test_provision_template_two_owners(env):
+ """The same template instantiates twice with different owners."""
+ svc = _svc(env)
+ r1 = await svc.provision(
+ svc.parse(
+ TEMPLATE, inputs={"owner": "alice", "deploy_agent": "claude-code.alice"}
+ ),
+ user_id=env["user_id"],
+ is_admin=False,
+ )
+ r2 = await svc.provision(
+ svc.parse(TEMPLATE, inputs={"owner": "bob", "deploy_agent": "claude-code.bob"}),
+ user_id=env["user_id"],
+ is_admin=False,
+ )
+ assert r1.room_name == "alice local-deploy"
+ assert r2.room_name == "bob local-deploy"
+ assert r1.room_id != r2.room_id
+
+ # Export shows resolved values, no placeholders.
+ yaml1 = await svc.export(r1.room_id)
+ yaml2 = await svc.export(r2.room_id)
+ assert "{owner}" not in yaml1
+ assert "{owner}" not in yaml2
+ assert "alice" in yaml1
+ assert "bob" in yaml2
+
+
+async def test_provision_template_missing_required_400(env):
+ """A required param left blank raises before any room is created."""
+ svc = _svc(env)
+ with pytest.raises(ValueError, match="Missing required param.*owner"):
+ svc.parse(TEMPLATE, inputs={"deploy_agent": "claude-code.alice"})
+
+ # Verify no room was created.
+ async with env["session_factory"]() as session:
+ rooms = (
+ (
+ await session.execute(
+ select(Room).where(Room.name.like("%local-deploy%"))
+ )
+ )
+ .scalars()
+ .all()
+ )
+ assert rooms == []
+
+
+# ── endpoint test (JSON body) ──────────────────────────────────────────────
+
+
+async def test_endpoint_json_body(env):
+ """Call the real create_room_from_yaml with a JSON request."""
+ import json
+ from unittest.mock import AsyncMock
+
+ from fastapi import HTTPException
+
+ from switch_core.gateway.rooms import create_room_from_yaml
+
+ svc = _svc(env)
+ user_id = env["user_id"]
+ user = User(name="alice", email="[email protected]", role="member")
+ # Poke the id to match the seeded user so provision works.
+ object.__setattr__(user, "id", user_id)
+
+ body = json.dumps(
+ {
+ "yaml": TEMPLATE,
+ "inputs": {"owner": "carol", "deploy_agent": "claude-code.alice"},
+ }
+ ).encode()
+
+ request = AsyncMock()
+ request.headers = {"content-type": "application/json"}
+ request.body.return_value = body
+
+ result = await create_room_from_yaml(request, svc, user)
+ assert result.room_name == "carol local-deploy"
+
+ # Non-string yaml value → 400.
+ bad_body = json.dumps({"yaml": 123}).encode()
+ request.body.return_value = bad_body
+ with pytest.raises(HTTPException) as exc_info:
+ await create_room_from_yaml(request, svc, user)
+ assert exc_info.value.status_code == 400