northstar-sdk 1.0__tar.gz

northstar_sdk-1.0/.env.example

@@ -0,0 +1,4 @@
+# Northstar platform (Next.js API) — required for the HTTP SDK
+NORTHSTAR_API_URL=http://localhost:3000/api
+# Developer account API key from the app: Admin → Developers
+NORTHSTAR_API_KEY=northstar_...

northstar_sdk-1.0/.gitignore

@@ -0,0 +1,79 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+**/node_modules/
+**/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# Testing
+**/coverage/
+
+# Next.js
+**/.next/
+**/out/
+
+# Production
+**/build/
+
+# Python
+**/__pycache__/
+**/*.py[cod]
+**/.venv/
+**/dist/
+**/wheels/
+**/*.egg-info/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# TypeScript
+**/*.tsbuildinfo
+**/next-env.d.ts
+
+# Prisma
+**/prisma/generated/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Deployment
+**/.vercel/
+
+# OS
+**/.DS_Store
+**/Thumbs.db
+
+# IDE — ignore personal settings, keep shared workspace config
+**/.vscode/*
+!**/.vscode/settings.json
+!**/.vscode/extensions.json
+!**/.vscode/tasks.json
+!**/.vscode/launch.json
+**/.idea/
+
+# Cursor
+**/.cursor/
+
+# Local themes & branding
+**/src/config/themes/
+**/public/branding/
+
+# Notebooks
+*.ipynb_checkpoints/
+notebook.ipynb
+
+# Secrets
+*.pem

northstar_sdk-1.0/.python-version

@@ -0,0 +1 @@
+3.13

