pipecatcloud 0.6.0__tar.gz → 0.7.0__tar.gz

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to **Pipecat Cloud** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-05-07
+
+### Added
+
+- `pcc secrets list` now shows a `Status` column for each secret set
+  (`ready`, `pending`, or `failed`). When a single set is requested
+  (`pcc secrets list <name>`), the readiness status is shown in the panel
+  title alongside the keys, and a follow-up message explains pending or
+  failed states. Backed by a new `secrets_get` API client method that
+  fetches a single secret set's full payload, including readiness fields.
+
+### Changed
+
+- `pcc agent status` and the `pcc deploy` polling output now show
+  customer-friendly headlines for failed deployments when the API
+  supplies them. An OOM-killed container reads "Out of memory" instead
+  of "CrashLoopBackOff (OOMKilled, exit 137)"; an application crash
+  reads "Application Error" with the captured traceback on the next
+  line. Exit codes render as "exit code N" rather than "exit N" for
+  clarity. Older API responses without the new field continue to render
+  via the previous format.
+
 ## [0.6.0] - 2026-04-22
 
 ### Added

pipecatcloud-0.7.0/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repo.
+
+## What this is
+
+**Pipecat Cloud** is the Python SDK and `pcc` CLI for deploying and managing Pipecat voice agents on Pipecat Cloud infrastructure. It ships to PyPI as `pipecatcloud`. Users install it to authenticate, build and push container images, deploy agents, manage secrets and scaling, and open sessions against running agents.
+
+- Package root: `src/pipecatcloud/`
+- CLI entry points: `pcc` and `pipecatcloud` (also registered as a Pipecat CLI extension via the `pipecat_cli.extensions:cloud` entry point)
+- Public docs: https://docs.pipecat.daily.co
+
+## Toolchain
+
+- **Python 3.11+** (bumped from 3.10 in v0.5.0 to match Pipecat 1.0). Type hints use `X | Y` syntax, not `Union[X, Y]`.
+- **uv** for dependency management. `uv.lock` is committed.
+- **setuptools** build backend. Version is derived from git tags via `setuptools_scm` (tag format `v0.6.0`), so there is no hand-edited version file.
+- **Ruff** for lint and format (100-char line length, `I` and `UP` rule sets).
+- **Pyright** for type checking.
+- **Pytest** with `pytest-asyncio` in `auto` mode.
+
+## Common commands
+
+Always use `uv run` rather than activating a venv.
+
+```bash
+# First-time setup
+uv sync --group dev
+uv run pre-commit install
+
+# Tests
+uv run pytest                                    # full suite
+uv run pytest tests/test_auth.py                 # single file
+uv run pytest tests/test_auth.py::TestPKCE       # single class
+uv run pytest -v                                 # verbose
+
+# Lint / format / typecheck
+uv run ruff format .
+uv run ruff check --fix .
+uv run pyright
+bash scripts/fix-ruff.sh                         # format + check --fix
+
+# Build (usually CI-only)
+uv build
+```
+
+Pre-commit runs `ruff format` and `ruff check --fix` on every commit. If the hook fails, fix the issue and make a **new** commit rather than amending.
+
+## Repository layout
+
+```
+src/pipecatcloud/
+  __init__.py            Public SDK surface (Session, exceptions, session argument types)
+  api.py                 Async aiohttp API client (_API class)
+  session.py             User-facing Session client
+  agent.py               Session argument types with fallbacks when pipecat-ai is absent
+  config.py              Base settings, API path constants
+  constants.py           Krisp VIVA models, region-related literals
+  exception.py           Error hierarchy (AuthError, AgentStartError, etc.)
+  cli/
+    entry_point.py       Typer app, wired as a Pipecat CLI extension
+    config.py            Reads/writes ~/.config/pipecatcloud/pipecatcloud.toml
+    api.py               CLI-flavored wrapper around _API
+    commands/            auth, agent, deploy, docker, build, secrets, regions, organizations
+  _utils/
+    auth_utils.py        @requires_login decorator, default-org resolution
+    build_utils.py       Deterministic tarballs, S3 upload, build polling
+    deploy_utils.py      pcc-deploy.toml parsing, deployment-status interpretation
+    regions.py           Region fetch and validation
+    async_utils.py       synchronizer for bridging async into the sync Typer CLI
+    console_utils.py     Rich console helpers
+  smallwebrtc/
+    session_manager.py   SmallWebRTC support for non-Pipecat agents
+tests/                   Pytest suite, parallel to src/
+.github/workflows/       tests.yml, format.yml, publish-pypi.yml, publish-test.yml
+pcc-deploy.toml          Example deployment config consumed by `pcc deploy`
+```
+
+## Testing conventions
+
+- Layout mirrors `src/`. New tests go in `tests/test_<module>.py`.
+- `tests/conftest.py` sets `PIPECAT_CONFIG_PATH` to an isolated temp file **before imports**, pre-populated with `token = "test-token"` and `org = "test-org"`. This prevents tests from reading or clobbering real credentials. Do not bypass it.
+- Async tests use `@pytest.mark.asyncio`. Mock async calls with `unittest.mock.AsyncMock`.
+- `tests/test_agent_sessions.py` is **skipped in CI** because it needs real auth or heavier mocking. Run it locally if you touch session code.
+- `pytest.ini` uses `--import-mode=importlib`. Some tests manually insert `src/` onto `sys.path`, which is expected.
+
+## CI
+
+- `tests.yml` runs on push to main and PRs. It currently runs `uv run pytest tests/test_docker_commands.py -v` rather than the full suite, so green CI does not guarantee the whole suite passes. Run `uv run pytest` locally before opening PRs.
+- `format.yml` runs `ruff format --diff` and `ruff check`. Both must pass.
+- `publish-pypi.yml` and `publish-test.yml` are manual dispatches that build and publish a specific git tag.
+
+## Config and environment
+
+- User config lives at `~/.config/pipecatcloud/pipecatcloud.toml`. Overridable with `PIPECAT_CONFIG_PATH`.
+- Deployment config is `pcc-deploy.toml` in the project root. Overridable with `PIPECAT_DEPLOY_CONFIG_PATH`.
+- Other overrides follow the `PIPECAT_<UPPERCASE_SETTING>` pattern (e.g. `PIPECAT_API_HOST`).
+- `PCC_LOG_LEVEL` controls the loguru log level (default `INFO`). This codebase uses **loguru**, not the stdlib `logging` module.
+- The credentials file is force-chmod'd to `0600` on read and written atomically (temp file, fsync, rename). Preserve this when touching `cli/config.py`.
+
+## Gotchas
+
+- The CLI is sync (Typer) but the API client is async. Bridge with `@synchronizer` from `_utils/async_utils.py`. Do not invent a new bridging pattern.
+- Auth uses OAuth2 with PKCE (RFC 7636). OAuth endpoints are discovered from the API server, not hardcoded. The callback server tries ports 8400-8404.
+- `SmallWebRTCSessionArguments` and `SmallWebRTCRunnerArguments` have fallback definitions in `agent.py` for when `pipecat-ai` isn't installed. Keep the two paths in sync.
+- Krisp VIVA audio filter names are `Literal["tel", "pro"]` in `constants.py`. These must match the server-side ConfigMap, so coordinate changes with the backend.
+
+## Release flow
+
+1. Update `CHANGELOG.md` following Keep a Changelog format.
+2. Tag the commit with `v<MAJOR>.<MINOR>.<PATCH>`.
+3. Trigger `publish-pypi.yml` manually with that tag. `setuptools_scm` picks up the version from the tag.
+
+## Writing style for generated content in this repo
+
+- No emdashes.
+- Clear mid-length sentences. Short paragraphs.
+- Bold for key terms on first use only.
+- Don't hedge, don't hype, don't pad with "let's dive in" style openers.

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipecatcloud
-Version: 0.6.0
+Version: 0.7.0
 Summary: Cloud hosting for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Website, https://docs.pipecat.daily.co/

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/pyproject.toml

