voice-firewall-client 0.1.0__tar.gz

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,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
+ # The sdist ships the package, README and licences only; the tests stay in the repository.
2
+ prune tests
3
+ global-exclude *.py[cod]
@@ -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,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,93 @@
1
+ # voice-firewall-client
2
+
3
+ The client for the hosted Voice Firewall. The firewall decides whether your voice bot's
4
+ tool calls may run: who the caller is, whether they read back a texted code, and whether
5
+ the account holder approved a payment on their phone. That logic runs on the service. This
6
+ package sends the bot's tool calls and the caller's words there, runs your own tool
7
+ functions only when the service says so, and wires it into Pipecat or LiveKit Agents.
8
+
9
+ You need an API key for the service. The step-by-step guide is the hosted quickstart,
10
+ `docs/hosted-quickstart.md` in the Voice Firewall repository, with a copyable example bot in
11
+ `examples/hosted_bot/`.
12
+
13
+ ## Install
14
+
15
+ ```
16
+ pip install voice-firewall-client # plain Python (scripts, tests)
17
+ pip install "voice-firewall-client[pipecat]" # with Pipecat
18
+ pip install "voice-firewall-client[livekit]" # with LiveKit Agents
19
+ ```
20
+
21
+ Python 3.11 or newer. The only required dependency is `httpx`.
22
+
23
+ ## Example
24
+
25
+ A plain script, no voice pipeline. `heard` is the caller speaking; `call` is the model
26
+ asking for a tool. Your function runs only if the firewall allows it.
27
+
28
+ ```python
29
+ import asyncio, os
30
+ from voice_firewall_client import RemoteFirewall
31
+
32
+ def lookup_order(order_id: str, account_id: str) -> dict: # account_id comes from the service
33
+ return {"order_id": order_id, "status": "shipped", "account_id": account_id}
34
+
35
+ fw = RemoteFirewall(url=os.environ["VFW_URL"], api_key=os.environ["VFW_API_KEY"])
36
+ fw.implement("lookup_order", lookup_order)
37
+
38
+ async def main() -> None:
39
+ async with fw.session("+15550100001") as s: # the caller's phone number
40
+ await s.heard("Where is my order A-1001?")
41
+ answer = await s.call("lookup_order", order_id="A-1001")
42
+ print(answer["status"]) # executed, denied, pending_approval...
43
+
44
+ asyncio.run(main())
45
+ ```
46
+
47
+ ## In a voice pipeline
48
+
49
+ Pipecat (put `guard.processor()` right after speech-to-text):
50
+
51
+ ```python
52
+ guard = await fw.pipecat_tools(caller_id)
53
+ guard.register(llm)
54
+ context = LLMContext(messages, tools=guard.tools_schema())
55
+ pipeline = Pipeline([transport.input(), stt, guard.processor(),
56
+ user_aggregator, llm, tts, transport.output(), assistant_aggregator])
57
+ ```
58
+
59
+ With a speech-to-speech model (Gemini Live, OpenAI Realtime), use
60
+ `fw.pipecat_tools(caller_id, words_wait_seconds=1.5)`.
61
+
62
+ LiveKit Agents:
63
+
64
+ ```python
65
+ guard = await fw.livekit_tools(caller_id)
66
+ agent = Agent(instructions="...", tools=guard.tools())
67
+ guard.attach(session) # before session.start
68
+ ctx.add_shutdown_callback(guard.aclose)
69
+ ```
70
+
71
+ ## Good to know
72
+
73
+ - Your function runs only when the service sends a `run` event for it, with the arguments
74
+ the service sends. A function that takes `account_id` gets the account the service
75
+ matched to the caller; the model can never set it. Raise `NotDone("reason")` if your
76
+ function could not do the thing.
77
+ - The answer's `status` is one of `executed`, `denied`, `pending_approval`, `withheld`,
78
+ `approval_unavailable`, `invalid_arguments`, `error`, `session_closed`, or for the code
79
+ tools `sent`, `refused`, `verified`, `wrong`, `locked`, `expired`, `no_code`. Only `error`
80
+ means something failed.
81
+ - Send the caller's words before each call. A tool runs only after the caller said one of
82
+ its keywords; otherwise you get `denied` with `"reason": "intent_not_heard"`.
83
+ - If the service can't be reached, the model is told nothing was done. Tools never run
84
+ locally as a fallback.
85
+ - The URL must be `https://` (plain `http://` only for localhost).
86
+ - What goes to the service: the caller ID, final transcriptions of what the caller said,
87
+ each tool call (name, arguments, call id) and what your functions return.
88
+ - The client never logs your key, tool arguments, results, transcripts or spoken lines.
89
+ Pipecat and LiveKit log some of these at debug level, so run your bot at INFO or above.
90
+ - In test mode, `await fw.inbox()` returns the texts the service would have sent (codes
91
+ and approval links). They are secrets: don't log them.
92
+
93
+ License: Apache-2.0.
@@ -0,0 +1,50 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "voice-firewall-client"
7
+ version = "0.1.0"
8
+ description = "Thin client for the hosted Voice Firewall: HTTP calls plus Pipecat and LiveKit glue."
9
+ readme = "README.md"
10
+ license = "Apache-2.0"
11
+ license-files = ["LICENSE", "NOTICE"]
12
+ requires-python = ">=3.11"
13
+ dependencies = ["httpx>=0.27"]
14
+ keywords = ["voice", "agents", "pipecat", "livekit", "tool-calling", "security", "firewall"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Topic :: Communications :: Telephony",
24
+ "Topic :: Security",
25
+ "Typing :: Typed",
26
+ ]
27
+
28
+ [project.optional-dependencies]
29
+ pipecat = ["pipecat-ai>=1.15,<2"]
30
+ livekit = ["livekit-agents>=1.8,<2"]
31
+
32
+ [tool.setuptools]
33
+ packages = ["voice_firewall_client"]
34
+
35
+ [tool.setuptools.package-data]
36
+ voice_firewall_client = ["py.typed"]
37
+
38
+ [tool.ruff]
39
+ line-length = 100
40
+ target-version = "py311"
41
+
42
+ [tool.ruff.lint]
43
+ select = ["E", "W", "F", "I", "UP", "B", "C4", "SIM", "TCH", "RUF"]
44
+ ignore = ["E501"]
45
+
46
+ [tool.pytest.ini_options]
47
+ asyncio_mode = "auto"
48
+ asyncio_default_fixture_loop_scope = "function"
49
+ testpaths = ["tests"]
50
+ pythonpath = [".", "tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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"