scalebrowser 0.7.0__tar.gz → 0.8.0__tar.gz

scalebrowser-0.8.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+The Python SDK for the Scalebrowser daemon.
+
+This file starts at 0.5.0, the oldest release still on PyPI when it was written
+(2026-09-09). What came before is in the repository's history. It was never
+published as release notes, and reconstructing it here would look like a record
+that had been kept all along.
+
+The daemon and the SDK version independently. An SDK release names the daemon
+version it was tested against wherever that matters.
+
+## 0.8.0 (2026-09-11)
+
+Breaking: `host_mode` is gone, and with it the `HostMode` alias and the
+`HOST_MODES` tuple. It named one of two tiers, and there is only one left: a
+daemon runs the engine built for its own operating system, so the tier is the
+host. The field disappears from `Profile`, from `CreateProfileBody` and from a
+preset's `config`. A client that keeps sending it is not refused; the daemon
+ignores the key.
+
+Reading a profile from a daemon of this generation needs this release: 0.7.0
+refuses the answer, because `host_mode` and the persona's `headless_guards` are
+no longer in it.
+
+- The source distribution carries the package, the README, this file and the
+  licence, and no longer the repository's own tests and examples.
+
+## 0.7.0 (2026-09-09)
+
+- `check_proxy` and the exit-address views report the address KIND (mobile, fixed
+  line, datacenter, unknown) from an ASN dataset instead of the provider's own
+  description. The ownership term for an exit address follows that kind, so a
+  wrong classification used to be off by a factor of 30.
+- A proxy row carries a name and lists the profiles bound to it.
+- The exit-exclusivity rule has a switch, globally and per profile.
+
+## 0.6.0 (2026-09-01)
+
+- Remote access (the MCP tunnel) has a switch. It ships off, and it can only be
+  turned on at the machine itself.
+
+## 0.5.0 (2026-08-31)
+
+- Every profile carries a memory (`PROFILE.md`) and a task list. Both are
+  reachable through the client.
+- `proxy_short_side` in both SDKs.
+- The agent layer says "lease" throughout, matching the names of its tools.
+
+## What this file does not promise
+
+Nothing here promises a stable wire format. The daemon's REST surface is
+versioned under `/v1` and this client tracks it. A breaking change there arrives
+as a major version of the SDK, with the reason written in this file.

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: scalebrowser
-Version: 0.7.0
-Summary: Official Python SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver (nodriver-style).
+Version: 0.8.0
+Summary: Official Python SDK for the Scalebrowser daemon: typed REST client plus a direct-CDP driver (nodriver-style).
 Project-URL: Homepage, https://scalebrowser.net
 Project-URL: Documentation, https://scalebrowser.net
+Project-URL: Examples, https://github.com/blackdiamond-labs/scalebrowser-mcp/tree/main/examples/python
 Author: Scalebrowser
 License-Expression: MIT
 License-File: LICENSE
