gutenberg-sdk 0.1.0__py3-none-any.whl

gutenberg/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from gutenberg.client import gutenberg
+
+try:
+    __version__ = version("gutenberg-sdk")
+except PackageNotFoundError:  # editable / source checkout without metadata
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["gutenberg", "__version__"]

gutenberg/client.py

@@ -0,0 +1,682 @@
+"""Gutenberg Python SDK."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import httpx
+
+from gutenberg.models import (
+    activation_response,
+    aggregation_info,
+    autointerp_run_info,
+    dataset_info,
+    dataset_phenomenon,
+    experiment_info,
+    feature_example,
+    feature_score,
+    interpret_response,
+    job_info,
+    meta_autointerp_report,
+    meta_autointerp_run_info,
+    model_info,
+    sae_info,
+)
+
+DEFAULT_BASE_URL = "https://api.gutenberg.ai"
+
+
+class gutenberg:
+    """Client for the Gutenberg SAE Activation API.
+
+    Usage:
+        from gutenberg import gutenberg
+
+        client = gutenberg(api_key="gtn_xxx")
+        result = client.activations("I like cats")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 120,
+    ):
+        import os
+        if not api_key:
+            api_key = os.environ.get("GUTENBERG_API_KEY", "")
+        if not api_key:
+            raise ValueError(
+                "API key required. Pass api_key= or set GUTENBERG_API_KEY env var."
+            )
+        if base_url is None:
+            base_url = os.environ.get("GUTENBERG_API_URL", DEFAULT_BASE_URL)
+
+        if base_url != DEFAULT_BASE_URL:
+            import sys
+            print(f"[gutenberg] hitting {base_url}", file=sys.stderr)
+
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+        self.jobs = _jobs(self._http)
+        self.datasets = _datasets(self._http)
+        self.experiments = _experiments(self._http)
+        self.aggregations = _aggregations(self._http)
+        self.subsets = _subsets(self._http)
+        self.autointerp = _autointerp(self._http)
+        self.meta_autointerp = _meta_autointerp(self._http)
+
+    def activations(
+        self,
+        text: str,
+        model_id: str = "google/gemma-3-12b-it",
+        sae_id: str | None = None,
+        top_k: int = 50,
+    ) -> activation_response:
+        """Extract SAE activations for a text string (sync).
+
+        Args:
+            sae_id: Optional. Specific SAE to use. If omitted, the model's
+                default SAE is used. See `client.saes(model_id=...)` for the
+                list per model.
+
+        Note: the SAE-extraction window size is not user-tunable — the server
+        always uses the SAE's registry `max_window_size` (= max of base model
+        native context and what was probed for the model+GPU pair). Reducing
+        it would mean both more compute *and* worse features.
+        """
+        body: dict = {
+            "text": text,
+            "model_id": model_id,
+            "top_k": top_k,
+        }
+        if sae_id is not None:
+            body["sae_id"] = sae_id
+        r = self._http.post("/v1/activations", json=body)
+        r.raise_for_status()
+        return activation_response(**r.json())
+
+    def interpret(
+        self,
+        examples: list[dict],
+        model: str | None = None,
+    ) -> interpret_response:
+        """Interpret a feature from token/activation examples."""
+        body: dict = {"examples": examples}
+        if model:
+            body["model"] = model
+        r = self._http.post("/v1/interpret", json=body)
+        r.raise_for_status()
+        return interpret_response(**r.json())
+
+    def models(self) -> list[model_info]:
+        """List supported model + SAE combinations.
+
+        Each `model_info` includes an `available_saes` list. For a flat list
+        of all SAEs across models (optionally filtered), use `client.saes()`.
+        """
+        r = self._http.get("/v1/models")
+        r.raise_for_status()
+        return [model_info(**m) for m in r.json()["models"]]
+
+    def saes(self, model_id: str | None = None) -> list[sae_info]:
+        """List available SAEs. Optionally filter by `model_id`.
+
+        SDK-first discovery: `client.saes("Qwen/Qwen3.5-9B-Base")` returns
+        every SAE registered for that model, including the default.
+        """
+        out: list[sae_info] = []
+        for m in self.models():
+            if model_id is not None and m.model_id != model_id:
+                continue
+            for s in m.available_saes:
+                out.append(sae_info(model_id=m.model_id, **s.model_dump()))
+        return out
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class _jobs:
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        dataset_id: str,
+        model_id: str = "google/gemma-3-12b-it",
+        sae_id: str | None = None,
+        top_k: int = 100,
+        num_workers: int = 1,
+        timeout_seconds: int = 21600,
+    ) -> job_info:
+        """Submit an async batch activation job.
+
+        Args:
+            sae_id: Optional. Specific SAE to use. If omitted, the model's
+                default SAE is used. See `client.saes(model_id=...)`.
+            num_workers: Parallel GPU workers. The server partitions the
+                dataset across workers and stitches their outputs into one
+                parquet. 1 = single-worker (default); higher = faster on
+                large datasets at proportional cost.
+            timeout_seconds: Per-worker GPU timeout (default 6h).
+
+        Note: the SAE-extraction window size is not user-tunable — the server
+        always uses the SAE's registry `max_window_size`. See
+        `activations()` for the rationale.
+        """
+        sae_config: dict = {
+            "model_id": model_id,
+            "top_k": top_k,
+        }
+        if sae_id is not None:
+            sae_config["sae_id"] = sae_id
+        r = self._http.post("/v1/jobs", json={
+            "dataset_id": dataset_id,
+            "sae_config": sae_config,
+            "job_config": {
+                "num_workers": num_workers,
+                "timeout_seconds": timeout_seconds,
+            },
+        })
+        r.raise_for_status()
+        return job_info(**r.json())
+
+    def get(self, job_id: str) -> job_info:
+        """Get job status."""
+        r = self._http.get(f"/v1/jobs/{job_id}")
+        r.raise_for_status()
+        return job_info(**r.json())
+
+    def list(self) -> list[job_info]:
+        """List all jobs."""
+        r = self._http.get("/v1/jobs")
+        r.raise_for_status()
+        return [job_info(**j) for j in r.json()["jobs"]]
+
+    def wait(self, job_id: str, poll_interval: float = 5.0) -> job_info:
+        """Poll until job completes or fails.
+
+        Renders a tqdm progress bar driven by `rows_processed / rows_total` if
+        tqdm is installed; falls back to a `\\r`-style print otherwise.
+        """
+        try:
+            from tqdm import tqdm  # type: ignore
+            _has_tqdm = True
+        except ImportError:
+            tqdm = None  # type: ignore
+            _has_tqdm = False
+
+        bar = None
+        last_processed = 0
+        try:
+            while True:
+                job = self.get(job_id)
+                total = job.rows_total or 0
+                processed = job.rows_processed or 0
+
+                if _has_tqdm and bar is None and total:
+                    bar = tqdm(total=total, desc=f"job {job_id[:8]}", unit="row")
+                if bar is not None:
+                    bar.update(processed - last_processed)
+                    last_processed = processed
+                elif total:
+                    print(f"\rjob {job_id[:8]}: {processed}/{total}", end="", flush=True)
+
+                if job.status in ("completed", "failed"):
+                    if bar is not None:
+                        bar.close()
+                    elif total:
+                        print()  # newline after the \r-style progress
+                    return job
+                time.sleep(poll_interval)
+        except BaseException:
+            if bar is not None:
+                bar.close()
+            raise
+
+    def download(self, job_id: str, output_path: str = "activations.parquet") -> Path:
+        """Download job results to a local file."""
+        r = self._http.get(f"/v1/jobs/{job_id}/result")
+        r.raise_for_status()
+        data = r.json()
+
+        # Download from presigned URL
+        with httpx.stream("GET", data["download_url"]) as stream:
+            stream.raise_for_status()
+            path = Path(output_path)
+            with path.open("wb") as f:
+                for chunk in stream.iter_bytes():
+                    f.write(chunk)
+        return path
+
+    def load_activations_df(self, job_id: str):
+        """Fetch a completed job's activations parquet and return a pandas DataFrame.
+
+        Skips the file-on-disk step — useful in notebooks or scripts that diff
+        activations across different extraction params (e.g. window_size=1024
+        vs window_size=8192 on the same dataset).
+
+        Requires the `pandas` extra: `pip install gutenberg-sdk[pandas]`.
+        """
+        try:
+            import io
+            import pandas as pd  # type: ignore
+        except ImportError as e:
+            raise ImportError(
+                "load_activations_df requires pandas + pyarrow. "
+                "Install with: pip install gutenberg-sdk[pandas]"
+            ) from e
+
+        r = self._http.get(f"/v1/jobs/{job_id}/result")
+        r.raise_for_status()
+        data = r.json()
+
+        buf = io.BytesIO()
+        with httpx.stream("GET", data["download_url"]) as stream:
+            stream.raise_for_status()
+            for chunk in stream.iter_bytes():
+                buf.write(chunk)
+        buf.seek(0)
+        return pd.read_parquet(buf)
+
+
+class _datasets:
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def upload(self, filepath: str | Path) -> dataset_info:
+        """Upload a parquet file as a dataset.
+
+        Gets a presigned URL, PUTs the file to S3, then confirms the upload.
+        """
+        filepath = Path(filepath)
+        if not filepath.exists():
+            raise FileNotFoundError(f"{filepath} not found")
+
+        # Get presigned upload URL
+        r = self._http.post("/v1/datasets", json={"filename": filepath.name})
+        r.raise_for_status()
+        data = r.json()
+        dataset_id = data["dataset_id"]
+
+        # PUT file to S3
+        with filepath.open("rb") as f:
+            put_r = httpx.put(
+                data["upload_url"],
+                content=f,
+                headers={"Content-Type": "application/octet-stream"},
+                timeout=600,
+            )
+            put_r.raise_for_status()
+
+        # Confirm upload
+        confirm_r = self._http.post(f"/v1/datasets/{dataset_id}/confirm")
+        confirm_r.raise_for_status()
+        confirm_data = confirm_r.json()
+
+        return dataset_info(
+            dataset_id=dataset_id,
+            name=filepath.name,
+            size_bytes=confirm_data.get("size_bytes"),
+        )
+
+    def get(self, dataset_id: str) -> dataset_info:
+        """Get dataset detail."""
+        r = self._http.get(f"/v1/datasets/{dataset_id}")
+        r.raise_for_status()
+        return dataset_info(**r.json())
+
+    def list(self) -> list[dataset_info]:
+        """List all datasets."""
+        r = self._http.get("/v1/datasets")
+        r.raise_for_status()
+        return [dataset_info(**d) for d in r.json()["datasets"]]
+
+    def columns(self, dataset_id: str) -> list[str]:
+        """Get column names from the dataset parquet."""
+        r = self._http.get(f"/v1/datasets/{dataset_id}/columns")
+        r.raise_for_status()
+        return r.json()["columns"]
+
+    def update(
+        self, dataset_id: str, *,
+        name: str | None = None, description: str | None = None,
+    ) -> dataset_info:
+        """Update dataset display metadata. Only fields passed are changed."""
+        body: dict = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        r = self._http.patch(f"/v1/datasets/{dataset_id}", json=body)
+        r.raise_for_status()
+        return dataset_info(**r.json())
+
+    def share(self, dataset_id: str) -> dict:
+        """Make a dataset publicly accessible. Returns share_url."""
+        r = self._http.post(f"/v1/datasets/{dataset_id}/share")
+        r.raise_for_status()
+        return r.json()
+
+    def unshare(self, dataset_id: str) -> dict:
+        """Revoke public access to a dataset."""
+        r = self._http.delete(f"/v1/datasets/{dataset_id}/share")
+        r.raise_for_status()
+        return r.json()
+
+
+class _experiments:
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        job_id: str,
+        target_column: str,
+        target_column_type: str = "binary",
+        positive_value: str | None = None,
+        scoring_method: str = "auroc",
+        activation_aggregation: str = "max",
+        name: str | None = None,
+        subset_id: str | None = None,
+    ) -> experiment_info:
+        """Create a scoring experiment against a target column.
+
+        Every experiment scores all four aggregations (sum/mean/max/bin) and
+        ranks by their averaged composite, server-side on Modal. If the
+        aggregate_v2 stats substrate for the experiment's role mask isn't
+        ready yet, the experiment is returned as `queued` and dispatched
+        automatically when the aggregation completes. Pass `subset_id` to
+        scope scoring to a subset's samples. (The legacy single-aggregation
+        mode is retired; the old `composite` flag is ignored by the server.)
+        """
+        body: dict = {
+            "job_id": job_id,
+            "target_column": target_column,
+            "target_column_type": target_column_type,
+            "scoring_method": scoring_method,
+            "activation_aggregation": activation_aggregation,
+        }
+        if positive_value is not None:
+            body["positive_value"] = positive_value
+        if name is not None:
+            body["name"] = name
+        if subset_id is not None:
+            body["subset_id"] = subset_id
+        r = self._http.post("/v1/experiments", json=body)
+        r.raise_for_status()
+        return experiment_info(**r.json())
+
+    def samples(self, experiment_id: str, offset: int = 0, limit: int = 50) -> dict:
+        """List the samples this experiment scored (its subset) + 'N of Y' counts."""
+        r = self._http.get(
+            f"/v1/experiments/{experiment_id}/samples",
+            params={"offset": offset, "limit": limit},
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def get(self, experiment_id: str) -> experiment_info:
+        """Get experiment status and summary."""
+        r = self._http.get(f"/v1/experiments/{experiment_id}")
+        r.raise_for_status()
+        return experiment_info(**r.json())
+
+    def wait(self, experiment_id: str, poll_interval: float = 5.0) -> experiment_info:
+        """Poll until experiment completes or fails."""
+        while True:
+            exp = self.get(experiment_id)
+            if exp.status in ("completed", "failed"):
+                return exp
+            time.sleep(poll_interval)
+
+    def features(self, experiment_id: str) -> list[feature_score]:
+        """Get ranked features for a completed experiment."""
+        r = self._http.get(f"/v1/experiments/{experiment_id}/features")
+        r.raise_for_status()
+        return [feature_score(**f) for f in r.json()["features"]]
+
+    def examples(self, experiment_id: str, feature_id: int) -> list[feature_example]:
+        """Get token-level examples for a specific feature."""
+        r = self._http.get(f"/v1/experiments/{experiment_id}/features/{feature_id}/examples")
+        r.raise_for_status()
+        return [feature_example(**e) for e in r.json()["examples"]]
+
+
+class _aggregations:
+    """Build the aggregate_v2 scoring substrate for a job.
+
+    Production runs are auto-chained off extraction (role_mask='all'); use this
+    for an explicit re-run, a non-default role_mask, or the sharded strategy on a
+    big job. Composite experiments read the resulting per_sample_feature_stats.
+    """
+
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        job_id: str,
+        role_mask: str = "all",
+        tokens_uri: str | None = None,
+        tier: str | None = None,
+        strategy: str | None = None,
+    ) -> aggregation_info:
+        """Trigger a hosted aggregate_v2 run (idempotent per (job, role_mask))."""
+        body = {"job_id": job_id, "role_mask": role_mask}
+        if tokens_uri is not None:
+            body["tokens_uri"] = tokens_uri
+        if tier is not None:
+            body["tier"] = tier
+        if strategy is not None:
+            body["strategy"] = strategy
+        r = self._http.post("/v1/aggregations", json=body)
+        r.raise_for_status()
+        return aggregation_info(**r.json())
+
+    def get(self, aggregation_id: str) -> aggregation_info:
+        """Get aggregate_v2 run status."""
+        r = self._http.get(f"/v1/aggregations/{aggregation_id}")
+        r.raise_for_status()
+        return aggregation_info(**r.json())
+
+    def list(self, job_id: str) -> list[aggregation_info]:
+        """List aggregate_v2 runs for a job."""
+        r = self._http.get("/v1/aggregations", params={"job_id": job_id})
+        r.raise_for_status()
+        return [aggregation_info(**a) for a in r.json()["aggregations"]]
+
+    def wait(self, aggregation_id: str, poll_interval: float = 10.0) -> aggregation_info:
+        """Poll until the aggregate_v2 run completes or fails."""
+        while True:
+            agg = self.get(aggregation_id)
+            if agg.status in ("completed", "failed"):
+                return agg
+            time.sleep(poll_interval)
+
+
+class _autointerp:
+    """Hosted feature labeling (autointerp) — LLM explanations of an
+    experiment's top features, written to the dataset-scoped explanation store
+    (labels survive across experiments on the same dataset+SAE).
+
+    `create(experiment_id=...)` plans the work server-side: the experiment's
+    top-N features by composite, minus features already explained under the
+    same config signature, then runs the explain loop on Modal. Returns None
+    when everything is already labeled (a noop costs nothing).
+    """
+
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        experiment_id: str,
+        top_n: int = 200,
+        config: dict | None = None,
+        feature_ids: list[int] | None = None,
+        name: str | None = None,
+    ) -> autointerp_run_info | None:
+        """Dispatch a hosted autointerp run for an experiment's top features.
+
+        config overrides merge over the cheap default (haiku-4-5 / 0-shot /
+        20 examples); pass e.g. {"model": "anthropic/claude-sonnet-4-6",
+        "kshot_variant": "k9_full"} for the calibrated high-quality config.
+        Owner-only. Returns None if all planned features are already explained.
+        """
+        r = self._http.get(f"/v1/experiments/{experiment_id}")
+        r.raise_for_status()
+        exp = r.json()
+        dataset_id, sae_id = exp.get("dataset_id"), exp.get("sae_id")
+        if not dataset_id or not sae_id:
+            raise RuntimeError(
+                f"experiment {experiment_id} has no dataset/SAE linkage"
+            )
+        body: dict = {"experiment_id": experiment_id, "top_n": top_n,
+                      "config": config or {}}
+        if feature_ids is not None:
+            body["feature_ids"] = feature_ids
+        if name is not None:
+            body["name"] = name
+        r = self._http.post(
+            f"/v1/datasets/{dataset_id}/saes/{sae_id}/autointerp/runs", json=body,
+        )
+        r.raise_for_status()
+        js = r.json()
+        if js.get("status") == "noop":
+            return None
+        return autointerp_run_info(**js)
+
+    def get(self, run_id: str) -> autointerp_run_info:
+        """Get autointerp run status/progress."""
+        r = self._http.get(f"/v1/autointerp/runs/{run_id}")
+        r.raise_for_status()
+        return autointerp_run_info(**r.json())
+
+    def wait(self, run_id: str, poll_interval: float = 5.0) -> autointerp_run_info:
+        """Poll until the run finishes. NOTE: autointerp's terminal success
+        status is 'complete' (not 'completed' like jobs/experiments)."""
+        while True:
+            run = self.get(run_id)
+            if run.status in ("complete", "failed"):
+                return run
+            time.sleep(poll_interval)
+
+    def explanations(self, run_id: str, offset: int = 0, limit: int = 200) -> list[dict]:
+        """Explanation rows for a run (explanation, patterns, scores, cost)."""
+        r = self._http.get(
+            f"/v1/autointerp/runs/{run_id}/explanations",
+            params={"offset": offset, "limit": limit},
+        )
+        r.raise_for_status()
+        return r.json()["explanations"]
+
+
+class _meta_autointerp:
+    """Hosted analysis over autointerp'd SAE features.
+
+    `create(experiment_id=..., interest=...)` derives dataset/SAE server-side,
+    chooses the default completed autointerp run unless one is supplied, and
+    dispatches a hosted plan-to-report job.
+    """
+
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        experiment_id: str,
+        interest: str,
+        autointerp_run_id: str | None = None,
+        name: str | None = None,
+        config: dict | None = None,
+    ) -> meta_autointerp_run_info:
+        body: dict = {"interest": interest, "config": config or {}}
+        if autointerp_run_id is not None:
+            body["autointerp_run_id"] = autointerp_run_id
+        if name is not None:
+            body["name"] = name
+        r = self._http.post(
+            f"/v1/experiments/{experiment_id}/meta-autointerp/runs",
+            json=body,
+        )
+        r.raise_for_status()
+        return meta_autointerp_run_info(**r.json())
+
+    def list(self, experiment_id: str) -> list[meta_autointerp_run_info]:
+        r = self._http.get(f"/v1/experiments/{experiment_id}/meta-autointerp/runs")
+        r.raise_for_status()
+        return [meta_autointerp_run_info(**row) for row in r.json()["runs"]]
+
+    def get(self, run_id: str) -> meta_autointerp_run_info:
+        r = self._http.get(f"/v1/meta-autointerp/runs/{run_id}")
+        r.raise_for_status()
+        return meta_autointerp_run_info(**r.json())
+
+    def wait(self, run_id: str, poll_interval: float = 10.0) -> meta_autointerp_run_info:
+        while True:
+            run = self.get(run_id)
+            if run.status in ("complete", "failed"):
+                return run
+            time.sleep(poll_interval)
+
+    def phenomena(self, run_id: str) -> list[dataset_phenomenon]:
+        r = self._http.get(f"/v1/meta-autointerp/runs/{run_id}/phenomena")
+        r.raise_for_status()
+        return [dataset_phenomenon(**row) for row in r.json()["phenomena"]]
+
+    def report(self, run_id: str) -> meta_autointerp_report:
+        r = self._http.get(f"/v1/meta-autointerp/runs/{run_id}/report")
+        r.raise_for_status()
+        return meta_autointerp_report(**r.json())
+
+
+class _subsets:
+    """Named, reusable sample subsets over a dataset (a DuckDB predicate +
+    optional role_mask). Reference one from `experiments.create(subset_id=...)`
+    to scope scoring to its samples."""
+
+    def __init__(self, http: httpx.Client):
+        self._http = http
+
+    def create(
+        self,
+        dataset_id: str,
+        name: str,
+        filter_sql: str,
+        description: str | None = None,
+        role_mask: str | None = None,
+    ) -> dict:
+        """Create a subset from a DuckDB boolean predicate over the dataset
+        (e.g. "text_type <> 'ai_edited'"). Returns the subset incl. matched count."""
+        body: dict = {"name": name, "filter_sql": filter_sql}
+        if description is not None:
+            body["description"] = description
+        if role_mask is not None:
+            body["role_mask"] = role_mask
+        r = self._http.post(f"/v1/datasets/{dataset_id}/subsets", json=body)
+        r.raise_for_status()
+        return r.json()
+
+    def list(self, dataset_id: str) -> list[dict]:
+        """List subsets defined on a dataset."""
+        r = self._http.get(f"/v1/datasets/{dataset_id}/subsets")
+        r.raise_for_status()
+        return r.json()["subsets"]
+
+    def filterables(self, dataset_id: str) -> list[dict]:
+        """List dataset columns + low-cardinality distinct values (predicate aid)."""
+        r = self._http.get(f"/v1/datasets/{dataset_id}/filterables")
+        r.raise_for_status()
+        return r.json()["filterables"]