@@ -56,7 +56,6 @@ include = ["pipecatcloud*"]
 pipecatcloud = ["py.typed"]
 
 [tool.ruff]
-exclude = ["*_pb2.py"]
 line-length = 100
 
 [tool.ruff.lint]

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/src/pipecatcloud/_utils/deploy_utils.py

@@ -104,19 +104,26 @@ def format_health_lines(health: dict) -> list:
     """Format health details as indented lines under a revision."""
     lines = []
     reason_parts = []
+
+    # Prefer the customer-friendly headline from the API when present. Older API
+    # responses don't include it, so fall back to constructing a string from raw
+    # k8s fields.
+    headline = health.get("headline")
     reason = health.get("reason", "")
     term_reason = health.get("lastTerminationReason", "")
     exit_code = health.get("lastExitCode")
 
-    if reason:
+    if headline:
+        reason_parts.append(f"[red]{headline}[/red]")
+    elif reason:
         detail = reason
         if term_reason and term_reason != reason:
             detail += f" ({term_reason}"
             if exit_code is not None:
-                detail += f", exit {exit_code}"
+                detail += f", exit code {exit_code}"
             detail += ")"
         elif exit_code is not None:
-            detail += f" (exit {exit_code})"
+            detail += f" (exit code {exit_code})"
         reason_parts.append(f"[red]{detail}[/red]")
 
     restarts = health.get("restartCount", 0)
