drc-vantage 2.2.2

Thin HTTP client for the DRC Vantage platform API

drc-vantage

Thin HTTP client for the Vantage platform. Talks only to the Next.js API (VANTAGE_API_URL) with a global API key — never to Postgres or FastAPI directly.

Install

pip install drc-vantage
# or
uv add drc-vantage

Configuration

Variable	Description	Example
VANTAGE_API_URL	Next.js API base (includes /api)	http://localhost:3000/api
VANTAGE_API_KEY	Global platform API key (same as server API_KEY)	your_api_key
API_KEY	Alias if VANTAGE_API_KEY is unset
VANTAGE_ORGANIZATION_ID	Optional org scope (X-Organization-Id)	org_xxx
VANTAGE_ORGANIZATION_SLUG	Resolve org id from slug when id is unset	acme

Classes

Client, Dataset, DataSource, DataSourceCategory, DataStorageSystem

Orchestration helpers: send_orchestration_event, orchestration_hooks (see below).

Prefect orchestration events

Register deployment run state on the platform (home / data sources / datasets health). The deployment UUID must match a DataSource or Dataset already registered in the org (e.g. prefect_deployment_id=deployment.id when calling register() inside the same flow).

from prefect import flow
from prefect.runtime import deployment
from vantage import Client, DataSource, DataSourceCategory
from vantage.orchestration import orchestration_hooks

client = Client(organization_slug="acme")
hooks = orchestration_hooks(client)  # resolves deployment.id at hook time

@flow(
    name="ingest-anthropic",
    on_running=hooks.on_running,
    on_completion=hooks.on_completion,
    on_failure=hooks.on_failure,
    on_crashed=hooks.on_crashed,
    on_cancellation=hooks.on_cancellation,
)
def ingest_anthropic():
    category = DataSourceCategory(client=client, slug="saas", name="SaaS", color="#3366FF")
    DataSource(
        client=client,
        slug="anthropic",
        name="Anthropic",
        category=category,
        prefect_deployment_id=deployment.id,
        logo_url="https://example.com/logo.svg",
    ).register()
    ...

# Optional: pin the deployment UUID explicitly instead of runtime resolution
hooks = orchestration_hooks(client, prefect_deployment_id="your-prefect-deployment-uuid")

Manual event (e.g. custom hook):

from vantage.orchestration import send_orchestration_event

send_orchestration_event(
    client,
    prefect_deployment_id="...",
    event="FAILED",
    flow_run_id="...",
    error_message="warehouse timeout",
)

Hook HTTP failures are logged and do not fail the Prefect flow.

Dataset lifecycle example

from vantage import Client, Dataset

client = Client(organization_slug="acme")  # or organization_id="org_xxx"

dataset = Dataset(
    client=client,
    location={"schema": "marts", "table": "customer_success_nps"},
    name="Customer Success NPS",
    type="TABLE",
    description="Qualtrics survey NPS summaries enriched with HubSpot contacts.",
    chat_question_examples={
        "en": ["What is the average NPS score by survey?"],
        "fr": ["Quel est le score NPS moyen par enquête?"],
    },
    data_source_slugs=["qualtrics", "hubspot"],
    storage_system_slug="postgresql",
)

result = dataset.register()
dataset.assign_to_team("customer-success", owner="[e-mail]")
result = dataset.analyze_and_check_alerts()

Individual steps:

dataset.register()
dataset.analyze()              # Prefect — includes validations
dataset.check_alerts()         # Prefect
dataset.analyze_and_check_alerts()  # Prefect — preferred combined pipeline

Catalog register

from vantage import Client, DataSource, DataSourceCategory, DataStorageSystem

client = Client(organization_slug="acme")

category = DataSourceCategory(
    client=client, slug="saas", name="SaaS", color="#3366FF"
)
category.register()

source = DataSource(
    client=client,
    slug="hubspot",
    name="HubSpot",
    category=category,
    logo_url="https://example.com/hubspot.svg",
)
source.register()

storage = DataStorageSystem(
    client=client,
    slug="postgresql",
    name="PostgreSQL",
    kind="POSTGRESQL",
    logo_url="https://example.com/pg.svg",
)
storage.register()

Architecture

drc-vantage  →  Next.js (/api)  →  FastAPI  →  vantage-compute / Prefect