sunstone-data-platform 1.3.0__tar.gz → 1.4.1__tar.gz

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sunstone-data-platform
-Version: 1.3.0
+Version: 1.4.1
 Summary: Sunstone Data Platform - Data lakehouse with semantic metadata
 Author-email: Sunstone Institute <stig@sunstone.institute>
 License-Expression: MIT
@@ -15,8 +15,9 @@ Requires-Dist: pyiceberg[duckdb,gcsfs,s3fs]>=0.10.0
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: python-slugify>=8.0.0
+Requires-Dist: rdflib>=7.6
 Requires-Dist: rich>=14.0.0
-Requires-Dist: sunstone-py>=1.15.0
+Requires-Dist: sunstone-py>=1.19.0
 Requires-Dist: typer>=0.27.1
 Provides-Extra: pipelines
 Requires-Dist: dagster-docker>=0.29.0; extra == 'pipelines'
@@ -62,7 +63,7 @@ full data flow.
 ## Endpoints
 
 - `/catalog` — DCAT JSON-LD view of the lakehouse, served by graph-server views
-  (see [the views design](docs/specs/2026-08-02-graph-server-views-design.md))
+  (see [DP-SPEC-13](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-13))
 - `/ui/` — the data explorer, a 3D view of the data graph, served by
   graph-server (see [docs/data-explorer.md](docs/data-explorer.md))
 
@@ -264,8 +265,8 @@ src/sunstone_data/
 ## Documentation
 
 - [docs/README.md](docs/README.md) - Index of all documentation
-- [docs/architecture.md](docs/architecture.md) - System overview and data flow
-- [docs/specs2/](docs/specs2/) - Current design, one file per subsystem. The Python client and CLI are in [05-python-client.md](docs/specs2/05-python-client.md).
+- [docs/architecture.md](docs/architecture.md) - System overview, data flow, and an index of the specs in Worklode. The Python client and CLI are in [DP-SPEC-1](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-1).
+- [docs/releasing.md](docs/releasing.md) - How to release the server and the client
 
 ## Resetting the Stack
 
@@ -285,7 +286,7 @@ MIT
 `graph-server` requires a Keycloak bearer token on every route except
 `/healthz`/`/readyz`. Access is role-based: the client roles in your token
 determine which environment you can use. See
-`docs/specs/2026-07-05-graph-server-auth-design.md`.
+[DP-SPEC-14](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-14).
 
 No hostnames or client ids ship in this package. Each environment's
 `base_iri` comes from config: Sunstone-managed machines get

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/README.md

@@ -35,7 +35,7 @@ full data flow.
 ## Endpoints
 
 - `/catalog` — DCAT JSON-LD view of the lakehouse, served by graph-server views
-  (see [the views design](docs/specs/2026-08-02-graph-server-views-design.md))
+  (see [DP-SPEC-13](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-13))
 - `/ui/` — the data explorer, a 3D view of the data graph, served by
   graph-server (see [docs/data-explorer.md](docs/data-explorer.md))
 
@@ -237,8 +237,8 @@ src/sunstone_data/
 ## Documentation
 
 - [docs/README.md](docs/README.md) - Index of all documentation
-- [docs/architecture.md](docs/architecture.md) - System overview and data flow
-- [docs/specs2/](docs/specs2/) - Current design, one file per subsystem. The Python client and CLI are in [05-python-client.md](docs/specs2/05-python-client.md).
+- [docs/architecture.md](docs/architecture.md) - System overview, data flow, and an index of the specs in Worklode. The Python client and CLI are in [DP-SPEC-1](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-1).
+- [docs/releasing.md](docs/releasing.md) - How to release the server and the client
 
 ## Resetting the Stack
 
@@ -258,7 +258,7 @@ MIT
 `graph-server` requires a Keycloak bearer token on every route except
 `/healthz`/`/readyz`. Access is role-based: the client roles in your token
 determine which environment you can use. See
