provedex-pipecat 0.1.0__tar.gz

provedex_pipecat-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.pyc

provedex_pipecat-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: provedex-pipecat
+Version: 0.1.0
+Summary: Pipecat FrameProcessor that signs every frame via the Provedex sidecar.
+Project-URL: Homepage, https://github.com/provedex/provedex
+Project-URL: Repository, https://github.com/provedex/provedex
+Project-URL: Issues, https://github.com/provedex/provedex/issues
+Author-email: Aditya Suresh <adi@provedex.io>
+License: Apache-2.0
+Keywords: audit,compliance,ed25519,pipecat,provedex,signing,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pipecat-ai<0.1.0,>=0.0.40
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# provedex-pipecat
+
+provedex-pipecat is a Pipecat FrameProcessor that signs every frame in your
+voice agent pipeline using the Provedex sidecar. One line of integration code.
+Hash-chained, Ed25519-signed audit ledger as output. Built for regulated voice
+agents: healthcare scribes, financial voice bots, claims handlers.
+
+The binding translates Pipecat frames into `AgentEvent` shapes and POSTs them
+over loopback HTTP to the Provedex sidecar. The sidecar holds the signing key
+and ledger. Your pipeline code never touches a key.
+
+
+## Quickstart
+
+```
+pip install provedex-pipecat
+```
+
+```python
+from provedex_pipecat import ProvedexConfig, ProvedexFrameProcessor
+
+processor = ProvedexFrameProcessor(config=ProvedexConfig())
+# Add `processor` anywhere in your Pipecat pipeline.
+```
+
+Assumes `provedex-agent` is running on `127.0.0.1:8765` (the default). To
+start the agent:
+
+```
+provedex-agent
+```
+
+Override the URL via the `PROVEDEX_AGENT_URL` environment variable or the
+`agent_url` constructor argument.
+
+
+## Frame mapping
+
+| Pipecat Frame | AgentEvent variant | Fields populated |
+|---|---|---|
+| `StartFrame` | `SessionStarted` | `agent_id`, `model_id` (both from config), `session_id` (config or uuid) |
+| `EndFrame` | `SessionEnded` | `reason = "pipeline_end"`, `summary_sha256 = sha256("")` |
+| `TranscriptionFrame` (final) | `UtteranceCaptured` | `audio_sha256 = sha256(transcript bytes)`, `transcript`, `lang`, `duration_ms = 0` if unknown |
+| `LLMMessagesFrame` + `LLMFullResponseEndFrame` (paired) | `ModelInvoked` | `model_id` (from config or inferred), `prompt_sha256 = sha256(canonical_json(messages))`, `response_sha256 = sha256(end_frame.text)`, `prompt_tokens = 0` if unknown, `response_tokens = 0` if unknown |
+| `TextFrame` (final, post-LLM, no end-frame pairing) | `UtteranceSpoken` | `text_sha256 = sha256(text)`, `text`, `audio_sha256 = sha256(b"")` |
+| `FunctionCallInProgressFrame` | `ToolCalled` | `tool_name`, `args_sha256 = sha256(canonical_json(arguments))`, `args_redacted = arguments` |
+| `FunctionCallResultFrame` | `ToolReturned` | `tool_name`, `result_sha256 = sha256(canonical_json(result))`, `latency_ms` (measured if start-frame timestamp captured), `success` |
+
+**Skipped frames** (not signed):
+
+- `AudioRawFrame` - too high frequency; hashing every audio chunk would
+  saturate the ledger with noise.
+- `InterimTranscriptionFrame` - not final; only committed transcripts are
+  auditable.
+- `MetricsFrame` - telemetry, not a decision event.
+- `SystemFrame` subclasses - control flow, not agent output.
+- `LLMFullResponseStartFrame` - used internally for pairing only.
+
+
+## Configuration reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `agent_url` | `str` | `$PROVEDEX_AGENT_URL` or `http://127.0.0.1:8765` | URL of the running `provedex-agent`. Override via env var `PROVEDEX_AGENT_URL` or constructor argument. |
+| `session_id` | `str` | `uuid4()` | Identifier for this call session. Passed as-is into `SessionStarted`. Override to tie the ledger entry to your own session ID. |
+| `agent_id` | `str` | `"pipecat-agent"` | Logical name of your agent. Appears in every signed event for that session. |
+| `model_id` | `str` | `"unknown"` | LLM model identifier. Used in `ModelInvoked` events. |
+| `include_frames` | `list[type] \| None` | `None` (use default list) | Override the set of frame types to sign. `None` uses the mapping table above. |
+| `on_sign_failure` | `"warn" \| "raise" \| "silent"` | `"warn"` | What to do when the agent returns 4xx. `warn` logs a warning and continues. `raise` propagates the exception out of the background worker and kills the pipeline - useful in test environments. `silent` increments counters only. |
+| `queue_size` | `int` | `1000` | Capacity of the internal deque. When full, the oldest queued event is dropped. |
+| `request_timeout_seconds` | `float` | `2.0` | HTTP timeout for each POST to the agent. |
+| `shutdown_drain_seconds` | `float` | `5.0` | How long to wait for the queue to drain after `EndFrame` before forwarding it downstream. |
+
+
+## Latency budget
+
+Test rig: 1000-frame burst with a 1 ms simulated agent response time
+(`tests/test_async_smoke.py`).
+
+| Percentile | Producer block time |
+|---|---|
+| p50 | 1.1 microseconds |
+| p99 | 2.2 microseconds |
+
+The producer just enqueues onto a deque; the background worker does the HTTP
+POST off the audio hot path. The signing round-trip never touches the frame's
+pass-through latency.
+
+
+## Failure modes
+
+| Failure | Behaviour | Counter |
+|---|---|---|
+| Agent unreachable (ConnectionRefused) | warn + drop | `dropped_total` |
+| Agent slow (timeout) | warn + drop | `dropped_total` |
+| Agent 4xx | log error + apply `on_sign_failure` | `dropped_total` |
+| Agent 5xx | warn + drop | `dropped_total` |
+| Queue overflow | drop oldest, rate-limited warning | `overflow_total` |
+| Frame mapping failure | log warning, drop event | n/a |
+
+Counters are readable as attributes on the processor instance:
+`processor.signed_total`, `processor.dropped_total`, `processor.overflow_total`.
+
+
+## Architecture
+
+This binding does not contain the signing primitive. The primitive is the Rust
+agent at https://github.com/provedex/provedex. The binding translates Pipecat
+frames into `AgentEvent` shapes per `docs/spec/event-schema-v1.md` and POSTs
+them to the agent over loopback HTTP. No key material passes through Python.
+
+The agent signs each event with the operator's Ed25519 key and chains it via
+SHA-256 parent hashes into a local NDJSON ledger. Anyone with the public key
+can verify the ledger offline without contacting any external service.
+
+
+## Verifying the ledger
+
+```
+provedex verify
+```
+
+```
+provedex verify --ledger ~/.provedex/ledger.ndjson
+```
+
+```
+provedex verify --ledger /path/to/sandboxed/ledger.ndjson
+```
+
+`provedex verify` walks the chain, checks each Ed25519 signature, recomputes
+each SHA-256 parent hash, and exits 0 on success or 1 with a diagnostic on the
+first broken link.
+
+
+## Regulatory context
+
+Tamper-evident audit logs are a direct requirement across several frameworks
+currently in force or taking effect in 2026. The EU AI Act Article 12 requires
+high-risk AI deployments to produce audit logs that are tamper-evident and
+retained for at least six months; enforcement applies from August 2, 2026.
+The Colorado AI Act (effective February 1, 2026) requires deployers of
+high-risk AI systems to maintain records sufficient to demonstrate compliance
+with consumer protection obligations. HIPAA's audit-control safeguard
+(45 CFR 164.312(b)) requires clinical voice agents to record and examine
+system activity, which for AI scribes means a verifiable transcript of every
+utterance processed. FINRA's 2026 examination priorities identify AI agent
+auditability as a focus area for broker-dealer supervision. A hash-chained,
+Ed25519-signed ledger satisfies the tamper-evident requirement across all four
+frameworks with a single integration point.
+
+
+---
+
+License: Apache-2.0
+
+Main repo: https://github.com/provedex/provedex

