Metadata-Version: 2.4
Name: drc-vantage
Version: 2.2.6
Summary: Thin HTTP client for the DRC Vantage platform API
Project-URL: Homepage, https://github.com/nathan294/vantage
Project-URL: Repository, https://github.com/nathan294/vantage
Project-URL: Issues, https://github.com/nathan294/vantage/issues
Author: DRC
License-Expression: LicenseRef-Proprietary
Keywords: api,data,http,sdk,vantage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.0
Requires-Dist: loguru>=0.7.0
Description-Content-Type: text/markdown

# drc-vantage

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

> **Breaking change:** the deployment-wide `API_KEY` and `X-Organization-Id` / `organization_slug` are no longer used by the SDK. Create a developer account and API key in the app (**Developers** page). The organization is bound to the key.

## Install

```bash
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` | Developer account API key (Developers page) | `vantage_…`                 |




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

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

client = Client()  # uses VANTAGE_API_KEY (developer key)
hooks = orchestration_hooks(client)

@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()
    ...
```



## Dataset lifecycle example

```python
from vantage import Client, Dataset

client = Client()  # organization is inferred from the developer API key

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")
dataset.assign_owner("owner@example.com")
result = dataset.analyze_and_check_alerts()
```



## Catalog register

```python
from vantage import Client, DataSource, DataSourceCategory, DataStorageSystem

client = Client()
```

