pipecatcloud 1.5.0__tar.gz → 1.6.0__tar.gz

{pipecatcloud-1.5.0 → pipecatcloud-1.6.0}/CHANGELOG.md

@@ -5,6 +5,93 @@ 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).
 
+## [1.6.0] - 2026-11-12
+
+### Added
+
+- `project` is the command group for everything you deploy and run. A project
+  is an agent with environments; each environment is an agent of its own, and
+  `--env` addresses one through its project.
+
+  ```
+  pipecat cloud project list
+  pipecat cloud project status my-bot --env staging
+  pipecat cloud project logs my-bot --env pr-7
+  ```
+
+  Every command that took an agent name takes `--env` as well: `status`,
+  `logs`, `sessions`, `deployments`, `delete`, `start`, `stop`, `link`,
+  `unlink` and `deploy`. A positional agent name still works, so
+  `project status my-bot-pr-7` resolves the same preview.
+
+- `project env` manages a project's environments.
+
+  - `project env add <project> <name> --agent <agent>` links an existing agent
+    as an environment. `project env remove` unlinks it, leaving it running as
+    a project of its own. `project env list` lists them: `production`, which
+    is the project's own agent, then the named environments and then the PR
+    previews.
+  - `--env production` is the project itself, which is the environment it
+    doubles as, so it means the same as naming the project with no `--env`.
+    `env promote` and `env remove` name an environment to act on, so they
+    refuse `production` and say why.
+  - `project env promote <project> <name>` deploys an environment's running
+    build, or the image it was deployed from, onto the project. Code only: the
+    project keeps its own secrets, scaling and profile. It confirms first, and
+    `--force` skips the prompt.
+
+- `project previews enable <project> --secret-set <set>` turns PR previews on,
+  with `--bot-pull-requests` to include pull requests opened by bots.
+  `project previews disable` turns them off and deletes the previews it has.
+  `project previews status` shows the setting and the open previews.
+
+- `project watch-paths set <project> <pattern>...` sets the glob patterns a
+  change has to match to deploy, `clear` removes them, and `show` prints them. They are a
+  project setting: its environments and previews follow the same list.
+
+- `project list --all` includes environments and PR previews. Without it the
+  listing is projects only, as the dashboard shows them. Both carry columns for
+  a project's environment count and preview setting, and `--all` names each
+  environment's project.
+
+- `deploy`, when it runs a cloud build, and `docker build-push` warn when the
+  Dockerfile builds `FROM dailyco/pipecat-base:latest`, or from
+  `dailyco/pipecat-base` with no tag. That tag names no Python, runs Python
+  3.12, and stops building on 2027-04-05. The warning names the line, and the
+  tag that keeps the same Python: `dailyco/pipecat-base:latest-py3.12`.
+
+### Changed
+
+- `agent` is **deprecated**. It is the same group under its old name: every
+  command goes on working and `agent list` goes on listing every agent, with a
+  notice on stderr pointing at `project`. Use `project`, and `--env` to address
+  an environment.
+- `status` reports the project and environment of an agent that is one, its
+  watch paths, and, for a project, whether PR previews are on and whether bot
+  pull requests get them. For a PR preview it names the pull request.
+
+### Removed
+
+- `agent scale` is gone. It was never implemented: it printed "Not implemented"
+  and exited. Set an agent's instance counts with `pipecat cloud deploy
+  --min-agents/--max-agents`, or the `[scaling]` section of `pcc-deploy.toml`.
+
+### Fixed
+
+- A command no longer reports an operation as done when the CLI never managed
+  to make the request. A mistake inside the client, such as a call made with a
+  name the API method does not take, was handed back as an empty result, and
+  every command reads an empty error as success: a build promotion printed
+  "Promoted build ..." having sent no request at all. Such a failure now ends
+  the command with a non-zero exit code.
+- A command that cannot reach the API, or cannot read its answer, now says so
+  and exits 1. A dropped connection, a host that does not resolve, a request
+  that timed out and an answer that stops part way through were all read as an
+  empty answer, which most commands reported as success. `secrets set`
+  already said so, and still says whether a write it got no answer for may have
+  been stored. `deploy` and `github connect` still treat it as a blip while
+  they are waiting, and keep polling.
+
 ## [1.5.0] - 2026-11-05
 
 ### Added

{pipecatcloud-1.5.0/src/pipecatcloud.egg-info → pipecatcloud-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipecatcloud
-Version: 1.5.0
+Version: 1.6.0
 Summary: Cloud hosting for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Website, https://docs.pipecat.ai/pipecat-cloud

pipecatcloud-1.6.0/src/pipecatcloud/_utils/base_image.py

@@ -0,0 +1,89 @@
+#
+# Copyright (c) 2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Warnings about the base image an agent's Dockerfile builds from.
+
+``dailyco/pipecat-base:latest`` names no Python, so it carries Python 3.12, and
+it stops building on ``LATEST_RETIRES``. A Dockerfile that takes it is warned
+before its build. Version tags without ``-py3.X``, such as ``0.3.0``, are
+deprecated too, but each is fixed to one image and stays published, so a
+Dockerfile pinned to one keeps building and is not warned.
+"""
+
+import re
+from pathlib import Path
+
+from rich.markup import escape
+
+from pipecatcloud._utils.console_utils import console
+
+LATEST_RETIRES = "2027-04-05"
+LATEST_PYTHON = "3.12"
+
+# Docker Hub's own names for the repository, which Docker resolves alike.
+_BASE_IMAGE = re.compile(
+    r"(?:(?:docker\.io|index\.docker\.io|registry-1\.docker\.io)/)?dailyco/pipecat-base"
+    r"(?::(?P<tag>[\w][\w.-]*))?(?P<digest>@\S+)?"
+)
+_FROM = re.compile(r"\s*FROM\s+(?:--\S+\s+)*(?P<image>\S+)", re.IGNORECASE)
+
+
+def _instructions(text: str):
+    """Each instruction with the line it starts on, continuation lines joined.
+
+    Comment lines are dropped, inside a continuation too, as Docker drops them.
+    """
+    start, parts = None, []
+    for number, line in enumerate(text.splitlines(), start=1):
+        if line.lstrip().startswith("#"):
+            continue
+        if start is None:
+            start = number
+        if line.rstrip().endswith("\\"):
+            parts.append(line.rstrip()[:-1])
+            continue
+        parts.append(line)
+        yield start, " ".join(parts)
+        start, parts = None, []
+    if parts:
+        yield start, " ".join(parts)
+
+
+def latest_base_images(text: str) -> list[tuple[int, str]]:
+    """The FROM instructions that take ``dailyco/pipecat-base:latest``.
+
+    Returns each one's line number and image, as written. A FROM with no tag
+    takes ``latest`` too. One pinned by digest is fixed, and one built from a
+    variable cannot be read here, so neither is returned.
+    """
+    found = []
+    for number, instruction in _instructions(text):
+        match = _FROM.match(instruction)
+        if not match:
+            continue
+        image = match["image"]
+        base = _BASE_IMAGE.fullmatch(image)
+        if base and not base["digest"] and base["tag"] in (None, "latest"):
+            found.append((number, image))
+    return found
+
+
+def warn_latest_base_image(dockerfile: Path) -> None:
+    """Warn for each FROM in ``dockerfile`` that takes the base image's ``latest``.
+
+    An unreadable Dockerfile is left to the build to report.
+    """
+    try:
+        text = dockerfile.read_text(errors="replace")
+    except OSError:
+        return
+    for number, image in latest_base_images(text):
+        console.print(
+            f"[yellow]Warning: {escape(dockerfile.name)} line {number} builds FROM "
+            f"{escape(image)}, which stops building on {LATEST_RETIRES}. It names no "
+            f"Python, and runs Python {LATEST_PYTHON}: to keep it, use "
+            f"dailyco/pipecat-base:latest-py{LATEST_PYTHON}.[/yellow]"
+        )

{pipecatcloud-1.5.0 → pipecatcloud-1.6.0}/src/pipecatcloud/_utils/deploy_utils.py

@@ -763,7 +763,7 @@ def report_git_deploy_result(
     from pipecatcloud.cli import PIPECAT_CLI_NAME
 
     check_hint = (
-        f"[dim]Check it with [bold]{PIPECAT_CLI_NAME} agent status {agent_name}[/bold].[/dim]"
+        f"[dim]Check it with [bold]{PIPECAT_CLI_NAME} project status {agent_name}[/bold].[/dim]"
     )
     label = "First deploy" if first_deploy else "Deploy"
 

pipecatcloud-1.6.0/src/pipecatcloud/_utils/environment_utils.py

@@ -0,0 +1,136 @@
+#
+# Copyright (c) 2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Shared helpers for projects and environments (PCC-1255).
+
+An environment is an agent of its own, linked to the project it belongs to.
+The project doubles as its own `production` environment, so a project is
+simply an agent with no parent. These helpers read that shape out of the
+service payloads the API already returns, and mirror the name rules it
+enforces so a typo fails before the round trip.
+"""
+
+import re
+
+#: What the project itself is called among its environments.
+PRODUCTION_ENVIRONMENT_NAME = "production"
+
+#: PR previews are named `pr-<n>`, so the API reserves the prefix.
+PREVIEW_ENVIRONMENT_PREFIX = "pr-"
+
+#: The width of the environments.name column.
+MAX_ENVIRONMENT_NAME_LENGTH = 50
+
+# The agent-name rule, which environment names follow too.
+_ENVIRONMENT_NAME_SHAPE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])$")
+
+_PREVIEW_NAME = re.compile(r"^pr-(\d+)$")
+
+
+def environment_name_problem(name: str) -> str | None:
+    """Why the API would refuse this environment name, or None when it's fine."""
+    if not name:
+        return "Enter a name for the environment."
+    if name == PRODUCTION_ENVIRONMENT_NAME:
+        return f"'{PRODUCTION_ENVIRONMENT_NAME}' is the project itself, so it can't be an environment name."
+    if name.startswith(PREVIEW_ENVIRONMENT_PREFIX):
+        return f"Names starting with '{PREVIEW_ENVIRONMENT_PREFIX}' are reserved for PR previews."
+    if len(name) > MAX_ENVIRONMENT_NAME_LENGTH:
+        return f"Use at most {MAX_ENVIRONMENT_NAME_LENGTH} characters."
+    if not _ENVIRONMENT_NAME_SHAPE.match(name):
+        return (
+            "Use two or more lowercase letters, digits and dashes, starting and "
+            "ending with a letter or digit."
+        )
+    return None
+
+
+def is_preview_name(name: str | None) -> bool:
+    """Whether an environment's name is a PR preview's."""
+    return bool(name and _PREVIEW_NAME.match(name))
+
+
+def environment_sort_key(name: str) -> tuple[int, int, str]:
+    """Named environments by name, then PR previews, newest pull request first."""
+    preview = _PREVIEW_NAME.match(name or "")
+    if preview:
+        return (1, -int(preview.group(1)), "")
+    return (0, 0, name or "")
+
+
+def is_environment(service: dict) -> bool:
+    """Whether this agent is an environment of another agent."""
+    return bool(service.get("parentServiceId"))
+
+
+def projects_in(services: list[dict]) -> list[dict]:
+    """The agents that are projects: the ones that are not environments."""
+    return [service for service in services if not is_environment(service)]
+
+
+def environments_of(services: list[dict], project: dict) -> list[dict]:
+    """A project's environments, named ones first and then its PR previews."""
+    children = [
+        service for service in services if service.get("parentServiceId") == project.get("id")
+    ]
+    return sorted(children, key=lambda s: environment_sort_key(s.get("environmentName") or ""))
+
+
+def environments_with_production(services: list[dict], project: dict) -> list[dict]:
+    """A project's environments, the project itself first as `production`.
+
+    The project doubles as that environment, so a listing that left it out
+    would contradict the model the rest of the group works to. Callers that
+    mean only the agents linked to the project use `environments_of`.
+    """
+    return [
+        {**project, "environmentName": PRODUCTION_ENVIRONMENT_NAME},
+        *environments_of(services, project),
+    ]
+
+
+def promotion_source(environment: dict) -> dict | None:
+    """What promoting this environment deploys: its build, or the image it runs.
+
+    None when it has nothing deployed. Promotion moves code only, so this is
+    the whole payload the project is updated with.
+    """
+    deployment = environment.get("deployment") or {}
+    build_id = deployment.get("buildId")
+    if build_id:
+        return {"buildId": build_id}
+    image = ((deployment.get("manifest") or {}).get("spec") or {}).get("image")
+    if image:
+        return {"image": image}
+    return None
+
+
+def describe_promotion_source(source: dict) -> str:
+    """A promotion source as a short phrase, for confirmations and messages."""
+    build_id = source.get("buildId")
+    return f"build {build_id}" if build_id else str(source.get("image"))
+
+
+def previews_on(service: dict) -> bool:
+    """Whether this project has PR previews on.
+
+    Choosing the secret set previews mount is what turns them on, so the set
+    being present is the setting.
+    """
+    git = service.get("git") or {}
+    return bool(git.get("previewSecretSet"))
+
+
+def project_label(service: dict, project_names: dict[str, str]) -> str:
+    """`project > environment` for an environment, or a dash for a project.
+
+    `project_names` maps agent id to name, which is how a parent's name is
+    resolved: the service payload carries only `parentServiceId`.
+    """
+    if not is_environment(service):
+        return "—"
+    parent = project_names.get(service.get("parentServiceId") or "", "?")
+    return f"{parent} > {service.get('environmentName') or '?'}"

{pipecatcloud-1.5.0 → pipecatcloud-1.6.0}/src/pipecatcloud/api.py

@@ -164,6 +164,30 @@ class _API:
         self.token = new_token
         return new_token
 
+    def _record_unread_answer(self, e: BaseException, reading_the_answer: bool = False) -> None:
+        """Record a request that produced no answer this client could read, in
+        the shape of an error body from the API so that it renders as the
+        failure it is. The exception's type is named, never its text, which can
+        carry the URL and the body the request was sent with.
+
+        `error_status` and `error_retry_after` stay None whether the answer never
+        began or stopped part way through: there is no answer to take the
+        outcome from. That is what `no_response()` reads, and what tells a
+        caller the request may still have been carried out.
+        """
+        reach = (
+            "Could not read the answer from the Pipecat Cloud API"
+            if reading_the_answer
+            else "Could not reach the Pipecat Cloud API"
+        )
+        self.error = {
+            "error": (
+                f"{reach} ({describe_exception(e)}). Check your network connection and try again."
+            )
+        }
+        self.error_status = None
+        self.error_retry_after = None
+
     # TODO: several auth.py and agent.py calls bypass _base_request() with their
     # own aiohttp.ClientSession(). A longer-term cleanup could route all PCC API
     # calls through _base_request() so headers (User-Agent, Auth) are set in one place.
@@ -193,13 +217,22 @@ class _API:
                 f"params: {describe_body(params)} body: {describe_body(json)}"
             )
 
-            response = await session.request(
-                method=method,
-                url=url,
-                headers=self._configure_headers(override_token),
-                params=params,
-                json=json,
-            )
+            try:
+                response = await session.request(
+                    method=method,
+                    url=url,
+                    headers=self._configure_headers(override_token),
+                    params=params,
+                    json=json,
+                )
+            except (aiohttp.ClientError, TimeoutError) as e:
+                # The request got no answer at all: the host could not be
+                # resolved or reached, the connection dropped, the request timed
+                # out. Record it before raising, so it renders like any other
+                # failure rather than turning a dropped network into a traceback
+                # from the wrapper in `create_api_method`.
+                self._record_unread_answer(e)
+                raise
             self.capabilities_header = response.headers.get(CAPABILITIES_HEADER)
 
             if not response.ok:
@@ -232,7 +265,30 @@ class _API:
             if response.status == 204:
                 return None
 
-            return await response.json()
+            try:
+                return await response.json()
+            except aiohttp.ContentTypeError:
+                # An ok answer that is not JSON. The operation itself succeeded,
+                # so this stays None, the same answer a 204 gives, rather than
+                # becoming a failure: a caller tolerates a missing body already
+                # (`... or {}`), and reporting a completed write as failed would
+                # send the user to repeat it. Spelled out because the swallow in
+                # `create_api_method` that used to produce this is gone.
+                logger.debug(f"Response body is not JSON: {response.status}")
+                return None
+            except (aiohttp.ClientError, TimeoutError, ValueError) as e:
+                # The answer's headers arrived but its body did not: aiohttp
+                # returns from `request()` as soon as the headers are in, so a
+                # connection lost mid-body, a read that timed out, or a body
+                # that ends part way through its JSON all land here rather than
+                # in the catch above. It is the same transport failure, just
+                # later, and the status says only that the server had begun to
+                # answer — not what became of the request. So it is recorded the
+                # same way, with no status: a poll reads it as a blip worth
+                # repeating and a write as one that may or may not have landed,
+                # which is what they did before this answer could be read.
+                self._record_unread_answer(e, reading_the_answer=True)
+                raise
 
     def create_api_method(self, method_func: Callable) -> Callable:
         """Factory method that wraps API methods with error handling and live context"""
@@ -250,7 +306,34 @@ class _API:
                 if live and not self.bubble_next:
                     live.stop()
 
+                if not self.error:
+                    # Nothing recorded an error, so the API did not refuse the
+                    # request: this is a failure on our side of it — a TypeError
+                    # from a keyword that does not match the method's signature,
+                    # an AttributeError, a ValueError for a config value that is
+                    # not set, a KeyError on a response that is not shaped the
+                    # way the method reads it. There is no error to hand back,
+                    # and every caller reads a falsy error as success, so
+                    # returning `(None, None)` here reports a call that never
+                    # happened as a completed operation (cli#223 review: a build
+                    # promotion printed "Promoted build ..." having sent no HTTP
+                    # request at all). Let the exception out instead. In the CLI
+                    # it ends the process non-zero, like any other mistake in a
+                    # command body, and an SDK caller sees the original
+                    # exception rather than a silent None. A request that got no
+                    # response does not land here: `_base_request` records that
+                    # as an error before re-raising, so it still renders.
+                    self.bubble_next = False
+                    raise
+
                 if not self.is_cli and self.error and not self.bubble_next:
+                    if self.no_response():
+                        # Nothing the API said, so there is nothing to put in an
+                        # AgentStartError: the exception itself is what went
+                        # wrong, and it is what a caller of a client library
+                        # expects to catch. The recorded error stays readable on
+                        # the client for anyone who wants the rendered text.
+                        raise e
                     if isinstance(self.error, dict) and self.error.get("status", "429"):
                         raise AgentStartError(self.error)
                     else:
@@ -283,6 +366,15 @@ class _API:
         self.bubble_next = True
         return self
 
+    def no_response(self) -> bool:
+        """Whether the last call failed without an answer this client could
+        read: the API could not be reached, the connection dropped, the request
+        timed out, or the answer stopped part way through its body. A read that
+        got no answer simply has none; a write that got no answer may or may not
+        have landed, which is what the user has to be told. A failure the server
+        did answer with carries its status, so this is False for it."""
+        return self.error is not None and self.error_status is None
+
     # Auth
 
     async def _whoami(self) -> dict:
@@ -323,10 +415,14 @@ class _API:
         url = self.construct_api_url("organization_path")
         results = await self._base_request("GET", url)
 
-        if not results or not results.get("organizations", None):
-            raise
-
-        return results.get("organizations", None) or []
+        # An account that belongs to no organization is not a failed request:
+        # the empty list is the answer, and `organization list` says so in
+        # words. This used to be a bare `raise` — a RuntimeError, since no
+        # exception was being handled — which the wrapper swallowed into
+        # (None, None); now that it no longer swallows, say it plainly.
+        if not results:
+            return []
+        return results.get("organizations") or []
 
     @property
     def organizations(self):
@@ -1463,3 +1559,123 @@ class _API:
             The deploy intent: id, commitSha, ref, status
         """
         return self.create_api_method(self._agent_git_deploy)
+
+    # Projects and environments
+
+    async def _environment_link(
+        self, agent_name: str, org: str, parent: str, environment_name: str
+    ) -> dict | None:
+        url = self.construct_api_url("service_parent_path").format(org=org, service=agent_name)
+        return await self._base_request(
+            "PUT", url, json={"parent": parent, "environmentName": environment_name}
+        )
+
+    @property
+    def environment_link(self):
+        """Link an agent as an environment of a project.
+
+        A PUT, so it also renames an environment or moves it to another
+        project. The API refuses a link across regions, a chain in either
+        direction, a name another environment holds, and any change to a PR
+        preview's own link.
+
+        Args:
+            agent_name: Name of the agent to become an environment
+            org: Organization ID
+            parent: Name of the project it belongs to
+            environment_name: What to call it among that project's environments
+        Returns:
+            serviceName, parent, environmentName
+        """
+        return self.create_api_method(self._environment_link)
+
+    async def _environment_unlink(self, agent_name: str, org: str) -> dict | None:
+        url = self.construct_api_url("service_parent_path").format(org=org, service=agent_name)
+        return await self._base_request("DELETE", url)
+
+    @property
+    def environment_unlink(self):
+        """Unlink an environment from its project.
+
+        It stays an ordinary agent, running as before. Idempotent: an agent
+        that isn't an environment answers 200.
+
+        Args:
+            agent_name: Name of the environment's agent
+            org: Organization ID
+        Returns:
+            serviceName, parent (null), environmentName (null)
+        """
+        return self.create_api_method(self._environment_unlink)
+
+    async def _previews_update(
+        self, agent_name: str, org: str, secret_set: str | None, bot_pull_requests: bool | None
+    ) -> dict | None:
+        url = self.construct_api_url("service_previews_path").format(org=org, service=agent_name)
+        payload: dict = {"secretSet": secret_set}
+        if bot_pull_requests is not None:
+            payload["botPullRequests"] = bot_pull_requests
+        return await self._base_request("PUT", url, json=payload)
+
+    @property
+    def previews_update(self):
+        """Turn a project's PR previews on with the secret set they mount, or off.
+
+        Choosing the set is what turns previews on; `secret_set=None` turns
+        them off, which also deletes the previews that exist. Leaving
+        `bot_pull_requests` as None keeps the stored value.
+
+        Args:
+            agent_name: Name of the project
+            org: Organization ID
+            secret_set: Secret set previews mount, or None to turn them off
+            bot_pull_requests: Whether PRs opened by bots get previews too
+        """
+        return self.create_api_method(self._previews_update)
+
+    async def _watch_paths_update(
+        self, agent_name: str, org: str, watch_paths: list[str]
+    ) -> dict | None:
+        url = self.construct_api_url("service_watch_paths_path").format(org=org, service=agent_name)
+        result = await self._base_request("PUT", url, json={"watchPaths": watch_paths}) or {}
+        return result
+
+    @property
+    def watch_paths_update(self):
+        """Set a project's watch paths. An empty list clears them.
+
+        A project setting: its production, its environments and its PR
+        previews all follow this one list, so the API refuses it on an
+        environment.
+
+        Args:
+            agent_name: Name of the project
+            org: Organization ID
+            watch_paths: Glob patterns a change must match to deploy
+        Returns:
+            watchPaths, as stored
+        """
+        return self.create_api_method(self._watch_paths_update)
+
+    async def _agent_update_source(
+        self, agent_name: str, org: str, build_id: str | None = None, image: str | None = None
+    ) -> dict | None:
+        url = f"{self.construct_api_url('services_path').format(org=org)}/{agent_name}"
+        payload = {"buildId": build_id} if build_id else {"image": image}
+        return await self._base_request("POST", url, json=payload)
+
+    @property
+    def agent_update_source(self):
+        """Deploy a build or an image onto an agent, changing nothing else.
+
+        The update merges only the artifact into the agent's live manifest, so
+        its secrets, scaling and profile are left as they are. This is what
+        promotion does.
+
+        Args:
+            agent_name: Name of the agent to deploy onto
+            org: Organization ID
+            build_id: Build to deploy
+            image: Image to deploy, when there is no build
+        """
+        return self.create_api_method(self._agent_update_source)