schift-cli 0.1.0__tar.gz

schift_cli-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: schift-cli
+Version: 0.1.0
+Summary: Schift CLI — manage agents, embeddings, and vector collections
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"

schift_cli-0.1.0/README.md

@@ -0,0 +1,303 @@
+# Schift CLI
+
+Command-line interface for Schift, the operational layer for embedding catalogs, vector collections, benchmark runs, and model migration rollouts.
+
+## What it covers
+
+- Authenticate against the Schift API
+- Inspect the embedding model catalog
+- Generate single or batch embeddings
+- Create and inspect vector collections
+- Run semantic search queries
+- Benchmark a source-to-target migration before rollout
+- Fit and execute projection-based migrations
+- Inspect usage summaries
+
+## Installation
+
+From this repository:
+
+```bash
+cd sdk/cli
+python3 -m pip install -e .
+```
+
+For local development with test dependencies:
+
+```bash
+cd sdk/cli
+python3 -m pip install -e '.[dev]'
+```
+
+The package installs a `schift` executable via the console entry point in `pyproject.toml`.
+
+## Configuration
+
+The CLI reads configuration from two places:
+
+1. `SCHIFT_API_KEY`
+2. `~/.schift/config.json`
+
+If both are present, `SCHIFT_API_KEY` wins.
+
+The API base URL is resolved as:
+
+1. `SCHIFT_API_URL`
+2. `https://api.schift.io/v1`
+
+`schift auth login` stores the API key in `~/.schift/config.json` and writes the file with `0600` permissions.
+
+Example:
+
+```bash
+export SCHIFT_API_KEY=sch_your_key_here
+export SCHIFT_API_URL=http://localhost:8080/v1
+```
+
+## Quick Start
+
+```bash
+schift auth login
+schift auth status
+
+schift catalog list
+schift catalog get openai/text-embedding-3-large
+
+schift embed "hello world" --model openai/text-embedding-3-large
+
+schift db create my-docs --dim 3072 --metric cosine
+schift db list
+schift query "revenue report" --collection my-docs --top-k 5
+
+schift bench \
+  --source openai/text-embedding-3-large \
+  --target google/gemini-embedding-004 \
+  --data ./queries.jsonl
+
+schift migrate fit \
+  --source openai/text-embedding-3-large \
+  --target google/gemini-embedding-004 \
+  --sample 0.1
+
+schift migrate run \
+  --projection proj_abc123 \
+  --db pgvector://user:password@localhost:5432/app \
+  --dry-run
+```
+
+## Command Groups
+
+| Command | Purpose |
+| --- | --- |
+| `schift auth ...` | Manage local authentication state |
+| `schift catalog ...` | Browse supported embedding models |
+| `schift embed ...` | Generate embeddings from text |
+| `schift bench ...` | Evaluate migration quality between two models |
+| `schift migrate ...` | Fit a projection and apply it to a database |
+| `schift db ...` | Create, list, and inspect collections |
+| `schift query ...` | Run semantic search against a collection |
+| `schift usage ...` | Show aggregated usage and billing summary |
+
+## Authentication
+
+```bash
+schift auth login
+schift auth status
+schift auth logout
+```
+
+- `login` prompts for an API key and stores it in the config file.
+- `status` reports whether the CLI is using the environment variable or the config file.
+- `logout` removes the stored key from the config file. It does not unset `SCHIFT_API_KEY` from your shell.
+
+## Catalog Commands
+
+List all models:
+
+```bash
+schift catalog list
+```
+
+Show one model:
+
+```bash
+schift catalog get openai/text-embedding-3-large
+```
+
+Output is rendered as a Rich table or key-value panel and typically includes provider, dimensions, token limit, status, and description.
+
+## Embedding Commands
+
+Single text:
+
+```bash
+schift embed "quarterly revenue report" --model openai/text-embedding-3-large
+```
+
+The CLI prints a success line plus a short preview of the first embedding values instead of dumping the full vector.
+
+Batch mode:
+
+```bash
+schift embed batch \
+  --file ./texts.jsonl \
+  --model google/gemini-embedding-004 \
+  --output ./embeddings.jsonl
+```
+
+Input format for `--file`:
+
+```json
+{"text":"First document"}
+{"text":"Second document"}
+```
+
+Output format for `--output`:
+
+```json
+{"text":"First document","embedding":[0.123,0.456]}
+{"text":"Second document","embedding":[0.789,0.012]}
+```
+
+If `--output` is omitted, the CLI prints only a summary count and embedding dimension.
+
+## Collection Commands
+
+Create a collection:
+
+```bash
+schift db create my-docs --dim 3072 --metric cosine
+```
+
+List collections:
+
+```bash
+schift db list
+```
+
+Inspect one collection:
+
+```bash
+schift db stats my-docs
+```
+
+`db list` prints a table with collection name, dimensions, metric, vector count, and creation time. `db stats` prints a detailed panel with index and storage metadata when the API returns it.
+
+## Query Command
+
+```bash
+schift query \
+  "revenue guidance" \
+  --collection my-docs \
+  --top-k 10 \
+  --model openai/text-embedding-3-large \
+  --threshold 0.8
+```
+
+- `--collection` is required.
+- `--model` is optional.
+- `--threshold` lets you filter low-score results.
+
+The CLI prints a ranked result table with ID, score, and a truncated text preview.
+
+## Benchmark Command
+
+```bash
+schift bench \
+  --source openai/text-embedding-3-large \
+  --target google/gemini-embedding-004 \
+  --data ./queries.jsonl \
+  --top-k 10
+```
+
+- `--data` must be an existing local file path.
+- The command shows an indeterminate spinner while the API runs the benchmark.
+- Output includes recall, MRR, cosine similarity, and latency metrics when available.
+
+This command is the safety gate before a live migration. Use it first and treat low recall as a rollout blocker.
+
+## Migration Commands
+
+Fit a projection:
+
+```bash
+schift migrate fit \
+  --source openai/text-embedding-3-large \
+  --target google/gemini-embedding-004 \
+  --sample 0.1
+```
+
+- `--sample` must be greater than `0` and less than or equal to `1`.
+- The CLI returns a projection ID you pass into `migrate run`.
+
+Dry-run a migration:
+
+```bash
+schift migrate run \
+  --projection proj_abc123 \
+  --db pgvector://user:password@localhost:5432/app \
+  --dry-run \
+  --batch-size 1000
+```
+
+Execute a live migration:
+
+```bash
+schift migrate run \
+  --projection proj_abc123 \
+  --db pgvector://user:password@localhost:5432/app \
+  --batch-size 1000
+```
+
+Operational guidance:
+
+- Start with `--dry-run`. It previews the migration without applying changes.
+- A live run asks for interactive confirmation before proceeding.
+- The displayed connection string masks the password in terminal output.
+- Output includes processed vector count, skipped vector count, duration, and status.
+
+## Usage Command
+
+```bash
+schift usage --period 30d
+```
+
+Accepted values are free-form strings such as `7d`, `30d`, or `90d`; the server decides what periods it supports.
+
+The command prints:
+
+- A summary panel with total requests, embeddings, projections, queries, storage, and cost
+- A per-model usage table when the API returns `by_model`
+
+## Error Handling and Exit Behavior
+
+- Authentication failures raise a direct action message telling you to run `schift auth login`.
+- Connection failures mention the resolved API URL and suggest checking `SCHIFT_API_URL`.
+- API errors exit non-zero and surface server-provided detail text when available.
+- Empty result sets are handled as normal output, not crashes.
+
+## Local Development
+
+Install editable dependencies:
+
+```bash
+cd sdk/cli
+python3 -m pip install -e '.[dev]'
+```
+
+Useful commands:
+
+```bash
+schift --version
+schift --help
+schift auth --help
+schift migrate --help
+pytest
+```
+
+When testing against a local API:
+
+```bash
+export SCHIFT_API_URL=http://localhost:8080/v1
+schift auth status
+```

