predictabl 0.1.0__py3-none-any.whl

predictabl/errors.py

@@ -0,0 +1,61 @@
+"""Errors raised by the Predictabl client.
+
+Every error carries the server's machine `code` (when it sent one) and a
+message meant for a person: the API phrases refusals as "what happened and
+what to do", and these classes pass that through untouched.
+"""
+
+from __future__ import annotations
+
+
+class PredictablError(Exception):
+    """Base class for everything this package raises."""
+
+    def __init__(
+        self, message: str, *, code: str | None = None, status: int | None = None
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message}" if self.code else self.message
+
+
+class AuthenticationError(PredictablError):
+    """The API key is missing, wrong or revoked (HTTP 401)."""
+
+
+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."""
+
+
+class NotFound(PredictablError):
+    """No such object for this account (HTTP 404). Someone else's objects
+    look exactly like missing ones, by design."""
+
+
+class LimitReached(PredictablError):
+    """A free-plan allowance on Predictabl's AI key is used up (HTTP 402).
+    The message says how to continue (your own AI key, or an upgrade)."""
+
+
+class InvalidRequest(PredictablError):
+    """The request was understood but refused (HTTP 4xx), e.g. a model that
+    needs rows was asked to score without them."""
+
+
+class BuildFailed(PredictablError):
+    """A step of building a model (reading the data, finding the question,
+    planning, training) ended in failure. `suggestions` lists the server's
+    recovery options when it gave any."""
+
+    def __init__(self, message: str, *, code: str | None = None, suggestions=None):
+        super().__init__(message, code=code)
+        self.suggestions = list(suggestions or [])
+
+
+class ApiError(PredictablError):
+    """Anything else the server answered with an error."""

predictabl/mcp.py

@@ -0,0 +1,262 @@
+"""Predictabl as an MCP server, so an AI agent (Claude Code, Claude Desktop, any
+MCP client) can discover your models and score with them.
+
+    claude mcp add predictabl --env PREDICTABL_API_KEY=pk_... -- \
+        uvx --from "predictabl[mcp]" predictabl mcp
+
+It is a thin layer over the same client as the Python API: every tool is one
+or two API calls, so what an agent sees is exactly what your code would get,
+and a token reaches only its owner's models. The tools read and score; they
+never upload or train.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from .client import Client
+
+INSTRUCTIONS = (
+    "Predictabl hosts this user's trained prediction models. Start with "
+    "list_models, check get_model before relying on a model, then use predict "
+    "for anything about what happens next. Quote `meaning` with numbers so the "
+    "user knows what a score is, and state `as_of` for forecasts."
+)
+
+
+def _icons():
+    try:
+        from mcp.types import Icon
+
+        raw = (Path(__file__).parent / "assets" / "logo-128.png").read_bytes()
+        uri = "data:image/png;base64," + base64.b64encode(raw).decode()
+        return [Icon(src=uri, mimeType="image/png", sizes=["128x128"])]
+    except Exception:  # noqa: BLE001 - branding must never block startup
+        return None
+
+
+def _server_class():
+    """mcp 2.x calls the high-level server MCPServer; 1.x called it FastMCP.
+    Same decorator API for what this module uses (tool(), run())."""
+    try:
+        from mcp.server.mcpserver import MCPServer
+
+        return MCPServer
+    except ImportError:
+        pass
+    try:
+        from mcp.server.fastmcp import FastMCP
+
+        return FastMCP
+    except ImportError as exc:  # pragma: no cover - exercised by users only
+        raise SystemExit(
+            "The MCP server needs the `mcp` extra: pip install 'predictabl[mcp]'"
+        ) from exc
+
+
+def build_server(client: Client):
+    """The FastMCP server with every tool bound to `client`."""
+    Server = _server_class()
+    t = client._t
+    try:
+        mcp = Server("predictabl", instructions=INSTRUCTIONS, icons=_icons())
+    except TypeError:  # an mcp release without server icons
+        mcp = Server("predictabl", instructions=INSTRUCTIONS)
+
+    @mcp.tool()
+    def list_models(limit: int = 50) -> list[dict]:
+        """List trained models (successful training runs), newest first. Each
+        entry is one model you can inspect or score with; use its `id` with the
+        other tools. Returns: id, predicting (what it predicts), connection,
+        engine, headline metric (+ value), starred, started_at."""
+        out = []
+        for r in t.get("/runs", limit=max(limit * 2, 50)) or []:
+            if r.get("state") != "SUCCEEDED":
+                continue
+            hm = r.get("headline_metric") or {}
+            out.append(
+                {
+                    "id": r["id"],
+                    "predicting": r.get("opportunity_title"),
+                    "connection": r.get("connection_name"),
+                    "engine": r.get("engine_used") or r.get("engine_requested"),
+                    "metric": hm.get("name"),
+                    "metric_value": hm.get("value"),
+                    "starred": bool(r.get("starred")),
+                    "started_at": r.get("started_at"),
+                }
+            )
+            if len(out) >= limit:
+                break
+        return out
+
+    @mcp.tool()
+    def get_model(run_id: str) -> dict:
+        """Detailed card for one model: what it predicts and what its number
+        MEANS, how it picks what to score (`kind`: forecast | event | flat),
+        the winning engine and its tested metric, rows trained/tested and the
+        top features. Check this before quoting a model's predictions."""
+        return client.model(run_id).report()
+
+    @mcp.tool()
+    def get_forecast(run_id: str, limit: int = 100) -> dict:
+        """The forecasts this model produced AT TRAINING TIME: one prediction
+        per entity at the most recent training cutoff (a validated backtest
+        window, usually in the past). Returns as_of, total count and up to
+        `limit` items. For the genuine future ("next 7 days"), use `predict`."""
+        fc = t.get(f"/runs/{run_id}/forecasts")
+        if not fc:
+            raise RuntimeError(
+                f"no forecasts for run {run_id} (not a forecasting model?)"
+            )
+        items = (fc.get("items") or [])[:limit]
+        return {
+            "as_of": fc.get("score_at"),
+            "count": fc.get("count"),
+            "showing": len(items),
+            "items": items,
+        }
+
+    @mcp.tool()
+    def top_risks(run_id: str, n: int = 10, order: str = "desc") -> dict:
+        """The N entities a CLASSIFIER scored highest (or lowest) on its
+        held-out test: "the top 10 customers at risk of churn". Each item has
+        `score` and `actual` (the held-out truth), so you can see whether the
+        top of the ranking was right. For forecasting models use
+        top_forecasts."""
+        return t.get(f"/runs/{run_id}/top-scored", top=n, order=order)
+
+    @mcp.tool()
+    def top_forecasts(run_id: str, n: int = 10, order: str = "desc") -> dict:
+        """The top (or bottom) N entities by predicted value, ranked
+        server-side across the ENTIRE roster: exact "which store is highest".
+        `order`: "desc" (default) or "asc". Forecasting models only."""
+        fc = t.get(f"/runs/{run_id}/forecasts", top=n, order=order)
+        if not fc:
+            raise RuntimeError(
+                f"no forecasts to rank for run {run_id}: only per-step forecasting "
+                "models have them. For a classifier use top_risks."
+            )
+        return fc
+
+    @mcp.tool()
+    def get_backtest(run_id: str, entity: str | None = None) -> dict:
+        """A forecasting model's held-out backtest for one entity: predicted vs
+        ACTUAL over the horizon, on data it did not train on. Omit `entity` for
+        the default one. Use it as evidence the model works."""
+        meta = t.get(f"/runs/{run_id}/forecast/meta")
+        if not meta:
+            raise RuntimeError(
+                f"no backtest panel for run {run_id} (not a per-step forecast?)"
+            )
+        ent = entity or meta.get("default_entity")
+        series = t.get(f"/runs/{run_id}/forecast", entity=ent) if ent else None
+        points = []
+        for p in (series or {}).get("points", []):
+            actual = (
+                p.get("actual_bt")
+                if p.get("actual_bt") is not None
+                else p.get("actual_hist")
+            )
+            if p.get("pred_bt") is None and actual is None:
+                continue
+            points.append(
+                {"date": p.get("date"), "actual": actual, "predicted": p.get("pred_bt")}
+            )
+        return {
+            "model": run_id,
+            "entity": ent,
+            "cadence": meta.get("cadence"),
+            "horizon": meta.get("horizon"),
+            "origin_date": (series or {}).get("origin_date"),
+            "points": points,
+        }
+
+    @mcp.tool()
+    def predict(
+        run_id: str,
+        since_days: int | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        as_of: str | None = None,
+        filters: list[dict] | None = None,
+        include: list[str] | None = None,
+        top: int = 20,
+        entity_contains: str | None = None,
+        calibrated: bool = False,
+    ) -> dict:
+        """Score with a trained model ON FRESH DATA: features are rebuilt from
+        the data as of now, by the model itself. THE tool for "what happens
+        next".
+
+        - Forecast models: project from the latest data (or `as_of`,
+          YYYY-MM-DD). `entity_id` is `entity·cutoff·step`; step 1 is the
+          first future period. The response's `as_of` is the date forecast
+          FROM; say it, so stale data is visible.
+        - Event/risk models: score rows dated TODAY by default; widen with
+          `since_days`, or pick a window with `date_from`/`date_to`. If nothing
+          matched, the response has a `note` with the newest date in the data.
+        - Flat models (no time axis) cannot be scored this way: use
+          predict_rows with the records.
+
+        `filters`: [{"column","op","value"}], op eq|ne|in|contains|gt|gte|lt|lte,
+        on the model's table or a table it joins (e.g. city). `include`: extra
+        columns to return per prediction (in `context`). `entity_contains`:
+        only entities whose id contains this text. Results are ranked by value
+        and capped at `top`. Always read `meaning`: it says what the number is.
+        For MULTICLASS models read `predicted_class`, not `prediction`."""
+        body: dict = {"top": max(1, min(int(top), 2000)), "calibrated": calibrated}
+        if since_days is not None:
+            body["since_days"] = since_days
+        if date_from:
+            body["since"] = date_from
+        if date_to:
+            body["until"] = date_to
+        if as_of:
+            body["cutoff"] = as_of
+        if filters:
+            body["filters"] = filters
+        if include:
+            body["include"] = include
+        if entity_contains:
+            body["entity_contains"] = entity_contains
+        return t.post(f"/runs/{run_id}/predict", json=body)
+
+    @mcp.tool()
+    def predict_rows(run_id: str, rows: list[dict]) -> dict:
+        """Score records you HAND IN: "would a machine with this torque and
+        temperature fail?". Each row is a dict keyed by the model's SOURCE
+        columns (the raw columns of its table), without the outcome. The
+        model's own feature SQL is applied, so there is no train/serve skew.
+
+        Best for flat models (one row in, one prediction). If the response has
+        a `warning`, the model summarises history and only your rows were
+        available: prefer `predict` for those. At most 1000 rows per call."""
+        return t.post(f"/runs/{run_id}/predict-records", json={"rows": rows[:1000]})
+
+    @mcp.tool()
+    def list_connections() -> list[dict]:
+        """List the datasets (uploads and connected databases) on this account."""
+        return [
+            {
+                "id": c["id"],
+                "name": c.get("name"),
+                "kind": c.get("kind"),
+                "tables": c.get("table_count"),
+            }
+            for c in t.get("/connections") or []
+        ]
+
+    @mcp.tool()
+    def account() -> dict:
+        """The account behind this key: email, plan, builds used and left."""
+        return client.account()
+
+    return mcp
+
+
+def serve(base_url: str | None = None) -> None:
+    """Run over stdio until the client disconnects."""
+    client = Client(base_url=base_url, client_tag="mcp")
+    build_server(client).run()