gutenberg/models.py

@@ -0,0 +1,202 @@
+"""Response models for the Gutenberg SDK."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class feature(BaseModel):
+    id: int
+    value: float
+
+
+class token_activations(BaseModel):
+    pos: int
+    token: str
+    features: list[feature]
+
+
+class activation_response(BaseModel):
+    tokens: list[token_activations]
+    model_id: str
+    sae_id: str
+    token_count: int
+
+
+class interpret_response(BaseModel):
+    label: str
+    explanation: str
+
+
+class dataset_info(BaseModel):
+    dataset_id: str
+    name: str | None = None
+    description: str | None = None
+    sample_count: int | None = None
+    size_bytes: int | None = None
+    created_at: str | None = None
+
+
+class job_info(BaseModel):
+    job_id: str
+    status: str
+    model_id: str | None = None
+    sae_id: str | None = None
+    top_k: int | None = None
+    window_size: int | None = None
+    activations_path: str | None = None
+    error: str | None = None
+    rows_total: int | None = None
+    rows_processed: int | None = None
+    created_at: str | None = None
+    completed_at: str | None = None
+
+
+class sae_summary(BaseModel):
+    sae_id: str
+    hook_layer: int
+    d_sae: int
+    l0: int
+    max_window_size: int
+    is_default: bool = False
+
+
+class sae_info(BaseModel):
+    """Flat SAE descriptor returned by `client.saes()` — includes `model_id`.
+
+    `sae_summary` (nested under `model_info.available_saes`) omits `model_id`
+    since it's implicit from the parent.
+    """
+    model_id: str
+    sae_id: str
+    hook_layer: int
+    d_sae: int
+    l0: int
+    max_window_size: int
+    is_default: bool = False
+
+
+class model_info(BaseModel):
+    model_id: str
+    vram_gb: int
+    # Back-compat with pre-multi-SAE callers; populated from the model's
+    # default SAE.
+    sae_release: str | None = None
+    sae_id: str | None = None
+    hook_layer: int | None = None
+    max_window_size: int | None = None
+    default_sae_id: str | None = None
+    available_saes: list[sae_summary] = []
+
+
+class experiment_info(BaseModel):
+    experiment_id: str
+    status: str
+    name: str | None = None
+    target_column: str | None = None
+    scoring_method: str | None = None
+    summary: str | None = None
+    error: str | None = None
+    created_at: str | None = None
+
+
+class aggregation_info(BaseModel):
+    aggregation_id: str
+    job_id: str
+    status: str
+    role_mask: str | None = None
+    tier: str | None = None
+    strategy: str | None = None
+    trigger: str | None = None
+    output_prefix: str | None = None
+    error: str | None = None
+    progress: dict | None = None
+    created_at: str | None = None
+    completed_at: str | None = None
+
+
+class feature_score(BaseModel):
+    feature_id: int
+    score: float
+    p_value: float
+    rank: int
+    n_samples: int
+    explanation: str | None = None
+
+
+class feature_example(BaseModel):
+    feature_id: int
+    sample_id: str
+    tokens: list[str]
+    values: list[float]
+    # pick-semantics v2: which pool the window came from
+    # ('strongest' | 'stratified' | 'random' | legacy 'max'), and the window's
+    # anchor — (sample_id, anchor_token_pos) is the identity to dedupe on when
+    # drawing across pools. None on v1 artifacts / fallback windows.
+    pick_class: str | None = None
+    anchor_token_pos: int | None = None
+
+
+class autointerp_run_info(BaseModel):
+    id: str
+    dataset_id: str | None = None
+    sae_id: str | None = None
+    name: str | None = None
+    status: str
+    config: dict | None = None
+    error: str | None = None
+    n_features: int | None = None
+    n_features_completed: int | None = None
+    total_cost_usd: float | None = None
+    is_default: bool | None = None
+    created_at: str | None = None
+    completed_at: str | None = None
+
+
+class meta_autointerp_run_info(BaseModel):
+    id: str
+    dataset_id: str | None = None
+    sae_id: str | None = None
+    experiment_id: str
+    autointerp_run_id: str | None = None
+    name: str | None = None
+    interest: str
+    config: dict | None = None
+    status: str
+    stage: str | None = None
+    progress: dict | None = None
+    report_markdown: str | None = None
+    report_data: dict | None = None
+    total_tokens_in: int | None = None
+    total_tokens_out: int | None = None
+    total_cost_usd: float | None = None
+    modal_call_id: str | None = None
+    error: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    completed_at: str | None = None
+
+
+class dataset_phenomenon(BaseModel):
+    id: str
+    run_id: str
+    dataset_id: str
+    sae_id: str
+    node_id: str
+    name: str
+    description: str
+    trend_direction: str
+    interest_relevance: int
+    candidate_feature_ids: list[int]
+    rubric_text: str
+    rubric_version: int
+    stats: dict
+    trend: dict
+    evidence: list[dict]
+    created_at: str | None = None
+
+
+class meta_autointerp_report(BaseModel):
+    run_id: str
+    report_markdown: str | None = None
+    report_data: dict | None = None

gutenberg_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: gutenberg-sdk
+Version: 0.1.0
+Summary: Python SDK for the Gutenberg SAE Activation API
+Project-URL: Homepage, https://gutenberg.ai
+Project-URL: Console, https://console.gutenberg.ai
+Project-URL: Documentation, https://console.gutenberg.ai/d/docs
+Project-URL: Repository, https://github.com/gutenbergpbc/code
+Author: Gutenberg PBC
+License: MIT
+License-File: LICENSE
+Keywords: activations,interpretability,llm,mechanistic-interpretability,observability,sae
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tqdm>=4.66
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Requires-Dist: pyarrow>=14; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# gutenberg-sdk
+
+Python SDK for the **Gutenberg** SAE activation API — interpretability-based
+observability for language models. Upload text, read it through a sparse
+autoencoder (SAE) feature dictionary, and find the features that separate any
+two classes of documents.
+
+- **Docs:** https://console.gutenberg.ai/d/docs
+- **Console:** https://console.gutenberg.ai
+- **Get an API key:** https://console.gutenberg.ai/d/keys
+
+## Install
+
+```bash
+uv add gutenberg-sdk          # or: pip install gutenberg-sdk
+```
+
+The distribution is `gutenberg-sdk`; the import is `gutenberg`:
+
+```python
+from gutenberg import gutenberg
+```
+
+Optional `pandas` extra (for `load_activations_df` and parquet helpers):
+
+```bash
+uv add "gutenberg-sdk[pandas]"
+```
+
+## Quickstart
+
+```python
+from gutenberg import gutenberg
+
+client = gutenberg(api_key="gtn_...")   # or set GUTENBERG_API_KEY
+
+# 1. upload a parquet dataset (text + a binary target column)
+dataset = client.datasets.upload("examples/simple_binary_features_extraction_100.parquet")
+
+# 2. launch hosted SAE feature extraction
+job = client.jobs.create(
+    dataset_id=dataset.dataset_id,
+    model_id="google/gemma-3-27b-it",
+    sae_id="layer_31_width_262k_l0_medium",
+)
+job = client.jobs.wait(job.job_id)
+
+# 3. score every feature against the target with AUROC
+exp = client.experiments.create(
+    job_id=job.job_id,
+    target_column="is_ai",
+    target_column_type="binary",
+    positive_value="1",
+    scoring_method="auroc",
+)
+exp = client.experiments.wait(exp.experiment_id)
+
+# 4. read back ranked features and token-level examples
+for feature in client.experiments.features(exp.experiment_id)[:10]:
+    print(feature.rank, feature.feature_id, feature.score)
+```
+
+The full runnable script lives in
+[`examples/simple_binary_features_extraction.py`](examples/simple_binary_features_extraction.py),
+with a companion 100-row parquet. On production the whole flow runs in a couple
+of minutes. See [`docs/getting-started.md`](docs/getting-started.md) for the
+walkthrough, SAE selection guidance, and how token examples are served.
+
+> The bundled example is a **curated showcase**, not a benchmark — its 50 AI
+> passages were picked to exhibit a handful of recognizable AI-writing features,
+> so those features separate the two classes near-perfectly there. Run it on
+> your own data to see a realistic ranking.
+
+## API surface
+
+A single `gutenberg(...)` client with namespaced resources: `datasets`,
+`jobs`, `experiments`, `aggregations`, `autointerp`, `meta_autointerp`,
+`subsets`, plus the sync helpers `activations()`, `interpret()`, `models()`,
+and `saes()`.
+
+## License
+
+MIT

gutenberg_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+gutenberg/__init__.py,sha256=ePMhRc35gcVWvzXXN1qfsX7uRTYbd6xYUY-0SEIvaHc,300
+gutenberg/client.py,sha256=Ac9hF6Gm9iZlDFsEV93nBH1Dy-b84yW0fPPLgqSCbSs,24701
+gutenberg/models.py,sha256=i9BR3QgnsC5i1W3WN6_Mee3-zoNzFaayvAZiSnhK-As,4945
+gutenberg_sdk-0.1.0.dist-info/METADATA,sha256=vzRkWNEughQGZUUkA_Oh69Sxyacfe7DEAHfXd7Xat3c,3950
+gutenberg_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gutenberg_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=vrlyLJVXcsI3eM10HkMDoUZ3Q628-SOvCZtDGbogI34,1070
+gutenberg_sdk-0.1.0.dist-info/RECORD,,

gutenberg_sdk-0.1.0.dist-info/WHEEL

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

gutenberg_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gutenberg PBC
+
+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.