voice-firewall-client 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ """Client for the hosted Voice Firewall. The firewall's logic runs on the service; this
2
+ package only talks to it and wires it into Pipecat or LiveKit Agents."""
3
+ from __future__ import annotations
4
+
5
+ from .client import (
6
+ REFUSED,
7
+ UNREACHABLE,
8
+ FirewallError,
9
+ NotDone,
10
+ RemoteFirewall,
11
+ RemoteSession,
12
+ ScriptSession,
13
+ )
14
+
15
+ __all__ = ["REFUSED", "UNREACHABLE", "FirewallError", "NotDone", "RemoteFirewall", "RemoteSession",
16
+ "ScriptSession"]
17
+ __version__ = "0.1.0"
@@ -0,0 +1,593 @@
1
+ """HTTP client for the hosted Voice Firewall (contract: docs/hosted-service.md).
2
+
3
+ The firewall's logic runs on the service. This side only:
4
+
5
+ - opens a session for a caller and gets the tool list,
6
+ - sends what the caller said (``/heard``) and the model's tool calls (``/calls``),
7
+ - long-polls ``/events`` and runs the bot's own functions when a ``run`` event names them.
8
+
9
+ Nothing here decides anything. If the service can't be reached, the model is told the tool
10
+ didn't happen; a tool never runs locally as a fallback.
11
+
12
+ Logging: only ids, tool names, statuses and error type names. Never arguments, results,
13
+ transcripts, spoken lines or the API key.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import asyncio
18
+ import contextlib
19
+ import inspect
20
+ import json
21
+ import logging
22
+ import urllib.parse
23
+ import uuid
24
+ from typing import TYPE_CHECKING, Any, Final
25
+
26
+ import httpx
27
+
28
+ if TYPE_CHECKING:
29
+ from collections.abc import Awaitable, Callable
30
+
31
+ from .livekit import FirewallLiveKit
32
+ from .pipecat import FirewallTools
33
+
34
+ logger = logging.getLogger("voice_firewall_client")
35
+
36
+ # What the model gets when the service can't answer: the tool didn't happen.
37
+ UNREACHABLE: Final = {"status": "error",
38
+ "message": "The firewall couldn't be reached, so nothing was done."}
39
+ # What the model gets when the service turned the request down (a 4xx).
40
+ REFUSED: Final = {"status": "error",
41
+ "message": "The firewall refused this request, so nothing was done."}
42
+ # What the model gets once the service has closed the session (for example after the tester
43
+ # changed their tools): nothing more can happen in it; the bot must open a new session.
44
+ SESSION_CLOSED: Final = {"status": "session_closed",
45
+ "message": "The firewall closed this session, so nothing was done. "
46
+ "A new session is needed."}
47
+
48
+ # The service is done with this session: 401 (key refused), 403 (the tester is suspended),
49
+ # 404 (session closed). Nothing more happens in it; the events loop stops.
50
+ _CLOSED_STATUSES: Final = frozenset({401, 403, 404})
51
+ _LOCAL_HOSTS: Final = frozenset({"localhost", "127.0.0.1", "::1"})
52
+ _DELETE_TIMEOUT_SECONDS: Final = 2.0
53
+ # The DELETE's hard stop: httpx's timeout plus a margin for a transport that ignores it.
54
+ DELETE_CAP_SECONDS: Final = _DELETE_TIMEOUT_SECONDS + 0.5
55
+ _RESULT_RETRY_DELAYS: Final = (0.5, 1.0, 2.0)
56
+ # A session open answered 409 (the tester's tools are changing): open again after these
57
+ # waits, 30.5 s in all. A change takes at most the service's job timeout (15 s) plus 5 s to
58
+ # drain, then closing the old firewall and copying its spending: well inside this.
59
+ OPEN_RETRY_DELAYS: tuple[float, ...] = (0.5, 1.0, 2.0, 4.0, 5.0, 5.0, 6.5, 6.5)
60
+
61
+
62
+ class NotDone(Exception):
63
+ """Raise from a bot function to say it didn't do the thing, with a short reason."""
64
+
65
+ def __init__(self, reason: str) -> None:
66
+ super().__init__(reason)
67
+ self.reason = reason
68
+
69
+
70
+ class FirewallError(Exception):
71
+ """The service couldn't open a session or read the inbox. Never carries the API key or a
72
+ request body."""
73
+
74
+
75
+ def _check_url(url: str) -> str:
76
+ """https only (plain http just for this machine), and no user:password in it."""
77
+ parts = urllib.parse.urlsplit(url)
78
+ if parts.username is not None or parts.password is not None:
79
+ raise ValueError("the firewall url must not contain a user name or password")
80
+ if "?" in url or "#" in url:
81
+ raise ValueError("the firewall url must not have a query (?) or fragment (#)")
82
+ host = parts.hostname
83
+ if not host:
84
+ raise ValueError("the firewall url needs a host, such as https://firewall.example.com")
85
+ if parts.scheme == "https" or (parts.scheme == "http" and host in _LOCAL_HOSTS):
86
+ return url.rstrip("/")
87
+ raise ValueError("the firewall url must start with https:// "
88
+ "(plain http:// only for localhost, 127.0.0.1 or ::1)")
89
+
90
+
91
+ def _accepts_account_id(fn: Callable[..., Any]) -> bool:
92
+ try:
93
+ parameters = inspect.signature(fn).parameters.values()
94
+ except (TypeError, ValueError):
95
+ return False
96
+ for p in parameters:
97
+ if p.kind is inspect.Parameter.VAR_KEYWORD:
98
+ return True
99
+ if p.name == "account_id" and p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD,
100
+ inspect.Parameter.KEYWORD_ONLY):
101
+ return True
102
+ return False
103
+
104
+
105
+ class RemoteFirewall:
106
+ """The tester's handle on the hosted firewall: where it is, the key, the bot's functions."""
107
+
108
+ def __init__(
109
+ self,
110
+ url: str,
111
+ api_key: str,
112
+ *,
113
+ timeout_seconds: float = 10.0,
114
+ call_timeout_seconds: float = 18.0,
115
+ events_wait_seconds: int = 20,
116
+ transport: httpx.AsyncBaseTransport | None = None,
117
+ ) -> None:
118
+ """``call_timeout_seconds`` is for ``/calls``, which waits while the bot runs a job
119
+ (the service waits up to 15 s for it), and bounds how long a job's result is retried.
120
+ ``transport`` is for tests."""
121
+ if not url:
122
+ raise ValueError("url is required")
123
+ if not api_key:
124
+ raise ValueError("api_key is required")
125
+ if not 1 <= events_wait_seconds <= 25:
126
+ raise ValueError("events_wait_seconds must be between 1 and 25")
127
+ self._url = _check_url(url)
128
+ self._base = self._url + "/v1"
129
+ self._key = api_key
130
+ self._timeout = timeout_seconds
131
+ self._call_timeout = call_timeout_seconds
132
+ self._events_wait = events_wait_seconds
133
+ self._transport = transport
134
+ self._functions: dict[str, Callable[..., Any]] = {}
135
+
136
+ def __repr__(self) -> str: # never the key; the url has no credentials (checked above)
137
+ return f"RemoteFirewall(url={self._url!r})"
138
+
139
+ def implement(self, name: str, fn: Callable[..., Any]) -> None:
140
+ """The bot's own function for tool ``name``. Sync functions run in a thread.
141
+
142
+ If ``fn`` takes an ``account_id`` keyword (or ``**kwargs``), it gets the account the
143
+ service matched the caller to."""
144
+ if not callable(fn):
145
+ raise TypeError("fn must be callable")
146
+ self._functions[name] = fn
147
+
148
+ async def open_session(self, caller_id: str) -> RemoteSession:
149
+ """Open a session for this caller. Raises ``FirewallError`` if the service says no."""
150
+ http = httpx.AsyncClient(
151
+ base_url=self._base, transport=self._transport, timeout=self._timeout,
152
+ headers={"Authorization": f"Bearer {self._key}"},
153
+ )
154
+ try:
155
+ response = await http.post("/sessions", json={"caller_id": caller_id})
156
+ for delay in OPEN_RETRY_DELAYS:
157
+ if response.status_code != 409:
158
+ break
159
+ # The tester's tools are changing: the service says open again shortly.
160
+ logger.info("firewall session open answered 409 (tools changing), "
161
+ "trying again in %ss", delay)
162
+ await asyncio.sleep(delay)
163
+ response = await http.post("/sessions", json={"caller_id": caller_id})
164
+ if not response.is_success:
165
+ raise FirewallError(f"the firewall refused the session (HTTP {response.status_code})")
166
+ body = response.json()
167
+ session_id = body["session_id"]
168
+ tools = body.get("tools", [])
169
+ if not isinstance(session_id, str) or not isinstance(tools, list):
170
+ raise FirewallError("the firewall sent a session it couldn't read")
171
+ except (httpx.HTTPError, ValueError, KeyError, TypeError, AttributeError) as exc:
172
+ await http.aclose()
173
+ raise FirewallError(f"couldn't reach the firewall ({type(exc).__name__})") from None
174
+ except BaseException: # FirewallError, and a cancel while it waits to try again
175
+ # Shielded, so a cancel can't stop the close itself half-way.
176
+ await asyncio.shield(http.aclose())
177
+ raise
178
+ logger.info("firewall session opened: %s", session_id)
179
+ return RemoteSession(self, http, session_id, bool(body.get("known_caller")), tools)
180
+
181
+ async def inbox(self) -> dict[str, Any]:
182
+ """Test mode: the texts the service would have sent (codes, approval links), so you
183
+ can read them back while you try your bot. ``{"mode": "test" or "live", "messages":
184
+ [{"at", "to_masked", "text"}]}``, newest first, the last 30 minutes. In live mode
185
+ (real SMS) it is always empty. Raises ``FirewallError`` if the service says no.
186
+
187
+ The texts hold secrets: this never logs them, and neither should you."""
188
+ try:
189
+ async with httpx.AsyncClient(
190
+ base_url=self._base, transport=self._transport, timeout=self._timeout,
191
+ headers={"Authorization": f"Bearer {self._key}"},
192
+ ) as http:
193
+ response = await http.get("/inbox")
194
+ if not response.is_success:
195
+ raise FirewallError(f"the firewall refused the inbox (HTTP {response.status_code})")
196
+ body = response.json()
197
+ if not isinstance(body, dict) or not isinstance(body.get("messages"), list):
198
+ raise FirewallError("the firewall sent an inbox it couldn't read")
199
+ except (httpx.HTTPError, ValueError) as exc:
200
+ raise FirewallError(f"couldn't reach the firewall ({type(exc).__name__})") from None
201
+ return body
202
+
203
+ def session(self, caller_id: str) -> ScriptSession:
204
+ """A session for a plain script, with no voice framework: ``async with
205
+ fw.session(caller_id) as s:``, then ``await s.heard(text)``, ``await s.call(tool,
206
+ **arguments)`` and ``await s.inbox()``. Your ``implement``-ed functions run through the
207
+ same events loop as the Pipecat and LiveKit plugins. Closed when the block ends."""
208
+ return ScriptSession(self, caller_id)
209
+
210
+ async def pipecat_tools(self, caller_id: str, **options: Any) -> FirewallTools:
211
+ """Open a session and wrap it for Pipecat (needs the ``pipecat`` extra)."""
212
+ from .pipecat import FirewallTools
213
+
214
+ return FirewallTools(await self.open_session(caller_id), **options)
215
+
216
+ async def livekit_tools(self, caller_id: str, **options: Any) -> FirewallLiveKit:
217
+ """Open a session and wrap it for LiveKit Agents (needs the ``livekit`` extra)."""
218
+ from .livekit import FirewallLiveKit
219
+
220
+ return FirewallLiveKit(await self.open_session(caller_id), **options)
221
+
222
+
223
+ class RemoteSession:
224
+ """One caller's session on the service, and its events loop."""
225
+
226
+ def __init__(self, firewall: RemoteFirewall, http: httpx.AsyncClient, session_id: str,
227
+ known_caller: bool, tools: list[dict[str, Any]]) -> None:
228
+ self._fw = firewall
229
+ self._http = http
230
+ self.session_id = session_id
231
+ self.known_caller = known_caller
232
+ self.tools = [t for t in tools if isinstance(t, dict) and isinstance(t.get("name"), str)]
233
+ self._on_event: Callable[[dict[str, Any]], Awaitable[None]] | None = None
234
+ self._loop_task: asyncio.Task[None] | None = None
235
+ self._jobs: set[asyncio.Task[None]] = set()
236
+ self._seen_jobs: set[str] = set()
237
+ self._closed = False
238
+ self._close_task: asyncio.Task[None] | None = None
239
+ # Set when the service answered 401, 403 or 404 for this session: it closed it.
240
+ self.closed_by_service = False
241
+
242
+ @property
243
+ def call_timeout(self) -> float:
244
+ return self._fw._call_timeout
245
+
246
+ @property
247
+ def started(self) -> bool:
248
+ return self._loop_task is not None
249
+
250
+ # -- what the plugins call ------------------------------------------------------------
251
+
252
+ async def heard(self, text: str) -> None:
253
+ """Send one final transcription. Failures are logged and dropped."""
254
+ if self._closed or self.closed_by_service:
255
+ logger.warning("transcription not recorded: the session is closed")
256
+ return
257
+ try:
258
+ response = await self._http.post(f"/sessions/{self.session_id}/heard",
259
+ json={"text": text})
260
+ if response.status_code in _CLOSED_STATUSES:
261
+ self._service_closed(response.status_code)
262
+ elif not response.is_success:
263
+ logger.warning("transcription not recorded (HTTP %s)", response.status_code)
264
+ except httpx.HTTPError as exc:
265
+ logger.warning("transcription not recorded (%s)", type(exc).__name__)
266
+
267
+ async def call(self, tool: str, arguments: Any, call_id: str) -> dict[str, Any]:
268
+ """Send the model's tool call. Returns the service's answer for the model, or an
269
+ error body when there isn't one. Never runs the tool here."""
270
+ if self.closed_by_service:
271
+ logger.warning("tool call %s not sent: the firewall closed this session", tool)
272
+ return dict(SESSION_CLOSED)
273
+ if self._closed:
274
+ logger.warning("tool call %s not sent: the session is closed", tool)
275
+ return dict(UNREACHABLE)
276
+ if isinstance(arguments, dict):
277
+ arguments = dict(arguments)
278
+ try:
279
+ response = await self._http.post(
280
+ f"/sessions/{self.session_id}/calls",
281
+ json={"tool": tool, "arguments": arguments, "call_id": call_id},
282
+ timeout=self._fw._call_timeout,
283
+ )
284
+ if response.status_code in _CLOSED_STATUSES:
285
+ self._service_closed(response.status_code)
286
+ return dict(SESSION_CLOSED)
287
+ if not response.is_success:
288
+ logger.warning("tool call %s failed (HTTP %s)", tool, response.status_code)
289
+ return dict(REFUSED if response.is_client_error else UNREACHABLE)
290
+ body = response.json()
291
+ except (httpx.HTTPError, ValueError, TypeError) as exc:
292
+ logger.warning("tool call %s failed (%s)", tool, type(exc).__name__)
293
+ return dict(UNREACHABLE)
294
+ if not isinstance(body, dict):
295
+ return dict(UNREACHABLE)
296
+ return body
297
+
298
+ def start(self, on_event: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
299
+ """Start the events loop on the running event loop (``RuntimeError`` without one).
300
+ ``on_event`` gets ``say`` and ``finished`` events; ``run`` events are handled here."""
301
+ loop = asyncio.get_running_loop()
302
+ self._on_event = on_event
303
+ if self._closed or (self._loop_task is not None and not self._loop_task.done()):
304
+ return
305
+ self._loop_task = loop.create_task(self._events_loop())
306
+
307
+ async def close(self, *, jobs_wait_seconds: float | None = None) -> None:
308
+ """Stop the events loop, let running jobs post their results (up to
309
+ ``jobs_wait_seconds``, by default the call timeout), then close the session on the
310
+ service. Every caller awaits the same close; safe to call any number of times."""
311
+ if self._close_task is None:
312
+ self._closed = True
313
+ wait = self._fw._call_timeout if jobs_wait_seconds is None else jobs_wait_seconds
314
+ self._close_task = asyncio.get_running_loop().create_task(self._close(wait))
315
+ # Shielded: a caller giving up doesn't stop the close itself.
316
+ await asyncio.shield(self._close_task)
317
+
318
+ async def _close(self, jobs_wait_seconds: float) -> None:
319
+ if self._loop_task is not None and not self._loop_task.done():
320
+ self._loop_task.cancel()
321
+ with contextlib.suppress(asyncio.CancelledError):
322
+ await self._loop_task
323
+ # A tool that ran must be reported: its result goes before the session closes.
324
+ if self._jobs and jobs_wait_seconds > 0:
325
+ await asyncio.wait(set(self._jobs), timeout=jobs_wait_seconds)
326
+ still_running = sum(not task.done() for task in self._jobs)
327
+ if still_running:
328
+ logger.error("closing the firewall session with %s tool(s) still running: their "
329
+ "results won't reach the service", still_running)
330
+ try:
331
+ # Bounded twice: httpx's timeout, and a hard stop in case a transport ignores it.
332
+ await asyncio.wait_for(
333
+ self._http.delete(f"/sessions/{self.session_id}", timeout=_DELETE_TIMEOUT_SECONDS),
334
+ DELETE_CAP_SECONDS)
335
+ except (httpx.HTTPError, TimeoutError) as exc:
336
+ logger.warning("session close failed (%s)", type(exc).__name__)
337
+ await self._http.aclose()
338
+ logger.info("firewall session closed: %s", self.session_id)
339
+
340
+ # -- the events loop ------------------------------------------------------------------
341
+
342
+ async def _events_loop(self) -> None:
343
+ wait = self._fw._events_wait
344
+ backoff = 0.5
345
+ while not self._closed:
346
+ try:
347
+ response = await self._http.get(f"/sessions/{self.session_id}/events",
348
+ params={"wait": wait}, timeout=wait + 10)
349
+ if response.status_code in _CLOSED_STATUSES:
350
+ self._service_closed(response.status_code)
351
+ return
352
+ if not response.is_success:
353
+ raise httpx.HTTPStatusError("bad status", request=response.request,
354
+ response=response)
355
+ events = response.json().get("events", [])
356
+ if not isinstance(events, list):
357
+ raise ValueError("events is not a list")
358
+ except asyncio.CancelledError:
359
+ raise
360
+ except (httpx.HTTPError, ValueError, AttributeError) as exc:
361
+ logger.warning("events poll failed (%s), retrying", type(exc).__name__)
362
+ await asyncio.sleep(backoff)
363
+ backoff = min(backoff * 2, 5.0)
364
+ continue
365
+ backoff = 0.5
366
+ for event in events:
367
+ if isinstance(event, dict):
368
+ await self._dispatch(event)
369
+
370
+ def _service_closed(self, status: int) -> None:
371
+ """The service answered 401, 403 or 404: it closed this session. Said once, clearly."""
372
+ if self.closed_by_service:
373
+ return
374
+ self.closed_by_service = True
375
+ if status == 403:
376
+ logger.error("firewall events stopped (HTTP 403): the tester is suspended; nothing "
377
+ "more happens in this session.")
378
+ elif status == 401:
379
+ logger.error("firewall events stopped (HTTP 401): the API key was refused or the "
380
+ "tester is suspended; nothing more happens in this session.")
381
+ else:
382
+ logger.error("firewall events stopped (HTTP %s): the firewall closed this session "
383
+ "(its tools may have changed). Open a new session to go on; nothing "
384
+ "more happens in this one.", status)
385
+
386
+ async def _dispatch(self, event: dict[str, Any]) -> None:
387
+ kind = event.get("type")
388
+ if kind == "run":
389
+ job_id = event.get("job_id")
390
+ if not isinstance(job_id, str) or job_id in self._seen_jobs:
391
+ return # a job runs once
392
+ self._seen_jobs.add(job_id)
393
+ # Run alongside the loop, so a slow tool doesn't hold up other events.
394
+ task = asyncio.get_running_loop().create_task(self._run_job(job_id, event))
395
+ self._jobs.add(task)
396
+ task.add_done_callback(self._jobs.discard)
397
+ elif kind in ("say", "finished"):
398
+ if self._on_event is None:
399
+ return
400
+ try:
401
+ await self._on_event(event)
402
+ except Exception as exc:
403
+ logger.error("firewall event %s not handled (%s)", kind, type(exc).__name__)
404
+
405
+ async def _run_job(self, job_id: str, event: dict[str, Any]) -> None:
406
+ # Nothing may escape this task: it is never awaited by anyone.
407
+ try:
408
+ deadline = asyncio.get_running_loop().time() + self._fw._call_timeout
409
+ tool = event.get("tool")
410
+ answer, ran = await self._answer_for(tool, event.get("arguments"),
411
+ event.get("account_id"))
412
+ await self._post_result(job_id, answer, deadline, tool=str(tool), ran=ran)
413
+ except Exception as exc:
414
+ logger.error("job %s failed in the client (%s)", job_id, type(exc).__name__)
415
+
416
+ async def _post_result(self, job_id: str, answer: str, deadline: float, *,
417
+ tool: str = "", ran: bool = False) -> None:
418
+ """Post once; retry network errors and 5xx while there's time. A 4xx is final
419
+ (404: the service already has an answer or dropped the job)."""
420
+ loop = asyncio.get_running_loop()
421
+ delays = iter(_RESULT_RETRY_DELAYS)
422
+ # An earlier post that timed out may have reached the service after all.
423
+ maybe_recorded = False
424
+ while True:
425
+ if self._http.is_closed:
426
+ if ran:
427
+ logger.error("tool %s ran but its result wasn't sent: the session is closed",
428
+ tool)
429
+ else:
430
+ logger.warning("job %s answer not sent: the session is closed", job_id)
431
+ return
432
+ try:
433
+ response = await self._http.post(
434
+ f"/jobs/{job_id}/result", content=answer,
435
+ headers={"Content-Type": "application/json"})
436
+ if response.is_success:
437
+ return
438
+ if response.status_code == 404 and maybe_recorded:
439
+ logger.warning("job %s result may already have been recorded (an earlier "
440
+ "post timed out, then HTTP 404)", job_id)
441
+ return
442
+ if response.status_code < 500:
443
+ if ran:
444
+ logger.error("tool %s ran but its result wasn't accepted (HTTP %s)",
445
+ tool, response.status_code)
446
+ else:
447
+ logger.warning("job %s answer not taken (HTTP %s)", job_id,
448
+ response.status_code)
449
+ return
450
+ problem = f"HTTP {response.status_code}"
451
+ except httpx.HTTPError as exc:
452
+ problem = type(exc).__name__
453
+ if isinstance(exc, httpx.TimeoutException) and not isinstance(
454
+ exc, httpx.ConnectTimeout):
455
+ maybe_recorded = True # sent, but no answer in time
456
+ delay = next(delays, None)
457
+ if delay is None or loop.time() + delay >= deadline:
458
+ logger.error("job %s result not sent (%s)", job_id, problem)
459
+ return
460
+ logger.warning("job %s result not sent (%s), retrying", job_id, problem)
461
+ await asyncio.sleep(delay)
462
+
463
+ async def _answer_for(self, tool: Any, arguments: Any, account_id: Any) -> tuple[str, bool]:
464
+ """Run the bot's function. Returns the JSON body to post, and whether it ran."""
465
+ fn = self._fw._functions.get(tool) if isinstance(tool, str) else None
466
+ if fn is None:
467
+ logger.warning("job for a tool the bot doesn't implement: %s", tool)
468
+ return json.dumps({"error": True}), False
469
+ if not isinstance(arguments, dict):
470
+ logger.warning("job for %s with unreadable arguments", tool)
471
+ return json.dumps({"error": True}), False
472
+ kwargs = dict(arguments)
473
+ kwargs.pop("account_id", None) # only the service names the account
474
+ if isinstance(account_id, str) and _accepts_account_id(fn):
475
+ kwargs["account_id"] = account_id
476
+ try:
477
+ if inspect.iscoroutinefunction(fn):
478
+ result = await fn(**kwargs)
479
+ else:
480
+ result = await asyncio.to_thread(fn, **kwargs)
481
+ if inspect.isawaitable(result):
482
+ result = await result
483
+ except NotDone as exc:
484
+ logger.info("tool %s not done", tool)
485
+ return json.dumps({"not_done": str(exc.reason)}), True
486
+ except Exception as exc:
487
+ logger.warning("tool %s raised %s", tool, type(exc).__name__)
488
+ return json.dumps({"error": True}), True
489
+ return _encode_result(tool, result), True
490
+
491
+
492
+ class ScriptSession:
493
+ """One caller's session driven by a script instead of a voice pipeline.
494
+
495
+ The script plays both parts: ``heard`` is the caller speaking, ``call`` is the model asking
496
+ for a tool. Your functions run only when the service sends a ``run`` event (the same
497
+ events loop and job checks as the plugins); ``call`` itself never runs anything. What the
498
+ bot would say is kept in ``says``; ended approvals in ``finished``. They can hold an
499
+ approval number: never log them.
500
+ """
501
+
502
+ def __init__(self, firewall: RemoteFirewall, caller_id: str) -> None:
503
+ self._fw = firewall
504
+ self._caller_id = caller_id
505
+ self._session: RemoteSession | None = None
506
+ self.says: list[str] = []
507
+ self.finished: list[dict[str, Any]] = []
508
+ self._taken = {"says": 0, "finished": 0} # how many each wait_for_* has returned
509
+ self._changed = asyncio.Event()
510
+
511
+ async def __aenter__(self) -> ScriptSession:
512
+ session = await self._fw.open_session(self._caller_id)
513
+ self._session = session
514
+ session.start(self._on_event)
515
+ return self
516
+
517
+ async def __aexit__(self, *exc: object) -> None:
518
+ await self.aclose()
519
+
520
+ @property
521
+ def remote(self) -> RemoteSession:
522
+ if self._session is None:
523
+ raise RuntimeError("use 'async with fw.session(caller_id) as s:' first")
524
+ return self._session
525
+
526
+ @property
527
+ def session_id(self) -> str:
528
+ return self.remote.session_id
529
+
530
+ @property
531
+ def known_caller(self) -> bool:
532
+ return self.remote.known_caller
533
+
534
+ @property
535
+ def tools(self) -> list[dict[str, Any]]:
536
+ return self.remote.tools
537
+
538
+ async def heard(self, text: str) -> None:
539
+ """The caller said ``text`` (a final transcription). Send it before each call."""
540
+ await self.remote.heard(text)
541
+
542
+ async def call(self, tool: str, /, **arguments: Any) -> dict[str, Any]:
543
+ """The model asks for ``tool``. Returns the service's answer, the one the model would
544
+ get: ``status`` (``executed``, ``denied``, ``pending_approval``, ``error``...) and
545
+ ``message``."""
546
+ return await self.remote.call(tool, arguments, uuid.uuid4().hex)
547
+
548
+ async def inbox(self) -> dict[str, Any]:
549
+ """Test mode: the texts the service would have sent. See ``RemoteFirewall.inbox``."""
550
+ return await self._fw.inbox()
551
+
552
+ async def wait_for_finished(self, timeout: float = 30.0) -> dict[str, Any]:
553
+ """The next ended approval (``{"type": "finished", "tool", "line", "note"}``) not yet
554
+ returned by this. Raises ``TimeoutError``."""
555
+ return await self._wait("finished", timeout)
556
+
557
+ async def wait_for_say(self, timeout: float = 30.0) -> str:
558
+ """The next line the bot would say, not yet returned by this. Raises ``TimeoutError``."""
559
+ return await self._wait("says", timeout)
560
+
561
+ async def aclose(self) -> None:
562
+ if self._session is not None:
563
+ await self._session.close()
564
+
565
+ async def _wait(self, kind: str, timeout: float) -> Any:
566
+ items: list[Any] = getattr(self, kind)
567
+ taken = self._taken[kind]
568
+ async with asyncio.timeout(timeout):
569
+ while len(items) <= taken:
570
+ self._changed.clear()
571
+ await self._changed.wait()
572
+ self._taken[kind] = taken + 1
573
+ return items[taken]
574
+
575
+ async def _on_event(self, event: dict[str, Any]) -> None:
576
+ if event.get("type") == "say" and isinstance(event.get("text"), str):
577
+ self.says.append(event["text"])
578
+ elif event.get("type") == "finished":
579
+ self.finished.append(dict(event))
580
+ self._changed.set()
581
+
582
+
583
+ def _encode_result(tool: Any, result: Any) -> str:
584
+ """The tool ran, so its result is always sent as a result, never as an error."""
585
+ try:
586
+ # Same rule as httpx (no NaN); anything else not JSON becomes text, e.g. Decimal.
587
+ return json.dumps({"result": result}, allow_nan=False, default=str)
588
+ except Exception: # NaN, tuple keys, a loop, or a str() that raises
589
+ logger.warning("tool %s ran; its result isn't JSON, so it's sent as text", tool)
590
+ try:
591
+ return json.dumps({"result": str(result)[:2000]})
592
+ except Exception:
593
+ return json.dumps({"result": "the tool ran; its result couldn't be encoded"})
@@ -0,0 +1,180 @@
1
+ """Hosted Voice Firewall for LiveKit Agents. Install with
2
+ ``pip install voice-firewall-client[livekit]``. In your agent's entrypoint::
3
+
4
+ fw = RemoteFirewall(url="https://...", api_key=os.environ["VFW_API_KEY"])
5
+ fw.implement("lookup_order", lookup_order)
6
+ guard = await fw.livekit_tools(caller_id)
7
+ agent = Agent(instructions=..., tools=guard.tools())
8
+ session = AgentSession(stt=..., llm=..., tts=..., vad=...)
9
+ guard.attach(session) # before session.start
10
+ ctx.add_shutdown_callback(guard.aclose) # results posted and session closed before exit
11
+ await session.start(agent=agent, room=ctx.room)
12
+
13
+ - ``tools()``: one raw function tool per tool the service offers. Each sends the call to the
14
+ service and returns only its answer.
15
+ - ``attach(session)``: sends final user transcriptions to the service, starts the events
16
+ loop, speaks the firewall's lines with ``session.say`` (never into the chat context when
17
+ the service says so), gives the model a finished approval's outcome, and closes the
18
+ firewall session when the agent session closes.
19
+ - ``aclose()``: waits for that close (running jobs post their results, then the session is
20
+ deleted). Register it with ``ctx.add_shutdown_callback`` so the worker doesn't exit first.
21
+ LiveKit kills the job process 10 s after shutdown starts (``shutdown_process_timeout``),
22
+ so the close takes at most 9 s: words still being sent, then running tools, then the
23
+ DELETE. A tool still running at the cap is logged as an ERROR and its result is lost. Bots
24
+ with slow tools should raise ``shutdown_process_timeout`` in their ``WorkerOptions``.
25
+
26
+ Logging: LiveKit logs tool arguments at debug level. Run the worker at INFO or above.
27
+ """
28
+ from __future__ import annotations
29
+
30
+ import asyncio
31
+ import contextlib
32
+ import json
33
+ import logging
34
+ import secrets
35
+ from typing import TYPE_CHECKING, Any
36
+
37
+ try:
38
+ from livekit.agents import RunContext, function_tool
39
+ except ImportError as exc: # pragma: no cover - only without the extra
40
+ raise ImportError(
41
+ "voice_firewall_client.livekit needs LiveKit Agents: "
42
+ "pip install voice-firewall-client[livekit]"
43
+ ) from exc
44
+
45
+ from .client import DELETE_CAP_SECONDS
46
+
47
+ if TYPE_CHECKING:
48
+ from .client import RemoteSession
49
+
50
+ logger = logging.getLogger("voice_firewall_client")
51
+
52
+ __all__ = ["FirewallLiveKit"]
53
+
54
+ # How long a tool call waits for transcriptions still being sent, so they arrive first.
55
+ _HEARD_WAIT_SECONDS = 5.0
56
+ # The whole close (words, jobs, DELETE) must end before LiveKit kills the job process, which
57
+ # it does shutdown_process_timeout (10 s by default) after shutdown starts.
58
+ _CLOSE_CAP_SECONDS = 9.0
59
+
60
+
61
+ def _call_id(context: Any) -> str:
62
+ """The model's own call id from LiveKit's RunContext; a random one if it's missing."""
63
+ call_id = getattr(getattr(context, "function_call", None), "call_id", None)
64
+ if isinstance(call_id, str) and call_id:
65
+ return call_id
66
+ return "lk-" + secrets.token_urlsafe(12)
67
+
68
+
69
+ class FirewallLiveKit:
70
+ """Puts a hosted firewall session between a LiveKit agent and the bot's tools."""
71
+
72
+ def __init__(self, session: RemoteSession) -> None:
73
+ self._session = session
74
+ self._agent_session: Any = None
75
+ self._heard: set[asyncio.Task[None]] = set()
76
+ self._closing: asyncio.Task[None] | None = None
77
+
78
+ @property
79
+ def session(self) -> RemoteSession:
80
+ return self._session
81
+
82
+ def tools(self) -> list[Any]:
83
+ """One LiveKit raw function tool per tool the service offers."""
84
+ return [self._tool_for(t["name"], t.get("description", ""),
85
+ t.get("parameters") or {"type": "object", "properties": {}})
86
+ for t in self._session.tools]
87
+
88
+ def attach(self, agent_session: Any) -> None:
89
+ """Listen to the session and use it to speak. Call before ``start``.
90
+
91
+ Called outside a running event loop (as the in-process plugin allows), the events
92
+ loop starts with the first transcription or tool call instead."""
93
+ if self._agent_session is not None:
94
+ raise RuntimeError("already attached to an agent session")
95
+ self._agent_session = agent_session
96
+ agent_session.on("user_input_transcribed", self._on_transcribed)
97
+ agent_session.on("close", self._on_close)
98
+ if not self._ensure_started():
99
+ logger.warning("attached outside an event loop: firewall events start with the "
100
+ "first transcription or tool call")
101
+
102
+ def _ensure_started(self) -> bool:
103
+ """Start the events loop if attached and on a running loop. True once started."""
104
+ if self._session.started:
105
+ return True
106
+ if self._agent_session is None:
107
+ return False
108
+ try:
109
+ self._session.start(self._on_event)
110
+ except RuntimeError:
111
+ return False
112
+ return True
113
+
114
+ def _tool_for(self, name: str, description: str, parameters: dict[str, Any]) -> Any:
115
+ async def handler(raw_arguments: dict[str, object], context: RunContext = None) -> str: # type: ignore[assignment]
116
+ self._ensure_started()
117
+ # Words heard before the call reach the service before it.
118
+ if self._heard:
119
+ await asyncio.wait(set(self._heard), timeout=_HEARD_WAIT_SECONDS)
120
+ call_id = _call_id(context)
121
+ return json.dumps(await self._session.call(name, raw_arguments, call_id))
122
+
123
+ handler.__name__ = name
124
+ return function_tool(handler, raw_schema={"name": name, "description": description,
125
+ "parameters": parameters})
126
+
127
+ def _on_transcribed(self, event: Any) -> None:
128
+ if not getattr(event, "is_final", False):
129
+ return
130
+ text = getattr(event, "transcript", "")
131
+ if not isinstance(text, str) or not text:
132
+ return
133
+ try:
134
+ task = asyncio.get_running_loop().create_task(self._session.heard(text))
135
+ self._ensure_started()
136
+ except RuntimeError:
137
+ logger.warning("transcription not recorded: no running event loop")
138
+ return
139
+ self._heard.add(task)
140
+ task.add_done_callback(self._heard.discard)
141
+
142
+ def _on_close(self, *_: Any) -> None:
143
+ with contextlib.suppress(RuntimeError): # no running loop: aclose() does it
144
+ self._start_close()
145
+
146
+ def _start_close(self) -> asyncio.Task[None]:
147
+ """The one close task: words still being sent go first, then jobs, then DELETE."""
148
+ if self._closing is None:
149
+ self._closing = asyncio.get_running_loop().create_task(self._close())
150
+ return self._closing
151
+
152
+ async def _close(self) -> None:
153
+ loop = asyncio.get_running_loop()
154
+ deadline = loop.time() + _CLOSE_CAP_SECONDS
155
+ # Leave room for the DELETE at the end; words first, then running tools.
156
+ budget = max(0.0, _CLOSE_CAP_SECONDS - DELETE_CAP_SECONDS)
157
+ if self._heard:
158
+ await asyncio.wait(set(self._heard), timeout=min(_HEARD_WAIT_SECONDS, budget))
159
+ jobs_wait = max(0.0, deadline - loop.time() - DELETE_CAP_SECONDS)
160
+ await self._session.close(jobs_wait_seconds=min(jobs_wait, self._session.call_timeout))
161
+
162
+ async def aclose(self) -> None:
163
+ """Close the firewall session and wait for it. Safe to call more than once."""
164
+ await asyncio.shield(self._start_close())
165
+
166
+ async def _on_event(self, event: dict[str, Any]) -> None:
167
+ session = self._agent_session
168
+ if session is None:
169
+ return
170
+ if event.get("type") == "say":
171
+ text = event.get("text")
172
+ if isinstance(text, str) and text:
173
+ session.say(text, add_to_chat_ctx=event.get("into_context") is True)
174
+ elif event.get("type") == "finished":
175
+ line, note = event.get("line"), event.get("note")
176
+ if isinstance(line, str) and line:
177
+ session.say(line, add_to_chat_ctx=True)
178
+ if isinstance(note, str) and note:
179
+ # The model was told "waiting for approval": give it the outcome to answer from.
180
+ session.generate_reply(instructions=note)
@@ -0,0 +1,182 @@
1
+ """Hosted Voice Firewall for Pipecat. Install with ``pip install voice-firewall-client[pipecat]``.
2
+
3
+ fw = RemoteFirewall(url="https://...", api_key=os.environ["VFW_API_KEY"])
4
+ fw.implement("lookup_order", lookup_order)
5
+ guard = await fw.pipecat_tools(caller_id)
6
+ guard.register(llm)
7
+ context = LLMContext(messages, tools=guard.tools_schema())
8
+ pipeline = Pipeline([transport.input(), stt, guard.processor(),
9
+ user_aggregator, llm, tts, transport.output(), assistant_aggregator])
10
+
11
+ - The handlers send each tool call to the service and give the model only its answer.
12
+ - ``processor()`` goes right after speech-to-text. It sends final transcriptions to the
13
+ service, starts the events loop when the pipeline starts, speaks the firewall's lines
14
+ (never into the model's context when the service says so), gives the model the outcome
15
+ of a finished approval, and closes the session when the pipeline ends.
16
+
17
+ Logging: Pipecat logs tool arguments and spoken lines at DEBUG. Run the bot at INFO or above.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import asyncio
22
+ import logging
23
+ import time
24
+ from typing import TYPE_CHECKING, Any
25
+
26
+ try:
27
+ from pipecat.adapters.llm.schemas.function_schema import FunctionSchema
28
+ from pipecat.adapters.llm.schemas.tools_schema import ToolsSchema
29
+ from pipecat.frames.frames import (
30
+ CancelFrame,
31
+ EndFrame,
32
+ Frame,
33
+ InterimTranscriptionFrame,
34
+ LLMMessagesAppendFrame,
35
+ StartFrame,
36
+ TranscriptionFrame,
37
+ TTSSpeakFrame,
38
+ )
39
+ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
40
+ except ImportError as exc: # pragma: no cover - only without the extra
41
+ raise ImportError(
42
+ "voice_firewall_client.pipecat needs Pipecat: pip install voice-firewall-client[pipecat]"
43
+ ) from exc
44
+
45
+ if TYPE_CHECKING:
46
+ from collections.abc import Callable
47
+
48
+ from .client import RemoteSession
49
+
50
+ logger = logging.getLogger("voice_firewall_client")
51
+
52
+ __all__ = ["FirewallProcessor", "FirewallTools"]
53
+
54
+ # How long the pipeline's cleanup waits for the session to close (jobs, then DELETE).
55
+ _CLOSE_WAIT_SECONDS = 25.0 # > default call timeout (18 s) + the DELETE (2.5 s)
56
+
57
+
58
+ class FirewallTools:
59
+ """Puts a hosted firewall session between a Pipecat LLM service and the bot's tools."""
60
+
61
+ def __init__(self, session: RemoteSession, *, words_wait_seconds: float = 0.0) -> None:
62
+ """``words_wait_seconds``: with a speech-to-speech model, wait up to this long for a
63
+ sentence still being transcribed before sending a tool call, so the firewall judges
64
+ it with the caller's words. Leave at 0 when speech-to-text feeds the model."""
65
+ if words_wait_seconds < 0:
66
+ raise ValueError("words_wait_seconds can't be negative")
67
+ self._session = session
68
+ self._words_wait = words_wait_seconds
69
+ self._processor = FirewallProcessor(self)
70
+
71
+ @property
72
+ def session(self) -> RemoteSession:
73
+ return self._session
74
+
75
+ async def aclose(self) -> None:
76
+ """Close the firewall session and wait for it: running jobs post their results,
77
+ then the session is deleted. Pipecat's runner does this in the processor's cleanup;
78
+ call it yourself if you don't run the pipeline. Safe to call more than once."""
79
+ await self._processor.aclose()
80
+
81
+ def tools_schema(self) -> ToolsSchema:
82
+ """The tools the service offers for this caller."""
83
+ return ToolsSchema(standard_tools=self.function_schemas())
84
+
85
+ def function_schemas(self) -> list[FunctionSchema]:
86
+ schemas = []
87
+ for tool in self._session.tools:
88
+ parameters = tool.get("parameters") or {}
89
+ schemas.append(FunctionSchema(
90
+ name=tool["name"], description=tool.get("description", ""),
91
+ properties=parameters.get("properties", {}),
92
+ required=parameters.get("required", []),
93
+ ))
94
+ return schemas
95
+
96
+ def register(self, llm: Any) -> None:
97
+ """Register a handler on the LLM service for each tool in ``tools_schema``."""
98
+ for tool in self._session.tools:
99
+ llm.register_function(tool["name"], self._handler_for(tool["name"]))
100
+
101
+ def processor(self) -> FirewallProcessor:
102
+ """The pipeline step to put right after speech-to-text."""
103
+ return self._processor
104
+
105
+ def _handler_for(self, name: str) -> Callable[[Any], Any]:
106
+ async def handler(params: Any) -> None:
107
+ if self._words_wait:
108
+ await self._processor.wait_for_words(self._words_wait)
109
+ result = await self._session.call(name, params.arguments, params.tool_call_id)
110
+ await params.result_callback(result)
111
+
112
+ return handler
113
+
114
+
115
+ class FirewallProcessor(FrameProcessor):
116
+ """Sends the caller's words to the service and says the service's lines.
117
+
118
+ Only transcriptions travelling downstream count: those come from your speech-to-text.
119
+ A speech-to-speech model sends its own transcript upstream; that isn't evidence.
120
+ """
121
+
122
+ def __init__(self, tools: FirewallTools) -> None:
123
+ super().__init__(name="VoiceFirewall")
124
+ self._tools = tools
125
+ self._sentence_open = False
126
+ self._closing: asyncio.Task[None] | None = None
127
+
128
+ async def wait_for_words(self, timeout: float) -> None:
129
+ """If a sentence is still being transcribed, wait up to ``timeout`` for it to finish."""
130
+ deadline = time.monotonic() + timeout
131
+ while self._sentence_open and time.monotonic() < deadline:
132
+ await asyncio.sleep(0.05)
133
+
134
+ async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
135
+ await super().process_frame(frame, direction)
136
+ downstream = direction == FrameDirection.DOWNSTREAM
137
+ if isinstance(frame, StartFrame):
138
+ self._tools.session.start(self._on_event)
139
+ elif isinstance(frame, InterimTranscriptionFrame):
140
+ if downstream and frame.text.strip():
141
+ self._sentence_open = True
142
+ elif isinstance(frame, TranscriptionFrame) and downstream:
143
+ await self._tools.session.heard(frame.text)
144
+ self._sentence_open = False
145
+ await self.push_frame(frame, direction)
146
+ if isinstance(frame, (EndFrame, CancelFrame)):
147
+ # Never hold the pipeline's end on the network: the close runs in the
148
+ # background, and cleanup() (awaited by Pipecat's runner) waits for it.
149
+ self.start_close()
150
+
151
+ def start_close(self) -> asyncio.Task[None]:
152
+ """Start closing the session (once). Running jobs post their results first."""
153
+ if self._closing is None:
154
+ self._closing = asyncio.get_running_loop().create_task(self._tools.session.close())
155
+ return self._closing
156
+
157
+ async def aclose(self, timeout: float = _CLOSE_WAIT_SECONDS) -> None:
158
+ """Close the session and wait for it, at most ``timeout`` seconds."""
159
+ try:
160
+ await asyncio.wait_for(asyncio.shield(self.start_close()), timeout)
161
+ except TimeoutError:
162
+ logger.error("firewall session close took over %s s; left running", timeout)
163
+
164
+ async def cleanup(self) -> None:
165
+ await super().cleanup()
166
+ await self.aclose()
167
+
168
+ async def _on_event(self, event: dict[str, Any]) -> None:
169
+ down = FrameDirection.DOWNSTREAM
170
+ if event.get("type") == "say":
171
+ text = event.get("text")
172
+ if isinstance(text, str) and text:
173
+ into_context = event.get("into_context") is True
174
+ await self.push_frame(TTSSpeakFrame(text, append_to_context=into_context), down)
175
+ elif event.get("type") == "finished":
176
+ line, note = event.get("line"), event.get("note")
177
+ if isinstance(line, str) and line:
178
+ await self.push_frame(TTSSpeakFrame(line, append_to_context=True), down)
179
+ if isinstance(note, str) and note:
180
+ # The model was told "waiting for approval": give it the outcome to answer from.
181
+ message = {"role": "user", "content": note}
182
+ await self.push_frame(LLMMessagesAppendFrame([message], run_llm=True), down)
File without changes
@@ -0,0 +1,120 @@
1
+ Metadata-Version: 2.4
2
+ Name: voice-firewall-client
3
+ Version: 0.1.0
4
+ Summary: Thin client for the hosted Voice Firewall: HTTP calls plus Pipecat and LiveKit glue.
5
+ License-Expression: Apache-2.0
6
+ Keywords: voice,agents,pipecat,livekit,tool-calling,security,firewall
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Topic :: Communications :: Telephony
15
+ Classifier: Topic :: Security
16
+ Classifier: Typing :: Typed
17
+ Requires-Python: >=3.11
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ License-File: NOTICE
21
+ Requires-Dist: httpx>=0.27
22
+ Provides-Extra: pipecat
23
+ Requires-Dist: pipecat-ai<2,>=1.15; extra == "pipecat"
24
+ Provides-Extra: livekit
25
+ Requires-Dist: livekit-agents<2,>=1.8; extra == "livekit"
26
+ Dynamic: license-file
27
+
28
+ # voice-firewall-client
29
+
30
+ The client for the hosted Voice Firewall. The firewall decides whether your voice bot's
31
+ tool calls may run: who the caller is, whether they read back a texted code, and whether
32
+ the account holder approved a payment on their phone. That logic runs on the service. This
33
+ package sends the bot's tool calls and the caller's words there, runs your own tool
34
+ functions only when the service says so, and wires it into Pipecat or LiveKit Agents.
35
+
36
+ You need an API key for the service. The step-by-step guide is the hosted quickstart,
37
+ `docs/hosted-quickstart.md` in the Voice Firewall repository, with a copyable example bot in
38
+ `examples/hosted_bot/`.
39
+
40
+ ## Install
41
+
42
+ ```
43
+ pip install voice-firewall-client # plain Python (scripts, tests)
44
+ pip install "voice-firewall-client[pipecat]" # with Pipecat
45
+ pip install "voice-firewall-client[livekit]" # with LiveKit Agents
46
+ ```
47
+
48
+ Python 3.11 or newer. The only required dependency is `httpx`.
49
+
50
+ ## Example
51
+
52
+ A plain script, no voice pipeline. `heard` is the caller speaking; `call` is the model
53
+ asking for a tool. Your function runs only if the firewall allows it.
54
+
55
+ ```python
56
+ import asyncio, os
57
+ from voice_firewall_client import RemoteFirewall
58
+
59
+ def lookup_order(order_id: str, account_id: str) -> dict: # account_id comes from the service
60
+ return {"order_id": order_id, "status": "shipped", "account_id": account_id}
61
+
62
+ fw = RemoteFirewall(url=os.environ["VFW_URL"], api_key=os.environ["VFW_API_KEY"])
63
+ fw.implement("lookup_order", lookup_order)
64
+
65
+ async def main() -> None:
66
+ async with fw.session("+15550100001") as s: # the caller's phone number
67
+ await s.heard("Where is my order A-1001?")
68
+ answer = await s.call("lookup_order", order_id="A-1001")
69
+ print(answer["status"]) # executed, denied, pending_approval...
70
+
71
+ asyncio.run(main())
72
+ ```
73
+
74
+ ## In a voice pipeline
75
+
76
+ Pipecat (put `guard.processor()` right after speech-to-text):
77
+
78
+ ```python
79
+ guard = await fw.pipecat_tools(caller_id)
80
+ guard.register(llm)
81
+ context = LLMContext(messages, tools=guard.tools_schema())
82
+ pipeline = Pipeline([transport.input(), stt, guard.processor(),
83
+ user_aggregator, llm, tts, transport.output(), assistant_aggregator])
84
+ ```
85
+
86
+ With a speech-to-speech model (Gemini Live, OpenAI Realtime), use
87
+ `fw.pipecat_tools(caller_id, words_wait_seconds=1.5)`.
88
+
89
+ LiveKit Agents:
90
+
91
+ ```python
92
+ guard = await fw.livekit_tools(caller_id)
93
+ agent = Agent(instructions="...", tools=guard.tools())
94
+ guard.attach(session) # before session.start
95
+ ctx.add_shutdown_callback(guard.aclose)
96
+ ```
97
+
98
+ ## Good to know
99
+
100
+ - Your function runs only when the service sends a `run` event for it, with the arguments
101
+ the service sends. A function that takes `account_id` gets the account the service
102
+ matched to the caller; the model can never set it. Raise `NotDone("reason")` if your
103
+ function could not do the thing.
104
+ - The answer's `status` is one of `executed`, `denied`, `pending_approval`, `withheld`,
105
+ `approval_unavailable`, `invalid_arguments`, `error`, `session_closed`, or for the code
106
+ tools `sent`, `refused`, `verified`, `wrong`, `locked`, `expired`, `no_code`. Only `error`
107
+ means something failed.
108
+ - Send the caller's words before each call. A tool runs only after the caller said one of
109
+ its keywords; otherwise you get `denied` with `"reason": "intent_not_heard"`.
110
+ - If the service can't be reached, the model is told nothing was done. Tools never run
111
+ locally as a fallback.
112
+ - The URL must be `https://` (plain `http://` only for localhost).
113
+ - What goes to the service: the caller ID, final transcriptions of what the caller said,
114
+ each tool call (name, arguments, call id) and what your functions return.
115
+ - The client never logs your key, tool arguments, results, transcripts or spoken lines.
116
+ Pipecat and LiveKit log some of these at debug level, so run your bot at INFO or above.
117
+ - In test mode, `await fw.inbox()` returns the texts the service would have sent (codes
118
+ and approval links). They are secrets: don't log them.
119
+
120
+ License: Apache-2.0.
@@ -0,0 +1,11 @@
1
+ voice_firewall_client/__init__.py,sha256=OjE7souIrpWLsJJmZTscVgTm-Dc0_N8ae9avboTbetc,509
2
+ voice_firewall_client/client.py,sha256=Tc2jvsqhu1LW7SMI-TD13U-hxQN3KUa-9qnnXqwe17s,29288
3
+ voice_firewall_client/livekit.py,sha256=__47qTnnho1MU1hAxPJpok66YUyOxVW-MNmoVffOexc,8350
4
+ voice_firewall_client/pipecat.py,sha256=orpMQrVNVoG2w5pTfuxR0BQr9F5kFqP882zg35BwFqc,8362
5
+ voice_firewall_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ voice_firewall_client-0.1.0.dist-info/licenses/LICENSE,sha256=2r0Ty-W2L4UO5RtwMTjJUlxarEQShnhzWgyutyOuwiQ,6783
7
+ voice_firewall_client-0.1.0.dist-info/licenses/NOTICE,sha256=Y8ODwXSDj6rNoYu2FzXvz5mMyDhUjswm1YUJPeN0pnM,129
8
+ voice_firewall_client-0.1.0.dist-info/METADATA,sha256=EMBZ-RJZ2Mb8FCQGQcT0uQRtoKidzL9s7-5c3vnwX88,5209
9
+ voice_firewall_client-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
10
+ voice_firewall_client-0.1.0.dist-info/top_level.txt,sha256=FTl2y1hIt4dFXBqUkktvi5c72NNIrN5OCivAqK7rYOE,22
11
+ voice_firewall_client-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,125 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship made available under
36
+ the License, as indicated by a copyright notice that is included in
37
+ or attached to the work (an example is provided in the Appendix below).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean, as submitted to the Licensor for inclusion
48
+ in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes
50
+ of this definition, "submitted" means any form of electronic, verbal,
51
+ or written communication sent to the Licensor or its representatives,
52
+ including but not limited to communication on electronic mailing lists,
53
+ source code control systems, and issue tracking systems that are managed
54
+ by, or on behalf of, the Licensor for the purpose of discussing and
55
+ improving the Work, but excluding communication that is conspicuously
56
+ marked or designated in writing by the copyright owner as "Not a
57
+ Contribution."
58
+
59
+ "Contributor" shall mean Licensor and any Legal Entity on behalf of
60
+ whom a Contribution has been received by the Licensor and included
61
+ within the Work.
62
+
63
+ 2. Grant of Copyright License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ copyright license to reproduce, prepare Derivative Works of,
67
+ publicly display, publicly perform, sublicense, and distribute the
68
+ Work and such Derivative Works in Source or Object form.
69
+
70
+ 3. Grant of Patent License. Subject to the terms and conditions of
71
+ this License, each Contributor hereby grants to You a perpetual,
72
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
73
+ (except as stated in this section) patent license to make, have made,
74
+ use, offer to sell, sell, import, and otherwise transfer the Work,
75
+ where such license applies only to those patent claims licensable
76
+ by such Contributor that are necessarily infringed by their
77
+ Contribution(s) alone or by the combination of their Contributions
78
+ with the Work to which such Contributions were submitted.
79
+
80
+ 4. Redistribution. You may reproduce and distribute copies of the
81
+ Work or Derivative Works thereof in any medium, with or without
82
+ modifications, and in Source or Object form, provided that You
83
+ meet the following conditions:
84
+
85
+ (a) You must give any other recipients of the Work or Derivative
86
+ Works a copy of this License; and
87
+
88
+ (b) You must cause any modified files to carry prominent notices
89
+ stating that You changed the files; and
90
+
91
+ (c) You must retain, in the Source form of any Derivative Works
92
+ that You distribute, all copyright, patent, trademark, and
93
+ attribution notices from the Source form of the Work,
94
+ excluding those notices that do not pertain to any part of
95
+ the Derivative Works; and
96
+
97
+ (d) If the Work includes a "NOTICE" text file, You must include a
98
+ readable copy of the attribution notices contained within such
99
+ NOTICE file, in at least one of the following places: within a
100
+ NOTICE text displayed to end-users, within the Source form or
101
+ documentation, or within a display generated by the Derivative
102
+ Works, if and within any third-party notices normally appear.
103
+
104
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
105
+ any Contribution intentionally submitted for inclusion in the Work
106
+ by You to the Licensor shall be under the terms and conditions of
107
+ this License, without any additional terms or conditions.
108
+
109
+ 6. Trademarks. This License does not grant permission to use the trade
110
+ names, trademarks, service marks, or product names of the Licensor,
111
+ except as required for reasonable and customary use in describing the
112
+ origin of the Work.
113
+
114
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed
115
+ to in writing, Licensor provides the Work on an "AS IS" BASIS,
116
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
117
+
118
+ 8. Limitation of Liability. In no event and under no legal theory shall
119
+ any Contributor be liable for damages arising from this software.
120
+
121
+ 9. Accepting Warranty or Additional Liability. While redistributing the
122
+ Work, You may offer acceptance of support, warranty, indemnity, or
123
+ other liability obligations consistent with this License.
124
+
125
+ END OF TERMS AND CONDITIONS
@@ -0,0 +1,3 @@
1
+ voice-firewall-client
2
+ Copyright 2024 VoiceFirewall contributors
3
+ Licensed under the Apache License, Version 2.0 (see LICENSE).
@@ -0,0 +1 @@
1
+ voice_firewall_client