predictabl-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: predictabl
+Version: 0.1.0
+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
+Project-URL: Source, https://github.com/predictabl/predictabl-python
+Project-URL: Issues, https://github.com/predictabl/predictabl-python/issues
+Author: Predictabl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automl,forecasting,machine learning,mcp,prediction,tabular
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# Predictabl Python API library
+
+Turn a question about your data into a trained, tested model, then score with
+it. Predictabl reads your tables, plans the features in SQL you can review,
+checks for leakage, trains and tests the model, and serves predictions.
+
+**Documentation: [predictabl.tech/docs](https://predictabl.tech/docs/)** · for AI
+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.
+
+```bash
+pip install predictabl
+```
+
+```python
+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?")
+```
+
+```
+✓ Uploading      orders.csv · 18.2 MB
+✓ Reading data   1 table
+✓ Understanding  Predict whether an order arrives after its promised date
+✓ Planning       31 features · 2 excluded
+✓ Building data
+✓ Training       lightgbm: kept 840 trees
+✓ Final model    auc 0.8712
+```
+
+```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
+```
+
+Everything you build from code also appears in the web app, labelled with the
+token that created it.
+
+## Get an API key
+
+In the web app: **Settings → API access & usage → New 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.
+
+A token only ever reaches its owner's data and models. It cannot create other
+tokens. Revoking it stops it immediately.
+
+## Review the plan before training
+
+`data.predict(question)` goes straight from question to model. To look first:
+
+```python
+plan = data.plan("Which customers will stop buying in the next 30 days?")
+print(plan)                     # target, features, and what was excluded and why
+plan = plan.refine("Don't use the support_tier column")
+model = plan.train()            # or plan.train(preset="fast_preview") for a 15-second check
+```
+
+## Scoring
+
+How a model picks what to score depends on its kind (`model.kind`):
+
+| kind | what `model.predict()` does | typical model |
+|---|---|---|
+| `flat` | needs `rows=`: one record in, one prediction out | survey, sensor reading, form |
+| `event` | scores rows dated **today** in the data it trained on; pick a window with `since=`/`until=` or `since_days=` | orders, sign-ups, bookings |
+| `forecast` | projects from the latest data, or `as_of="2026-10-01"` | sales per store, demand per item |
+
+```python
+preds = model.predict(rows=df)                     # your records
+preds = model.predict(since_days=7)                # event model: last week's rows
+preds = model.predict(ids=["store_12"], limit=48)  # one entity
+preds = model.predict(filters=[{"column": "city", "op": "eq", "value": "Milano"}],
+                      include=["city"])
+
+preds.meaning    # e.g. "probability that customer churned"
+preds.as_of      # forecasts: the date they are made from
+preds.note       # e.g. why nothing matched, and the newest date in the data
+preds.to_pandas()
+```
+
+A record you score can still contain its outcome column (e.g. a row copied from
+the training file): it never reaches the model, and comes back as `actual` so
+the call doubles as a check.
+
+## Plans and limits
+
+On Predictabl's AI key a free account has a fixed number of model builds (one
+build = one question taken to a model; refining and retraining it is included).
+With your own OpenAI or Anthropic key (Settings → AI provider) builds are not
+limited. `pb.account()` shows what is left; running out raises
+`predictabl.LimitReached` with what to do next.
+
+## Use it from an AI agent (MCP)
+
+```bash
+claude mcp add predictabl --env PREDICTABL_API_KEY=pk_... -- uvx --from "predictabl[mcp]" predictabl mcp
+```
+
+Then ask: *"Which of my customers are most likely to churn this month, and how
+good is that model?"* The tools list your models, show how good they are, and
+score them. They never upload or train.
+
+## Configuration
+
+| | |
+|---|---|
+| `PREDICTABL_API_KEY` | your token (`pk_...`) |
+| `PREDICTABL_BASE_URL` | default `https://app.predictabl.tech/pub/v1`; a local instance is `http://localhost:8000/api/v1` |
+
+For several accounts or instances, use clients directly:
+`pb.Client(api_key=..., base_url=...)` has the same methods.
+
+## Errors
+
+All errors derive from `predictabl.PredictablError` and carry the server's
+`code` and a message that says what to do: `AuthenticationError` (bad or
+revoked key), `PermissionDenied` (the key's scope does not allow it),
+`NotFound`, `LimitReached`, `InvalidRequest`, `BuildFailed` (with the server's
+recovery `suggestions`).
+
+## License
+
+MIT

predictabl-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+predictabl/__init__.py,sha256=0KwF9vUdg9Q_8tRgkyJDHBLHYkKmTxr6FWVa0sPn5Lc,2375
+predictabl/__main__.py,sha256=W1g9RAwxgzCz5ByVfENg7n9_xVFeuYSUDkWLLeHIGtA,1524
+predictabl/_http.py,sha256=MYfNAc53Jc4N48-4zn_KU4uXKcdozY-tV-bgi5nk1Q8,4471
+predictabl/_progress.py,sha256=zsf5PJ-nViCYf_4EOU2ZZVAAoEKkX4pGw7US3zOfSrU,3458
+predictabl/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+predictabl/client.py,sha256=RDuGRJK_p2S1DHAw2DlqEcoIMgX4Jy9y356dIC4ge-Q,29705
+predictabl/errors.py,sha256=Eus12DOTHZq-8NBmfNNVF-767TZRGBpF_0xYffxebKM,2036
+predictabl/mcp.py,sha256=KMiiImJjdumu5rNKE89pMSAtZXVLgBBTOwxMNow9lVc,10792
+predictabl/assets/logo-128.png,sha256=RXc2Zci9riDv6jz0zr4UnFIGoVYCbeSc3sztl_hHtQU,7771
+predictabl-0.1.0.dist-info/METADATA,sha256=1x1uRhn2iJQsUgM6uVniy9ku5G4317TpyPACqUP-QxU,6111
+predictabl-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+predictabl-0.1.0.dist-info/entry_points.txt,sha256=9QXysFU2nEkahX_xv1xnneLmUpsVao3dnhLHsifkWw8,56
+predictabl-0.1.0.dist-info/licenses/LICENSE,sha256=EA5vRqAE-hKyxexJiBs-1jV8WWSfAVTFg3SMqgb2eK0,1067
+predictabl-0.1.0.dist-info/RECORD,,

predictabl-0.1.0.dist-info/WHEEL

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

predictabl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+predictabl = predictabl.__main__:main

predictabl-0.1.0.dist-info/licenses/LICENSE

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