signalwire-sdk 3.7.0.dev127__tar.gz → 3.7.1.dev128__tar.gz

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [3.7.1] - 2026-10-13
+
+### Added
+- Semantic gates take `visual_input`: how many of the caller's newest video
+  frames the decision model sees with the gate, true for 1 or a whole number
+  up to 5. `SemanticGate(visual_input=...)` sets it, and gate dicts are
+  checked by the platform's rule. 3.7.0 refused the key, so a gate that
+  looks at the caller's video could only be written in raw SWML.
+
 ## [3.7.0] - 2026-10-12
 
 ### Fixed

{signalwire_sdk-3.7.0.dev127/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.7.1.dev128}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.7.0.dev127
+Version: 3.7.1.dev128
 Summary: SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation.
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/docs/api_reference.md

@@ -650,12 +650,13 @@ agent.define_tool(
 )
 ```
 
-`SemanticGate(question, threshold, on_fail, *, id=None, true_means=None, false_means=None)`:
+`SemanticGate(question, threshold, on_fail, *, id=None, true_means=None, false_means=None, visual_input=None)`:
 - `question` (str): The yes/no question, at most 8 KB. Its `${...}` variables are expanded from the call's global data when the gate is checked
 - `threshold` (float): The probability of yes, above 0 and at most 1, at or above which the gate passes
 - `on_fail` (Union[str, FunctionResult, Dict[str, Any]]): What the model gets when this is the first gate that fails: the tool result text, a `FunctionResult`, whose response and actions are used, or a data_map output dict. It needs a response, and in the `tool_result`/`tool_prompt` form a `tool_result`: a blocked call must never read as a success. The `tool_prompt` becomes a system message after the tool result; OpenAI Realtime agents don't use it, so put what they need in the `tool_result`. The actions run as written, without template expansion
 - `id` (Optional[str]): 1 to 64 letters, digits or underscores, unique within the function. Default `gate_<n>`, 1-based
 - `true_means`, `false_means` (Optional[str]): What yes and no mean, at most 2 KB each
+- `visual_input` (Optional[Union[bool, int]]): How many of the caller's newest video frames the decision model sees with this gate, as `visual_input`: True is 1, False or 0 none, or a whole number up to 5. Name it in the question, as in "Is the caller holding a photo ID up to the camera in `visual_input`?". All of a function's gates share one request, so each sees as many frames as the gate asking for the most. The gate provider must take images; one that doesn't makes the check a configuration error, which blocks the call. Left out by default. A function's own `visual_input`, frames sent to its webhook, is a separate `define_tool()` field
 
 Gates are checked by the platform's rules when the tool is defined. The platform refuses the whole function for an invalid gate, so the SDK raises `ValueError` instead. Gates aren't allowed on the hook names `startup_hook`, `hangup_hook` and `check_for_input`, on `end_call`, or on a built-in function's name.
 

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.7.0.dev127"
+version = "3.7.1.dev128"
 description = "SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation."
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/signalwire/signalwire/__init__.py

@@ -59,7 +59,7 @@ if TYPE_CHECKING:
     from signalwire.utils.schema_utils import SchemaValidationError
     from signalwire.web import WebService
 
-__version__ = "3.7.0.dev127"
+__version__ = "3.7.1.dev128"
 
 # §6.2-python (owner decision: NO packaging split — one package, all deps required;
 # IMPORT-TIME behavior only): the agent/web symbols are lazy-imported via module

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/signalwire/signalwire/agent_server.py

@@ -68,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.7.0.dev127",
+            version="3.7.1.dev128",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128}/signalwire/signalwire/core/semantic_gate.py

@@ -38,8 +38,10 @@ MAX_GATES = 8
 MAX_QUESTION_BYTES = 8192
 MAX_CRITERIA_BYTES = 2048
 MAX_ON_FAIL_BYTES = 8192
+# The most caller video frames a gate may ask for (AI_VISUAL_INPUT_MAX)
+MAX_VISUAL_INPUT = 5
 
-_GATE_KEYS = ("id", "question", "criteria", "threshold", "on_fail")
+_GATE_KEYS = ("id", "question", "criteria", "threshold", "on_fail", "visual_input")
 _GATE_ID = re.compile(r"[A-Za-z0-9_]{1,64}")
 
 # Hooks the platform calls itself, the function OART intercepts by name, and
@@ -102,6 +104,7 @@ class SemanticGate:
         id: str | None = None,
         true_means: str | None = None,
         false_means: str | None = None,
+        visual_input: bool | int | None = None,
     ) -> None:
         """
         Args:
@@ -122,6 +125,14 @@ class SemanticGate:
                 within the function. Default ``gate_<n>``, 1-based.
             true_means: What yes means, at most 2 KB.
             false_means: What no means, at most 2 KB.
+            visual_input: How many of the caller's newest video frames the
+                decision model sees with this gate, as ``visual_input``:
+                True is 1, False or 0 none, or a whole number up to 5. All of
+                a function's gates share one request, so each sees as many
+                frames as the gate asking for the most. The gate's provider
+                must take images; one that doesn't makes the check a
+                configuration error, which blocks the call. Default: no
+                frames, and the key is left out.
 
         Raises:
             ValueError: If ``on_fail`` has no response: a blocked call must
@@ -136,6 +147,7 @@ class SemanticGate:
         if false_means is not None:
             self.criteria["false"] = false_means
         self.on_fail: dict[str, Any] = _on_fail(on_fail)
+        self.visual_input = visual_input
 
     def to_dict(self) -> dict[str, Any]:
         """The gate as the platform reads it."""
@@ -147,6 +159,8 @@ class SemanticGate:
             gate["criteria"] = dict(self.criteria)
         gate["threshold"] = self.threshold
         gate["on_fail"] = json.loads(json.dumps(self.on_fail))
+        if self.visual_input is not None:
+            gate["visual_input"] = self.visual_input
         return gate
 
 
@@ -341,9 +355,29 @@ def _check_gate(gate: Any) -> str:
         gate_id = gate["id"]
         if not isinstance(gate_id, str) or not _GATE_ID.fullmatch(gate_id):
             return "id must be 1 to 64 letters, digits or underscores"
+    if "visual_input" in gate and not _valid_visual_input(gate["visual_input"]):
+        return (
+            "visual_input must be true, false or a whole number from 0 to "
+            f"{MAX_VISUAL_INPUT}"
+        )
     return ""
 
 
+def _valid_visual_input(value: Any) -> bool:
+    """Whether the platform reads ``value`` as a frame count.
+
+    A boolean, or a JSON number that is whole and from 0 to 5: 2.0 counts as
+    2, and 1.5, -1, 6, null and strings are refused.
+    """
+    if isinstance(value, bool):
+        return True
+    if not isinstance(value, (int, float)):
+        return False
+    if isinstance(value, float) and not (math.isfinite(value) and value.is_integer()):
+        return False
+    return 0 <= value <= MAX_VISUAL_INPUT
+
+
 def gate_definitions(
     gates: Sequence["SemanticGate | dict[str, Any]"], function: str
 ) -> list[dict[str, Any]]:

{signalwire_sdk-3.7.0.dev127 → signalwire_sdk-3.7.1.dev128/signalwire/signalwire_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.7.0.dev127
+Version: 3.7.1.dev128
 Summary: SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation.
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT