scictl 0.0.1__py3-none-any.whl

scictl/__init__.py

@@ -0,0 +1 @@
+"""scictl — upload JSONL files to Sciforium storage."""

scictl/api.py

@@ -0,0 +1,171 @@
+"""Sciforium API and storage client.
+
+The upload flow has two steps:
+
+1. ``create_dataset`` registers the dataset with the API and receives a
+   short-lived presigned S3 PUT URL.
+2. ``upload_file`` PUTs the file bytes directly to that URL.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import httpx
+from tqdm import tqdm
+
+from scictl.version import get_version
+
+BASE_URL = "https://api.sciforium.com"
+DATASETS_PATH = "/v1/datasets"
+
+#: Chunk size used when streaming the file to storage. Heuristically chosen to balance speed and memory usage.
+CHUNK_SIZE_BYTES = 8 * 1024 * 1024
+
+#: Storage uploads may take a long time, so the write timeout is disabled.
+UPLOAD_TIMEOUT = httpx.Timeout(connect=10.0, read=30.0, write=None, pool=10.0)
+
+
+class ApiError(Exception):
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        *,
+        cause: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.cause = cause
+
+
+class ApiUnreachable(ApiError):
+    def __init__(self, cause: str) -> None:
+        super().__init__(0, "request failed", cause=cause)
+
+
+def create_client() -> httpx.Client:
+    version = get_version()
+    return httpx.Client(
+        headers={
+            "User-Agent": f"scictl/{version}",
+            "X-Scictl-Version": version,
+        }
+    )
+
+
+def create_storage_client() -> httpx.Client:
+    return httpx.Client()
+
+
+def create_dataset(
+    api_key: str,
+    name: str,
+    file_size_bytes: int,
+    *,
+    client: httpx.Client,
+) -> dict[str, Any]:
+    """Register a dataset and return the parsed ``201`` response body."""
+    try:
+        response = client.post(
+            f"{BASE_URL}{DATASETS_PATH}",
+            headers={"x-api-key": api_key, "accept": "application/json"},
+            json={"name": name, "file_size_bytes": file_size_bytes},
+        )
+    except httpx.HTTPError as exc:
+        raise ApiUnreachable(str(exc)) from exc
+
+    if response.status_code != 201:
+        raise _api_error(response)
+    body = _parse_json_object(response)
+    if body is None:
+        raise ApiError(response.status_code, "unexpected response body")
+    return body
+
+
+def upload_file(
+    upload: dict[str, Any],
+    file_path: Path,
+    file_size_bytes: int,
+    *,
+    client: httpx.Client,
+) -> None:
+    headers = {
+        str(key): str(value) for key, value in (upload.get("headers") or {}).items()
+    }
+    headers["Content-Length"] = str(file_size_bytes)
+
+    with file_path.open("rb") as handle:
+        chunks = _read_chunks(handle, file_size_bytes, file_path.name)
+        try:
+            response = client.put(
+                upload["url"],
+                headers=headers,
+                content=chunks,
+                timeout=UPLOAD_TIMEOUT,
+            )
+        except httpx.HTTPError as exc:
+            raise ApiUnreachable(str(exc)) from exc
+
+    if not response.is_success:
+        raise _storage_error(response)
+
+
+def _read_chunks(handle: Any, total: int, description: str) -> Iterator[bytes]:
+    with tqdm(
+        total=total,
+        desc=description,
+        unit="B",
+        unit_scale=True,
+        unit_divisor=1000,
+        file=sys.stderr,
+    ) as bar:
+        while chunk := handle.read(CHUNK_SIZE_BYTES):
+            bar.update(len(chunk))
+            yield chunk
+
+
+def _api_error(response: httpx.Response) -> ApiError:
+    message = response.reason_phrase or f"HTTP {response.status_code}"
+    cause: str | None = None
+
+    body = _parse_json_object(response)
+    if body is not None:
+        if isinstance(body.get("message"), str) and body["message"]:
+            message = body["message"]
+        value = body.get("cause")
+        if isinstance(value, str) and value:
+            cause = value
+
+    return ApiError(response.status_code, message, cause=cause)
+
+
+def _storage_error(response: httpx.Response) -> ApiError:
+    """Parse an S3 XML error body into an :class:`ApiError`."""
+    message = response.reason_phrase or f"HTTP {response.status_code}"
+
+    text = response.text or ""
+    detail = _xml_element(text, "Message")
+    if detail:
+        message = detail
+
+    return ApiError(response.status_code, message)
+
+
+def _xml_element(body: str, tag: str) -> str | None:
+    match = re.search(rf"<{tag}>(.*?)</{tag}>", body, re.DOTALL)
+    return match.group(1).strip() or None if match else None
+
+
+def _parse_json_object(response: httpx.Response) -> dict[str, Any] | None:
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return None
+    return body if isinstance(body, dict) else None

scictl/cli.py

@@ -0,0 +1,22 @@
+"""Command-line interface for scictl."""
+
+import click
+
+from scictl.commands.dataset import dataset
+from scictl.commands.version import version
+from scictl.metavars import OPTIONS_METAVAR, SUBCOMMAND_METAVAR
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(
+    context_settings=CONTEXT_SETTINGS,
+    options_metavar=OPTIONS_METAVAR,
+    subcommand_metavar=SUBCOMMAND_METAVAR,
+)
+def cli() -> None:
+    """scictl — upload JSONL files to Sciforium storage."""
+
+
+cli.add_command(dataset)
+cli.add_command(version)

scictl/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for the scictl CLI."""

scictl/commands/dataset/__init__.py

@@ -0,0 +1,14 @@
+"""The ``dataset`` command group."""
+
+import click
+
+from scictl.commands.dataset.upload import upload
+from scictl.metavars import OPTIONS_METAVAR, SUBCOMMAND_METAVAR
+
+
+@click.group(options_metavar=OPTIONS_METAVAR, subcommand_metavar=SUBCOMMAND_METAVAR)
+def dataset() -> None:
+    """Manage customer datasets."""
+
+
+dataset.add_command(upload)

scictl/commands/dataset/upload.py

@@ -0,0 +1,105 @@
+"""The ``dataset upload`` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from scictl import api
+from scictl.metavars import OPTIONS_METAVAR
+
+CONNECT_MESSAGE = "Could not reach api.sciforium.com. Please retry your request."
+UNEXPECTED_RESPONSE_MESSAGE = (
+    "The API returned an unexpected response. Please retry your request."
+)
+
+
+@click.command(options_metavar=OPTIONS_METAVAR)
+@click.argument("dataset_name", metavar="<dataset_name>")
+@click.argument(
+    "file_path",
+    metavar="<file_path>",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--api-key",
+    default=None,
+    metavar="<key>",
+    help="Sciforium API key. Prompted for (hidden) if omitted.",
+)
+def upload(dataset_name: str, file_path: Path, api_key: str | None) -> None:
+    """Register <dataset_name> and upload a local JSONL file to Sciforium storage."""
+    if api_key is None:
+        api_key = click.prompt("Sciforium API key", hide_input=True)
+    key = (api_key or "").strip()
+    if not key:
+        raise click.UsageError(
+            "An API key is required. Provision one at https://console.sciforium.com/keys"
+        )
+
+    file_size_bytes = file_path.stat().st_size
+    if file_path.suffix.lower() != ".jsonl":
+        click.secho(
+            f"warning: {file_path.name} does not end in .jsonl", fg="yellow", err=True
+        )
+
+    with api.create_client() as client:
+        try:
+            created = api.create_dataset(
+                key, dataset_name, file_size_bytes, client=client
+            )
+        except api.ApiUnreachable as exc:
+            raise click.ClickException(CONNECT_MESSAGE) from exc
+        except api.ApiError as exc:
+            raise click.ClickException(_display_message(exc)) from exc
+
+        presigned = _presigned_upload(created)
+        if presigned is None:
+            raise click.ClickException(UNEXPECTED_RESPONSE_MESSAGE)
+
+        with api.create_storage_client() as storage_client:
+            try:
+                api.upload_file(
+                    presigned, file_path, file_size_bytes, client=storage_client
+                )
+            except api.ApiUnreachable as exc:
+                raise click.ClickException(
+                    "Lost the connection while uploading to storage. Please try again."
+                ) from exc
+            except api.ApiError as exc:
+                raise click.ClickException(_upload_message(exc)) from exc
+
+    click.echo(f"Uploaded '{dataset_name}' successfully!")
+
+
+def _presigned_upload(created: dict) -> dict | None:
+    """Return the validated ``upload`` object from a create response, or ``None``."""
+    presigned = created.get("upload")
+    if not isinstance(presigned, dict):
+        return None
+    url = presigned.get("url")
+    if not isinstance(url, str) or not url:
+        return None
+    headers = presigned.get("headers")
+    if headers is not None and not isinstance(headers, dict):
+        return None
+    return presigned
+
+
+def _display_message(error: api.ApiError) -> str:
+    """Show the API-owned copy, preferring ``cause`` over ``message`` (web parity)."""
+    return error.cause or error.message
+
+
+def _upload_message(error: api.ApiError) -> str:
+    if error.status == 412:
+        reason = (
+            "A file was already uploaded for this dataset, so the upload was rejected. "
+            "Use a different name to upload a new file."
+        )
+    elif error.status == 403 and "expired" in error.message.lower():
+        reason = "The upload URL expired before the file finished (presigned URLs last 15 minutes)."
+    else:
+        reason = f"Upload to storage failed (HTTP {error.status}): {error.message}"
+    return reason

scictl/commands/version.py

@@ -0,0 +1,26 @@
+"""The ``version`` command."""
+
+import json
+import platform
+
+import click
+
+from scictl.metavars import OPTIONS_METAVAR
+from scictl.version import PACKAGE_NAME, get_version
+
+
+@click.command(options_metavar=OPTIONS_METAVAR)
+@click.option("--json", "as_json", is_flag=True, help="Print the version as JSON.")
+def version(as_json: bool) -> None:
+    """Show the scictl version and the runtime it is running on."""
+    if as_json:
+        payload = {
+            "name": PACKAGE_NAME,
+            "version": get_version(),
+            "python": platform.python_version(),
+            "platform": f"{platform.system().lower()}-{platform.machine()}",
+        }
+        click.echo(json.dumps(payload))
+        return
+
+    click.echo(f"{PACKAGE_NAME} version {get_version()}")

scictl/metavars.py

@@ -0,0 +1,8 @@
+"""Usage-line placeholders shared by every command.
+
+Click renders positional arguments and its ``[OPTIONS]`` / ``COMMAND [ARGS]...`` slots
+in ALL CAPS by default; scictl shows them as ``[options]`` and ``<name>`` instead.
+"""
+
+OPTIONS_METAVAR = "[options]"
+SUBCOMMAND_METAVAR = "<command> [args]..."

scictl/version.py

@@ -0,0 +1,23 @@
+"""The scictl version, read from installed distribution metadata."""
+
+import importlib.metadata
+
+PACKAGE_NAME = "scictl"
+
+#: Returned when distribution metadata is unavailable, e.g. a source checkout that was
+#: never installed. This is a valid PEP 440 local version that sorts below every real
+#: release, so a version-aware server reads an unidentifiable client as older than any
+#: minimum supported version rather than newer.
+UNKNOWN_VERSION = "0.0.0+unknown"
+
+
+def get_version() -> str:
+    """Return the scictl version as a PEP 440 string.
+
+    Reads the version recorded when the distribution was installed, so this is the same
+    value the package was built with rather than whatever is on disk now.
+    """
+    try:
+        return importlib.metadata.version(PACKAGE_NAME)
+    except importlib.metadata.PackageNotFoundError:
+        return UNKNOWN_VERSION

scictl-0.0.1.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: scictl
+Version: 0.0.1
+Summary: Sciforium command-line interface tool
+Author: Purna Doddapaneni
+Author-email: Purna Doddapaneni <purna@sciforium.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: click>=8.5.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: tqdm>=4.66
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# scictl
+
+The command-line interface to Sciforium's ecosystem. Today that means registering
+datasets and uploading files straight to Sciforium storage for SpecFoundry, with more
+features coming soon.
+
+## Installation
+
+```sh
+# with uv (recommended)
+uv tool install scictl
+
+# with pip
+pip install scictl
+```
+
+## Usage
+
+Visit [sciforium.com](https://sciforium.com) to provision an API key.
+
+```sh
+scictl dataset upload training-data data.jsonl --api-key "$SCIFORIUM_API_KEY"
+```
+
+- **`dataset upload`** — registers the dataset to your account, and uploads to storage.
+- **`version`** — `scictl version`; pass `--json` for scripts and bug reports.
+
+Requires Python 3.10+.

scictl-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+scictl/__init__.py,sha256=N1A1O7VwExNCyQx2ca6e4xzpmwj582jQ9AOKgz6JBac,58
+scictl/api.py,sha256=Q4ClHn1mwWNszNgcH3Er_-fGmtL5uZSgzqIAQ-8zFXk,4723
+scictl/cli.py,sha256=rUMWHqwuWopKsEH3o_MmslBEyp2ps3_T2CM7w6CJOSQ,538
+scictl/commands/__init__.py,sha256=_SzUfwOQ3gnyQMzeOoL3Jf5mvBlRuTOpR4gheVllK1g,50
+scictl/commands/dataset/__init__.py,sha256=mID9jXy8q2ZIdEN9N_MVIwuPSz89pU38e45Gp8PyGsM,342
+scictl/commands/dataset/upload.py,sha256=p-fiiXt1ipU1v_D1J6puqiVC35eUvURJ6X7MDuky0h0,3713
+scictl/commands/version.py,sha256=lidrfuPoBfOhcg73sHet9rYM0OB7-wTarpmgtLGhBaA,768
+scictl/metavars.py,sha256=LFFkqGJW4M_CGSje9EdNB84KuCKAHoJtXKsrVuD8Go0,301
+scictl/version.py,sha256=zlkVaWZ4wNKRpvAwck6fkVEcS1fU_4fPYEqzyeMzos0,865
+scictl-0.0.1.dist-info/licenses/LICENSE,sha256=t-FNn93kbcEudzyCmUBbQsHV3aFFUiQgYmzrOhD1CrM,1066
+scictl-0.0.1.dist-info/WHEEL,sha256=Kot-FOXwz2no6rGIg4et79Z7m6vcKPAXr2Y6fTFpZuI,81
+scictl-0.0.1.dist-info/entry_points.txt,sha256=2uZQfCMcEvR2-RCn1WJuOahe8cqQh2nVsgoH-AYizy4,43
+scictl-0.0.1.dist-info/METADATA,sha256=1vZhBy0lEJwC3ZOhUyFM5CAsAUBRooa6NqDdnPgD2oQ,1041
+scictl-0.0.1.dist-info/RECORD,,

scictl-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.10
+Root-Is-Purelib: true
+Tag: py3-none-any

scictl-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+scictl = scictl.cli:cli
+

scictl-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sciforium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.