northstar_sdk-1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: northstar-sdk
+Version: 1.0
+Summary: Thin HTTP client for the Northstar platform API
+Project-URL: Homepage, https://github.com/nathan294/northstar
+Project-URL: Repository, https://github.com/nathan294/northstar
+Project-URL: Issues, https://github.com/nathan294/northstar/issues
+Author: Nathan Boulogne
+License-Expression: Apache-2.0
+Keywords: api,data,http,northstar,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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
+
+# 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
+
+```bash
+pip install northstar-sdk
+# or
+uv add northstar-sdk
+```
+
+## Configuration
+
+| Variable          | Description                        | Example                     |
+| ----------------- | ---------------------------------- | --------------------------- |
+| `NORTHSTAR_API_URL` | Next.js API base (includes `/api`) | `http://localhost:3000/api` |
+| `NORTHSTAR_API_KEY` | Developer account API key          | `northstar_…`                 |
+
+## Quick start (100 % `Client`)
+
+```python
+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",
+)
+dataset.analyze_and_check_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`](src/northstar_sdk/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](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](docs/document-collections.md).
+
+## Client namespaces
+
+| Property | Read | Write |
+| -------- | ---- | ----- |
+| `client.datasets` | list, get, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.kpis` | list, get, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.figures` | catalogue | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.dashboards` | browse, get, find_by_title | `create`, `upsert`, `update`, `delete`, `for_id`, `create_folder` |
+| `client.dashboard_folders` | browse, list, get, find_by_id, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.data_sources` | list, get | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.data_source_categories` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.storage_systems` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.document_collections` | — | `create`, `upsert`, `update`, `delete`, `ingest`, `for_id` |
+| `client.teams` | list, find_by_name, find_by_slug | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.users` | — | `create`, `upsert`, `update`, `resolve`, `for_ref`, `for_id` |
+| `client.organisations` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.search` | global search | — |
+
+## Orchestration
+
+```python
+from northstar_sdk import Client, northstar_flow
+
+client = Client()
+
+@northstar_flow(client)
+def my_flow():
+    client.data_sources.create(...)
+```

northstar_sdk-1.0/PUBLISHING.md

@@ -0,0 +1,70 @@
+# Publication sur PyPI
+
+Le package `northstar-sdk` partage la **même version** que la plateforme Northstar ([`VERSION`](../../VERSION) à la racine du dépôt). Les scripts [`scripts/bump_version.py`](../../scripts/bump_version.py) et [`scripts/release.py`](../../scripts/release.py) synchronisent `packages/python_sdk/pyproject.toml` avec ce fichier.
+
+## Workflow de release
+
+Depuis la racine du monorepo :
+
+```bash
+task bump:minor   # ou bump:major / bump:rc — met à jour VERSION + tous les manifests
+task release      # commit, tag, push, build SDK, publication PyPI
+```
+
+`task release` exécute `uv build --package northstar-sdk` puis `uv publish --index pypi` après le push Git. Un token PyPI doit être disponible dans l'environnement.
+
+## Prérequis
+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) installé
+- Un compte sur [pypi.org](https://pypi.org/)
+- Un token API PyPI avec accès au projet `northstar-sdk`
+
+## Token PyPI
+
+1. PyPI → **Account settings → API tokens**
+2. Crée un token (scope « Project: northstar-sdk » une fois le projet créé, sinon « Entire account » pour la première release)
+3. Exporte-le **sans le commiter** :
+
+```powershell
+$env:UV_PUBLISH_TOKEN = "pypi-..."
+```
+
+```bash
+export UV_PUBLISH_TOKEN="pypi-..."
+```
+
+`uv publish` lit automatiquement `UV_PUBLISH_TOKEN`.
+
+## Build manuel (debug)
+
+Depuis la racine du monorepo :
+
+```bash
+python scripts/bump_version.py --sync-only
+uv build --package northstar-sdk --clear
+uv publish --index pypi dist/northstar_sdk-*
+```
+
+Les artefacts sont écrits dans `dist/` à la racine du dépôt.
+
+## TestPyPI (optionnel)
+
+Les index `pypi` et `testpypi` sont déclarés dans le [`pyproject.toml` racine](../../pyproject.toml). Pour un essai sur [TestPyPI](https://test.pypi.org/) :
+
+```bash
+uv build --package northstar-sdk --clear
+uv publish --index testpypi dist/northstar_sdk-*
+```
+
+Utilise un token TestPyPI dans `UV_PUBLISH_TOKEN`.
+
+## Dépannage
+
+- **UV_PUBLISH_TOKEN is not set** : exporte le token avant `task release`.
+- **403 / invalid credentials** : vérifie le token et le scope du projet.
+- **File already exists** : la version est déjà sur PyPI — bump avec `task bump:minor` (ou major/rc) puis relance la release.
+
+## Références
+
+- [uv — Building and publishing a package](https://docs.astral.sh/uv/guides/package/)
+- [PyPI — API tokens](https://pypi.org/help/#apitoken)

northstar_sdk-1.0/README.md

@@ -0,0 +1,124 @@
+# 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
+
+```bash
+pip install northstar-sdk
+# or
+uv add northstar-sdk
+```
+
+## Configuration
+
+| Variable          | Description                        | Example                     |
+| ----------------- | ---------------------------------- | --------------------------- |
+| `NORTHSTAR_API_URL` | Next.js API base (includes `/api`) | `http://localhost:3000/api` |
+| `NORTHSTAR_API_KEY` | Developer account API key          | `northstar_…`                 |
+
+## Quick start (100 % `Client`)
+
+```python
+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",
+)
+dataset.analyze_and_check_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`](src/northstar_sdk/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](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](docs/document-collections.md).
+
+## Client namespaces
+
+| Property | Read | Write |
+| -------- | ---- | ----- |
+| `client.datasets` | list, get, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.kpis` | list, get, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.figures` | catalogue | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.dashboards` | browse, get, find_by_title | `create`, `upsert`, `update`, `delete`, `for_id`, `create_folder` |
+| `client.dashboard_folders` | browse, list, get, find_by_id, find_by_name | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.data_sources` | list, get | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.data_source_categories` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.storage_systems` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.document_collections` | — | `create`, `upsert`, `update`, `delete`, `ingest`, `for_id` |
+| `client.teams` | list, find_by_name, find_by_slug | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.users` | — | `create`, `upsert`, `update`, `resolve`, `for_ref`, `for_id` |
+| `client.organisations` | — | `create`, `upsert`, `update`, `delete`, `for_id` |
+| `client.search` | global search | — |
+
+## Orchestration
+
+```python
+from northstar_sdk import Client, northstar_flow
+
+client = Client()
+
+@northstar_flow(client)
+def my_flow():
+    client.data_sources.create(...)
+```

northstar_sdk-1.0/docs/document-collections.md

