siphon-ai 0.1.0__tar.gz

siphon_ai-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.env
+*.pyc
+__pycache__/
+*.egg-info/
+dist/
+build/
+BRD.md
+SRD.md
+.env.local
+.env.*
+requirements.txt

siphon_ai-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,123 @@
+# SIPHON Code of Conduct
+
+## 1. Purpose
+
+SIPHON is a LiveKit-based telephony AI agent framework. It is intended to make it easier to build responsible, production-grade AI calling systems.
+
+This Code of Conduct defines expectations for everyone who participates in the SIPHON ecosystem, including:
+
+- Users of the framework
+- Contributors and maintainers
+- Community members in issues, discussions, and any official channels
+
+Our goal is to foster a respectful, safe, and inclusive environment for collaboration.
+
+---
+
+## 2. Scope
+
+This Code of Conduct applies to all SIPHON-related spaces, including but not limited to:
+
+- Project repositories and issue trackers
+- Pull requests, code reviews, and discussions
+- Any official communication channels hosted or moderated by SIPHON maintainers
+
+It also applies when representing the project in public spaces, such as conferences, social media, or blog posts, where you are identifiable as a SIPHON user, contributor, or maintainer.
+
+---
+
+## 3. Our Standards
+
+### 3.1 Expected behavior
+
+- **Be respectful**  
+  Treat everyone with courtesy and professionalism. Disagreement is normal; disrespect is not.
+
+- **Be inclusive**  
+  Welcome people of all backgrounds, experience levels, and identities. Avoid exclusionary or dismissive behavior.
+
+- **Be constructive**  
+  - Provide helpful feedback on issues, proposals, and pull requests.  
+  - Focus on the code, design, and use cases, not the person.
+
+- **Protect users and data**  
+  - Treat telephony and conversational data as sensitive by default.  
+  - Respect privacy laws and best practices when using SIPHON in production.  
+  - Avoid sharing real user data or secrets (API keys, credentials, phone numbers) in public spaces.
+
+- **Promote responsible AI use**  
+  - Avoid building or promoting abusive, deceptive, or clearly harmful calling experiences with SIPHON (e.g., fraud, harassment, spam).  
+  - Follow applicable laws and regulations in your jurisdiction, especially those related to telecom, privacy, consent, and AI.
+
+### 3.2 Unacceptable behavior
+
+- **Harassment or discrimination**, including:
+  - Hate speech, personal attacks, or slurs.
+  - Sexist, racist, or otherwise exclusionary comments or jokes.
+
+- **Abusive community behavior**, such as:
+  - Persistent trolling or flame wars.
+  - Threats of violence or doxxing.
+  - Deliberately derailing conversations or PRs.
+
+- **Irresponsible or malicious use of SIPHON**, including:
+  - Using SIPHON to create harassing, deceptive, or non-consensual calling systems.
+  - Intentionally bypassing consent, opt-out, or applicable telephony/AI regulations.
+  - Publicly sharing sensitive call logs, transcripts, or recordings without proper redaction and consent.
+
+- **Unprofessional collaboration**, such as:
+  - Repeatedly ignoring review feedback or project guidelines.
+  - Misrepresenting others’ work as your own.
+  - Spamming issues, PRs, or discussions.
+
+---
+
+## 4. Responsibilities of Maintainers
+
+- **Review and moderate**  
+  - Maintain a welcoming, respectful space in issues, PRs, and discussions.  
+  - Intervene when behavior violates this Code of Conduct.
+
+- **Set expectations clearly**  
+  - Provide clear contribution guidelines and technical direction.  
+  - Communicate decisions and project priorities in a respectful way.
+
+- **Take appropriate action**  
+  - Warn, restrict participation, or temporarily/permanently ban individuals when necessary.  
+  - Close or reject contributions that are abusive, obviously malicious, or substantially misaligned with project goals (e.g., promoting harmful telephony use cases).
+
+---
+
+## 5. Reporting & Enforcement
+
+- **How to report**  
+  - You can report violations or concerns by contacting the maintainers at:  
+    - Email: `siphon@blackdwarf.in`  
+  - Provide as much detail as possible (links, timestamps, screenshots) while respecting the privacy of those involved.
+
+- **How reports are handled**  
+  - Reports will be reviewed by the maintainers in good faith.  
+  - When appropriate, they may:
+    - Ask clarifying questions.  
+    - Take action on GitHub or other platforms (warnings, content removal, access restrictions).  
+    - Escalate or involve platform support if needed.
+
+- **Confidentiality**  
+  - The maintainers will treat reports as confidential to the extent reasonably possible, and will only share details as required to investigate and act.
+
+- **Consequences**  
+  - Actions may include, but are not limited to:
+    - Verbal or written warning  
+    - Temporary or permanent ban from project spaces  
+    - Reversion or rejection of contributions
+
+---
+
+## 6. Changes & Attribution
+
+- **Evolution**  
+  - This Code of Conduct may change over time as the project and community evolve.  
+  - Substantive changes will be documented in the repository history.
+
+- **Attribution**  
+  - This document is inspired by community standards such as the Contributor Covenant and similar open source Codes of Conduct, adapted for the SIPHON project and its telephony-AI context.