@@ -124,6 +131,11 @@ def format_health_lines(health: dict) -> list:
     if restarts > 0:
         reason_parts.append(f"[dim]·[/dim] {restarts} restarts across {replicas_started} replicas")
 
+    # When using the headline, surface the exit code as its own subhead segment.
+    # The fallback path already includes the exit code inline with the reason.
+    if headline and exit_code is not None:
+        reason_parts.append(f"[dim]·[/dim] exit code {exit_code}")
+
     if reason_parts:
         lines.append("      " + " ".join(reason_parts))
 

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/src/pipecatcloud/api.py

@@ -354,6 +354,27 @@ class _API:
         """
         return self.create_api_method(self._secrets_list)
 
+    async def _secrets_get(self, org: str, secret_set: str) -> dict | None:
+        """Fetch a single secret set, including its readiness status.
+
+        Returns the full response object: {secrets, region, status, errorMessage?}.
+        Use this when you need readiness; use _secrets_list when you only need
+        the existence check or the flat keys array.
+        """
+        url = f"{self.construct_api_url('secrets_path').format(org=org)}/{secret_set}"
+        result = await self._base_request("GET", url, not_found_is_empty=True)
+        return result or None
+
+    @property
+    def secrets_get(self):
+        """Get a single secret set with readiness status.
+
+        Args:
+            org: Organization ID
+            secret_set: Name of the secret set
+        """
+        return self.create_api_method(self._secrets_get)
+
     async def _secrets_upsert(
         self, data: dict, set_name: str, org: str, region: str | None = None
     ) -> dict:

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/src/pipecatcloud/cli/commands/secrets.py

@@ -33,6 +33,17 @@ secrets_cli = typer.Typer(
 # ---- Methods ----
 
 
+def _format_status(status: str | None) -> str:
+    """Render a readiness status with Rich styling. Unknown values pass through."""
+    if status == "ready":
+        return "[green]ready[/green]"
+    if status == "pending":
+        return "[yellow]pending[/yellow]"
+    if status == "failed":
+        return "[red]failed[/red]"
+    return status or "[dim]unknown[/dim]"
+
+
 def validate_secrets(secrets: dict):
     valid_name_pattern = re.compile(r"^[a-zA-Z0-9_-]+$")
 
@@ -382,7 +393,10 @@ async def list(
     logger.debug(f"Secret set name to lookup: {name}")
 
     with console.status(f"[dim]{status_title}[/dim]", spinner="dots"):
-        data, error = await API.bubble_error().secrets_list(org=org, secret_set=name, region=region)
+        if name:
+            data, error = await API.bubble_error().secrets_get(org=org, secret_set=name)
+        else:
+            data, error = await API.bubble_error().secrets_list(org=org, region=region)
 
         if error:
             if error == 400:
@@ -401,19 +415,27 @@ async def list(
             return typer.Exit()
 
         if name:
-            # Match
+            secrets = data.get("secrets") or []
+            status = data.get("status")
+            error_message = data.get("errorMessage")
 
             table = Table(border_style="dim", show_header=False, show_edge=True, show_lines=True)
             table.add_column(name, style="white")
-            for s in data:
+            for s in secrets:
                 table.add_row(s["fieldName"])
-            console.print(
-                Panel(
-                    table,
-                    title=f"[bold]Secret keys for set [green]{name}[/green][/bold]",
-                    title_align="left",
-                )
+
+            title = (
+                f"[bold]Secret keys for set [green]{name}[/green][/bold] "
+                f"(status: {_format_status(status)})"
             )
+            console.print(Panel(table, title=title, title_align="left"))
+            if status == "failed" and error_message:
+                console.print(f"[red]{error_message}[/red]")
+            elif status == "pending":
+                console.print(
+                    "[yellow]This secret set is still being provisioned. "
+                    "Deploys that bind it will be rejected until it is ready.[/yellow]"
+                )
         else:
             # Filter out image pull secrets if show all is False
             filtered_sets = [s for s in data if show_all or s["type"] != "imagePullSecret"]
@@ -431,6 +453,7 @@ async def list(
             )
             table.add_column("Secret Set Name", style="white")
             table.add_column("Region", style="white")
+            table.add_column("Status", style="white")
             if show_all:
                 table.add_column("Type", style="white")
                 for secret_set in filtered_sets:
@@ -439,10 +462,19 @@ async def list(
                         if secret_set["type"] == "imagePullSecret"
                         else "Secret Set"
                     )
-                    table.add_row(secret_set["name"], secret_set["region"], set_type)
+                    table.add_row(
+                        secret_set["name"],
+                        secret_set["region"],
+                        _format_status(secret_set.get("status")),
+                        set_type,
+                    )
             else:
                 for secret_set in filtered_sets:
-                    table.add_row(secret_set["name"], secret_set["region"])
+                    table.add_row(
+                        secret_set["name"],
+                        secret_set["region"],
+                        _format_status(secret_set.get("status")),
+                    )
 
             console.success(table, title_extra=f"Secret sets for {org}")
 

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/src/pipecatcloud.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipecatcloud
-Version: 0.6.0
+Version: 0.7.0
 Summary: Cloud hosting for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Website, https://docs.pipecat.daily.co/

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/src/pipecatcloud.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 .gitignore
 .pre-commit-config.yaml
 CHANGELOG.md
+CLAUDE.md
 LICENSE
 README.md
 pipecat-cloud.png

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/tests/test_api_client.py

@@ -71,6 +71,41 @@ class TestAPISecretsRegions:
             call_args = mock_request.call_args
             assert call_args[1]["params"] == {"region": "ap"}
 
+    @pytest.mark.asyncio
+    async def test_secrets_get_returns_full_response(self, api_client):
+        """secrets_get returns the whole single-set response, including readiness fields."""
+        # Arrange
+        with patch.object(api_client, "_base_request", new_callable=AsyncMock) as mock_request:
+            mock_request.return_value = {
+                "secrets": [{"fieldName": "API_KEY"}],
+                "region": "us-west",
+                "status": "ready",
+            }
+
+            # Act
+            result = await api_client._secrets_get(org="test-org", secret_set="my-secrets")
+
+            # Assert
+            mock_request.assert_called_once()
+            assert result == {
+                "secrets": [{"fieldName": "API_KEY"}],
+                "region": "us-west",
+                "status": "ready",
+            }
+
+    @pytest.mark.asyncio
+    async def test_secrets_get_returns_none_on_404(self, api_client):
+        """secrets_get returns None when the set does not exist."""
+        # Arrange
+        with patch.object(api_client, "_base_request", new_callable=AsyncMock) as mock_request:
+            mock_request.return_value = None
+
+            # Act
+            result = await api_client._secrets_get(org="test-org", secret_set="missing")
+
+            # Assert
+            assert result is None
+
     @pytest.mark.asyncio
     async def test_secrets_upsert_with_region(self, api_client):
         """Secrets upsert with region should include region in payload."""

{pipecatcloud-0.6.0 → pipecatcloud-0.7.0}/tests/test_deployment_status.py

@@ -497,7 +497,7 @@ class TestHealthLines:
         assert len(lines) >= 1
         assert "CrashLoopBackOff" in lines[0]
         assert "OOMKilled" in lines[0]
-        assert "exit 137" in lines[0]
+        assert "exit code 137" in lines[0]
         assert "42 restarts" in lines[0]
         assert "3 replicas" in lines[0]
 
@@ -511,7 +511,7 @@ class TestHealthLines:
             }
         )
         assert "Error" in lines[0]
-        assert "exit 1" in lines[0]
+        assert "exit code 1" in lines[0]
         assert "4 restarts" in lines[0]
 
     def test_message_shows_last_line(self):
@@ -564,8 +564,86 @@ class TestHealthLines:
                 "replicasStarted": 1,
             }
         )
-        # Should show "Error (exit 1)" not "Error (Error, exit 1)"
-        assert "Error (exit 1)" in lines[0]
+        # Should show "Error (exit code 1)" not "Error (Error, exit code 1)"
+        assert "Error (exit code 1)" in lines[0]
+
+    def test_headline_replaces_reason_string(self):
+        """When the API supplies a customer-friendly headline, render it instead of
+        the raw k8s reason. Exit code is appended as its own segment so it stays
+        visible (today's format folded the exit code into the reason string)."""
+        lines = format_health_lines(
+            {
+                "reason": "CrashLoopBackOff",
+                "lastTerminationReason": "OOMKilled",
+                "lastExitCode": 137,
+                "restartCount": 5,
+                "replicasStarted": 2,
+                "headline": "Out of memory",
+            }
+        )
+        assert "Out of memory" in lines[0]
+        # Raw k8s vocabulary should NOT appear in the rendered line when we have a headline.
+        assert "CrashLoopBackOff" not in lines[0]
+        assert "OOMKilled" not in lines[0]
+        # Restart count and exit code are both visible.
+        assert "5 restarts across 2 replicas" in lines[0]
+        assert "exit code 137" in lines[0]
+
+    def test_headline_with_traceback_message(self):
+        """Application Error case: headline plus the last line of the captured traceback."""
+        lines = format_health_lines(
+            {
+                "reason": "CrashLoopBackOff",
+                "lastTerminationReason": "Error",
+                "lastExitCode": 1,
+                "restartCount": 3,
+                "replicasStarted": 2,
+                "headline": "Application Error",
+                "message": (
+                    "Traceback (most recent call last):\n"
+                    '  File "bot.py"\n'
+                    "ModuleNotFoundError: No module named 'nonexistentlibthiswillfail'"
+                ),
+            }
+        )
+        assert len(lines) == 2
+        assert "Application Error" in lines[0]
+        assert "exit code 1" in lines[0]
+        assert "ModuleNotFoundError" in lines[1]
+        assert "Traceback" not in lines[1]
+
+    def test_headline_without_exit_code(self):
+        """ImagePullBackOff and similar pre-start failures have no exit code; the
+        exit-code segment must be omitted, not rendered as 'exit None' or similar."""
+        lines = format_health_lines(
+            {
+                "reason": "ImagePullBackOff",
+                "restartCount": 0,
+                "replicasStarted": 2,
+                "headline": "Cannot pull image",
+                "message": 'Back-off pulling image "nonexistent:latest"',
+            }
+        )
+        assert "Cannot pull image" in lines[0]
+        assert "exit" not in lines[0]
+        assert "ImagePullBackOff" not in lines[0]
+        assert "nonexistent:latest" in lines[1]
+
+    def test_unmapped_reason_falls_back_to_raw_format(self):
+        """An older API response (or a future unmapped reason) has no headline;
+        rendering must continue to work via the fallback path."""
+        lines = format_health_lines(
+            {
+                "reason": "CrashLoopBackOff",
+                "lastTerminationReason": "OOMKilled",
+                "lastExitCode": 137,
+                "restartCount": 5,
+                "replicasStarted": 2,
+            }
+        )
+        # Existing format preserved exactly: parens, comma, k8s vocabulary.
+        assert "CrashLoopBackOff (OOMKilled, exit code 137)" in lines[0]
+        assert "5 restarts across 2 replicas" in lines[0]
 
 
 class TestRevisionLineWithHealth: