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).