siphon_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,204 @@
+# Contributing to SIPHON
+
+Thank you for your interest in contributing to **SIPHON**, a LiveKit-based telephony AI agent framework.
+
+This document explains how to get set up for development, the types of contributions we welcome, and the standards we expect in this project.
+
+---
+
+## 1. Code of Conduct & Responsible Use
+
+By participating in this project, you agree to follow the:
+
+- **[SIPHON Code of Conduct](./CODE_OF_CONDUCT.md)**
+
+In addition, because SIPHON is used for **telephony and AI calling systems**, we expect contributors to:
+
+- Avoid building or promoting **harassing, deceptive, or non-consensual** calling flows.
+- Respect **privacy, telecom, and AI-related regulations** in your jurisdiction.
+- Treat call metadata, audio, and transcripts as **sensitive data** by default.
+
+---
+
+## 2. Ways to Contribute
+
+### 2.1 Good first issues
+
+- We may tag some GitHub issues with a label such as **"good first issue"** when they are well-scoped and suitable for newcomers.
+- If you’d like to work on one, please leave a short comment like **“Can I take this?”** so maintainers can assign it to you and avoid duplicate work.
+
+### 2.2 Bug reports
+
+- Use the issue tracker to report reproducible bugs.
+- Include environment details, SIP/telephony settings (without secrets), logs, and clear steps to reproduce.
+
+### 2.3 Feature requests & design proposals
+
+- Open an issue describing the **use case and motivation**, not only the implementation idea.
+- For larger or potentially breaking changes, start with a brief design discussion (via GitHub issue, discussion, or the project’s preferred chat channel) before writing a lot of code.
+
+### 2.4 Code contributions (PRs)
+
+- Fix bugs or add features that align with SIPHON’s goals: LiveKit-based AI telephony, agents, and tooling.
+- Keep changes focused and well-scoped; avoid huge PRs that mix unrelated changes.
+
+### 2.5 Documentation & examples
+
+- Improve docs, comments, and README sections.
+- Add small examples for common patterns (e.g. inbound agent, outbound dialer, provider-specific configs).
+
+---
+
+## 3. Development Setup
+
+### 3.1 Prerequisites
+
+- Python **3.10+**
+- Git
+- A LiveKit cloud / self-hosted project (for actual telephony tests)
+- Optionally: conda/virtualenv/uv/poetry to manage environments
+
+### 3.2 Clone the repository
+
+```bash
+git clone https://github.com/blackdwarftech/siphon.git
+cd siphon
+```
+
+### 3.3 Create a virtual environment (recommended)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate
+```
+
+### 3.4 Install SIPHON in editable mode
+
+SIPHON uses `pyproject.toml` with `hatchling`. For local development, install dependencies in editable mode:
+
+```bash
+pip install -e .
+```
+
+This will install `siphon-ai` and all required runtime dependencies (LiveKit, providers, etc.).
+
+### 3.5 Environment configuration
+
+- Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+- Fill in the secrets and configuration required for your setup, for example:
+  - LiveKit API keys / URLs
+  - Provider API keys (OpenAI, Anthropic, Groq, Deepgram, etc.)
+  - Storage / database connection strings if you want recording/metadata persistence
+
+Do **not** commit real secrets to the repository.
+
+---
+
+## 4. Running SIPHON During Development
+
+SIPHON is organized around:
+
+- `siphon.agent`  – agent runner and core entrypoint.
+- `siphon.telephony.inbound`  – inbound SIP trunk + dispatch helpers.
+- `siphon.telephony.outbound`  – outbound call helpers.
+- `siphon.plugins`  – model/STT/TTS provider integrations.
+
+Typical workflows during development:
+
+- **Run an agent worker locally** using `siphon.agent.runner.Agent`.
+- **Configure inbound calling** via `siphon.telephony.inbound.Dispatch`.
+- **Place outbound calls** via `siphon.telephony.outbound.Call`.
+
+---
+
+## 5. Coding Style & Guidelines
+
+- **Python style**
+  - Follow idiomatic Python and PEP 8 where practical.
+  - Prefer explicit over implicit; write clear, maintainable code over clever one-liners.
+
+- **Types**
+  - Use type hints where reasonable.
+  - Keep function signatures clear; use `Dict[str, Any]` only when the structure cannot be strongly typed yet.
+
+- **Logging & errors**
+  - Use the project’s `get_logger` helper for logging.
+  - Include enough context in error logs to debug telephony/agent issues (IDs, trunk/number, but no secrets).
+
+- **Abstractions**
+  - Keep **LiveKit-specific wiring** localized in `siphon.telephony` and `siphon.agent.core`.
+  - Keep provider-specific logic in `siphon.plugins.<provider>`; higher-level code should talk to provider-agnostic interfaces.
+
+---
+
+## 6. Tests & Quality
+
+If/when tests are added to the project:
+
+- Write tests for new behavior where possible.
+- Ensure existing tests pass before opening a PR.
+
+Example:
+
+```bash
+pytest
+```
+
+If there is no test suite yet, consider contributing small, focused tests around:
+
+- SIP trunk helpers (inbound/outbound trunk creation and lookup).
+- Metadata handling in `siphon.agent.core.entrypoint`.
+- Provider config parsing in `siphon.agent.agent_components`.
+
+---
+
+## 7. Pull Request Process
+
+1. **Fork** the repository and create a feature branch:
+
+   ```bash
+   git checkout -b feature/my-change
+   ```
+
+2. **Make your changes** in small, logical commits.
+
+3. **Add or update documentation** if your change affects public APIs, configuration, or behavior.
+
+4. **Run tests / sanity checks** locally.
+
+5. **Open a Pull Request**
+   - In the PR description, briefly explain:
+     - What changed.
+     - Why the change is needed (link the related issue if there is one).
+     - How you tested it (and whether it might be a breaking change).
+   - If relevant, mention how it impacts telephony flows or AI/LLM behavior.
+
+6. Engage in review
+   - Be open to feedback and iterate as needed.
+
+Once tests pass and reviews are resolved, a maintainer will merge your PR (often using squash-merge to keep history tidy).
+
+---
+
+## 8. Security, Privacy & Abuse
+
+If you discover a vulnerability, privacy issue, or a way SIPHON could be abused in production deployments, please **do not** open a public issue with exploit details.
+
+Instead, contact the maintainers privately so we can assess and respond responsibly.
+
+---
+
+## 9. Questions & Support
+
+If you’re unsure how best to contribute or want guidance on an idea:
+
+- Open a GitHub issue marked as **question** or **proposal**.
+- Or reach out via the project’s listed contact channels.
+- Our [Discord server](https://discord.gg/YOUR_INVITE_CODE) is constantly open; if you are unsure about anything, it is a good place to discuss. We’d love to collaborate and will always be friendly.
+
+Thank you again for helping improve SIPHON!

siphon_ai-0.1.0/LICENSE

@@ -0,0 +1,212 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor
+ hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+ royalty-free, irrevocable copyright license to reproduce, prepare
+ Derivative Works of, publicly display, publicly perform, sublicense,
+ and distribute the Work and such Derivative Works in Source or Object
+ form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor
+ hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+ royalty-free, irrevocable (except as stated in this section) patent
+ license to make, have made, use, offer to sell, sell, import, and
+ otherwise transfer the Work, where such license applies only to those
+ patent claims licensable by such Contributor that are necessarily
+ infringed by their Contribution(s) alone or by combination of their
+ Contribution(s) with the Work to which such Contribution(s) was
+ submitted. If You institute patent litigation against any entity
+ (including a cross-claim or counterclaim in a lawsuit) alleging that
+ the Work or a Contribution incorporated within the Work constitutes
+ direct or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate as of
+ the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative
+ Works thereof in any medium, with or without modifications, and in
+ Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Work by You to the Licensor shall be
+under the terms and conditions of this License, without any additional
+terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you
+may have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor
+provides the Work (and each Contributor provides its Contributions)
+on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied, including, without limitation, any
+warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
+or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+determining the appropriateness of using or redistributing the Work
+and assume any risks associated with Your exercise of permissions
+under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including
+negligence), contract, or otherwise, unless required by applicable
+law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including
+any direct, indirect, special, incidental, or consequential damages
+of any character arising as a result of this License or out of the
+use or inability to use the Work (including but not limited to damages
+for loss of goodwill, work stoppage, computer failure or malfunction,
+or any and all other commercial damages or losses), even if such
+Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may
+choose to offer, and charge a fee for, acceptance of support,
+warranty, indemnity, or other liability obligations and/or rights
+consistent with this License. However, in accepting such obligations,
+You may act only on Your own behalf and on Your sole responsibility,
+not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+   Copyright 2026 BLACKDWARF
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.