Metadata-Version: 2.4
Name: vars-client
Version: 0.1.0
Summary: Python client library unifying access to MBARI's VARS microservice stack
Keywords: vars,mbari,oceanography,video-annotation,marine-biology,kiota,openapi-client
Author: Kevin Barnard
Author-email: Kevin Barnard <kbarnard@mbari.org>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1
Requires-Dist: microsoft-kiota-abstractions>=1.11.7
Requires-Dist: microsoft-kiota-http>=1.11.7
Requires-Dist: microsoft-kiota-serialization-form>=1.11.7
Requires-Dist: microsoft-kiota-serialization-json>=1.11.7
Requires-Dist: microsoft-kiota-serialization-multipart>=1.11.7
Requires-Dist: microsoft-kiota-serialization-text>=1.11.7
Requires-Dist: pyyaml>=6.0.3
Maintainer: Kevin Barnard
Maintainer-email: Kevin Barnard <kbarnard@mbari.org>
Requires-Python: >=3.14
Project-URL: Homepage, https://mbari-org.github.io/vars-client/
Project-URL: Documentation, https://mbari-org.github.io/vars-client/
Project-URL: Repository, https://github.com/mbari-org/vars-client
Project-URL: Issues, https://github.com/mbari-org/vars-client/issues
Description-Content-Type: text/markdown

# vars-client

[![CI](https://github.com/mbari-org/vars-client/actions/workflows/ci.yml/badge.svg)](https://github.com/mbari-org/vars-client/actions/workflows/ci.yml)
[![Documentation](https://github.com/mbari-org/vars-client/actions/workflows/docs.yml/badge.svg)](https://mbari-org.github.io/vars-client/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](pyproject.toml)

Python client library unifying access to MBARI's [VARS](https://www.mbari.org/technology/video-annotation-and-reference-system-vars/)
microservice stack:

| Service        | Purpose                                   |
| -------------- | ------------------------------------------ |
| Annosaurus     | Annotations                                |
| Vampire Squid  | Video assets                               |
| Oni            | Taxonomy / knowledge base                  |
| Panoptes       | Image upload / archive                     |
| Beholder       | On-demand video frame extraction           |
| Skimmer        | ROI cropping                               |
| Raziel         | Service configuration / discovery          |

VARS is used by multiple institutions, so this library is built so each one
can supply its own service URLs and credentials without touching code, and
so read-only use works even with no credentials at all.

**[Full documentation →](https://mbari-org.github.io/vars-client/)**

## Features

- **Unified client.** [`VARSClient`](https://mbari-org.github.io/vars-client/client/)
  wires up all seven services from a single config object.
- **Pluggable endpoint discovery.** Bootstrap from a running
  [Raziel](https://mbari-org.github.io/vars-client/config/#razielconfigprovider)
  instance, or supply endpoints directly via dict, YAML, or environment
  variables — no institution-specific code required.
- **Handles VARS' four auth schemes** (JWT exchange, Raziel's two-stage
  bootstrap, static API keys, and no auth) uniformly, including token
  caching, proactive refresh, and retry-on-401. See
  [Auth](https://mbari-org.github.io/vars-client/auth/).
- **Works with zero credentials.** Every read endpoint on Annosaurus, Vampire
  Squid, Oni, and Panoptes is unauthenticated — omit a secret and you still
  get a fully read-capable client.
- **Generated, not hand-maintained.** Five of the six OpenAPI-backed services
  are wrapped by [Kiota](https://learn.microsoft.com/openapi/kiota/)-generated
  clients kept current with `just fetch-specs && just generate`; the
  [API reference](https://mbari-org.github.io/vars-client/exploring-the-api/)
  is itself generated from those specs, cross-referenced against the actual
  generated code.

## Installation

```sh
uv add vars-client
```

## Quick start

```python
import asyncio

from vars_client.client import VARSClient
from vars_client.config import RazielConfigProvider


async def main():
    config = RazielConfigProvider("https://vars.example.org/raziel")  # anonymous, read-only
    client = await VARSClient(config).connect()

    health = await client.annosaurus.v1.health.get()
    print(health.application)


asyncio.run(main())
```

See [Client](https://mbari-org.github.io/vars-client/client/) for the full
usage guide and [Configuration](https://mbari-org.github.io/vars-client/config/)
for institution-specific setups.

## Development

This project uses [`uv`](https://docs.astral.sh/uv/) and a
[`justfile`](justfile) for common tasks:

```sh
just sync    # install dependencies
just check   # lint + typecheck + test
just build   # build the sdist/wheel
```

See [Development](https://mbari-org.github.io/vars-client/development/) for
the full contributor workflow, including regenerating the Kiota clients from
upstream OpenAPI specs.

## License

Licensed under the [Apache License, Version 2.0](LICENSE).