@@ -25,6 +26,7 @@ Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: tomli>=2.4.1; (python_version < '3.11') and extra == 'dev'
 Description-Content-Type: text/markdown
 
 # scalebrowser: the Python SDK

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scalebrowser"
-version = "0.7.0"
-description = "Official Python SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver (nodriver-style)."
+version = "0.8.0"
+description = "Official Python SDK for the Scalebrowser daemon: typed REST client plus a direct-CDP driver (nodriver-style)."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -32,17 +32,26 @@ dependencies = [
 [project.urls]
 Homepage = "https://scalebrowser.net"
 Documentation = "https://scalebrowser.net"
+Examples = "https://github.com/blackdiamond-labs/scalebrowser-mcp/tree/main/examples/python"
 
 [project.optional-dependencies]
 dev = [
   "pytest>=8",
   "pytest-asyncio>=0.23",
   "build>=1.2",
+  # The tests read this file; tomllib only exists from 3.11 on, and the floor is 3.10.
+  "tomli>=2.4.1; python_version < '3.11'",
 ]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/scalebrowser"]
 
+# Das Quellpaket trug ohne diese Liste auch tests/ und examples/ nach pypi.org,
+# und damit Verweise ins Repo und Gedankenstriche, die kein Gate sah. Es liefert
+# jetzt dasselbe aus wie das Rad, plus die drei Texte, die ein Kunde liest.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/scalebrowser", "README.md", "CHANGELOG.md", "LICENSE"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/__init__.py

@@ -74,6 +74,7 @@ from .models import (
     AuditReport,
     AuditStatus,
     ExitStatus,
+    ProfileCounts,
     Extension,
     ExtensionPolicy,
     CredentialBundle,
@@ -85,7 +86,6 @@ from .models import (
     GeoMode,
     GpuPersona,
     Group,
-    HostMode,
     Locale,
     MediaDevice,
     Metrics,
@@ -192,7 +192,6 @@ __all__ = [
     "parse_sse_frame",
     # enums
     "RuntimeState",
-    "HostMode",
     "GeoMode",
     "ProxyKind",
     "Rotation",
@@ -247,6 +246,7 @@ __all__ = [
     "AuditReport",
     "AuditStatus",
     "ExitStatus",
+    "ProfileCounts",
     "Extension",
     "ExtensionPolicy",
     "CredentialBundle",

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/_version.py

@@ -5,4 +5,4 @@ distribution actually carries. This file is a second copy of that number, not
 its source: hatchling never reads it.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/client.py

@@ -25,6 +25,7 @@ from .models import (
     RunStep,
     AuditStatus,
     ExitStatus,
+    ProfileCounts,
     BulkAssignProxyBody,
     BulkCreateBody,
     BulkIdsBody,
@@ -99,6 +100,7 @@ from .models_videos import (
     Recording,
     RenderRequestBody,
     ShareLinkLocal,
+    ShareStatus,
     TtsProviderView,
     TtsVerifyResult,
     Video,
@@ -277,6 +279,24 @@ class AsyncScalebrowserClient:
             params={"group": group, "state": state, "q": q, "sort": sort, "order": order},
         )
 
+    async def count_profiles(
+        self,
+        *,
+        group: Optional[str] = None,
+        q: Optional[str] = None,
+    ) -> ProfileCounts:
+        """How many profiles match, split by runtime state, in one small response.
+
+        ``list_profiles`` is paged and answers a bare array, so counting what came
+        back counts the page. ``list_profile_ids`` carries the same total but ships
+        an identifier per profile to do it, and cannot split by state at all.
+
+        There is deliberately no ``state`` parameter: the route ignores it, because
+        a caller labelling every state is sitting in one of them.
+        """
+        data = await self._t.get("/v1/profiles/count", params={"group": group, "q": q})
+        return ProfileCounts.model_validate(data)
+
     async def bulk_start(self, ids: Sequence[str], *, headless: Optional[bool] = None) -> Any:
         """Start a batch.
 
@@ -987,7 +1007,7 @@ class AsyncScalebrowserClient:
         data = await self._t.post(f"/v1/videos/{_q(video_id)}/share", body)
         return ShareLinkLocal.model_validate(data)
 
-    async def share_status(self, video_id: str) -> ShareLinkLocal:
+    async def share_status(self, video_id: str) -> ShareStatus:
         """The share ORDER as this machine knows it.
 
         How many people watched and whether the link still lives is read from the
@@ -995,7 +1015,7 @@ class AsyncScalebrowserClient:
         moment another machine revoked.
         """
         data = await self._t.get(f"/v1/videos/{_q(video_id)}/share")
-        return ShareLinkLocal.model_validate(data)
+        return ShareStatus.model_validate(data)
 
     async def revoke_share(self, video_id: str) -> None:
         """Revoke the link. The files fall at once."""

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/errors.py

@@ -1,7 +1,7 @@
 """Typed SDK errors and the daemon's stable numeric error codes.
 
 The daemon returns error bodies shaped ``{ "code": <4001-4013>, "message": "…" }``
-with the HTTP status from ``core::Error::http_status()`` (docs/features/api.md, SPEC §5).
+and the matching HTTP status.
 """
 
 from __future__ import annotations
@@ -10,7 +10,7 @@ from typing import Any, Final, Optional
 
 
 class ErrorCode:
-    """Stable numeric API error codes (SPEC §5, ``crates/core/src/error.rs``)."""
+    """The daemon's stable numeric API error codes."""
 
     NOT_FOUND: Final = 4001
     PROXY_GEO: Final = 4002

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/events.py

@@ -1,8 +1,7 @@
 """Live lifecycle event stream (``GET /v1/events``, AC-API-003).
 
 We read the ``text/event-stream`` over the authenticated transport and frame it
-into the typed :data:`~scalebrowser.models.Event` union, mirroring the behaviour
-of ``web-ui/src/api/events.ts``.
+into the typed :data:`~scalebrowser.models.Event` union.
 """
 
 from __future__ import annotations

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/models.py

@@ -1,6 +1,5 @@
-"""Wire models: a 1:1 mirror of the daemon's serialized domain model and the
-endpoint contract in ``docs/features/api.md`` (kept in lockstep with
-``web-ui/src/api/types.ts``).
+"""Wire models: a 1:1 mirror of the daemon's serialized domain model and of
+its endpoint contract.
 
 All Rust enums serialize ``snake_case``. Timestamps are unix seconds (``int``).
 Read models tolerate unknown fields (forward-compat); request models are plain
@@ -19,10 +18,6 @@ from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
 RuntimeState = Literal["stopped", "starting", "running", "crashed"]
 RUNTIME_STATES: tuple[RuntimeState, ...] = ("stopped", "starting", "running", "crashed")
 
-HostMode = Literal["linux_engine_spoof", "local_native_windows"]
-HOST_MODES: tuple[HostMode, ...] = ("linux_engine_spoof", "local_native_windows")
-
-
 GeoMode = Literal["strict_expected", "follow_exit", "off"]
 GEO_MODES: tuple[GeoMode, ...] = ("strict_expected", "follow_exit", "off")
 
@@ -156,7 +151,6 @@ class PersonaMisc(_ReadModel):
     get_installed_related_apps: bool
     max_touch_points: int
     pdf_viewer_enabled: bool
-    headless_guards: bool
 
 
 class Persona(_ReadModel):
@@ -210,7 +204,6 @@ class Profile(_ReadModel):
     seed: str
     engine_version: str
     persona: Persona
-    host_mode: HostMode
     gpu_persona: Optional[str] = None
     group_id: Optional[str] = None
     proxy_id: Optional[str] = None
@@ -249,7 +242,6 @@ class PresetConfig(_ReadModel):
 
     # Pin the batch to one engine build. Omit for per-profile version diversity.
     engine_version: Optional[str] = None
-    host_mode: Optional[HostMode] = None
     geo_mode: Optional[GeoMode] = None
     # The geo GATE's expectation, not the persona's drawn region.
     expected_country: Optional[str] = None
@@ -349,7 +341,6 @@ class ProxyRow(Proxy):
 class CreateProfileBody(_WriteModel):
     name: str
     seed: Optional[str] = None
-    host_mode: Optional[HostMode] = None
     geo_mode: Optional[GeoMode] = None
     expected_country: Optional[str] = None
     #: Draw the identity for this region (ISO-3166 alpha-2, e.g. ``"DE"``): language,
@@ -370,11 +361,9 @@ class CreateProfileBody(_WriteModel):
 
 
 class UpdateProfileBody(_WriteModel):
-    # host_mode, seed and persona_country are fixed at create time (C4/C5): a
-    # DIFFERING host_mode is refused with 400, an unchanged echo is accepted. A tier
-    # change needs recreate. The drawn region cannot move either, because the whole
-    # persona hangs off the seed; what does change a running profile's region is its
-    # exit, through geo_mode.
+    # seed and persona_country are fixed at create time (C5). The drawn region
+    # cannot move, because the whole persona hangs off the seed; what does change a
+    # running profile's region is its exit, through geo_mode.
     name: Optional[str] = None
     geo_mode: Optional[GeoMode] = None
     expected_country: Optional[str] = None
@@ -941,7 +930,7 @@ EVENT_ADAPTER: TypeAdapter[Event] = TypeAdapter(Event)
 
 __all__ = [
     # enums
-    "RuntimeState", "RUNTIME_STATES", "HostMode", "HOST_MODES",
+    "RuntimeState", "RUNTIME_STATES",
     "GeoMode", "GEO_MODES", "ProxyKind", "PROXY_KINDS",
     "Rotation", "ROTATIONS", "SessionKind", "OsFamily", "InputAction",
     "RunActor", "RunOutcome", "StepKind",
@@ -1060,6 +1049,25 @@ class ExitClaimView(BaseModel):
     expires_at: int
 
 
+class ProfileCounts(_ReadModel):
+    """How many profiles match, split by runtime state (``GET /v1/profiles/count``).
+
+    ``total`` counts ROWS, so it equals the sum of the four states for every state
+    this daemon can read; a row in a state a newer build introduced counts in
+    ``total`` alone rather than being folded into ``stopped``.
+
+    The ``state`` filter is the one the route ignores. A caller labelling all four
+    scopes is sitting in one of them, so narrowing by it would answer the other
+    three with zero.
+    """
+
+    total: int
+    stopped: int = 0
+    starting: int = 0
+    running: int = 0
+    crashed: int = 0
+
+
 class ExitStatus(BaseModel):
     """A profile's exit-address situation.
 

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/models_control.py

@@ -1,8 +1,5 @@
 """What the browser asks (interruptions), the bytes that go in and out
 (artifacts), and what the licence says (account).
-
-Interruption shapes mirror ``web-ui/src/api/types/credentials.ts``, the shared
-source of contract truth.
 """
 
 from __future__ import annotations

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/models_identity.py

@@ -1,9 +1,8 @@
 """The account layer: mailboxes, passkeys and the one door a cookie value leaves
 through.
 
-Mailbox and passkey shapes mirror ``web-ui/src/api/types/{inboxes,credentials}.ts``,
-the shared source of contract truth. The cookie reveal has no UI counterpart: it
-is a REST-only route deliberately kept off every screen.
+The cookie reveal has no counterpart in the management app: it is a REST-only
+route deliberately kept off every screen.
 """
 
 from __future__ import annotations

{scalebrowser-0.7.0 → scalebrowser-0.8.0}/src/scalebrowser/models_videos.py

@@ -1,7 +1,6 @@
 """Videos and recordings (``/v1/videos``, ``/v1/recordings``).
 
-Mirrors ``crates/core/src/video/rows.rs``. A video row never carries a
-directory or a file name (the daemon may be on another machine), so files are
+A video row never carries a directory or a file name (the daemon may be on another machine), so files are
 fetched through the grant route (:meth:`~scalebrowser.AsyncScalebrowserClient.video_access`
 → :meth:`~scalebrowser.AsyncScalebrowserClient.download_video_file`).
 
@@ -21,7 +20,7 @@ RecordingState = Literal["recording", "finishing", "finished", "failed"]
 VideoState = Literal["queued", "rendering", "done", "failed", "cancelled"]
 ExportPresetName = Literal["web", "social", "4k", "editing", "gif"]
 AudioStatus = Literal["ok", "silent", "off", "failed"]
-RenderStage = Literal["planning", "narration", "compositing", "encoding", "finishing"]
+RenderStage = Literal["planning", "narration", "compositing", "encoding", "finishing", "extras"]
 # Die Extras tragen dasselbe Praefix wie das Schluessel-Register des Daemons
 # (`extra:<preset>`): ein zweiter Export ist unter dem Namen erreichbar, unter
 # dem er abgelegt wurde, nicht unter einem, den der Aufrufer erfindet.
@@ -95,9 +94,11 @@ class TimestampState(_ReadModel):
 
 
 class TranscriptWord(_ReadModel):
+    """One spoken word and when it is heard in the finished video, in milliseconds from its start."""
+
     text: str
-    from_ms: int
-    to_ms: int
+    start_ms: int
+    end_ms: int
 
 
 class Video(_ReadModel):
@@ -143,7 +144,10 @@ class Recording(_ReadModel):
     kind: RecordingKind
     state: RecordingState
     title: Optional[str] = None
+    #: The id of the stored preset the recording was made under, ``None`` when it named none.
     preset_id: Optional[str] = None
+    #: That preset's name as it read when the recording started.
+    preset_name: Optional[str] = None
     preset: dict[str, Any]
     manifest_version: int
     css_width: int
@@ -237,10 +241,12 @@ class VideosCapacity(_ReadModel):
 class VideosStorage(_ReadModel):
     recordings_bytes: int
     videos_bytes: int
+    #: The main files of the videos this machine still shares.
     link_bytes: int
-    link_limit: int
-    uploads_today: int
-    uploads_limit: int
+    #: Known only to the control plane; ``None`` here.
+    link_limit: Optional[int] = None
+    uploads_today: Optional[int] = None
+    uploads_limit: Optional[int] = None
     capacity: VideosCapacity
 
 
@@ -257,10 +263,23 @@ class OpenH264Status(_ReadModel):
     notice: str
 
 
+class BlockedExport(_ReadModel):
+    """One export the daemon refuses, e.g. ``4k`` while a 3840-wide capture is
+    not offered. ``reason`` starts with its snake code."""
+
+    export: ExportPresetName
+    reason: str
+
+
 class CodecsStatus(_ReadModel):
     openh264: OpenH264Status
     #: Hardware encoders that passed a real test encode, in preference order.
     hardware: list[str]
+    #: Whether the hardware probe has run. Before it, an empty ``hardware`` means
+    #: "not asked yet", not "none".
+    probed: bool = False
+    #: Exports this daemon refuses whatever the order says, with the reason.
+    exports_blocked: list[BlockedExport] = []
 
 
 class MediaAsset(_ReadModel):
@@ -359,3 +378,19 @@ class ShareLinkLocal(_ReadModel):
     download: bool
     updated_at: int
     error: Optional[str] = None
+
+
+
+class ShareStatus(ShareLinkLocal):
+    """``GET /v1/videos/:id/share``: the order, and the link's access code when
+    this machine keeps one (sealed at rest).
+
+    A link the daemon makes for a preset with ``export.destination.passcode``
+    gets a generated code of ten characters, and this is where its owner reads
+    it. ``Video.share``, ``video_changed`` and the ``video`` tool never carry the
+    code.
+    """
+
+    code: Optional[str] = None
+    """Absent on the wire when this machine keeps no code: the link has none, or
+    its revocation is ordered. Reads as ``None`` then."""

scalebrowser-0.7.0/examples/quickstart.py

@@ -1,45 +0,0 @@
-"""Async quickstart: start a profile, drive it over direct-CDP, humanize a click,
-stop it.
-
-    SCALEBROWSER_TOKEN=… SCALEBROWSER_PROFILE_ID=… python examples/quickstart.py
-
-Requires a running Scalebrowser daemon (the driver plane is direct-CDP, not
-Playwright).
-"""
-
-from __future__ import annotations
-
-import asyncio
-import os
-
-from scalebrowser import AsyncScalebrowserClient, CreateProfileBody
-
-
-async def main() -> None:
-    base_url = os.environ.get("SCALEBROWSER_BASE_URL", "http://127.0.0.1:8787")
-    token = os.environ.get("SCALEBROWSER_TOKEN")
-
-    async with AsyncScalebrowserClient(base_url, token=token) as sb:
-        # Reuse a profile if given, otherwise create one.
-        profile_id = os.environ.get("SCALEBROWSER_PROFILE_ID")
-        if profile_id is None:
-            profile = await sb.create_profile(CreateProfileBody(name="quickstart"))
-            profile_id = profile.id
-            print(f"created profile {profile_id}")
-
-        # start → direct-CDP connect → navigate → humanized click → stop
-        async with sb.launch(profile_id, headless=True) as page:
-            await page.navigate("https://example.com")
-            title = await page.evaluate("document.title")
-            print(f"page title: {title!r}")
-
-            # Humanized trusted input goes through the daemon (G8), not raw CDP.
-            await page.humanize_move(120, 240)
-            await page.humanize_click(120, 240)
-            print("humanized click sent")
-
-        print("profile stopped")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

scalebrowser-0.7.0/examples/quickstart_sync.py

@@ -1,35 +0,0 @@
-"""Synchronous quickstart — same flow as ``quickstart.py`` without async/await.
-
-    SCALEBROWSER_TOKEN=… SCALEBROWSER_PROFILE_ID=… python examples/quickstart_sync.py
-"""
-
-from __future__ import annotations
-
-import os
-
-from scalebrowser import CreateProfileBody, ScalebrowserClient
-
-
-def main() -> None:
-    base_url = os.environ.get("SCALEBROWSER_BASE_URL", "http://127.0.0.1:8787")
-    token = os.environ.get("SCALEBROWSER_TOKEN")
-
-    with ScalebrowserClient(base_url, token=token) as sb:
-        profile_id = os.environ.get("SCALEBROWSER_PROFILE_ID")
-        if profile_id is None:
-            profile = sb.create_profile(CreateProfileBody(name="quickstart-sync"))
-            profile_id = profile.id
-            print(f"created profile {profile_id}")
-
-        with sb.launch(profile_id, headless=True) as page:
-            page.navigate("https://example.com")
-            print(f"page title: {page.evaluate('document.title')!r}")
-            page.humanize_move(120, 240)
-            page.humanize_click(120, 240)
-            print("humanized click sent")
-
-        print("profile stopped")
-
-
-if __name__ == "__main__":
-    main()