Add outbound calling ability with proper SIP BYE hang-up (dialog-centric refactor)

.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+default_language_version:
+  python: python3.14
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -36,6 +38,7 @@ repos:
           - mdformat-footnote
           - mdformat-gfm
           - mdformat-gfm-alerts
+          - mdformat-mkdocs>=5.2.0b1
           - mdformat-ruff
         exclude: ^\.github/agents/.*\.agent\.md$
   - repo: https://github.com/astral-sh/ruff-pre-commit

CONTRIBUTING.md

@@ -9,23 +9,23 @@ curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/m
 
 To run the tests, use the following command:
 
-```bash
+```console
 uv run pytest
 ```
 
 Avoid mocking in your tests and instead use real dependencies to ensure that your tests are as close to real-world scenarios as possible.
 You may only mock transports to avoid network IO or to mimic network counterparts.
 
-Before your first commit, ensure that the pre-commit hooks are installed by running:
+## Testing with Extra Dependencies
 
-```bash
-uvx prek install
+```console
+uv run --extra=cli --extra=pygments --extra=audio pytest
 ```
 
-## Testing with Extra Dependencies
+Before your first commit, ensure that the pre-commit hooks are installed by running:
 
-```bash
-uv run --extra=cli --extra=pygments --extra=audio pytest
+```console
+uvx prek install
 ```
 
 ## Writing documentation
@@ -34,6 +34,6 @@ The documentation is built using [MkDocs](https://www.mkdocs.org/) with [mkdocst
 
 To serve the documentation locally for development, run:
 
-```bash
+```console
 uv run --group docs mkdocs serve --livereload
 ```

README.md

@@ -20,25 +20,41 @@ Async VoIP Python library for the AI age.
 
 ## Usage
 
+To get started, you will need a SIP account. One is usually included with ISP.
+Check your ISP's documentation or router for details.
+
+You will need a SIP AOR (URI), which looks like this:
+
+```INI
+sip:USER:PASSWORD@SIP_SERVER;transport=TCP
+```
+
+> [!NOTE]
+> This library uses secure defaults (TLS transport on port 5061).
+> However, most SIP servers only support unencrypted connections.
+> Therefore, you will need to provide an explict transport parameter.
+
 ### CLI
 
-Answer calls and transcribe them live from the terminal:
+A simple echo call can be started with:
 
 ```console
-uvx 'voip[cli]' sip sips:alice:********@sip.example.com transcribe
+uvx 'voip[cli]' sip sips:alice:********@sip.example.com echo
 ```
 
-A simple echo server can be started with:
+Each command supports an optional `--dial` argument to initiate an
+outbound call instead of waiting for an inbound one.
+
+To dial a number, say a message, and hang up automatically:
 
-````console
 ```console
-uvx 'voip[cli]' sip sips:alice:********@sip.example.com echo
-````
+uvx 'voip[cli]' sip sips:alice:********@sip.example.com say sip:+15551234567@sip.example.com "Your package has arrived."
+```
 
 You can also talk to a local agent (needs [Ollama]):
 
 ```console
-uvx 'voip[cli]' sip sips:alice:********@sip.example.com agent
+uvx 'voip[cli]' sip sips:alice:********@sip.example.com agent --initial-prompt "Hi, I am looking for a Mr. Ron, first name Mo?"
 ```
 
 ### Python API
@@ -48,15 +64,15 @@ uv add voip[audio,ai,pygments]
 ```
 
 Subclass `TranscribeCall` and override `transcription_received` to handle results.
-Pass it as `call_class` when answering an incoming call:
+Pass it as `session_class` when answering an incoming call:
 
 ```python
 import asyncio
 import dataclasses
 import ssl
 from voip.ai import TranscribeCall
 from voip.sip.protocol import SIP
-from voip.sip.types import SipUri
+from voip.sip.types import SipURI
 from voip.sip.transactions import InviteTransaction
 from voip.rtp import RealtimeTransportProtocol
 from faster_whisper import WhisperModel
@@ -72,7 +88,7 @@ class TranscribeInviteTransaction(InviteTransaction):
     def invite_received(self, request) -> None:
         self.ringing()
         self.answer(
-            call_class=TranscribingCall,
+            session_class=TranscribingCall,
             stt_model=WhisperModel("kyutai/stt-1b-en_fr-trfs", device="cuda"),
         )
 
@@ -87,7 +103,7 @@ async def main():
     await loop.create_connection(
         lambda: SIP(
             rtp=rtp_protocol,
-            aor=SipUri.parse("sips:alice:********@example.com"),
+            aor=SipURI.parse("sips:alice:********@example.com"),
             transaction_class=TranscribeInviteTransaction,
         ),
         host="sip.example.com",

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md