-`docs/specs/2026-07-05-graph-server-auth-design.md`.
+[DP-SPEC-14](https://worklode.dev.sunstoneinstitute.ai/DP-SPEC-14).
 
 No hostnames or client ids ship in this package. Each environment's
 `base_iri` comes from config: Sunstone-managed machines get

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/pyproject.toml

@@ -13,7 +13,7 @@ authors = [
     { name = "Sunstone Institute", email = "stig@sunstone.institute" }
 ]
 dependencies = [
-    "sunstone-py>=1.15.0",
+    "sunstone-py>=1.19.0",
     "pyiceberg[s3fs,gcsfs,duckdb]>=0.10.0",
     "duckdb>=1.5.3",
     "python-dotenv>=1.2.2",
@@ -26,6 +26,7 @@ dependencies = [
     "python-dateutil>=2.9.0.post0",
     "publicsuffixlist>=1.0.2.20261003",
     "keyring>=25",
+    "rdflib>=7.6",
 ]
 
 [project.entry-points."sunstone.plugins"]
@@ -41,6 +42,9 @@ pipelines = [
 
 [tool.hatch.version]
 source = "vcs"
+# Only `v*` tags are client versions. Without --match, setuptools-scm takes the
+# nearest tag of any kind and strips a `server-` prefix (DP-REQ-391).
+raw-options = { git_describe_command = "git describe --dirty --tags --long --match v[0-9]*" }
 
 [tool.hatch.build.hooks.vcs]
 version-file = "src/sunstone_data/_version.py"

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.0'
-__version_tuple__ = version_tuple = (1, 3, 0)
+__version__ = version = '1.4.1'
+__version_tuple__ = version_tuple = (1, 4, 1)
 
 __commit_id__ = commit_id = None

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/auth/stepup.py

@@ -83,10 +83,12 @@ def step_up(
     """
     settings = get_settings()
     if os.environ.get("SUNSTONE_ACCESS_TOKEN", "").strip() or (settings.client_id and settings.client_secret):
-        raise StepUpRequired("writes to main need a passkey sign-in; a service credential cannot step up")
+        raise StepUpRequired("writes to a protected ref need a passkey sign-in; a service credential cannot step up")
     session = store.read_session(env_name)
     if session is None:
-        raise StepUpRequired(f"writes to main need a passkey sign-in; run `sunstone auth login` for {env_name!r}")
+        raise StepUpRequired(
+            f"writes to a protected ref need a passkey sign-in; run `sunstone auth login` for {env_name!r}"
+        )
     issuer = session.issuer or discovered_issuer(env_name, settings.graph_url)
     authorization_endpoint = discover_authorization_endpoint(issuer, client)
     token_endpoint = discover_token_endpoint(issuer, client)

sunstone_data_platform-1.4.1/src/sunstone_data/branch.py

@@ -0,0 +1,66 @@
+"""Default data branch: the current git branch (or CI ref), normalized (DP-SPEC-12 section 12)."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+
+_MAX_LENGTH = 128
+
+
+class NoDataBranchError(ValueError):
+    """No data branch could be derived; the caller must pass ``--branch``."""
+
+
+def normalize_branch_name(name: str) -> str:
+    """Turn a git branch name into a valid data branch name.
+
+    In order: characters outside ``[A-Za-z0-9_.-]`` become ``-``, runs of
+    ``-`` collapse to one, a name not starting with a letter or ``_`` gets a
+    ``_`` prefix, and the result is cut to 128 characters.
+    """
+    name = re.sub(r"[^A-Za-z0-9_.-]", "-", name)
+    name = re.sub(r"-{2,}", "-", name)
+    if not re.match(r"[A-Za-z_]", name):
+        name = "_" + name
+    return name[:_MAX_LENGTH]
+
+
+def _git_branch(cwd: Path | None) -> str | None:
+    """The checked-out git branch, or None (not a checkout, git missing, detached HEAD)."""
+    try:
+        result = subprocess.run(
+            ["git", "symbolic-ref", "--short", "-q", "HEAD"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    name = result.stdout.strip()
+    return name if result.returncode == 0 and name else None
+
+
+def current_data_branch(cwd: Path | None = None, env: Mapping[str, str] | None = None) -> str:
+    """Return the data branch for ``cwd``, normalized.
+
+    Order: the checked-out git branch (also on a branch with no commits yet),
+    then ``GITHUB_HEAD_REF``, then ``GITHUB_REF_NAME``. CI checks out pull
+    requests on a detached HEAD, which is why the variables come second.
+
+    Raises:
+        NoDataBranchError: None of these gives a branch. Never falls back to ``main``.
+    """
+    env = os.environ if env is None else env
+    name = _git_branch(cwd) or env.get("GITHUB_HEAD_REF") or env.get("GITHUB_REF_NAME")
+    if not name:
+        raise NoDataBranchError(
+            "Cannot tell which data branch to use: not on a git branch and GITHUB_HEAD_REF / "
+            "GITHUB_REF_NAME are unset. Pass --branch."
+        )
+    return normalize_branch_name(name)

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/__init__.py

@@ -9,6 +9,7 @@ point can register the whole CLI surface in well under 100ms.
 """
 
 from sunstone_data.cli.commands import (  # noqa: F401  (import side-effect: registers commands)
+    conceptmap,
     data_auth,
     data_import,
     data_info,

sunstone_data_platform-1.4.1/src/sunstone_data/cli/commands/conceptmap.py

@@ -0,0 +1,81 @@
+"""``sunstone data conceptmap create|update|sssom``: push a map-concepts scope directory, read its mappings (DP-REQ-323)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+import typer
+
+from sunstone_data.cli._app import console, data_app
+from sunstone_data.cli._errors import cli_errors
+
+conceptmap_app = typer.Typer(help="Push concept maps from map-concepts scope directories", no_args_is_help=True)
+data_app.add_typer(conceptmap_app, name="conceptmap")
+
+_SCOPE_DIR = typer.Argument(
+    ..., help="Scope directory written by map-concepts (reads scheme/*.ttl and scheme/mappings.sssom.tsv)"
+)
+# Concept maps are published content, so the default is main, not the git
+# branch of the directory the command runs in (DP-REQ-30).
+_BRANCH = typer.Option("main", "--branch", "-b", help="Branch to write")
+_BRANCH_READ = typer.Option("main", "--branch", "-b", help="Branch to read")
+_JSON = typer.Option(False, "--json", help="Output as JSON")
+
+
+def _report(result, json_output: bool) -> None:
+    from urllib.parse import quote
+
+    from sunstone_data.config import get_settings
+
+    link = f"{get_settings().graph_url}/ui/#visualise?graph={quote(result.graph_iri, safe='')}"
+    if json_output:
+        print(json.dumps({**asdict(result), "url": link}))
+        return
+    console.print(
+        f"Concept map [cyan]{result.conceptmap}[/cyan]: {result.graph_iri} on {result.branch}, "
+        f"{result.triples} triples (ETag {result.etag})"
+    )
+    console.print(link)
+
+
+@conceptmap_app.command("create")
+def create_cmd(scope_dir: Path = _SCOPE_DIR, branch: str = _BRANCH, json_output: bool = _JSON) -> None:
+    """Allocate a new concept map and push the scope directory to it."""
+    with cli_errors(json_output):
+        from sunstone_data import conceptmap
+
+        _report(conceptmap.create(scope_dir, branch), json_output)
+
+
+@conceptmap_app.command("update")
+def update_cmd(
+    n: int = typer.Argument(..., help="Concept map id, the <n> in /conceptmap/<n>"),
+    scope_dir: Path = _SCOPE_DIR,
+    branch: str = _BRANCH,
+    json_output: bool = _JSON,
+) -> None:
+    """Replace an existing concept map with the scope directory."""
+    with cli_errors(json_output):
+        from sunstone_data import conceptmap
+
+        _report(conceptmap.update(n, scope_dir, branch), json_output)
+
+
+@conceptmap_app.command("sssom")
+def sssom_cmd(
+    n: int = typer.Argument(..., help="Concept map id, the <n> in /conceptmap/<n>"),
+    branch: str = _BRANCH_READ,
+    output: Path | None = typer.Option(None, "--output", "-o", help="File to write (default: stdout)"),
+) -> None:
+    """Write a concept map's mappings as an SSSOM TSV file."""
+    with cli_errors(False):
+        from sunstone_data import conceptmap
+
+        text = conceptmap.sssom(n, branch)
+        if output is None:
+            sys.stdout.write(text)
+        else:
+            output.write_text(text, encoding="utf-8")

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/data_import.py

@@ -49,8 +49,7 @@ def _format_result(result, as_json: bool = False, branch: str = "main") -> None:
     console.print(f"  Snapshot: {result.snapshot_id}")
     console.print(f"  Dataset: [cyan]{iri}[/cyan]")
     console.print(f"  Activity: [cyan]{activity}[/cyan]")
-    if branch != "main":
-        console.print(f"  Branch: [cyan]{branch}[/cyan]")
+    console.print(f"  Branch: [cyan]{branch}[/cyan]")
 
 
 @data_app.command("import")
@@ -71,7 +70,12 @@ def import_cmd(
         help="Publisher organization path, e.g. un/who. Overrides the source-URL rules file. Does not set the namespace.",
     ),
     tag: list[str] | None = typer.Option(None, "--tag", "-t", help="Add tags (key:value)"),
-    branch: str = typer.Option("main", "--branch", "-b", help="Branch to import to"),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Branch to import to (default: the normalized git branch, else the CI ref; fails if neither)",
+    ),
     force_schema: bool = typer.Option(False, "--force-schema", help="Allow unsafe schema changes"),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
@@ -86,11 +90,15 @@ def import_cmd(
         TransferSpeedColumn,
     )
 
+    from sunstone_data.branch import current_data_branch
     from sunstone_data.import_ import run_import
 
     is_url = source.startswith(("http://", "https://"))
 
     try:
+        if branch is None:
+            branch = current_data_branch()
+
         if sys.stdout.isatty() and not json_output:
             with Progress(
                 SpinnerColumn(),

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/data_publish.py

@@ -10,7 +10,12 @@ from sunstone_data.cli._app import console, data_app
 @data_app.command("publish")
 def publish_cmd(
     table: str = typer.Argument(..., help="Table identifier (namespace.table)"),
-    branch: str = typer.Option("main", "--branch", "-b", help="Branch to publish on"),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Branch to publish on (default: the normalized git branch, else the CI ref; fails if neither)",
+    ),
     version: str | None = typer.Option(
         None, "--version", help="Publish the table's current snapshot under this version label, e.g. v1.0"
     ),
@@ -27,6 +32,7 @@ def publish_cmd(
 
     from sunstone.lineage import Metadata
 
+    from sunstone_data.branch import current_data_branch
     from sunstone_data.catalog import get_catalog
     from sunstone_data.graph.dataset import DatasetDescription, DatasetVersion
     from sunstone_data.publish import publish
@@ -34,6 +40,9 @@ def publish_cmd(
     from sunstone_data.resolve import dataset_iri
 
     try:
+        if branch is None:
+            branch = current_data_branch()
+
         ref = TableRef.parse(table)
         identifier = f"{ref.namespace}.{ref.table}"
         versions: tuple[DatasetVersion, ...] = ()

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/refs.py

@@ -1,4 +1,4 @@
-"""graph-server refs: ``branches``, ``branch create|delete``, ``tags``,
+"""graph-server refs: ``branches``, ``branch create|delete|merge``, ``tags``,
 ``tag create|delete`` (spec 180 §8).
 
 Branch and tag names go into a URL path, so they are validated here before
@@ -93,6 +93,53 @@ def branch_delete_cmd(
             console.print(f"[green]Deleted branch[/green] {name}")
 
 
+@branch_app.command("merge")
+def branch_merge_cmd(
+    name: str = typer.Argument(..., help="Name of the branch to merge into main"),
+    strategy: str = typer.Option(
+        None,
+        "--strategy",
+        help="How to settle conflicts: report (default), branch-wins or main-wins",
+    ),
+    take_branch: list[str] = typer.Option(
+        [], "--take-branch", help="Graph IRI whose conflict takes the branch side (repeatable)"
+    ),
+    take_main: list[str] = typer.Option(
+        [], "--take-main", help="Graph IRI whose conflict keeps main's side (repeatable)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Merge a branch into main. Conflicts are reported unless resolved.
+
+    Exits 2 when conflicts remain, so CI knows to keep the branch.
+    """
+    with cli_errors(json_output):
+        from sunstone_data.identifiers import validate_ref_name
+
+        validate_ref_name(name, "branch")
+        if strategy is not None and strategy not in ("report", "branch-wins", "main-wins"):
+            raise ValueError(f"--strategy must be report, branch-wins or main-wins, not {strategy!r}")
+        resolve = [{"graph": g, "take": "branch"} for g in take_branch]
+        resolve += [{"graph": g, "take": "main"} for g in take_main]
+        result = _client().merge_branch(name, strategy, resolve or None)
+
+        merged, conflicts = result.get("merged", []), result.get("conflicts", [])
+        if json_output:
+            print(json.dumps(result, indent=2))
+            if conflicts:
+                raise typer.Exit(2)
+            return
+        color = "yellow" if conflicts else "green"
+        console.print(f"[{color}]Merged[/{color}] {name} into main: {len(merged)} merged, {len(conflicts)} in conflict")
+        for e in merged:
+            note = f" (took {e['resolution']})" if e.get("resolution") else ""
+            console.print(f"  merged    {e.get('table') or e['graph']}{note}")
+        for e in conflicts:
+            console.print(f"  [red]conflict[/red]  {e.get('table') or e['graph']}")
+        if conflicts:
+            raise typer.Exit(2)
+
+
 @data_app.command("tags")
 def tags_cmd(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/show.py

@@ -20,7 +20,12 @@ FORMATS = ("table", "turtle", "jsonld")
 def show_cmd(
     table: str = typer.Argument(..., help="Table reference (namespace.table[@branch])"),
     output_format: str = typer.Option("table", "--format", "-f", help=f"One of: {', '.join(FORMATS)}"),
-    branch: str = typer.Option("main", "--branch", "-b", help="Branch to read the graph from"),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Branch to read the graph from (default: the normalized git branch, else the CI ref; fails if neither)",
+    ),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON-LD (same as --format jsonld)"),
 ) -> None:
     """Show a dataset's metadata graph.
@@ -35,6 +40,7 @@ def show_cmd(
         if chosen not in FORMATS:
             raise ValueError(f"Unknown format {output_format!r}. Use one of: {', '.join(FORMATS)}")
 
+        from sunstone_data.branch import current_data_branch
         from sunstone_data.graph.client import N_TRIPLES, get_graph_client
         from sunstone_data.query import TableRef
         from sunstone_data.resolve import dataset_iri
@@ -44,7 +50,7 @@ def show_cmd(
         client = get_graph_client()
         # A ref after `@` names a graph-server branch here: the graph is
         # per-branch, and versions/snapshots are inside it, not selectors on it.
-        source_branch = ref.version_ref or branch
+        source_branch = ref.version_ref or branch or current_data_branch()
 
         if chosen == "turtle":
             print(client.get_graph(source_branch, iri))
@@ -58,6 +64,7 @@ def show_cmd(
             print(json.dumps(to_jsonld(graph), indent=2))
             return
 
+        console.print(f"Branch: [cyan]{source_branch}[/cyan]")
         _print_table(graph, iri)
 
 

{sunstone_data_platform-1.3.0 → sunstone_data_platform-1.4.1}/src/sunstone_data/cli/commands/snapshots.py

@@ -16,7 +16,12 @@ from sunstone_data.cli._errors import cli_errors
 @data_app.command("history")
 def history_cmd(
     table: str = typer.Argument(..., help="Table reference (namespace.table[@branch])"),
-    branch: str = typer.Option("main", "--branch", "-b", help="Catalog branch to read"),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Catalog branch to read (default: the normalized git branch, else the CI ref; fails if neither)",
+    ),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Show a table's Iceberg snapshot log, oldest snapshot first.
@@ -28,11 +33,13 @@ def history_cmd(
     with cli_errors(json_output):
         from datetime import datetime, timezone
 
+        from sunstone_data.branch import current_data_branch
         from sunstone_data.catalog import get_catalog
         from sunstone_data.query import TableRef
 
         ref = TableRef.parse(table)
-        iceberg_table = get_catalog(ref.version_ref or branch).load_table(f"{ref.namespace}.{ref.table}")
+        source_branch = ref.version_ref or branch or current_data_branch()
+        iceberg_table = get_catalog(source_branch).load_table(f"{ref.namespace}.{ref.table}")
 
         rows = []
         for entry in iceberg_table.history():
@@ -54,6 +61,7 @@ def history_cmd(
             print(json.dumps(rows, indent=2))
             return
 
+        console.print(f"Branch: [cyan]{source_branch}[/cyan]")
         if not rows:
             console.print("[yellow]No snapshots found[/yellow]")
             return