vars-client 0.1.0

Python client library unifying access to MBARI's VARS microservice stack

vars-client

Python client library unifying access to MBARI's 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 →

Features

• Unified client. VARSClient wires up all seven services from a single config object.
• Pluggable endpoint discovery. Bootstrap from a running Raziel 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.
• 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-generated clients kept current with just fetch-specs && just generate; the API reference is itself generated from those specs, cross-referenced against the actual generated code.

Installation

uv add vars-client

Quick start

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 for the full usage guide and Configuration for institution-specific setups.

Development

This project uses uv and a justfile for common tasks:

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

See Development for the full contributor workflow, including regenerating the Kiota clients from upstream OpenAPI specs.

License

Licensed under the Apache License, Version 2.0.