superb-ai 0.1.0__tar.gz

superb_ai-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# uv / venv
+.venv/
+
+# CDK
+cdk.out/
+.cdk.staging/
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+.env.*
+# (no tracked .env* files; if an example is ever committed, add `!.env.example`)
+# Migration record files hold test credentials — never commit.
+workos-migration-accounts-*.md
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Demo seeding artifacts (live tenant credentials + sample IDs; not for source)
+demo/
+
+# ffmpeg layer tarball — fetched at deploy time via infra/layers/ffmpeg/fetch.sh
+infra/layers/ffmpeg/*.tar.xz
+
+# Local scratch space for one-off rendering, debugging, etc.
+tmp/
+# FE handoff docs + test-account credentials — never commit (untracked working files).
+fe-*.md
+
+# CEO/stakeholder reports — working files, not product docs
+report/
+cost/
+infra/sam/*.pt
+
+# e2e seed/validation package + keyrings (untracked working files)
+e2e/
+sdk-plan.md
+
+# SDK build artifacts
+sdk/dist/
+ops-*.md

superb_ai-0.1.0/AGENTS.md

@@ -0,0 +1,257 @@
+# superb-ai — agent guide
+
+You are using the official Python SDK for **Superb AI** (datasets → labeling →
+versions → training → deployment). This file is your skill doc: auth, the client map,
+worked recipes, and the gotchas that waste hours if you rediscover them.
+
+Discovery: `api-map.md` (same dir) lists EVERY method one-line-per-method — grep it.
+Every method has a full docstring (args, returns, `Raises:` with error codes).
+Errors are typed: branch on `exc.code` (an `ErrorCode`), read `exc.hint`.
+
+## Auth (3 lines)
+
+```python
+from superb_ai import Client
+client = Client(tenant="acme", api_key="sbd_pk_...")   # or set SUPERB_AI_TENANT + SUPERB_AI_API_KEY
+# with both env vars set, `Client()` alone works — nothing to hardcode
+assert client.projects.list().items is not None         # smoke: you're in
+```
+
+Machine keys (`sbd_pk_…`) are the primary credential. The `client.auth.*` surface is
+**JWT-bootstrap-only** (browser login dance) — a key holder never calls it. Each key
+acts as ONE user; multi-actor workflows need one client per user key.
+
+## Client map (namespaces)
+
+`client.` → `tenants users api_keys auth account invitations datasets assets projects
+classes members guidelines labeling_time tags workflow workflow_batch project_assets
+annotations revisions comments versions exports jobs training models deployments
+auto_label foundation segment activity visualization`
+
+`account` (my workspaces / accept invitations) is **JWT-session-only** — an
+`sbd_pk_…` key gets 401 there; machine keys already know their workspace.
+`invitations` (admin: invite email + role, list, revoke) works with keys.
+
+Pagination: list methods return `Page[T]` — iterate the page object to auto-fetch all
+pages (`for x in client.annotations.list(pid): ...`). `include_total=True` adds
+`.total`. Non-list collection reads (classes, tags, progress, queue stats) return
+complete models, not pages.
+
+Async jobs: kickoff methods return a `JobHandle` — call `.wait(timeout=...)`; it
+raises `JobFailedError` on failure and `JobTimeoutError` (job keeps running) on
+timeout. `handle.result_summary` carries per-kind outcome keys.
+
+## Batch first — the anti-flood rule
+
+**Never loop a single-item call when N > ~5.** Every hot path has a batch twin
+(sync, explicit ids, ≤1000) and most have a bulk twin (async job, id-list or
+filter-scoped). Pick by N:
+
+| doing this per-item?            | ≤1000 → sync batch                          | any size → async bulk (JobHandle) |
+|---------------------------------|---------------------------------------------|------------------------------------|
+| create annotations              | `annotations.asset_batch_create` (1 asset) / `annotations.project_batch_create` | `annotations.import_ndjson` |
+| edit/delete annotations         | `annotations.batch_edit` (atomic mixed) / `annotations.batch_delete` (≤500 ids) | `project_assets.bulk_delete_annotations` (+class/source predicates) |
+| assign/approve/reject/unassign  | `workflow_batch.batch_*`                    | `workflow_batch.bulk_*` (filter-scoped) |
+| add/remove project assets       | `project_assets.batch_add` / `batch_remove` | `project_assets.bulk_add` / `bulk_remove` |
+| tag assets                      | `tags.batch_update`                         | `tags.bulk_update` |
+| delete assets                   | `assets.batch_delete`                       | `assets.bulk_delete` |
+| upload files                    | `assets.upload_paths` (does presign+PUT batching for you) | — |
+| predict on many assets          | —                                           | `auto_label.create_run` (never a predict loop) |
+
+Flood etiquette (the rate buckets in the Limits section are the budget):
+- **Polling**: use the built-in waiters (`JobHandle.wait`, `versions.wait_ready`,
+  `training.wait_run` — they poll at ~3s). Don't hand-roll tighter loops; for
+  long jobs (training, big imports) pass a larger `poll_interval`.
+- **Counting**: `include_total=True` on one list call — never "iterate and count",
+  and never per-item GETs to check existence (list with a filter instead).
+- **Reading many items**: iterate the `Page` (sequential, one request per page at
+  the max `limit`) — don't fan out parallel GET-by-id.
+- **Upload concurrency ≤16** on shared/dev tenants; the write bucket is shared
+  by everyone on the tenant.
+
+## Recipe 1 — REQUIRED READING: import a COCO dataset end-to-end
+
+The full path: upload images → create project with class vocabulary → convert COCO
+GT → bulk-import → verify. Every step below is load-bearing.
+
+### 1a. Upload images (never hand-roll the presign dance)
+
+```python
+from pathlib import Path
+ds = client.datasets.create(name="COCO val2017")
+paths = sorted(Path("/data/val2017").glob("*.jpg"))
+client.assets.upload_paths(ds.id, paths, concurrency=8)   # presign→PUT, batched
+# Asset rows are created ASYNCHRONOUSLY by the platform's storage events.
+# Poll until they're all ready:
+import time
+while True:
+    ready = client.datasets.stats(ds.id).by_status.get("ready", 0)
+    if ready >= len(paths): break
+    time.sleep(10)
+asset_by_name = {a.filename: a.id for page in [client.assets.list(ds.id, limit=100)]
+                 for a in page}  # iterate the Page for ALL assets
+```
+
+Keep `concurrency<=16` on shared/dev environments (rate limits are per-tenant).
+
+### 1b. Create the project + class vocabulary
+
+One geometry type per class (`allowed_types`). 80 COCO classes = 80 class specs:
+
+```python
+classes = [{"name": c["name"], "color": f"#{hash(c['name']) & 0xffffff:06x}",
+            "allowed_types": ["bbox"]} for c in coco["categories"]]
+project = client.projects.create(name="Detection", dataset_id=ds.id,
+                                 scope={"all": True}, classes=classes)
+class_id = {c.name: c.id for c in client.classes.list(project.id).classes}
+```
+
+Keypoint classes additionally need a topology (COCO person = 17 nodes; edges are
+COCO's 1-indexed skeleton converted to 0-indexed pairs):
+
+```python
+KP_NAMES = ["nose","left_eye","right_eye","left_ear","right_ear","left_shoulder",
+  "right_shoulder","left_elbow","right_elbow","left_wrist","right_wrist",
+  "left_hip","right_hip","left_knee","right_knee","left_ankle","right_ankle"]
+topology = {"version": 1, "nodes": [{"id": i, "name": n} for i, n in enumerate(KP_NAMES)],
+            "edges": [[a-1, b-1] for a, b in coco_skeleton_1_indexed]}
+classes = [{"name": "person", "color": "#ff0000", "allowed_types": ["keypoint"],
+            "keypoint_topology": topology}]
+```
+
+### 1c. Convert COCO annotations → platform geometry (ALL THREE KINDS)
+
+```python
+def bbox_geometry(coco_ann):                      # COCO bbox = [x, y, w, h] pixels
+    x, y, w, h = coco_ann["bbox"]
+    if w <= 0 or h <= 0: return None              # server rejects degenerate boxes
+    return {"type": "bbox", "x": x, "y": y, "w": w, "h": h}
+
+def polygon_geometry(coco_ann):
+    if coco_ann.get("iscrowd"): return None       # RLE crowds are NOT convertible — SKIP
+    parts = []
+    for flat in coco_ann["segmentation"]:         # list of flat [x1,y1,x2,y2,...] rings
+        pts = list(zip(flat[0::2], flat[1::2]))
+        if len(pts) >= 3:                          # rings need >= 3 vertices
+            parts.append({"exterior": pts, "holes": []})
+    return {"type": "polygon", "polygons": parts} if parts else None
+
+def keypoint_geometry(coco_ann):                  # [x,y,v] * 17; v in {0,1,2} maps 1:1
+    if coco_ann.get("num_keypoints", 0) == 0: return None
+    k = coco_ann["keypoints"]
+    return {"type": "keypoint",
+            "points": [{"x": k[i], "y": k[i+1], "visibility": k[i+2]}
+                       for i in range(0, len(k), 3)]}
+```
+
+### 1d. Bulk import (>10k rows → the ASYNC staged path, one call does it all)
+
+```python
+rows = [{"id": str(uuid.uuid5(NS, str(ann["id"]))),   # deterministic ids => re-import
+         "asset_id": asset_by_name[img_name[ann["image_id"]]],  #   is an idempotent upsert
+         "class_id": class_id[cat_name[ann["category_id"]]],
+         "type": "bbox", "geometry": bbox_geometry(ann)}
+        for ann in coco["annotations"] if bbox_geometry(ann)]
+job = client.annotations.import_ndjson(project.id, rows, source="imported")
+job.wait(timeout=900)
+total = client.annotations.list(project.id, limit=1, include_total=True).total
+assert total == len(rows)
+```
+
+(≤1000 rows? `client.annotations.project_batch_create(project.id, annotations=rows,
+source="manual")` is the sync path — instant, all-or-nothing.)
+
+## Recipes 2-12 (each maps to docstrings — grep api-map.md for the methods)
+
+2.  **Jobs**: kickoff → `handle.wait()`; per-tenant cap is **3 active jobs** —
+    serialize embed/train/export, don't parallelize. `ConflictError(JOB_PER_TENANT_CAP)`.
+3.  **Workflow**: `workflow.claim/submit/approve/reject` (single, as the acting user's
+    key), `workflow_batch.*` (≤1000 explicit ids), bulk variants return JobHandles.
+    Edit-locks: a labeler editing someone else's in-progress asset → 409.
+4.  **Versions**: `versions.create(project_id, name=..., selection=...)` → poll
+    `versions.wait_ready(...)` (freeze is an internal job, not in `/jobs`). Browse
+    frozen assets + shapes via `versions.assets/asset_detail`.
+5.  **Exports**: `exp = exports.create(project_id, version_id, format=...)`
+    (idempotent per version+format+options) → `client.jobs.get(exp.job_id).wait()`
+    → `exports.download_to(...)`. `GoneError` = expired/failed → re-create.
+6.  **Search**: `assets.search(dataset_id, parts=[{"type": "text",
+    "text": "a red car"}])` — requires embeddings
+    (`datasets.embed()` job) AND the GPU search endpoint (see gotchas).
+7.  **SAM segment**: `segment.segment(project_id, asset_id,
+    points=[{"x": 100, "y": 200, "label": 1}])` → polygon suggestion; commit it
+    as a normal annotation with a class.
+8.  **Training**: `training.catalog()` → `run = training.create_run(...)` (GPU,
+    ~minutes to hours; `training.wait_run`) → find YOUR model:
+    `model = next(m for m in client.models.list() if m.training_run_id == run.id)`.
+9.  **Deploy + predict**: `deployments.create(model_id)` → poll ready →
+    `deployments.predict(deployment_id, image_url=...)` (for a platform asset,
+    pass `assets.download_url(...)`; local file → `image_b64`; whole-dataset
+    runs → the auto-label job, not a predict loop). An `UnavailableError` with
+    code MODEL_LOADING (~15s) / MODEL_STARTING (~60s) = warming — sleep that long
+    and retry (the SDK already auto-retries 5xx a couple times).
+10. **Auto-label**: `auto_label.put_config` → `auto_label.create_run(...)`
+    (JobHandle) or per-asset `auto_label.suggest(...)`. Runs never touch human
+    annotations.
+11. **Activity verification**: `activity.project_feed(project_id)` — assert your
+    operations produced their actions (bulk ops emit kickoff+completed pairs sharing
+    `correlation_id` == job id).
+12. **Errors**: catch typed exceptions; `RateLimitError` is auto-retried by the SDK;
+    `PayloadTooLargeError.hint` names the bulk alternative; `UnprocessableError.details`
+    has per-field errors.
+
+## Limits, quotas & concurrency (plan around these, don't discover them)
+
+All are per-tenant unless noted. Numbers are the platform's authoritative values.
+
+**Rate limits** (token buckets; 429 + `Retry-After`, and the SDK auto-retries):
+- reads ~500/s sustained (burst 1000) · writes ~100/s (burst 200) ·
+  upload-init ~100/s (burst 200)
+- shared-GPU inference (semantic search, foundation/ZERO): **30 burst, ~0.5/s
+  sustained** — deliberately tight; batch work belongs in jobs, not loops.
+
+**Concurrency caps** (409, typed codes):
+- **3 active jobs** (`JOB_PER_TENANT_CAP`) — embed/train/export/bulk compete
+  tenant-wide; serialize.
+- 3 live model deployments · auto-label run scope ≤ 20,000 explicit asset ids ·
+  **1 active API key per user** (revoke before re-creating; multi-actor work
+  needs one key per seeded user).
+
+**Resource quotas** (`RESOURCE_LIMIT_EXCEEDED`, 409, checked at create):
+- assets: 1M per tenant AND per dataset · datasets 100 · projects 200
+- per project: versions 100, classes 1,000, members 50
+- per asset: annotations 5,000, comments 200
+- models 100 · **users 50 per workspace — pending invitations count toward it**
+
+**Size caps** (413/422):
+- image ≤ 50 MB and ≤ 80 megapixels; > 100 MB objects need multipart (the SDK's
+  `upload_paths` handles this)
+- sync batch endpoints: ≤ 1000 items AND ≤ 5 MB body · annotation batch-delete
+  ≤ 500 ids · staged NDJSON import: ≤ 500k rows / 256 MB
+- guidelines: 1 MB markdown / 10 MB per image · page `limit` ≤ 100 (a few wide
+  list endpoints allow 200)
+
+## Gotchas (cost hours if unknown)
+
+- **Every dict-shaped parameter has a TypedDict** in `superb_ai/types/requests.py`
+  (`AssetFilterParam`, `MappedAnnotationCreateParam`, `ProjectScopeParam`, …) —
+  read that file for the exact keys instead of guessing (e.g. the filename filter
+  key is `q`, not `filename`). Plain dict literals still work; the TypedDicts are
+  the reference (and a type-checker will validate your keys against them).
+- **Debugging: `export SUPERB_AI_LOG=debug`** — every request logs as
+  `METHOD path [request-id] -> status in Nms` plus retry warnings, and the
+  bracketed id equals the `request_id` in error envelopes AND in the platform's
+  server logs (the SDK sends it as `x-request-id`). Quote it when reporting.
+- **GPU endpoints are SCHEDULED**: search-embedder + SAM run weekdays ~10:00-17:00
+  KST and are DELETED outside the window — a 503 `EMBEDDER_UNAVAILABLE` may mean
+  *scheduled-off*, not cold-start. Ask the operator to bring them up; don't retry-loop.
+- **Job cap 3 is per-tenant** — your parallel jobs compete with everyone on the tenant.
+- **Sync caps**: batch endpoints cap at 1000 items (413 → use the bulk twin);
+  annotation batch-delete caps at 500 ids.
+- **Uploads confirm asynchronously** — S3 PUT success ≠ asset row exists; always poll.
+- **Presigned URLs**: never send your Authorization header to them (different host —
+  the SDK's `download_to`/`upload_paths` handle this; don't fetch them with the client).
+- **`/jobs` hides `cleanup_s3_objects`** unless you filter for it explicitly.
+- **Idempotency**: job kickoffs auto-generate an `Idempotency-Key`; pass your own to
+  make retries replay (same body) — a REUSED key with a DIFFERENT body is a 409.
+- **Deletes are hard** — no undo. Version/asset/annotation deletes are permanent
+  (annotation revision snapshots from past submits remain readable).

superb_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to `superb-ai` are documented here, newest first.
+
+> **Public versioning starts at 0.1.0** (the first PyPI release — the
+> `[Unreleased]` section below becomes it). Earlier internal, never-published
+> builds were renumbered to 0.0.x when public versioning was set, to keep the
+> history monotonic. 0.1.0 targets the dev environment
+> (`api.bdai.dev.superb-ai.com`) for the BDAI hackathon; 0.2.0 will move to
+> production + the workspace vocabulary rename.
+
+Format: [Keep a Changelog 1.1](https://keepachangelog.com/en/1.1.0/); versioning:
+[SemVer](https://semver.org/) with 0.x semantics — **minor releases may break**
+(each breaking entry carries a migration note), patch releases never do. Entries
+reference ADRs (the platform's decision records) rather than commits. Maintained
+in lockstep: a change that alters the SDK surface adds its line under
+`[Unreleased]` in the same change; a release renames that section.
+
+## [0.1.0] - 2026-07-10
+
+### Breaking
+
+- **Account-first auth (ADR-0113).** `auth.authorize`/`callback`/`refresh`/
+  `logout` moved to the API root and are account-level: `authorize` no longer
+  scopes to the tenant's organization (new optional `state=` passthrough),
+  `callback` returns plain `AuthTokens` (no tenant context exists at login),
+  and `auth.exchange_code`/`SessionTokens` are removed — the root callback IS
+  the only callback now. Migration: exchange the code, then route via the new
+  `account` namespace.
+- `users.invite` is gone. Split: `users.create(email=, first_name=,
+  last_name=, password=, role=)` — the programmatic-seeding path (creates a
+  ready-to-login account, no email) — and `invitations.create(email=, role=)`
+  for human invites (the invitee accepts in-app via `account`).
+- `tenants.create` is now OPERATOR-only (ADR-0116): pass `bootstrap_secret=`
+  (or set `SUPERB_AI_BOOTSTRAP_SECRET`) — without the deployment's secret the
+  endpoint 404s (fail-closed). Regular users create workspaces in-app via
+  `account.create_tenant` after signing up.
+
+### Added
+
+- `account` namespace (JWT sessions only): `tenants()`, `create_tenant(name=,
+  slug=)`, `invitations()`, `accept_invitation(id)`, `decline_invitation(id)`
+  — the cross-workspace view of the signed-in account.
+- `invitations` namespace (admin): `create` (returns the copyable
+  `accept_url`), `list(status=)`, `revoke`.
+- `users.leave()` (leave this workspace) and `users.remove(user_id)` (admin
+  removes a member); both guarded against removing the last admin
+  (`LAST_ADMIN`).
+- New error codes mirrored: `INVITATION_NOT_FOUND/PENDING/NOT_PENDING/EXPIRED`,
+  `LAST_ADMIN`.
+
+- `jobs.list(project_id=...)` — filter jobs to one project, mirroring the new
+  server filter (ADR-0111). Server-side in the same change: project-scoped job
+  targets now carry `dataset_id`, so `jobs.list(dataset_id=...)` also returns
+  auto-label / project-bulk / export / version-manifest jobs (it silently
+  missed them before).
+- **Negative filter twins (ADR-0115)** on every `ProjectFilter` surface:
+  `tags_none` (carries NONE of the listed tags), `classes_none` (no annotation
+  of any listed class), `status_not` (exclude listed statuses), and the
+  `assigned`/`tagged` tri-states. Compose with the positive fields by AND —
+  `tags=["reviewed"], tags_none=["blurry"]` = "all of these, except those".
+  Same value on both sides of a pair → 400/422 (contradiction). Available as
+  kwargs on `workflow.list_asset_states` and `versions.list_assets`
+  (`tags_none`/`tagged`/`classes_none` only — workflow state isn't frozen),
+  and as `ProjectFilterParam` keys everywhere a filter body is accepted
+  (bulk ops, tag summary, version selection).
+
+## [0.0.3] - 2026-07-07 (internal)
+
+### Added
+
+- `tenant` falls back to the `SUPERB_AI_TENANT` environment variable when omitted,
+  mirroring `api_key`/`base_url` — so `Client()` with no args works when both env
+  vars are set (agents can be told "key and tenant are in the env"). Found by
+  dogfooding the starter kit with an AI agent (shko@superb-ai.com).
+
+### Fixed
+
+- `examples/team_quickstart.py` docstring implied a `SUPERB_AI_TENANT` env var that
+  nothing read while the body hardcoded the slug — now uses `Client()` + the env var.
+
+## [0.0.2] - 2026-07-06 (internal)
+
+### Breaking
+
+- Removed `deployments.predict_batch` and `foundation.predict_batch`, and the
+  `s3_key` image source on both `predict` methods (ADR-0106). The endpoints were
+  unreachable by construction (asset rows never expose bucket keys). Migration:
+  single predict with `image_url=assets.download_url(...).url` (platform assets)
+  or `image_b64` (local bytes); whole-dataset inference is the `auto_label` job.
+- `training.list_runs` now returns `Page[TrainingRun]` (cursor-paginated, was a
+  plain `list`). Migration: iterate the page (`for r in ...` — auto-fetches all
+  pages) instead of indexing; `limit=`/`cursor=` are now honored.
+
+### Added
+
+- Typed request params (ADR-0107): every dict-shaped parameter has a `*Param`
+  TypedDict in `superb_ai.types.requests` (filters, scope/selection, geometry,
+  annotation rows, ontology specs, tag config, search parts, anchors, upload
+  items, SAM points, foundation refs, training split). Dict literals are
+  unchanged at runtime and now type-check; closed-vocabulary keys are `Literal`
+  values. Gates G5/G5b pin keys and values to the server's schemas.
+- Debug logging: `SUPERB_AI_LOG=debug|info` (or the `superb_ai` logger) emits
+  `METHOD path [request-id] -> status in Nms` per request plus retry warnings.
+- Request correlation: every request sends a client-minted `x-request-id`; the
+  server threads it into its logs and error envelopes, so the bracketed id in
+  SDK logs equals `APIError.request_id` equals the server-side log entry.
+- `User-Agent: superb-ai-sdk/<version> python/<ver> httpx/<ver>` on every
+  request (version attribution in server logs).
+
+### Fixed
+
+- Docstring corrections from the autonomous validation run: `AssetFilter`'s
+  filename key is `q` (not `filename`); comment anchor coords are normalized
+  image fractions (not pixels); `workflow.assign` leaves status `to_label`
+  until the assignee `claim`s (contrast `batch_assign`). `datasets.embed`'s
+  coarse progress reporting documented.
+
+## [0.0.1] - 2026-07-05 (internal)
+
+Initial build (ADR-0105). Hand-written OpenAI/Anthropic-style client: sync +
+async twins, 29 resource namespaces / 153 operations, `Page[T]` auto-pagination,
+`JobHandle.wait()`, 11-class typed error taxonomy + 56-code `ErrorCode` mirror,
+jittered retries honoring `Retry-After`, auto `Idempotency-Key` on job kickoffs,
+presigned-upload toolkit. Python >= 3.12; runtime deps `httpx` + `pydantic`
+only. Validated by an autonomous agent driving the full platform (5k-image COCO
+seed, every namespace) with zero SDK defects.

superb_ai-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

superb_ai-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: superb-ai
+Version: 0.1.0
+Summary: Official Python SDK for Superb AI — datasets, labeling, versions, training, and deployments.
+Project-URL: Homepage, https://github.com/Superb-AI-Suite/superb-ai-python
+Project-URL: Repository, https://github.com/Superb-AI-Suite/superb-ai-python
+Project-URL: Changelog, https://github.com/Superb-AI-Suite/superb-ai-python/blob/main/CHANGELOG.md
+Author: Superb AI
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Description-Content-Type: text/markdown
+
+# superb-ai
+
+Official Python SDK for Superb AI. Docs: AGENTS.md (agents), api-map.md (index).

superb_ai-0.1.0/README.md

@@ -0,0 +1,3 @@
+# superb-ai
+
+Official Python SDK for Superb AI. Docs: AGENTS.md (agents), api-map.md (index).