schift_cli-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "schift-cli"
+version = "0.1.0"
+description = "Schift CLI — manage agents, embeddings, and vector collections"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[project.scripts]
+schift = "schift_cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["schift_cli*"]
+
+[tool.setuptools.package-data]
+schift_cli = ["data/schift-best-practices/**/*.md"]

schift_cli-0.1.0/schift_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

schift_cli-0.1.0/schift_cli/client.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import httpx
+
+from schift_cli.config import get_api_key, get_api_url
+
+# Timeout: 30s connect, 120s read (migrations can be slow)
+DEFAULT_TIMEOUT = httpx.Timeout(30.0, read=120.0)
+
+
+class SchiftAPIError(Exception):
+    """Raised when the Schift API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class SchiftClient:
+    """HTTP client for the Schift API.
+
+    Handles authentication headers, base URL resolution, and consistent
+    error handling so command modules can stay focused on CLI logic.
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+        self.api_key = api_key or get_api_key()
+        self.base_url = (base_url or get_api_url()).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=DEFAULT_TIMEOUT,
+            headers=self._build_headers(),
+        )
+
+    def _build_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "User-Agent": "schift-cli/0.1.0",
+            "Accept": "application/json",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    # -- HTTP verbs ----------------------------------------------------------
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self._request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+    # -- Internal -------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.ConnectError:
+            raise click.ClickException(
+                f"Could not connect to Schift API at {self.base_url}\n"
+                "  The server may be unavailable. Check your network or set "
+                "SCHIFT_API_URL if using a custom endpoint."
+            )
+        except httpx.TimeoutException:
+            raise click.ClickException(
+                "Request timed out. The server may be under heavy load — try again."
+            )
+
+        if resp.status_code == 401:
+            raise click.ClickException(
+                "Authentication failed. Run `schift auth login` to set your API key."
+            )
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                detail = body.get("detail") or body.get("message") or resp.text
+            except Exception:
+                detail = resp.text
+            raise SchiftAPIError(resp.status_code, str(detail))
+
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SchiftClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+def require_api_key() -> str:
+    """Return the API key or abort with a helpful message."""
+    key = get_api_key()
+    if not key:
+        raise click.ClickException(
+            "No API key configured.\n"
+            "  Run `schift auth login` or set the SCHIFT_API_KEY environment variable."
+        )
+    return key
+
+
+def get_client() -> SchiftClient:
+    """Create a client, ensuring an API key is present."""
+    api_key = require_api_key()
+    return SchiftClient(api_key=api_key)

