Metadata-Version: 2.4
Name: drc-vantage
Version: 2.1.1
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 global API key — never to Postgres or FastAPI directly.

## 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` | 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`

## Dataset lifecycle example

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

Individual steps:

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

## Catalog register

```python
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
```
