northstar-sdk

Thin HTTP client for the Northstar platform. Talks only to the Next.js API (NORTHSTAR_API_URL) with a developer account API key.

Install

pip install northstar-sdk
# or
uv add northstar-sdk

Configuration

Quick start (100 % Client)

from northstar_sdk import Client

client = Client()

# Teams: read + create on the same namespace
team = client.teams.create(name="Sales", description="Revenue ops")
record = client.teams.find_by_name("Sales")

# Users: resolve profile or get a handle for actions
guest = client.users.resolve("guest@example.com")  # .id, .email, .name
guest_handle = client.users.for_ref("guest@example.com")
user = client.users.create(
    first_name="Ada",
    last_name="Lovelace",
    email="ada@example.com",
    password="secure-password",
)

# KPI → chain governance on the returned 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")

# Ingestion (flat — no client.ingestion.*)
client.storage_systems.create(
    slug="wh-pg",
    name="Warehouse PostgreSQL",
    kind="POSTGRESQL",
    credentials={
        "host": "db.internal",
        "user": "northstar",
        "password": "...",
        "database": "analytics",
    },
)
category = client.data_source_categories.create(
    slug="saas", name="SaaS", color="#3366FF"
)
client.data_sources.create(slug="hubspot", name="HubSpot", category=category)

dataset = client.datasets.create(
    location={"schema": "marts", "table": "nps"},
    name="NPS",
    type="TABLE",
    layer="GOLD",  # no layer = BRONZE: no AI recommendations, not used by default in the chat
)
dataset.analyze()  # full analysis: validations, profiling, quality, alerts

# Dashboard → create then chain governance on the returned handle
dashboard = client.dashboards.create(
    title="Sales metrics",
    icon="layout-dashboard",
    embed_url="https://dashboards.example.com/sales/metrics",
)
dashboard.assign_to_team("Sales")
dashboard.assign_owner("nathan.boulogne@gmail.com")
dashboard.link_datasets(["NPS"])
dashboard.assign_editors(["editor@example.com"])

Public exports

Client, catalogue exceptions (NotFoundError, AmbiguousLookupError), Page, orchestration helpers.

Advanced typing: from northstar_sdk.handles import User, Kpi, Dataset (not exported from top-level northstar).

This package ships py.typed — use Pylance basic or stricter for parameter hints on client.*.create / upsert.

Create / update / upsert payloads (storage systems, datasets, data sources, collections, KPIs, dashboards): see docs/register.md. That page maps SDK calls to the FastAPI Pydantic models and Next.js Zod schemas that actually validate the body. Document collections (create + ingest() / RAG): docs/document-collections.md.

Client namespaces

Orchestration

from northstar_sdk import Client, northstar_flow

client = Client()

@northstar_flow(client)
def my_flow():
    client.data_sources.create(...)