predictabl 0.1.0__tar.gz → 0.1.1__tar.gz

{predictabl-0.1.0 → predictabl-0.1.1}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.1
+
+- `connect()` replaces `upload()`: pass files or a DataFrame as before, or a
+  Postgres address (`"postgresql://user:pw@host/db"`), which Predictabl reads
+  in place, read-only. The password never appears in progress or errors.
+  `upload()` still works and warns; it will be removed in a later version.
+- Predictions print readably: what the number means, then the numbers.
+  One prediction prints on one line, e.g.
+  `Probability that customer churned: 0.82`.
+- README: churn example with its output; token access is *Full access* or
+  *Predictions only*.
+
 ## 0.1.0
 
 First release.

{predictabl-0.1.0 → predictabl-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: predictabl
-Version: 0.1.0
+Version: 0.1.1
 Summary: Predictabl from Python: turn a question about your data into a trained model, then score it.
 Project-URL: Homepage, https://predictabl.tech
 Project-URL: Documentation, https://github.com/predictabl/predictabl-python#readme
@@ -35,9 +35,7 @@ checks for leakage, trains and tests the model, and serves predictions.
 agents, the whole documentation as one Markdown file:
 [predictabl.tech/docs/llms-full.txt](https://predictabl.tech/docs/llms-full.txt)
 
-> **Status: alpha (0.1).** Building models from code needs a *Build and
-> score* token, which the hosted app starts offering with its next release.
-> Scoring tokens work today.
+> **Status: alpha (0.1).** The API may still change between minor versions.
 
 ```bash
 pip install predictabl
@@ -48,14 +46,14 @@ import predictabl as pb
 
 pb.login("pk_...")          # or set PREDICTABL_API_KEY
 
-data  = pb.upload("orders.csv")
-model = data.predict("Will an order arrive late?")
+data = pb.connect("customers.csv")      # a file, a DataFrame, or a database
+churn_model = data.predict("Which customers will churn?")
 ```
 
 ```
-✓ Uploading      orders.csv · 18.2 MB
+✓ Uploading      customers.csv · 18.2 MB
 ✓ Reading data   1 table
-✓ Understanding  Predict whether an order arrives after its promised date
+✓ Understanding  Predict which customers will churn
 ✓ Planning       31 features · 2 excluded
 ✓ Building data
 ✓ Training       lightgbm: kept 840 trees
@@ -63,9 +61,23 @@ model = data.predict("Will an order arrive late?")
 ```
 
 ```python
-model.report()                       # what it predicts, tested score, top features
-model.predict(rows=new_orders)       # score your own records (DataFrame or dicts)
-model.url                            # the same model in the web app
+churn_model.predict(customer)        # one customer (a dict), a list, or a DataFrame
+```
+
+```text
+Probability that customer churned: 0.82
+```
+
+```python
+churn_model.report()                 # what it predicts, tested score, top features
+churn_model.url                      # the same model in the web app
+```
+
+Your data can be files, a pandas DataFrame, or a Postgres database, which
+Predictabl reads in place, read-only:
+
+```python
+data = pb.connect("postgresql://readonly:pw@db.acme.com/sales")
 ```
 
 Everything you build from code also appears in the web app, labelled with the
@@ -73,10 +85,12 @@ token that created it.
 
 ## Get an API key
 
-In the web app: **Settings → API access & usage → New token**.
+In the web app: **Settings → API & MCP → Create token**.
 
-- **Build and score** can upload data, plan and train models, and score them.
-- **Score models only** can score your trained models and nothing else.
+- By default a token has **full access**: it can do from code what you do in the
+  web app (upload, ask, plan, train and get predictions).
+- Tick **Predictions only** for a read-only token: it can get predictions from
+  your trained models and change nothing.
 
 A token only ever reaches its owner's data and models. It cannot create other
 tokens. Revoking it stops it immediately.

{predictabl-0.1.0 → predictabl-0.1.1}/README.md

@@ -8,9 +8,7 @@ checks for leakage, trains and tests the model, and serves predictions.
 agents, the whole documentation as one Markdown file:
 [predictabl.tech/docs/llms-full.txt](https://predictabl.tech/docs/llms-full.txt)
 
-> **Status: alpha (0.1).** Building models from code needs a *Build and
-> score* token, which the hosted app starts offering with its next release.
-> Scoring tokens work today.
+> **Status: alpha (0.1).** The API may still change between minor versions.
 
 ```bash
 pip install predictabl
@@ -21,14 +19,14 @@ import predictabl as pb
 
 pb.login("pk_...")          # or set PREDICTABL_API_KEY
 
-data  = pb.upload("orders.csv")
-model = data.predict("Will an order arrive late?")
+data = pb.connect("customers.csv")      # a file, a DataFrame, or a database
+churn_model = data.predict("Which customers will churn?")
 ```
 
 ```
-✓ Uploading      orders.csv · 18.2 MB
+✓ Uploading      customers.csv · 18.2 MB
 ✓ Reading data   1 table
-✓ Understanding  Predict whether an order arrives after its promised date
+✓ Understanding  Predict which customers will churn
 ✓ Planning       31 features · 2 excluded
 ✓ Building data
 ✓ Training       lightgbm: kept 840 trees
@@ -36,9 +34,23 @@ model = data.predict("Will an order arrive late?")
 ```
 
 ```python
-model.report()                       # what it predicts, tested score, top features
-model.predict(rows=new_orders)       # score your own records (DataFrame or dicts)
-model.url                            # the same model in the web app
+churn_model.predict(customer)        # one customer (a dict), a list, or a DataFrame
+```
+
+```text
+Probability that customer churned: 0.82
+```
+
+```python
+churn_model.report()                 # what it predicts, tested score, top features
+churn_model.url                      # the same model in the web app
+```
+
+Your data can be files, a pandas DataFrame, or a Postgres database, which
+Predictabl reads in place, read-only:
+
+```python
+data = pb.connect("postgresql://readonly:pw@db.acme.com/sales")
 ```
 
 Everything you build from code also appears in the web app, labelled with the
@@ -46,10 +58,12 @@ token that created it.
 
 ## Get an API key
 
-In the web app: **Settings → API access & usage → New token**.
+In the web app: **Settings → API & MCP → Create token**.
 
-- **Build and score** can upload data, plan and train models, and score them.
-- **Score models only** can score your trained models and nothing else.
+- By default a token has **full access**: it can do from code what you do in the
+  web app (upload, ask, plan, train and get predictions).
+- Tick **Predictions only** for a read-only token: it can get predictions from
+  your trained models and change nothing.
 
 A token only ever reaches its owner's data and models. It cannot create other
 tokens. Revoking it stops it immediately.

{predictabl-0.1.0 → predictabl-0.1.1}/src/predictabl/__init__.py

@@ -3,10 +3,9 @@
     import predictabl as pb
 
     pb.login("pk_...")                      # or set PREDICTABL_API_KEY
-    data  = pb.upload("orders.csv")
-    model = data.predict("Will an order arrive late?")
-    model.report()
-    model.predict(rows=new_orders)
+    data = pb.connect("customers.csv")      # files, a DataFrame, or a Postgres address
+    churn_model = data.predict("Which customers will churn?")
+    churn_model.predict(customer)           # Probability that customer churned: 0.82
 
 Module-level functions use one shared client, configured by `login()` or the
 PREDICTABL_API_KEY / PREDICTABL_BASE_URL environment variables. For several
@@ -34,7 +33,7 @@ __all__ = [
     "login",
     "client",
     "account",
-    "upload",
+    "connect",
     "data",
     "datasets",
     "plan",
@@ -81,8 +80,23 @@ def account() -> dict:
     return client().account()
 
 
+def connect(source, name: str | None = None, **kw) -> Data:
+    """Connect a Postgres database (by address) or upload files / a DataFrame.
+    See `Client.connect`."""
+    return client().connect(source, name, **kw)
+
+
 def upload(source, name: str | None = None, **kw) -> Data:
-    return client().upload(source, name, **kw)
+    """Deprecated: renamed to `connect()`."""
+    import warnings
+
+    warnings.warn(
+        "predictabl: upload() is now connect(); upload() will be removed in a "
+        "future version.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return client().connect(source, name, **kw)
 
 
 def data(data_id: str) -> Data:

predictabl-0.1.1/src/predictabl/_version.py

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

{predictabl-0.1.0 → predictabl-0.1.1}/src/predictabl/client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import io
 import os
 import time
+import warnings
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from datetime import date, datetime
@@ -96,7 +97,7 @@ class Client:
                 return Data._from(self, row)
         raise errors.NotFound(f"No dataset {data_id!r} on this account.")
 
-    def upload(
+    def connect(
         self,
         source: str | Path | Iterable[str | Path] | Any,
         name: str | None = None,
@@ -106,12 +107,38 @@ class Client:
         on_progress: Callback | None = None,
         timeout: float | None = 1800,
     ) -> Data:
-        """Upload CSV, Excel or Parquet files (or a pandas DataFrame) as a new
-        dataset. Several files become several tables Predictabl can join.
+        """Connect data to Predictabl: a database or files.
+
+        * A Postgres address (``"postgresql://user:password@host:5432/db"``):
+          Predictabl reads the database where it is, read-only. Use a
+          read-only user, and make sure the database accepts connections from
+          Predictabl's server.
+        * CSV, Excel or Parquet files, a list of them, or a pandas DataFrame:
+          the files are uploaded to Predictabl. Several files become several
+          tables Predictabl can join.
 
         With `wait` (default) returns once Predictabl has read the tables."""
-        files, label = _files_of(source)
         progress = Progress(quiet=quiet, on_update=on_progress)
+        if isinstance(source, str) and _is_database_url(source):
+            data = self._connect_database(source, name, progress)
+        else:
+            data = self._upload_files(source, name, progress)
+        if wait:
+            data.wait_ready(progress=progress, timeout=timeout)
+        return data
+
+    def upload(self, source, name: str | None = None, **kw) -> Data:
+        """Deprecated: renamed to `connect()`, which also takes databases."""
+        warnings.warn(
+            "predictabl: upload() is now connect(); upload() will be removed in a "
+            "future version.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.connect(source, name, **kw)
+
+    def _upload_files(self, source: Any, name: str | None, progress: Progress) -> Data:
+        files, label = _files_of(source)
         size = sum(len(content) for _, content, _ in files)
         progress.running("Uploading", f"{label} · {_human_bytes(size)}")
         try:
@@ -126,10 +153,26 @@ class Client:
             progress.failed("Uploading")
             raise
         progress.done("Uploading", f"{label} · {_human_bytes(size)}")
-        data = Data._from(self, row)
-        if wait:
-            data.wait_ready(progress=progress, timeout=timeout)
-        return data
+        return Data._from(self, row)
+
+    def _connect_database(self, url: str, name: str | None, progress: Progress) -> Data:
+        label = _safe_db_label(url)  # never shows the password
+        progress.running("Connecting", label)
+        try:
+            row = self._t.post(
+                "/connections",
+                json={
+                    "name": name or label,
+                    "kind": "postgres",
+                    "config": {"dsn": url},
+                },
+            )
+            self._t.post(f"/connections/{row['id']}/introspect")
+        except errors.PredictablError:
+            progress.failed("Connecting", label)
+            raise
+        progress.done("Connecting", label)
+        return Data._from(self, row)
 
     def plan(self, question_id: str) -> Plan:
         """The latest plan of a question (opportunity) planned earlier, e.g.
@@ -727,19 +770,88 @@ class Predictions(list):
         return pd.DataFrame(flat)
 
     def __repr__(self) -> str:
-        head = f"<Predictions {len(self)}"
-        if self.count and self.count > len(self):
-            head += f" of {self.count}"
-        if self.meaning:
-            head += f" · {self.meaning}"
+        # Readable at a glance in a REPL or notebook: what the number means,
+        # then the numbers. One prediction prints on one line.
+        title = _sentence(self.meaning) or "Predictions"
         if self.as_of:
-            head += f" · as of {self.as_of}"
-        return head + ">"
+            title += f" (as of {self.as_of})"
+        if not self:
+            return f"{title}: none" + (f"\n{self.note}" if self.note else "")
+        if len(self) == 1:
+            return f"{title}: {_value_of(self[0])}"
+        shown = self[:10]
+        width = max(len(str(p.get("entity_id", ""))) for p in shown)
+        lines = [title]
+        lines += [
+            f"  {str(p.get('entity_id', '')):<{width}}  {_value_of(p)}" for p in shown
+        ]
+        if len(self) > len(shown):
+            lines.append(f"  … and {len(self) - len(shown):,} more")
+        if self.count > len(self):
+            lines.append(
+                f"  ({len(self):,} of {self.count:,} returned; pass limit= for more)"
+            )
+        return "\n".join(lines)
+
+    __str__ = __repr__
+
+
+def _sentence(text: str | None) -> str:
+    return (text[0].upper() + text[1:]) if text else ""
+
+
+def _value_of(p: Mapping) -> str:
+    """One prediction as text: the class (and its probability) for a
+    classifier that names one, otherwise the number, rounded for reading."""
+    v = p.get("prediction")
+    num = (
+        f"{v:.2f}"
+        if isinstance(v, float) and abs(v) < 1000
+        else (f"{v:,.0f}" if isinstance(v, float) else str(v))
+    )
+    cls = p.get("predicted_class")
+    return f"{cls} ({num})" if cls is not None else num
 
 
 # ============================================================================
 
 
+_DB_SCHEMES = (
+    "postgres://",
+    "postgresql://",
+    "postgresql+psycopg://",
+    "postgresql+psycopg2://",
+)
+
+
+def _is_database_url(source: str) -> bool:
+    """True for a database address. Postgres is supported; other databases
+    raise a clear error instead of being read as a file name."""
+    low = source.strip().lower()
+    if low.startswith(_DB_SCHEMES):
+        return True
+    scheme = low.split("://", 1)[0] if "://" in low else ""
+    if scheme and not scheme.startswith(("http", "file")) and "/" not in scheme:
+        raise errors.InvalidRequest(
+            f"Predictabl connects to Postgres databases ({scheme}:// is not "
+            "supported yet). Export the tables to files and pass those instead."
+        )
+    return False
+
+
+def _safe_db_label(url: str) -> str:
+    """'sales on db.acme.com' from a database address, without credentials."""
+    from urllib.parse import urlsplit
+
+    try:
+        parts = urlsplit(url.strip())
+        db = parts.path.lstrip("/") or "database"
+        host = parts.hostname or "localhost"
+    except ValueError:
+        return "database"
+    return f"{db} on {host}"
+
+
 def _files_of(source: Any) -> tuple[list[tuple[str, bytes, str]], str]:
     """(files, label) for an upload: paths, a list of paths, or a DataFrame."""
     if hasattr(source, "to_csv") and hasattr(source, "columns"):  # DataFrame

{predictabl-0.1.0 → predictabl-0.1.1}/src/predictabl/errors.py

@@ -29,7 +29,7 @@ class AuthenticationError(PredictablError):
 
 class PermissionDenied(PredictablError):
     """The API key is valid but its scope does not allow this (HTTP 403).
-    Scoring-only (`inference`) keys cannot upload, plan or train."""
+    Predictions only keys cannot connect data, plan or train."""
 
 
 class NotFound(PredictablError):

{predictabl-0.1.0 → predictabl-0.1.1}/tests/fake_api.py

@@ -74,6 +74,18 @@ class FakeApi:
                     "kind": "duckdb",
                 }
             )
+        if path == "/connections" and m == "POST":
+            return ok(
+                {
+                    "id": "c1",
+                    "name": body["name"],
+                    "status": "created",
+                    "kind": "postgres",
+                },
+                201,
+            )
+        if path == "/connections/c1/introspect" and m == "POST":
+            return ok({"job": "introspect", "connection_id": "c1"}, 202)
         if path == "/connections" and m == "GET":
             self._conn_polls += 1
             status = (

{predictabl-0.1.0 → predictabl-0.1.1}/tests/test_client.py

@@ -125,33 +125,33 @@ def test_reads_are_retried_on_a_gateway_error_but_writes_are_not(monkeypatch):
 # -------------------------------------------------------------- build flow
 
 
-def test_upload_waits_until_the_data_is_read():
+def test_connect_waits_until_the_data_is_read():
     c, api = make()
-    data = c.upload(_tmp_csv(), quiet=True)
+    data = c.connect(_tmp_csv(), quiet=True)
     assert data.status == "ready" and data.table_count == 1
     method, path, _, headers = api.calls[0]
     assert (method, path) == ("POST", "/connections/from-csv")
     assert headers["content-type"].startswith("multipart/form-data")
 
 
-def test_upload_accepts_a_dataframe():
+def test_connect_accepts_a_dataframe():
     pd = pytest.importorskip("pandas")
     c, api = make()
-    c.upload(pd.DataFrame({"a": [1, 2]}), name="frame", quiet=True)
+    c.connect(pd.DataFrame({"a": [1, 2]}), name="frame", quiet=True)
     assert api.calls[0][1] == "/connections/from-csv"
 
 
-def test_upload_of_a_missing_file_fails_before_any_request():
+def test_connect_of_a_missing_file_fails_before_any_request():
     c, api = make()
     with pytest.raises(errors.InvalidRequest):
-        c.upload("/no/such/file.csv", quiet=True)
+        c.connect("/no/such/file.csv", quiet=True)
     assert api.calls == []
 
 
 def test_question_to_model_in_one_call_with_progress():
     c, api = make()
     updates = []
-    data = c.upload(_tmp_csv(), quiet=True)
+    data = c.connect(_tmp_csv(), quiet=True)
     model = data.predict(
         "Will an order arrive late?", quiet=True, on_progress=updates.append
     )
@@ -171,7 +171,7 @@ def test_an_older_finished_job_is_not_mistaken_for_ours():
     """The first job poll returns an earlier, finished job; the client must
     keep waiting for the job its own request created."""
     c, api = make(FakeApi(older_job_done=True))
-    data = c.upload(_tmp_csv(), quiet=True)
+    data = c.connect(_tmp_csv(), quiet=True)
     plan = data.plan("late?", quiet=True)
     job_polls = [p for (m, p, _, _) in api.calls if p.endswith("/opportunities/job")]
     assert len(job_polls) >= 3
@@ -180,7 +180,7 @@ def test_an_older_finished_job_is_not_mistaken_for_ours():
 
 def test_plan_shows_target_features_and_exclusions():
     c, _ = make()
-    plan = c.upload(_tmp_csv(), quiet=True).plan("late?", quiet=True)
+    plan = c.connect(_tmp_csv(), quiet=True).plan("late?", quiet=True)
     assert plan.features == ["f1", "f3"]  # disabled features are not listed
     text = str(plan)
     assert "Order delivered after promised date" in text
@@ -189,21 +189,21 @@ def test_plan_shows_target_features_and_exclusions():
 
 def test_refine_returns_the_next_version_and_leaves_the_old_one():
     c, _ = make()
-    plan = c.upload(_tmp_csv(), quiet=True).plan("late?", quiet=True)
+    plan = c.connect(_tmp_csv(), quiet=True).plan("late?", quiet=True)
     newer = plan.refine("drop courier", quiet=True)
     assert (plan.version, newer.version) == (1, 2)
 
 
 def test_a_failed_plan_raises_with_the_servers_reason():
     c, _ = make(FakeApi(fail_plan=True, polls_until_spec=1))
-    data = c.upload(_tmp_csv(), quiet=True)
+    data = c.connect(_tmp_csv(), quiet=True)
     with pytest.raises(errors.BuildFailed, match="bad SQL"):
         data.plan("late?", quiet=True)
 
 
 def test_a_failed_run_raises_with_code_and_suggestions():
     c, _ = make(FakeApi(fail_run=True))
-    data = c.upload(_tmp_csv(), quiet=True)
+    data = c.connect(_tmp_csv(), quiet=True)
     with pytest.raises(errors.BuildFailed) as exc:
         data.predict("late?", quiet=True)
     assert exc.value.code == "BUILD_LIMIT_REACHED"
@@ -346,3 +346,71 @@ def _tmp_csv():
     p = Path(tempfile.mkdtemp()) / "orders.csv"
     p.write_text("id,amount,late\n1,10,0\n2,20,1\n")
     return p
+
+
+def test_predictions_print_readably():
+    from predictabl.client import Predictions
+
+    one = Predictions._from(
+        {
+            "meaning": "probability that customer churned",
+            "predictions": [{"entity_id": "0", "prediction": 0.8213}],
+        }
+    )
+    assert repr(one) == "Probability that customer churned: 0.82"
+    many = Predictions._from(
+        {
+            "meaning": "probability that customer churned",
+            "count": 500,
+            "predictions": [
+                {"entity_id": f"C-{i}", "prediction": 0.5} for i in range(12)
+            ],
+        }
+    )
+    text = str(many)
+    assert text.splitlines()[0] == "Probability that customer churned"
+    assert "  C-0  0.50" in text and "C-10" not in text
+    assert "… and 2 more" in text and "12 of 500 returned" in text
+    cls = Predictions._from(
+        {
+            "meaning": "probability of the predicted class (tier)",
+            "predictions": [
+                {"entity_id": "a", "prediction": 0.7, "predicted_class": "gold"}
+            ],
+        }
+    )
+    assert str(cls).endswith(": gold (0.70)")
+    assert list(one) == [{"entity_id": "0", "prediction": 0.8213}]  # still a plain list
+
+
+def test_connect_a_postgres_database_reads_it_in_place(capsys):
+    c, api = make()
+    url = "postgresql://ro_user:s3cret@db.acme.com:5432/sales"
+    updates = []
+    data = c.connect(url, on_progress=updates.append)
+    assert data.status == "ready"
+    posts = [(p, b) for m, p, b, _ in api.calls if m == "POST"]
+    assert posts[0] == (
+        "/connections",
+        {"name": "sales on db.acme.com", "kind": "postgres", "config": {"dsn": url}},
+    )
+    assert posts[1][0] == "/connections/c1/introspect"
+    shown = " ".join(f"{u.step} {u.detail}" for u in updates) + capsys.readouterr().err
+    assert "s3cret" not in shown and "ro_user" not in shown
+    assert "sales on db.acme.com" in shown
+    assert not any(p == "/connections/from-csv" for _, p, _, _ in api.calls)
+
+
+def test_connect_refuses_unsupported_databases_clearly():
+    c, api = make()
+    with pytest.raises(pb.InvalidRequest, match="Postgres"):
+        c.connect("mysql://u:p@host/db", quiet=True)
+    assert api.calls == []
+
+
+def test_upload_still_works_but_warns():
+    c, api = make()
+    with pytest.warns(DeprecationWarning, match="connect"):
+        data = c.upload(_tmp_csv(), quiet=True)
+    assert data.status == "ready"
+    assert "upload" not in pb.__all__ and "connect" in pb.__all__

{predictabl-0.1.0 → predictabl-0.1.1}/tests/test_integration.py

@@ -153,7 +153,7 @@ def test_an_inference_token_scores_but_cannot_build(ids):
     with pb.Client(api_key=key, base_url=URL) as inf:
         assert len(inf.model(ids["flat"]).predict(rows=_airline_rows(2))) == 2
         with pytest.raises(errors.PermissionDenied):
-            inf.upload(_tiny_csv(), quiet=True)
+            inf.connect(_tiny_csv(), quiet=True)
         with pytest.raises(errors.PermissionDenied):
             inf.datasets()
 
@@ -182,11 +182,11 @@ def test_a_bad_key_is_an_authentication_error():
 # ------------------------------------------------------------ build path
 
 
-def test_upload_creates_a_dataset_marked_with_the_token(c):
+def test_connect_creates_a_dataset_marked_with_the_token(c):
     """Introspection needs the LLM; on a server without a key it fails, and
     the SDK must say so instead of hanging."""
     try:
-        data = c.upload(_tiny_csv(), name="sdk-integration", quiet=True, timeout=300)
+        data = c.connect(_tiny_csv(), name="sdk-integration", quiet=True, timeout=300)
         assert data.status == "ready"
     except errors.BuildFailed as exc:
         assert "Could not read this dataset" in str(exc)

predictabl-0.1.0/src/predictabl/_version.py

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