predictabl 0.1.0__tar.gz

predictabl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run pytest -q
+      - run: uv build

predictabl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+# Publishes to PyPI when a GitHub release is published (tag vX.Y.Z).
+# Uses PyPI trusted publishing: no API token is stored here. Configure it once
+# on PyPI (project -> Publishing -> add GitHub publisher: this repo,
+# workflow publish.yml, environment pypi).
+name: Publish
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync && uv run pytest -q
+      - run: uv build
+      - name: Version matches the tag
+        run: |
+          v=$(python -c "import re;print(re.search(r'\"(.+)\"', open('src/predictabl/_version.py').read()).group(1))")
+          test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v$v"; exit 1; }
+      - uses: pypa/gh-action-pypi-publish@release/v1

predictabl-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/

predictabl-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `upload()` files or a DataFrame; `Data.predict(question)` builds a tested
+  model in one call with step-by-step progress; `Data.plan()`,
+  `Plan.refine()`, `Plan.train()` to review first; `pb.plan()` to retrain an
+  existing plan.
+- `Model.predict()` scores handed-in rows (batched) or the model's own data
+  (`ids`, `since`/`until`, `since_days`, `as_of`, `limit`, `filters`,
+  `include`). Predictions say what they mean and, for forecasts, the date
+  they are made from.
+- Typed errors with the server's code and message.
+- `predictabl mcp`: an MCP server for AI agents over the same client.

predictabl-0.1.0/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.

predictabl-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,133 @@
+# 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/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "predictabl"
+dynamic = ["version"]
+description = "Predictabl from Python: turn a question about your data into a trained model, then score it."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Predictabl" }]
+keywords = ["machine learning", "prediction", "forecasting", "automl", "tabular", "mcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+mcp = ["mcp>=1.2"]
+
+[project.urls]
+Homepage = "https://predictabl.tech"
+Documentation = "https://github.com/predictabl/predictabl-python#readme"
+Source = "https://github.com/predictabl/predictabl-python"
+Issues = "https://github.com/predictabl/predictabl-python/issues"
+
+[project.scripts]
+predictabl = "predictabl.__main__:main"
+
+[tool.hatch.version]
+path = "src/predictabl/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/predictabl"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pandas>=2.0", "mcp>=1.2", "ruff>=0.7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: needs a running Predictabl backend (PREDICTABL_TEST_URL)"]
+addopts = "-m 'not integration'"
+
+[tool.ruff]
+line-length = 90
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

predictabl-0.1.0/src/predictabl/__init__.py

@@ -0,0 +1,105 @@
+"""Predictabl from 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?")
+    model.report()
+    model.predict(rows=new_orders)
+
+Module-level functions use one shared client, configured by `login()` or the
+PREDICTABL_API_KEY / PREDICTABL_BASE_URL environment variables. For several
+accounts or instances at once, create `predictabl.Client` objects instead.
+"""
+
+from __future__ import annotations
+
+from ._progress import Update
+from ._version import __version__
+from .client import Client, Data, Model, Plan, Predictions
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    BuildFailed,
+    InvalidRequest,
+    LimitReached,
+    NotFound,
+    PermissionDenied,
+    PredictablError,
+)
+
+__all__ = [
+    "__version__",
+    "login",
+    "client",
+    "account",
+    "upload",
+    "data",
+    "datasets",
+    "plan",
+    "model",
+    "models",
+    "Client",
+    "Data",
+    "Plan",
+    "Model",
+    "Predictions",
+    "Update",
+    "PredictablError",
+    "AuthenticationError",
+    "PermissionDenied",
+    "NotFound",
+    "LimitReached",
+    "InvalidRequest",
+    "BuildFailed",
+    "ApiError",
+]
+
+_default: Client | None = None
+
+
+def login(api_key: str | None = None, base_url: str | None = None, **kw) -> Client:
+    """Configure the shared client. Without arguments, reads
+    PREDICTABL_API_KEY (and PREDICTABL_BASE_URL) from the environment."""
+    global _default
+    if _default is not None:
+        _default.close()
+    _default = Client(api_key=api_key, base_url=base_url, **kw)
+    return _default
+
+
+def client() -> Client:
+    """The shared client, created from the environment on first use."""
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def account() -> dict:
+    return client().account()
+
+
+def upload(source, name: str | None = None, **kw) -> Data:
+    return client().upload(source, name, **kw)
+
+
+def data(data_id: str) -> Data:
+    return client().data(data_id)
+
+
+def datasets() -> list[Data]:
+    return client().datasets()
+
+
+def plan(question_id: str) -> Plan:
+    return client().plan(question_id)
+
+
+def model(model_id: str) -> Model:
+    return client().model(model_id)
+
+
+def models(limit: int = 50) -> list[Model]:
+    return client().models(limit)

predictabl-0.1.0/src/predictabl/__main__.py

@@ -0,0 +1,52 @@
+"""Command line: `predictabl whoami`, `predictabl models`, `predictabl mcp`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import errors
+from ._version import __version__
+from .client import Client
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="predictabl", description="Predictabl from the shell."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"predictabl {__version__}"
+    )
+    parser.add_argument(
+        "--base-url", help="default: PREDICTABL_BASE_URL or the hosted app"
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("whoami", help="your account, plan and builds left")
+    sub.add_parser("models", help="your models")
+    sub.add_parser(
+        "mcp", help="run the MCP server over stdio (for Claude and other agents)"
+    )
+    args = parser.parse_args(argv)
+
+    if args.cmd == "mcp":
+        from .mcp import serve
+
+        serve(base_url=args.base_url)
+        return 0
+
+    try:
+        with Client(base_url=args.base_url) as c:
+            if args.cmd == "whoami":
+                print(json.dumps(c.account(), indent=2))
+            elif args.cmd == "models":
+                for m in c.models():
+                    print(f"{m.id}  {m.state:<10} {m.title or ''}")
+    except errors.PredictablError as exc:
+        print(f"predictabl: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())