schift_cli-0.1.0/schift_cli/commands/auth.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import click
+
+from schift_cli.config import clear_api_key, get_api_key, set_api_key, CONFIG_FILE
+from schift_cli.display import success, info, error
+
+
+@click.group("auth")
+def auth() -> None:
+    """Manage authentication with the Schift platform."""
+
+
+@auth.command()
+def login() -> None:
+    """Set your Schift API key."""
+    existing = get_api_key()
+    if existing:
+        overwrite = click.confirm(
+            "An API key is already configured. Overwrite?", default=False
+        )
+        if not overwrite:
+            info("Keeping existing API key.")
+            return
+
+    api_key = click.prompt("Enter your Schift API key", hide_input=True)
+    api_key = api_key.strip()
+
+    if not api_key:
+        raise click.ClickException("API key cannot be empty.")
+
+    set_api_key(api_key)
+    success(f"API key saved to {CONFIG_FILE}")
+
+
+@auth.command()
+def logout() -> None:
+    """Remove the stored API key."""
+    if not get_api_key():
+        info("No API key is currently stored.")
+        return
+
+    clear_api_key()
+    success("API key removed.")
+
+
+@auth.command()
+def status() -> None:
+    """Show current authentication status."""
+    import os
+    from schift_cli.config import ENV_API_KEY
+
+    env_key = os.environ.get(ENV_API_KEY)
+    file_key = None
+    try:
+        from schift_cli.config import load_config
+        file_key = load_config().get("api_key")
+    except Exception:
+        pass
+
+    if env_key:
+        masked = env_key[:8] + "..." + env_key[-4:] if len(env_key) > 12 else "***"
+        success(f"Authenticated via {ENV_API_KEY} env var (key: {masked})")
+    elif file_key:
+        masked = file_key[:8] + "..." + file_key[-4:] if len(file_key) > 12 else "***"
+        success(f"Authenticated via config file (key: {masked})")
+    else:
+        error("Not authenticated. Run `schift auth login` to get started.")