@@ -0,0 +1,215 @@
+# Document collections (`northstar-sdk`)
+
+A **document collection** is a catalogue folder of files (today: **Google Drive PDFs**) that
+the platform can list, extract, embed, and search in Chat. Datasets are warehouse
+tables; collections are document stores.
+
+Create / update / upsert payloads are in [register.md](register.md). This page is the
+**lifecycle**: what a collection is, how `ingest()` works, and what you need for RAG.
+
+The SDK talks only to Next.js (`NORTHSTAR_API_URL`, including `/api`) with
+`NORTHSTAR_API_KEY`. Organization is inferred from the key.
+
+## Where the code lives
+
+```mermaid
+flowchart LR
+  Sdk["northstar-sdk Client"]
+  Bff["Next.js /api/feature/document-collections/…"]
+  FastApi["FastAPI /v1/feature/document-collection/…"]
+  Compute["northstar-compute ingest"]
+  Drive["Google Drive"]
+  Pg["Postgres document_collection + document"]
+  Qdrant["Qdrant document_chunk"]
+  Sdk -->|"X-API-KEY"| Bff
+  Bff -->|"proxyAuthenticatedJson"| FastApi
+  FastApi -->|"Prefect ingest-document-collection or in-process"| Compute
+  Compute --> Drive
+  Compute --> Pg
+  Compute --> Qdrant
+```
+
+| Step | SDK | Next.js | Canonical implementation |
+| --- | --- | --- | --- |
+| Create / upsert | `client.document_collections.create` / `.upsert` | [`create/route.ts`](../../../front/src/app/api/feature/document-collections/create/route.ts) → `POST /v1/feature/document-collection/create` | [`packages/northstar_compute/.../sync/sync_document_collection.py`](../../northstar_compute/src/northstar_compute/document_collections/sync/sync_document_collection.py) `upsert_document_collection` |
+| Ingest | `collection.ingest()` | [`ingest/route.ts`](../../../front/src/app/api/feature/document-collections/ingest/route.ts) → `POST /v1/feature/document-collection/ingest` | [`ingest_document_collection.py`](../../northstar_compute/src/northstar_compute/document_collections/ingest/ingest_document_collection.py) |
+| Location keys | `location={"folderId": "…"}` | — | [`location.py`](../../northstar_compute/src/northstar_compute/document_collections/location.py) `LOCATION_KEY_PARTS` |
+| Prefect job | — | — | [`jobs/src/jobs/flows/ingest_document_collection.py`](../../../jobs/src/jobs/flows/ingest_document_collection.py) (`ingest-document-collection`) |
+
+**Naming:** compute `upsert_document_collection` writes the **catalogue row**.
+SDK/API `ingest()` **pulls files** (Drive → Postgres → Qdrant). Create does not
+download PDFs.
+
+## What you get
+
+| Layer | Role |
+| --- | --- |
+| `document_collection` | One Drive folder. Unique per org on **slug** and on **storage system + `locationKey`** (`folderId`). |
+| `document` | One remote PDF. Unique per collection + Drive file id (`externalId`). |
+| Qdrant `document_chunk` | Embedded text chunks, used by platform Chat. |
+
+The UI (`/feature/documents`) lists collections and files. Chat can attach a
+collection and retrieve passages (`kind=document_chunk`).
+
+Ingestion is implemented **only** for storage kind `GOOGLE_DRIVE`.
+
+## Prerequisites
+
+1. A **Google Drive storage system** in the same org, with extracted service-account
+   fields (not a raw JSON blob). See [register.md](register.md).
+2. Share the Drive **folder** with the service-account email (`client_email`) as
+   a reader (or use a Shared Drive the account can access).
+3. For **indexed** files and Chat RAG, the process that runs ingest
+   (FastAPI in-process, or Prefect jobs) needs:
+   - `QDRANT_URL` (optional `QDRANT_API_KEY`)
+   - `OPENAI_API_KEY` (embeddings)
+   - the same `CREDENTIALS_ENCRYPTION_KEY` as the API (to decrypt Drive credentials)
+
+Without Qdrant, `ingest()` still lists files and writes `document` rows with
+`indexStatus=PENDING`. Chat retrieval then returns nothing.
+
+## Create / upsert
+
+```python
+from northstar_sdk import Client
+
+client = Client()
+
+drive = client.storage_systems.create(
+    slug="gdrive-legal",
+    name="Legal Drive",
+    kind="GOOGLE_DRIVE",
+    credentials={
+        key: value
+        for key, value in sa.items()
+        if key not in ("service_account", "service_account_json")
+    },
+)
+
+collection = client.document_collections.create(
+    name="Contracts",
+    storage_system_slug="gdrive-legal",
+    location={"folderId": "1abc…"},  # Drive folder id from the URL
+    description="Executed contracts",
+    tags=["legal"],
+)
+# collection.collection_id is set
+```
+
+`folder_id` is accepted and rewritten to `folderId`. FastAPI default slug is
+`"gdrive"` if omitted; the SDK always sends `storage_system_slug`.
+
+- **`create()`** inserts only. Same org slug or Drive folder → **409** with
+  `existing_id` / `conflict_key` (`slug` or `folderId`).
+- **`upsert()`** updates the existing row if either identity matches:
+  - `(organizationId, storageSystemId, locationKey)` — same Drive folder
+  - `(organizationId, slug)` — same catalogue name/slug
+- If the slug belongs to one collection and the folder to another, the API
+  returns **409**.
+
+Optional: `slug` (else slugified from `name`), `chat_question_examples`.
+
+## Ingest
+
+```python
+result = collection.ingest()
+# Prefect:
+# {
+#   "collection_id": "…",
+#   "deployment_name": "ingest-document-collection",
+#   "flow_run_id": "…",
+#   "message": "Successfully triggered flow run for deployment ingest-document-collection",
+#   "already_running": False,
+# }
+# In-process fallback (no Prefect deployment) also includes file_count, indexed_count, …
+```
+
+Requires `collection.collection_id` (call `create()` or `upsert()` first).
+
+HTTP: `POST /feature/document-collections/ingest` with `{ "collection_id": "…" }`.
+
+### What FastAPI does
+
+1. If Prefect deployment `ingest-document-collection` exists, enqueue it with
+   `collection_ids: [id]`. The HTTP response has `flow_run_id` + `message` —
+   the job fills `fileCount` / `indexedCount` / `lastSyncedAt` asynchronously.
+   Poll the UI or re-fetch the collection.
+2. If that deployment is **missing** (typical local `task api` without Prefect),
+   ingest runs **in-process** and the response includes real counts.
+
+If a run is already `RUNNING` / `PENDING` for that collection, FastAPI returns
+`already_running=True` and the existing `flow_run_id`.
+
+### What ingest does
+
+1. Load the collection + Drive credentials.
+2. List **PDFs directly in that folder** (not subfolders, not other MIME types).
+   Shared Drives: set `driveId` on the storage `config` or on `location`.
+3. For each file:
+   - Fingerprint = Drive `md5Checksum`, else `modifiedTime`, else name.
+   - Skip download if the row already has the same hash and `indexStatus=INDEXED`.
+   - Else download, extract text with PyMuPDF, chunk (~700 tokens, 80 overlap),
+     embed, upsert Qdrant points (`kind=document_chunk`).
+4. Delete Postgres rows **and** Qdrant points for files that disappeared from Drive.
+5. Update collection counters and `lastSyncedAt`.
+
+### Document `indexStatus`
+
+| Status | Meaning |
+| --- | --- |
+| `INDEXED` | Text extracted and vectors written (or unchanged hash). |
+| `PENDING` | Catalogue row exists; Qdrant/OpenAI not configured, so no vectors. |
+| `FAILED` | Download / extract / embed error (`indexError` set), or empty PDF text. |
+| `SKIPPED` | Non-PDF (should not appear in the Drive listing today). |
+
+Re-run `ingest()` after adding files, replacing a PDF, or enabling Qdrant.
+
+## Chat
+
+Indexed chunks are searched when Chat is scoped to the collection. The UI
+**Ask** link is `/feature/chat?collectionId=<id>`. Retrieval filters Qdrant by
+`organization_id` + `collection_id`.
+
+No vectors (`vectors_enabled: false` or all `PENDING`) → no document passages.
+
+## End-to-end
+
+```python
+import json
+from northstar_sdk import Client
+
+client = Client()
+
+with open("service-account.json") as fh:
+    sa = json.load(fh)
+
+client.storage_systems.create(
+    slug="gdrive-legal",
+    name="Legal Drive",
+    kind="GOOGLE_DRIVE",
+    credentials={
+        key: value
+        for key, value in sa.items()
+        if key not in ("service_account", "service_account_json")
+    },
+)
+
+collection = client.document_collections.create(
+    name="Contracts",
+    storage_system_slug="gdrive-legal",
+    location={"folderId": "1abc…"},
+)
+print(collection.ingest())
+```
+
+Share the folder with the service-account email before `ingest()`, or Drive returns
+an empty list / a 403 from the Drive API.
+
+## Limits (current)
+
+- Google Drive only.
+- PDFs only, **one folder** (no recursion).
+- Ingest is not exposed as a button in the UI; the detail page tells you to run
+  `collection.ingest()` from the SDK (or `POST /feature/document-collections/ingest`).
+- Service-account JSON must be **parsed locally**; the API rejects
+  `service_account` / `service_account_json` blobs.