provedex_pipecat-0.1.0/README.md

@@ -0,0 +1,157 @@
+# provedex-pipecat
+
+provedex-pipecat is a Pipecat FrameProcessor that signs every frame in your
+voice agent pipeline using the Provedex sidecar. One line of integration code.
+Hash-chained, Ed25519-signed audit ledger as output. Built for regulated voice
+agents: healthcare scribes, financial voice bots, claims handlers.
+
+The binding translates Pipecat frames into `AgentEvent` shapes and POSTs them
+over loopback HTTP to the Provedex sidecar. The sidecar holds the signing key
+and ledger. Your pipeline code never touches a key.
+
+
+## Quickstart
+
+```
+pip install provedex-pipecat
+```
+
+```python
+from provedex_pipecat import ProvedexConfig, ProvedexFrameProcessor
+
+processor = ProvedexFrameProcessor(config=ProvedexConfig())
+# Add `processor` anywhere in your Pipecat pipeline.
+```
+
+Assumes `provedex-agent` is running on `127.0.0.1:8765` (the default). To
+start the agent:
+
+```
+provedex-agent
+```
+
+Override the URL via the `PROVEDEX_AGENT_URL` environment variable or the
+`agent_url` constructor argument.
+
+
+## Frame mapping
+
+| Pipecat Frame | AgentEvent variant | Fields populated |
+|---|---|---|
+| `StartFrame` | `SessionStarted` | `agent_id`, `model_id` (both from config), `session_id` (config or uuid) |
+| `EndFrame` | `SessionEnded` | `reason = "pipeline_end"`, `summary_sha256 = sha256("")` |
+| `TranscriptionFrame` (final) | `UtteranceCaptured` | `audio_sha256 = sha256(transcript bytes)`, `transcript`, `lang`, `duration_ms = 0` if unknown |
+| `LLMMessagesFrame` + `LLMFullResponseEndFrame` (paired) | `ModelInvoked` | `model_id` (from config or inferred), `prompt_sha256 = sha256(canonical_json(messages))`, `response_sha256 = sha256(end_frame.text)`, `prompt_tokens = 0` if unknown, `response_tokens = 0` if unknown |
+| `TextFrame` (final, post-LLM, no end-frame pairing) | `UtteranceSpoken` | `text_sha256 = sha256(text)`, `text`, `audio_sha256 = sha256(b"")` |
+| `FunctionCallInProgressFrame` | `ToolCalled` | `tool_name`, `args_sha256 = sha256(canonical_json(arguments))`, `args_redacted = arguments` |
+| `FunctionCallResultFrame` | `ToolReturned` | `tool_name`, `result_sha256 = sha256(canonical_json(result))`, `latency_ms` (measured if start-frame timestamp captured), `success` |
+
+**Skipped frames** (not signed):
+
+- `AudioRawFrame` - too high frequency; hashing every audio chunk would
+  saturate the ledger with noise.
+- `InterimTranscriptionFrame` - not final; only committed transcripts are
+  auditable.
+- `MetricsFrame` - telemetry, not a decision event.
+- `SystemFrame` subclasses - control flow, not agent output.
+- `LLMFullResponseStartFrame` - used internally for pairing only.
+
+
+## Configuration reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `agent_url` | `str` | `$PROVEDEX_AGENT_URL` or `http://127.0.0.1:8765` | URL of the running `provedex-agent`. Override via env var `PROVEDEX_AGENT_URL` or constructor argument. |
+| `session_id` | `str` | `uuid4()` | Identifier for this call session. Passed as-is into `SessionStarted`. Override to tie the ledger entry to your own session ID. |
+| `agent_id` | `str` | `"pipecat-agent"` | Logical name of your agent. Appears in every signed event for that session. |
+| `model_id` | `str` | `"unknown"` | LLM model identifier. Used in `ModelInvoked` events. |
+| `include_frames` | `list[type] \| None` | `None` (use default list) | Override the set of frame types to sign. `None` uses the mapping table above. |
+| `on_sign_failure` | `"warn" \| "raise" \| "silent"` | `"warn"` | What to do when the agent returns 4xx. `warn` logs a warning and continues. `raise` propagates the exception out of the background worker and kills the pipeline - useful in test environments. `silent` increments counters only. |
+| `queue_size` | `int` | `1000` | Capacity of the internal deque. When full, the oldest queued event is dropped. |
+| `request_timeout_seconds` | `float` | `2.0` | HTTP timeout for each POST to the agent. |
+| `shutdown_drain_seconds` | `float` | `5.0` | How long to wait for the queue to drain after `EndFrame` before forwarding it downstream. |
+
+
+## Latency budget
+
+Test rig: 1000-frame burst with a 1 ms simulated agent response time
+(`tests/test_async_smoke.py`).
+
+| Percentile | Producer block time |
+|---|---|
+| p50 | 1.1 microseconds |
+| p99 | 2.2 microseconds |
+
+The producer just enqueues onto a deque; the background worker does the HTTP
+POST off the audio hot path. The signing round-trip never touches the frame's
+pass-through latency.
+
+
+## Failure modes
+
+| Failure | Behaviour | Counter |
+|---|---|---|
+| Agent unreachable (ConnectionRefused) | warn + drop | `dropped_total` |
+| Agent slow (timeout) | warn + drop | `dropped_total` |
+| Agent 4xx | log error + apply `on_sign_failure` | `dropped_total` |
+| Agent 5xx | warn + drop | `dropped_total` |
+| Queue overflow | drop oldest, rate-limited warning | `overflow_total` |
+| Frame mapping failure | log warning, drop event | n/a |
+
+Counters are readable as attributes on the processor instance:
+`processor.signed_total`, `processor.dropped_total`, `processor.overflow_total`.
+
+
+## Architecture
+
+This binding does not contain the signing primitive. The primitive is the Rust
+agent at https://github.com/provedex/provedex. The binding translates Pipecat
+frames into `AgentEvent` shapes per `docs/spec/event-schema-v1.md` and POSTs
+them to the agent over loopback HTTP. No key material passes through Python.
+
+The agent signs each event with the operator's Ed25519 key and chains it via
+SHA-256 parent hashes into a local NDJSON ledger. Anyone with the public key
+can verify the ledger offline without contacting any external service.
+
+
+## Verifying the ledger
+
+```
+provedex verify
+```
+
+```
+provedex verify --ledger ~/.provedex/ledger.ndjson
+```
+
+```
+provedex verify --ledger /path/to/sandboxed/ledger.ndjson
+```
+
+`provedex verify` walks the chain, checks each Ed25519 signature, recomputes
+each SHA-256 parent hash, and exits 0 on success or 1 with a diagnostic on the
+first broken link.
+
+
+## Regulatory context
+
+Tamper-evident audit logs are a direct requirement across several frameworks
+currently in force or taking effect in 2026. The EU AI Act Article 12 requires
+high-risk AI deployments to produce audit logs that are tamper-evident and
+retained for at least six months; enforcement applies from August 2, 2026.
+The Colorado AI Act (effective February 1, 2026) requires deployers of
+high-risk AI systems to maintain records sufficient to demonstrate compliance
+with consumer protection obligations. HIPAA's audit-control safeguard
+(45 CFR 164.312(b)) requires clinical voice agents to record and examine
+system activity, which for AI scribes means a verifiable transcript of every
+utterance processed. FINRA's 2026 examination priorities identify AI agent
+auditability as a focus area for broker-dealer supervision. A hash-chained,
+Ed25519-signed ledger satisfies the tamper-evident requirement across all four
+frameworks with a single integration point.
+
+
+---
+
+License: Apache-2.0
+
+Main repo: https://github.com/provedex/provedex