schift_cli-0.1.0/schift_cli/commands/bench.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from schift_cli.client import get_client, SchiftAPIError
+from schift_cli.display import console, error, info, print_kv, spinner, success
+
+
+@click.command("bench")
+@click.option("--source", "-s", required=True, help="Source model ID (e.g. openai/text-embedding-3-large)")
+@click.option("--target", "-t", required=True, help="Target model ID (e.g. google/gemini-embedding-004)")
+@click.option("--data", "-d", type=click.Path(exists=True, path_type=Path), required=True,
+              help="JSONL file with benchmark queries")
+@click.option("--top-k", "-k", type=int, default=10, show_default=True,
+              help="Number of results to compare per query")
+def bench(source: str, target: str, data: Path, top_k: int) -> None:
+    """Benchmark embedding quality between two models.
+
+    Measures how well a Schift projection preserves retrieval quality
+    when switching from SOURCE to TARGET model.
+    """
+    info(f"Benchmarking projection: {source} -> {target}")
+    info(f"Data: {data}  |  top-k: {top_k}")
+
+    try:
+        with get_client() as client:
+            with spinner("Running benchmark...") as progress:
+                progress.add_task("Running benchmark...", total=None)
+                result = client.post(
+                    "/bench",
+                    json={
+                        "source_model": source,
+                        "target_model": target,
+                        "data_path": str(data),
+                        "top_k": top_k,
+                    },
+                )
+    except SchiftAPIError as e:
+        error(f"Benchmark failed: {e.detail}")
+        raise SystemExit(1)
+    except click.ClickException:
+        raise
+
+    report = result.get("report", result)
+    print_kv("Benchmark Report", {
+        "Source Model": source,
+        "Target Model": target,
+        "Queries": report.get("num_queries", "-"),
+        "Recall@k": report.get("recall_at_k", "-"),
+        "MRR": report.get("mrr", "-"),
+        "Cosine Similarity (avg)": report.get("avg_cosine_similarity", "-"),
+        "Latency (p50)": report.get("latency_p50_ms", "-"),
+        "Latency (p99)": report.get("latency_p99_ms", "-"),
+    })
+
+    quality = report.get("recall_at_k")
+    if quality is not None:
+        if float(quality) >= 0.95:
+            success("Projection quality is excellent.")
+        elif float(quality) >= 0.85:
+            console.print("[yellow]Projection quality is acceptable but may degrade edge cases.[/]")
+        else:
+            console.print("[red]Projection quality is low. Consider increasing sample size in `migrate fit`.[/]")

schift_cli-0.1.0/schift_cli/commands/catalog.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import click
+
+from schift_cli.client import get_client, SchiftAPIError
+from schift_cli.display import print_table, print_kv, error
+
+
+@click.group("catalog")
+def catalog() -> None:
+    """Browse available embedding models."""
+
+
+@catalog.command("list")
+def list_models() -> None:
+    """List all supported embedding models."""
+    try:
+        with get_client() as client:
+            data = client.get("/catalog/models")
+    except SchiftAPIError as e:
+        error(f"Failed to fetch model catalog: {e.detail}")
+        raise SystemExit(1)
+    except click.ClickException:
+        raise
+
+    models = data.get("models", [])
+    if not models:
+        click.echo("No models found in the catalog.")
+        return
+
+    rows = [
+        (
+            m.get("id", ""),
+            m.get("provider", ""),
+            str(m.get("dimensions", "")),
+            m.get("max_tokens", ""),
+            m.get("status", ""),
+        )
+        for m in models
+    ]
+    print_table(
+        "Embedding Model Catalog",
+        ["Model ID", "Provider", "Dimensions", "Max Tokens", "Status"],
+        rows,
+    )
+
+
+@catalog.command("get")
+@click.argument("model_id")
+def get_model(model_id: str) -> None:
+    """Show details for a specific model.
+
+    MODEL_ID is the fully qualified model name, e.g. openai/text-embedding-3-large
+    """
+    try:
+        with get_client() as client:
+            data = client.get(f"/catalog/models/{model_id}")
+    except SchiftAPIError as e:
+        if e.status_code == 404:
+            error(f"Model not found: {model_id}")
+        else:
+            error(f"Failed to fetch model: {e.detail}")
+        raise SystemExit(1)
+    except click.ClickException:
+        raise
+
+    model = data.get("model", data)
+    print_kv(f"Model: {model_id}", {
+        "Provider": model.get("provider", "-"),
+        "Dimensions": model.get("dimensions", "-"),
+        "Max Tokens": model.get("max_tokens", "-"),
+        "Status": model.get("status", "-"),
+        "Description": model.get("description", "-"),
+    })