Metadata-Version: 2.4
Name: drc-vantage
Version: 1.6.0
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 2.0

Thin HTTP client for the Vantage platform. Talks only to the **Next.js API** (`VANTAGE_API_URL`) with a **developer account API 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          | `vantage_…`                 |

## Quick start (Client-centric)

```python
from vantage import Client

client = Client()

# KPI: create → chain governance on the same handle
my_kpi = client.kpis.create(
    name="Monthly revenue",
    dataset_id="…",
    definition_type="MANUAL",
    manual_config={"valueField": "amount", "aggregation": "SUM"},
)
my_kpi.assign_to_team("analytics")
my_kpi.assign_owner("owner@example.com")

# Lookup
record = client.kpis.find_by_name("Monthly revenue")
existing = client.kpis.for_id(record.id)

# Dataset
dataset = client.datasets.register(
    location={"schema": "marts", "table": "nps"},
    name="NPS",
    type="TABLE",
    storage_system_slug="postgresql",
)
dataset.assign_to_team("customer-success")
dataset.analyze_and_check_alerts()

# Ingestion
client.ingestion.storage_systems.register(
    slug="wh-pg",
    env_key="DRC_PG",
    name="Warehouse PostgreSQL",
    kind="POSTGRESQL",
    config={"database": "analytics"},
)

# Platform admin
client.platform.teams.create(name="Analytics")
```

## Public exports

`Client`, catalogue exceptions (`NotFoundError`, `AmbiguousLookupError`), `Page`, and orchestration helpers (`vantage_flow`, `orchestration_hooks`, …).

Resource types and records: `from vantage.resources import KpiResource` or `from vantage.catalogue import KpiRecord`.

## Migration from 1.x

| 1.x | 2.0 |
|-----|-----|
| `from vantage import KPI, Dataset, …` | `from vantage import Client` only |
| `KPI(client=…, …).create()` | `client.kpis.create(…)` → returns handle |
| `KPI.for_id(client, id)` | `client.kpis.for_id(id)` |
| `DataStorageSystem(…).register()` | `client.ingestion.storage_systems.register(…)` |
| `Team(…).create()` | `client.platform.teams.create(…)` |
| `client.kpis` was read-only | `client.kpis` = read + write |

## Orchestration

See previous examples using `vantage_flow`, `orchestration_hooks`, and `client.ingestion.data_sources.register` inside Prefect flows.