provedex_pipecat-0.1.0/RELEASING.md

@@ -0,0 +1,36 @@
+# Release process for provedex-pipecat
+
+Pre-release checklist:
+
+1. All tests pass locally and in CI.
+2. `pyproject.toml` version bumped if shipping a new version.
+3. Tag the binding release: `git tag pipecat-vX.Y.Z` (use a binding-scoped tag prefix so it does not collide with the agent's `vX.Y.Z` tags).
+
+Publish to PyPI:
+
+```
+cd bindings/python/provedex-pipecat
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+After publish:
+
+1. Verify `pip install provedex-pipecat` from a clean venv pulls the new version.
+2. Confirm the README on PyPI renders correctly (long_description comes from `README.md`).
+3. Bump the `provedex-pipecat` row in the root `README.md` Components table if anything material changed.
+
+Yank policy:
+
+```
+python -m twine yank provedex-pipecat==X.Y.Z
+```
+
+A yank does not delete the version; it stops new dependents from picking it up. Existing lockfiles keep their pin. Use yank when a published version has a hard bug; publish a fixed `X.Y.Z+1` and document the yank reason in the next release notes.
+
+Out of scope here:
+
+- The Rust agent + CLI publish process lives in the root `RELEASING.md`.
+- PyPI account ownership and 2FA recovery live in 1Password under the `provedex-pipecat-pypi` entry. Not in this repo.

provedex_pipecat-0.1.0/examples/voice_agent_basic.py

@@ -0,0 +1,41 @@
+"""Minimal Pipecat pipeline with Provedex signing.
+
+This is an illustrative skeleton. Replace the placeholder transport, STT,
+LLM, and TTS classes with the real Pipecat services from your stack
+(twilio_transport.TwilioTransport, deepgram.DeepgramSTTService, etc.).
+
+Run a local provedex-agent before starting this script:
+    provedex-agent --rate-limit-off &
+"""
+
+import asyncio
+import os
+
+from pipecat.frames.frames import EndFrame, StartFrame, TranscriptionFrame, TextFrame
+from provedex_pipecat import ProvedexConfig, ProvedexFrameProcessor
+
+
+async def main() -> None:
+    cfg = ProvedexConfig(
+        agent_url=os.getenv("PROVEDEX_AGENT_URL", "http://127.0.0.1:8765"),
+        agent_id="example-voice-agent",
+        model_id="llama3.2:3b",
+        session_id="example-session-001",
+    )
+    processor = ProvedexFrameProcessor(config=cfg)
+    await processor.start()
+
+    # Simulated pipeline events. Replace with real Pipecat pipeline composition.
+    await processor.handle_frame(StartFrame())
+    await processor.handle_frame(
+        TranscriptionFrame(text="hello", user_id="caller", timestamp="t", language="en-US")
+    )
+    await processor.handle_frame(TextFrame(text="hello back"))
+    await processor.handle_frame(EndFrame())
+
+    await processor.stop()
+    print(f"signed={processor.signed_total} dropped={processor.dropped_total}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

provedex_pipecat-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "provedex-pipecat"
+version = "0.1.0"
+description = "Pipecat FrameProcessor that signs every frame via the Provedex sidecar."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Aditya Suresh", email = "adi@provedex.io" },
+]
+keywords = ["pipecat", "voice", "audit", "signing", "compliance", "ed25519", "provedex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "pipecat-ai>=0.0.40,<0.1.0",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/provedex/provedex"
+Repository = "https://github.com/provedex/provedex"
+Issues = "https://github.com/provedex/provedex/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/provedex_pipecat"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests legitimately invoke cargo + provedex CLI via blocking subprocess.
+"tests/*" = ["ASYNC221"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "integration: requires real provedex-agent binary",
+    "slow: takes > 1s",
+]

provedex_pipecat-0.1.0/src/provedex_pipecat/__init__.py

@@ -0,0 +1,7 @@
+"""Provedex binding for Pipecat voice agent pipelines."""
+
+from .config import ProvedexConfig
+from .processor import ProvedexFrameProcessor
+
+__version__ = "0.1.0"
+__all__ = ["ProvedexConfig", "ProvedexFrameProcessor"]

provedex_pipecat-0.1.0/src/provedex_pipecat/_client.py

@@ -0,0 +1,37 @@
+"""Private async HTTP client for the provedex-agent /v1/sign endpoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class SignError(Exception):
+    """Raised when a sign attempt fails (network, timeout, or non-2xx)."""
+
+
+class AgentClient:
+    """Thin httpx wrapper. One per processor instance; reuses the connection."""
+
+    def __init__(self, base_url: str, timeout: float) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(timeout, connect=timeout),
+            headers={"content-type": "application/json"},
+        )
+
+    async def sign(self, event: dict[str, Any]) -> None:
+        """POST {event: ...} to /v1/sign. Raises SignError on any failure."""
+        try:
+            resp = await self._client.post("/v1/sign", json={"event": event})
+        except httpx.HTTPError as e:
+            raise SignError(f"agent unreachable: {e}") from e
+        if resp.status_code >= 400:
+            raise SignError(
+                f"agent returned {resp.status_code}: {resp.text[:200]}"
+            )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

provedex_pipecat-0.1.0/src/provedex_pipecat/_state.py

@@ -0,0 +1,41 @@
+"""Per-processor correlation buffer for paired LLM frames + frame dedup."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CorrelationState:
+    """Track in-flight LLM exchanges and seen frame IDs."""
+
+    last_messages: list[dict[str, Any]] | None = None
+    pending_response_text: str = ""
+    response_in_progress: bool = False
+    seen_frame_ids: set[int] = field(default_factory=set)
+
+    def buffer_messages(self, messages: list[dict[str, Any]]) -> None:
+        self.last_messages = messages
+
+    def buffer_response_text(self, text: str) -> None:
+        self.pending_response_text += text
+
+    def take_paired_invocation(self) -> tuple[list[dict[str, Any]] | None, str]:
+        """Return (messages, response_text) and clear the buffers."""
+        messages = self.last_messages
+        text = self.pending_response_text
+        self.last_messages = None
+        self.pending_response_text = ""
+        self.response_in_progress = False
+        return messages, text
+
+    def mark_response_start(self) -> None:
+        self.response_in_progress = True
+        self.pending_response_text = ""
+
+    def already_seen(self, frame_id: int) -> bool:
+        if frame_id in self.seen_frame_ids:
+            return True
+        self.seen_frame_ids.add(frame_id)
+        return False

provedex_pipecat-0.1.0/src/provedex_pipecat/config.py

@@ -0,0 +1,40 @@
+"""Configuration for the Provedex Pipecat binding."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+OnSignFailure = Literal["warn", "raise", "silent"]
+
+
+class ProvedexConfig(BaseModel):
+    """Configuration for ProvedexFrameProcessor.
+
+    Env-first with constructor overrides. PROVEDEX_AGENT_URL is the only
+    runtime-discovered field; everything else is set explicitly by the operator.
+    """
+
+    agent_url: str = Field(
+        default_factory=lambda: os.getenv("PROVEDEX_AGENT_URL", "http://127.0.0.1:8765")
+    )
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    agent_id: str = "pipecat-agent"
+    model_id: str = "unknown"
+    include_frames: list[type] | None = None
+    on_sign_failure: OnSignFailure = "warn"
+    queue_size: int = Field(default=1000, ge=1)
+    request_timeout_seconds: float = Field(default=2.0, gt=0)
+    shutdown_drain_seconds: float = Field(default=5.0, ge=0)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @field_validator("agent_url")
+    @classmethod
+    def url_must_be_http(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://")):
+            raise ValueError(f"agent_url must start with http:// or https://, got {v!r}")
+        return v