Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
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.pyindex 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 jsonimport loggingfrom 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.pyindex 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 (whichfails loud on bad agents / refs / config), then inline references and docs areattached, with any post-creation failures collected into ``failed_attachments``rather than silently dropped.++Export emits resolved rooms and never emits ``params:``."""from __future__ import annotationsimport logging+import refrom typing import TYPE_CHECKING, Any, Literal, castimport 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 eif 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 ediff --git a/core/tests/switch_core/test_rooms_yaml.py b/core/tests/switch_core/test_rooms_yaml.pyindex 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 RoomLinkStorefrom switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStorefrom 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