videovector 1.0.0__tar.gz

videovector-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Vector Methods
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

videovector-1.0.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: videovector
+Version: 1.0.0
+Summary: Python SDK for the VideoVector API
+Author: Vector Methods
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/VectorMethods/videovector-python
+Project-URL: Documentation, https://github.com/VectorMethods/videovector-python#readme
+Project-URL: Repository, https://github.com/VectorMethods/videovector-python
+Project-URL: Issues, https://github.com/VectorMethods/videovector-python/issues
+Keywords: video,search,ai,ml,computer-vision,video-understanding,semantic-search,sdk,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# VideoVector Python SDK
+
+Official Python SDK for the VideoVector API.
+
+This repository is the public source of truth for the Python package, SDK documentation, examples, tests, and release workflow. It does not contain backend, MCP, frontend, deployment, or internal operations code.
+
+## Installation
+
+```bash
+pip install videovector
+```
+
+For local development from this repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import os
+
+from videovector import VideoVector
+
+with VideoVector(api_key=os.environ["VIDEO_VECTOR_API_KEY"]) as client:
+    index = client.indexes.create(name="Field Review Clips")
+
+    upload = client.videos.upload(
+        file="/path/to/video.mp4",
+        title="Store walk-through",
+        index_id=index.index_id,
+    )
+
+    results = client.search.text(
+        index_id=index.index_id,
+        query="employee restocking shelves near checkout",
+        top_k=10,
+    )
+
+    for result in results:
+        print(result.video_id, result.start_time, result.similarity_score)
+```
+
+## Configuration
+
+The SDK reads credentials and operational settings from constructor arguments or environment variables.
+
+| Setting | Environment variable | Notes |
+|---|---|---|
+| API key | `VIDEO_VECTOR_API_KEY` | Recommended for server-to-server workflow calls. |
+| JWT bearer token | `VIDEO_VECTOR_BEARER_TOKEN` | Required for JWT-only endpoints such as API key management. |
+| Auth mode | `VIDEO_VECTOR_AUTH_MODE` | Optional; use `api_key` or `bearer` when both credentials are present. |
+| Base URL | `VIDEO_VECTOR_BASE_URL` | Defaults to `https://api.vectormethods.com/api/v2`. |
+| Timeout | `VIDEO_VECTOR_TIMEOUT` | Seconds; default is `60`. |
+| Retries | `VIDEO_VECTOR_MAX_RETRIES` | Default is `3`. |
+
+Explicit constructor arguments override environment values:
+
+```python
+from videovector import VideoVector
+
+client = VideoVector(
+    api_key="<VIDEO_VECTOR_API_KEY>",
+    base_url="https://api.vectormethods.com/api/v2",
+    timeout=90,
+    max_retries=5,
+)
+```
+
+Configure one auth mode at a time. If both an API key and bearer token are present, set `auth_mode` or `VIDEO_VECTOR_AUTH_MODE`.
+
+## Resource Overview
+
+- `client.videos`: upload, retrieve, process, segments, batch helpers, and playground media.
+- `client.indexes`: index CRUD, paginated index videos, and prompt-run history.
+- `client.prompts`: prompt CRUD, schema validation, usage, video-level synthesis, and semantic indexing config.
+- `client.prompt_runs`: estimate, execute, poll, retrieve results, inspect failures, retry failed segments, and inspect LLM calls.
+- `client.search`: text, image, multimodal, filter, multi-run, and playground search.
+- `client.connectors`: GCS, S3, and Azure connector creation, testing, browsing, and deletion.
+- `client.import_jobs`: bulk import from configured connectors.
+- `client.exports`: index and prompt-run metadata exports.
+- `client.webhooks`: webhook CRUD, delivery inspection, retries, event discovery, and secret rotation.
+- `client.api_keys`: API key CRUD, rotate, revoke, and delete with bearer auth.
+- `client.usage`: usage metrics, history, details, and breakdowns.
+- `client.rate_limits`: rate-limit status and refresh.
+
+Endpoint-by-endpoint coverage is documented in [docs/backend-parity-matrix.md](docs/backend-parity-matrix.md).
+
+## Pagination
+
+Paginated endpoints return `SyncPage[T]` or `AsyncPage[T]`.
+
+```python
+page = client.indexes.list_videos("idx_archive", limit=50)
+for video in page.auto_paging_iter():
+    print(video.video_id)
+```
+
+```python
+from videovector import AsyncVideoVector
+
+async with AsyncVideoVector(api_key="<VIDEO_VECTOR_API_KEY>") as client:
+    page = await client.videos.list_playground(limit=25)
+    async for video in page.auto_paging_iter():
+        print(video.video_id)
+```
+
+## Error Handling
+
+SDK exceptions map to API status classes:
+
+- `AuthenticationError` for `401`
+- `AuthorizationError` for `403`
+- `NotFoundError` for `404`
+- `ValidationError` for validation and other non-specialized `4xx` responses
+- `RateLimitError` for `429`, including `retry_after` when provided
+- `ConflictError` for `409`
+- `ExternalServiceError` for `5xx`
+- `TimeoutError`, `ConnectionError`, and `VideoVectorError` for transport or generic SDK failures
+
+```python
+import os
+
+from videovector import RateLimitError, ValidationError, VideoVector
+
+try:
+    with VideoVector(api_key=os.environ["VIDEO_VECTOR_API_KEY"]) as client:
+        client.search.text(index_id="idx_archive", query="")
+except ValidationError as exc:
+    print(exc.error_code, exc.message)
+except RateLimitError as exc:
+    print("retry after", exc.retry_after)
+```
+
+## Retry and Idempotency
+
+Automatic retries are enabled for:
+
+- idempotent methods: `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE`
+- any request that includes an explicit `idempotency_key`
+
+For non-idempotent operations, pass an idempotency key when retrying is safe:
+
+```python
+run = client.prompt_runs.execute(
+    prompt_id="prompt_scene_review",
+    target={"type": "index", "index_id": "idx_archive"},
+    idempotency_key="scene-review-2026-05-07",
+)
+```
+
+## Examples
+
+The [examples](examples) directory contains runnable, environment-driven examples for common and advanced workflows:
+
+- quickstart upload/search
+- sync and async client usage
+- custom prompt and schema design
+- video-level synthesis
+- text, image, multimodal, and filter search
+- GCS, S3, and Azure connectors
+- import jobs, exports, webhooks, idempotency, failed-segment recovery, usage, and rate limits
+
+Examples intentionally use placeholders and environment variables. Do not hardcode credentials in application code.
+
+## Development
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+ruff check videovector tests examples
+mypy videovector
+pytest -q tests
+python -m build
+python -m twine check dist/*
+```
+
+Optional local secret scan:
+
+```bash
+gitleaks detect --source . --no-git --redact
+```
+
+## Unsupported Surfaces
+
+This SDK intentionally does not wrap:
+
+- internal operations endpoints
+- billing endpoints
+- MCP endpoints
+- raw binary preview helpers such as GIF and thumbnail routes
+- server-sent processing event streams
+
+Use the REST API directly for unsupported public helper routes, and use the separate MCP package for MCP-specific workflows.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

videovector-1.0.0/README.md

@@ -0,0 +1,199 @@
+# VideoVector Python SDK
+
+Official Python SDK for the VideoVector API.
+
+This repository is the public source of truth for the Python package, SDK documentation, examples, tests, and release workflow. It does not contain backend, MCP, frontend, deployment, or internal operations code.
+
+## Installation
+
+```bash
+pip install videovector
+```
+
+For local development from this repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import os
+
+from videovector import VideoVector
+
+with VideoVector(api_key=os.environ["VIDEO_VECTOR_API_KEY"]) as client:
+    index = client.indexes.create(name="Field Review Clips")
+
+    upload = client.videos.upload(
+        file="/path/to/video.mp4",
+        title="Store walk-through",
+        index_id=index.index_id,
+    )
+
+    results = client.search.text(
+        index_id=index.index_id,
+        query="employee restocking shelves near checkout",
+        top_k=10,
+    )
+
+    for result in results:
+        print(result.video_id, result.start_time, result.similarity_score)
+```
+
+## Configuration
+
+The SDK reads credentials and operational settings from constructor arguments or environment variables.
+
+| Setting | Environment variable | Notes |
+|---|---|---|
+| API key | `VIDEO_VECTOR_API_KEY` | Recommended for server-to-server workflow calls. |
+| JWT bearer token | `VIDEO_VECTOR_BEARER_TOKEN` | Required for JWT-only endpoints such as API key management. |
+| Auth mode | `VIDEO_VECTOR_AUTH_MODE` | Optional; use `api_key` or `bearer` when both credentials are present. |
+| Base URL | `VIDEO_VECTOR_BASE_URL` | Defaults to `https://api.vectormethods.com/api/v2`. |
+| Timeout | `VIDEO_VECTOR_TIMEOUT` | Seconds; default is `60`. |
+| Retries | `VIDEO_VECTOR_MAX_RETRIES` | Default is `3`. |
+
+Explicit constructor arguments override environment values:
+
+```python
+from videovector import VideoVector
+
+client = VideoVector(
+    api_key="<VIDEO_VECTOR_API_KEY>",
+    base_url="https://api.vectormethods.com/api/v2",
+    timeout=90,
+    max_retries=5,
+)
+```
+
+Configure one auth mode at a time. If both an API key and bearer token are present, set `auth_mode` or `VIDEO_VECTOR_AUTH_MODE`.
+
+## Resource Overview
+
+- `client.videos`: upload, retrieve, process, segments, batch helpers, and playground media.
+- `client.indexes`: index CRUD, paginated index videos, and prompt-run history.
+- `client.prompts`: prompt CRUD, schema validation, usage, video-level synthesis, and semantic indexing config.
+- `client.prompt_runs`: estimate, execute, poll, retrieve results, inspect failures, retry failed segments, and inspect LLM calls.
+- `client.search`: text, image, multimodal, filter, multi-run, and playground search.
+- `client.connectors`: GCS, S3, and Azure connector creation, testing, browsing, and deletion.
+- `client.import_jobs`: bulk import from configured connectors.
+- `client.exports`: index and prompt-run metadata exports.
+- `client.webhooks`: webhook CRUD, delivery inspection, retries, event discovery, and secret rotation.
+- `client.api_keys`: API key CRUD, rotate, revoke, and delete with bearer auth.
+- `client.usage`: usage metrics, history, details, and breakdowns.
+- `client.rate_limits`: rate-limit status and refresh.
+
+Endpoint-by-endpoint coverage is documented in [docs/backend-parity-matrix.md](docs/backend-parity-matrix.md).
+
+## Pagination
+
+Paginated endpoints return `SyncPage[T]` or `AsyncPage[T]`.
+
+```python
+page = client.indexes.list_videos("idx_archive", limit=50)
+for video in page.auto_paging_iter():
+    print(video.video_id)
+```
+
+```python
+from videovector import AsyncVideoVector
+
+async with AsyncVideoVector(api_key="<VIDEO_VECTOR_API_KEY>") as client:
+    page = await client.videos.list_playground(limit=25)
+    async for video in page.auto_paging_iter():
+        print(video.video_id)
+```
+
+## Error Handling
+
+SDK exceptions map to API status classes:
+
+- `AuthenticationError` for `401`
+- `AuthorizationError` for `403`
+- `NotFoundError` for `404`
+- `ValidationError` for validation and other non-specialized `4xx` responses
+- `RateLimitError` for `429`, including `retry_after` when provided
+- `ConflictError` for `409`
+- `ExternalServiceError` for `5xx`
+- `TimeoutError`, `ConnectionError`, and `VideoVectorError` for transport or generic SDK failures
+
+```python
+import os
+
+from videovector import RateLimitError, ValidationError, VideoVector
+
+try:
+    with VideoVector(api_key=os.environ["VIDEO_VECTOR_API_KEY"]) as client:
+        client.search.text(index_id="idx_archive", query="")
+except ValidationError as exc:
+    print(exc.error_code, exc.message)
+except RateLimitError as exc:
+    print("retry after", exc.retry_after)
+```
+
+## Retry and Idempotency
+
+Automatic retries are enabled for:
+
+- idempotent methods: `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE`
+- any request that includes an explicit `idempotency_key`
+
+For non-idempotent operations, pass an idempotency key when retrying is safe:
+
+```python
+run = client.prompt_runs.execute(
+    prompt_id="prompt_scene_review",
+    target={"type": "index", "index_id": "idx_archive"},
+    idempotency_key="scene-review-2026-05-07",
+)
+```
+
+## Examples
+
+The [examples](examples) directory contains runnable, environment-driven examples for common and advanced workflows:
+
+- quickstart upload/search
+- sync and async client usage
+- custom prompt and schema design
+- video-level synthesis
+- text, image, multimodal, and filter search
+- GCS, S3, and Azure connectors
+- import jobs, exports, webhooks, idempotency, failed-segment recovery, usage, and rate limits
+
+Examples intentionally use placeholders and environment variables. Do not hardcode credentials in application code.
+
+## Development
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+ruff check videovector tests examples
+mypy videovector
+pytest -q tests
+python -m build
+python -m twine check dist/*
+```
+
+Optional local secret scan:
+
+```bash
+gitleaks detect --source . --no-git --redact
+```
+
+## Unsupported Surfaces
+
+This SDK intentionally does not wrap:
+
+- internal operations endpoints
+- billing endpoints
+- MCP endpoints
+- raw binary preview helpers such as GIF and thumbnail routes
+- server-sent processing event streams
+
+Use the REST API directly for unsupported public helper routes, and use the separate MCP package for MCP-specific workflows.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

videovector-1.0.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "videovector"
+version = "1.0.0"
+description = "Python SDK for the VideoVector API"
+authors = [
+    {name = "Vector Methods"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+keywords = [
+    "video",
+    "search",
+    "ai",
+    "ml",
+    "computer-vision",
+    "video-understanding",
+    "semantic-search",
+    "sdk",
+    "api",
+]
+
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-httpx>=0.30.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/VectorMethods/videovector-python"
+Documentation = "https://github.com/VectorMethods/videovector-python#readme"
+Repository = "https://github.com/VectorMethods/videovector-python"
+Issues = "https://github.com/VectorMethods/videovector-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["videovector*"]
+
+[tool.setuptools.package-data]
+videovector = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

videovector-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

videovector-1.0.0/tests/test_client_auth_mode.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import pytest
+
+from videovector import AsyncVideoVector, VideoVector
+
+
+def test_sync_client_accepts_explicit_auth_mode_with_dual_credentials() -> None:
+    client = VideoVector(
+        api_key="vv_test_api_key",
+        bearer_token="bearer-token",
+        auth_mode="api_key",
+    )
+    try:
+        headers = dict(client._http._client.headers)  # type: ignore[attr-defined]
+        assert headers.get("x-api-key") == "vv_test_api_key"
+        assert "authorization" not in headers
+    finally:
+        client.close()
+
+
+def test_async_client_accepts_explicit_auth_mode_with_dual_credentials() -> None:
+    client = AsyncVideoVector(
+        api_key="vv_test_api_key",
+        bearer_token="bearer-token",
+        auth_mode="bearer",
+    )
+    headers = client._http._default_headers()  # type: ignore[attr-defined]
+    assert headers.get("Authorization") == "Bearer bearer-token"
+    assert "X-API-Key" not in headers
+
+
+def test_client_rejects_dual_credentials_without_auth_mode() -> None:
+    with pytest.raises(ValueError, match="Provide only one authentication method"):
+        VideoVector(api_key="vv_test_api_key", bearer_token="bearer-token")

videovector-1.0.0/tests/test_config_auth.py

@@ -0,0 +1,97 @@
+
+from pathlib import Path
+
+import pytest
+
+from videovector._config import DEFAULT_BASE_URL, ClientConfig
+
+CANONICAL_BASE_URL = "https://api.vectormethods.com/api/v2"
+LEGACY_RAW_STAGE_BASE_URL = (
+    "https://playground-" + "api-stg-" + "udk7d32fva-uc.a.run.app/api/v2"
+)
+
+
+def test_config_accepts_api_key() -> None:
+    cfg = ClientConfig.from_env(api_key="vv_test_api_key")
+    assert cfg.api_key == "vv_test_api_key"
+    assert cfg.bearer_token is None
+
+
+def test_config_accepts_bearer_token() -> None:
+    cfg = ClientConfig.from_env(bearer_token="bearer-token-test")
+    assert cfg.bearer_token == "bearer-token-test"
+    assert cfg.api_key is None
+
+
+def test_config_uses_bearer_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VIDEO_VECTOR_BEARER_TOKEN", "env-bearer")
+    cfg = ClientConfig.from_env()
+    assert cfg.bearer_token == "env-bearer"
+
+
+def test_legacy_env_prefix_is_not_supported(monkeypatch: pytest.MonkeyPatch) -> None:
+    legacy_api_key_env = "VIDEO_" + "SEARCH_API_KEY"
+    monkeypatch.setenv(legacy_api_key_env, "legacy-token")
+    with pytest.raises(ValueError, match="Authentication is required"):
+        ClientConfig.from_env()
+
+
+def test_config_requires_auth() -> None:
+    with pytest.raises(ValueError, match="Authentication is required"):
+        ClientConfig.from_env()
+
+
+def test_config_rejects_both_auth_modes() -> None:
+    with pytest.raises(ValueError, match="Provide only one authentication method"):
+        ClientConfig.from_env(api_key="vv_test_api_key", bearer_token="<VIDEO_VECTOR_BEARER_TOKEN>")
+
+
+def test_config_env_auth_mode_validation(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VIDEO_VECTOR_API_KEY", "vv_test_api_key")
+    monkeypatch.setenv("VIDEO_VECTOR_AUTH_MODE", "invalid")
+    with pytest.raises(ValueError, match="VIDEO_VECTOR_AUTH_MODE"):
+        ClientConfig.from_env()
+
+
+def test_config_allows_both_credentials_with_explicit_auth_mode() -> None:
+    cfg = ClientConfig.from_env(
+        api_key="vv_test_api_key",
+        bearer_token="bearer-token-test",
+        auth_mode="bearer",
+    )
+    assert cfg.auth_mode == "bearer"
+    assert cfg.api_key == "vv_test_api_key"
+    assert cfg.bearer_token == "bearer-token-test"
+
+
+def test_config_uses_verified_default_base_url() -> None:
+    cfg = ClientConfig.from_env(api_key="vv_test_api_key")
+    assert cfg.base_url == DEFAULT_BASE_URL
+    assert DEFAULT_BASE_URL == CANONICAL_BASE_URL
+
+
+def test_legacy_raw_stage_url_is_absent_from_repo_text() -> None:
+    repo_root = Path(__file__).resolve().parents[1]
+    ignored_parts = {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+    }
+    offenders: list[str] = []
+
+    for path in repo_root.rglob("*"):
+        if not path.is_file() or ignored_parts.intersection(path.parts):
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        if LEGACY_RAW_STAGE_BASE_URL in content:
+            offenders.append(str(path.relative_to(repo_root)))
+
+    assert offenders == []