qombra 0.2.0__tar.gz

qombra-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Environment / secrets
+.env
+.env.*
+
+# Virtualenvs
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build / publish
+dist/
+build/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Examples
+examples/

qombra-0.2.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.2.0
+
+- `fit()` accepts `metric=` and `effort=`. `metric` chooses the evaluation
+  metric the engine tunes, selects and reports on (classification: `accuracy`,
+  `roc_auc`, `f1_micro`, `log_loss`, `qwk`; regression: `mape`, `rmse`,
+  `rmsle`, `mae`, `median_ae`, `smape`); unset keeps the task default and its
+  automatic class-imbalance safeguard. `effort` sets the compute budget
+  (`low` / `medium` / `high` / `auto`); unset keeps the server default.
+  Unknown values raise `ValidationError` at the call, before any training runs.
+
+## 0.1.0
+
+Initial release.
+
+- Browser login (PKCE loopback flow) with OS-keyring token storage, 12-hour
+  sessions, explicit `logout()` / context-manager revocation.
+- `analyze()` — dataset statistics on a least-NaN ≤1000-row sample.
+- `preprocessing()` — server-side, instruction-guided preprocessing returning
+  a `PreprocessingResult` (dataframe + summary + warnings).
+- `fit()` — AutoML training returning a server-side `Model` addressable by id
+  (`Model.from_id()` reconstructs it in later sessions).
+- `predict()` — inference on new samples, aligned to the caller's index.
+- `explain()` — SHAP values with a formatted console bar chart.
+- `auto_run()` — the full autonomous agent pipeline in one call.
+- `list_models()` / `delete_model()` and
+  `list_preprocessing_results()` / `delete_preprocessing_result()`.

qombra-0.2.0/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Qombra. All rights reserved.
+
+This software is proprietary. Use of this client library is permitted only in
+connection with a Qombra account and subject to the Qombra terms of service
+(https://www.qombra.com). Redistribution or modification without written
+permission is prohibited.

qombra-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: qombra
+Version: 0.2.0
+Summary: Python client for the Qombra data-analysis and AutoML platform.
+Project-URL: Homepage, https://www.qombra.com
+Project-URL: Documentation, https://www.qombra.com/api/docs
+Author: Qombra Team
+License: Copyright (c) 2026 Qombra. All rights reserved.
+        
+        This software is proprietary. Use of this client library is permitted only in
+        connection with a Qombra account and subject to the Qombra terms of service
+        (https://www.qombra.com). Redistribution or modification without written
+        permission is prohibited.
+License-File: LICENSE
+Keywords: automl,data-analysis,machine-learning,shap,tabular
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+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.27
+Requires-Dist: keyring>=24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qombra
+
+Python client for [Qombra](https://www.qombra.com) — data analysis, AI-guided
+preprocessing, AutoML training, inference, and SHAP explainability, all running
+on the Qombra platform through your account.
+
+```bash
+pip install qombra
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import qombra
+
+qombra.login()   # opens the browser; approve the SDK session (valid 12 hours)
+
+df = pd.read_csv("customers.csv")
+
+# 1. Dataset statistics (analyzes a ≤1000-row sample with the fewest NaNs)
+report = qombra.analyze(df)
+print(report.summary, report.warnings)
+
+# 2. Preprocessing with a natural-language instruction
+result = qombra.preprocessing(df, "drop duplicate rows and outliers in price")
+print(result)          # summary, actions, warnings
+clean_df = result.df
+
+# 3. Training — the model stays on the server, addressed by id
+model = qombra.fit(clean_df, target="churn_30d")
+print(model.id, model.metrics)
+# Optional: pick the evaluation metric and the compute budget yourself
+model = qombra.fit(clean_df, target="churn_30d", metric="roc_auc", effort="high")
+
+# 4. Inference
+predictions = model.predict(clean_df.head(100))
+
+# 5. Explainability (SHAP)
+print(model.explain())
+
+qombra.logout()  # revoke the session token
+```
+
+### Later, in another session — no retraining
+
+```python
+import qombra
+
+qombra.login()
+model = qombra.Model.from_id("«the model id from earlier»")
+predictions = model.predict(new_rows)
+```
+
+### Session management
+
+Every call needs an authenticated session. `qombra.login()` opens a browser
+window where you sign in on the web app and approve the SDK; the resulting
+token lives in your OS keyring and expires after 12 hours. Close a session
+explicitly, or scope it with `with` (leaving the block revokes the token):
+
+```python
+qombra.login()
+with qombra.Qombra() as client:
+    model = client.fit(df, target="price")
+    print(client.whoami())   # remaining quotas
+# token revoked here
+```
+
+No browser available (SSH, CI)? Use `qombra.login(headless=True)` and
+copy-paste the code shown on the consent page. In automated environments you
+can also provide a token via the `QOMBRA_API_TOKEN` environment variable.
+
+### The full pipeline in one call
+
+```python
+result = qombra.auto_run(df, "Predict which customers churn in the next 30 days")
+print(result)                     # phases, target, test metric
+preds = result.model.predict(new_rows)
+```
+
+`auto_run` drives the same agent workflow as the web app (ingest →
+preprocessing → target confirmation → training) without a human in the loop.
+Expect minutes to hours; the created analysis is fully browsable in the web
+app afterwards.
+
+### Managing stored artifacts
+
+```python
+qombra.list_models()                     # all trained models in your account
+qombra.delete_model(model)               # irreversible
+qombra.list_preprocessing_results()
+qombra.delete_preprocessing_result(job_id)
+```
+
+## Error handling
+
+All errors derive from `qombra.QombraError`:
+
+```python
+try:
+    model = qombra.fit(df, target="revenue")
+except qombra.AuthenticationError:
+    qombra.login()                       # token expired (12h) — sign in again
+except qombra.QuotaExceededError as e:
+    print("Usage limit reached:", e)
+except qombra.ValidationError as e:
+    print("Bad input:", e.code, e)
+except qombra.JobTimeoutError as e:
+    print("Still training server-side, job:", e.job_id)
+```
+
+Notable classes: `AuthenticationError`, `QuotaExceededError`,
+`ValidationError` (with a machine-readable `.code`), `PayloadTooLargeError`,
+`NotFoundError`, `JobFailedError`, `JobTimeoutError`, `NetworkError`,
+`ServerError`.
+
+## Data format & metering
+
+Dataframes travel as parquet with plain scalar columns (numbers, booleans,
+strings, dates, timestamps, decimals; pandas categoricals are fine) — cast
+mixed-type `object` columns before upload. Uploads are size-capped and calls
+are rate-limited: an oversized upload raises `PayloadTooLargeError` (reduce or
+batch it), rapid-fire calls raise `RateLimitedError`.
+
+All SDK usage counts toward your account's usage limits: each `fit`/`auto_run`
+consumes analysis quota, and instruction-guided preprocessing consumes
+chat/LLM-token quota. Check remaining quotas with `qombra.whoami()`.
+
+## Support
+
+Questions and issues: [www.qombra.com](https://www.qombra.com) — or reach out
+at [hey@qombra.com](mailto:hey@qombra.com).

qombra-0.2.0/README.md

@@ -0,0 +1,133 @@
+# qombra
+
+Python client for [Qombra](https://www.qombra.com) — data analysis, AI-guided
+preprocessing, AutoML training, inference, and SHAP explainability, all running
+on the Qombra platform through your account.
+
+```bash
+pip install qombra
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import qombra
+
+qombra.login()   # opens the browser; approve the SDK session (valid 12 hours)
+
+df = pd.read_csv("customers.csv")
+
+# 1. Dataset statistics (analyzes a ≤1000-row sample with the fewest NaNs)
+report = qombra.analyze(df)
+print(report.summary, report.warnings)
+
+# 2. Preprocessing with a natural-language instruction
+result = qombra.preprocessing(df, "drop duplicate rows and outliers in price")
+print(result)          # summary, actions, warnings
+clean_df = result.df
+
+# 3. Training — the model stays on the server, addressed by id
+model = qombra.fit(clean_df, target="churn_30d")
+print(model.id, model.metrics)
+# Optional: pick the evaluation metric and the compute budget yourself
+model = qombra.fit(clean_df, target="churn_30d", metric="roc_auc", effort="high")
+
+# 4. Inference
+predictions = model.predict(clean_df.head(100))
+
+# 5. Explainability (SHAP)
+print(model.explain())
+
+qombra.logout()  # revoke the session token
+```
+
+### Later, in another session — no retraining
+
+```python
+import qombra
+
+qombra.login()
+model = qombra.Model.from_id("«the model id from earlier»")
+predictions = model.predict(new_rows)
+```
+
+### Session management
+
+Every call needs an authenticated session. `qombra.login()` opens a browser
+window where you sign in on the web app and approve the SDK; the resulting
+token lives in your OS keyring and expires after 12 hours. Close a session
+explicitly, or scope it with `with` (leaving the block revokes the token):
+
+```python
+qombra.login()
+with qombra.Qombra() as client:
+    model = client.fit(df, target="price")
+    print(client.whoami())   # remaining quotas
+# token revoked here
+```
+
+No browser available (SSH, CI)? Use `qombra.login(headless=True)` and
+copy-paste the code shown on the consent page. In automated environments you
+can also provide a token via the `QOMBRA_API_TOKEN` environment variable.
+
+### The full pipeline in one call
+
+```python
+result = qombra.auto_run(df, "Predict which customers churn in the next 30 days")
+print(result)                     # phases, target, test metric
+preds = result.model.predict(new_rows)
+```
+
+`auto_run` drives the same agent workflow as the web app (ingest →
+preprocessing → target confirmation → training) without a human in the loop.
+Expect minutes to hours; the created analysis is fully browsable in the web
+app afterwards.
+
+### Managing stored artifacts
+
+```python
+qombra.list_models()                     # all trained models in your account
+qombra.delete_model(model)               # irreversible
+qombra.list_preprocessing_results()
+qombra.delete_preprocessing_result(job_id)
+```
+
+## Error handling
+
+All errors derive from `qombra.QombraError`:
+
+```python
+try:
+    model = qombra.fit(df, target="revenue")
+except qombra.AuthenticationError:
+    qombra.login()                       # token expired (12h) — sign in again
+except qombra.QuotaExceededError as e:
+    print("Usage limit reached:", e)
+except qombra.ValidationError as e:
+    print("Bad input:", e.code, e)
+except qombra.JobTimeoutError as e:
+    print("Still training server-side, job:", e.job_id)
+```
+
+Notable classes: `AuthenticationError`, `QuotaExceededError`,
+`ValidationError` (with a machine-readable `.code`), `PayloadTooLargeError`,
+`NotFoundError`, `JobFailedError`, `JobTimeoutError`, `NetworkError`,
+`ServerError`.
+
+## Data format & metering
+
+Dataframes travel as parquet with plain scalar columns (numbers, booleans,
+strings, dates, timestamps, decimals; pandas categoricals are fine) — cast
+mixed-type `object` columns before upload. Uploads are size-capped and calls
+are rate-limited: an oversized upload raises `PayloadTooLargeError` (reduce or
+batch it), rapid-fire calls raise `RateLimitedError`.
+
+All SDK usage counts toward your account's usage limits: each `fit`/`auto_run`
+consumes analysis quota, and instruction-guided preprocessing consumes
+chat/LLM-token quota. Check remaining quotas with `qombra.whoami()`.
+
+## Support
+
+Questions and issues: [www.qombra.com](https://www.qombra.com) — or reach out
+at [hey@qombra.com](mailto:hey@qombra.com).

qombra-0.2.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qombra"
+version = "0.2.0"
+description = "Python client for the Qombra data-analysis and AutoML platform."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Qombra Team" }]
+keywords = ["automl", "tabular", "machine-learning", "data-analysis", "shap"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pandas>=2.0",
+    "pyarrow>=14",
+    "keyring>=24",
+]
+
+[project.urls]
+Homepage = "https://www.qombra.com"
+Documentation = "https://www.qombra.com/api/docs"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "python-dotenv>=1.0",
+    "build",
+    "twine",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qombra"]
+
+[tool.hatch.build.targets.sdist]
+# Ship only what users need; DEVELOPMENT.md and tests stay internal.
+exclude = ["tests/", "DEVELOPMENT.md", ".gitignore", ".DS_Store"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+# PYI034 wants typing.Self, which needs Python >= 3.11; we support 3.10.
+ignore = ["PYI034"]
+
+[tool.mypy]
+# Runtime support is 3.10+, but modern numpy stubs need >=3.12 syntax to check.
+python_version = "3.12"
+strict = false
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qombra-0.2.0/src/qombra/__init__.py

@@ -0,0 +1,159 @@
+"""qombra — Python client for the Qombra data-analysis and AutoML platform.
+
+Quickstart::
+
+    import qombra
+
+    qombra.login()                              # browser sign-in, 12h session
+
+    report = qombra.analyze(df)                 # dataset statistics
+    clean = qombra.preprocessing(df, "drop outliers in price")
+    model = qombra.fit(clean.df, target="price")
+    predictions = model.predict(new_df)
+    print(model.explain())                      # SHAP bar chart
+
+    qombra.logout()                             # revoke the session
+
+All calls go through an authenticated session against https://www.qombra.com
+and count toward your account's usage limits.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._auth import TokenInfo, login, logout
+from ._client import Qombra, get_default_client, reset_default_client
+from ._errors import (
+    AuthenticationError,
+    JobFailedError,
+    JobTimeoutError,
+    LoginDeniedError,
+    LoginTimeoutError,
+    NetworkError,
+    NotFoundError,
+    PayloadTooLargeError,
+    QombraError,
+    QuotaExceededError,
+    RateLimitedError,
+    ServerError,
+    ValidationError,
+)
+from ._results import (
+    AnalysisReport,
+    AutoRunResult,
+    Explanation,
+    Model,
+    ModelInfo,
+    PreprocessingResult,
+    PreprocessingResultInfo,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AnalysisReport",
+    "AuthenticationError",
+    "AutoRunResult",
+    "Explanation",
+    "JobFailedError",
+    "JobTimeoutError",
+    "LoginDeniedError",
+    "LoginTimeoutError",
+    "Model",
+    "ModelInfo",
+    "NetworkError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PreprocessingResult",
+    "PreprocessingResultInfo",
+    "Qombra",
+    "QombraError",
+    "QuotaExceededError",
+    "RateLimitedError",
+    "ServerError",
+    "TokenInfo",
+    "ValidationError",
+    "__version__",
+    "analyze",
+    "auto_run",
+    "delete_model",
+    "delete_preprocessing_result",
+    "explain",
+    "fit",
+    "get_default_client",
+    "list_models",
+    "list_preprocessing_results",
+    "login",
+    "logout",
+    "predict",
+    "preprocessing",
+    "reset_default_client",
+    "whoami",
+]
+
+
+# Module-level convenience functions delegating to the default client. Each is
+# documented on the corresponding Qombra method.
+
+def analyze(df: pd.DataFrame, excluded_columns: list[str] | None = None) -> AnalysisReport:
+    """Dataset statistics for a ≤1000-row least-NaN sample. See :meth:`Qombra.analyze`."""
+    return get_default_client().analyze(df, excluded_columns)
+
+
+def preprocessing(df: pd.DataFrame, instruction: str, *, timeout: float = 1500.0) -> PreprocessingResult:
+    """Server-side, instruction-guided preprocessing. See :meth:`Qombra.preprocessing`."""
+    return get_default_client().preprocessing(df, instruction, timeout=timeout)
+
+
+def fit(df: pd.DataFrame, target: str, *, metric: str | None = None,
+        effort: str | None = None, timeout: float = 1800.0) -> Model:
+    """Train a model server-side. See :meth:`Qombra.fit`."""
+    return get_default_client().fit(df, target, metric=metric, effort=effort, timeout=timeout)
+
+
+def auto_run(df: pd.DataFrame, prompt: str, *, user_context: str = "",
+             preprocessing_mode: str = "deterministic", max_nudges: int = 3,
+             auto_approve: bool = True, name: str | None = None,
+             timeout: float = 7200.0) -> AutoRunResult:
+    """Full autonomous pipeline run. See :meth:`Qombra.auto_run`."""
+    return get_default_client().auto_run(
+        df, prompt, user_context=user_context, preprocessing_mode=preprocessing_mode,
+        max_nudges=max_nudges, auto_approve=auto_approve, name=name, timeout=timeout,
+    )
+
+
+def predict(model_or_id: Model | str, df: pd.DataFrame) -> pd.Series:
+    """Predict with a trained model. See :meth:`Qombra.predict`."""
+    return get_default_client().predict(model_or_id, df)
+
+
+def explain(model_or_id: Model | str, df: pd.DataFrame | None = None, *,
+            timeout: float = 900.0) -> Explanation:
+    """SHAP explainability for a trained model. See :meth:`Qombra.explain`."""
+    return get_default_client().explain(model_or_id, df, timeout=timeout)
+
+
+def list_models(created_via: str = "sdk") -> list[ModelInfo]:
+    """List this account's trained models ('sdk' | 'web' | 'all'). See :meth:`Qombra.list_models`."""
+    return get_default_client().list_models(created_via)
+
+
+def delete_model(model_or_id: Model | str) -> None:
+    """Delete a trained model permanently. See :meth:`Qombra.delete_model`."""
+    get_default_client().delete_model(model_or_id)
+
+
+def list_preprocessing_results() -> list[PreprocessingResultInfo]:
+    """List stored preprocessing results. See :meth:`Qombra.list_preprocessing_results`."""
+    return get_default_client().list_preprocessing_results()
+
+
+def delete_preprocessing_result(job_id: str) -> None:
+    """Delete a stored preprocessing result permanently. See :meth:`Qombra.delete_preprocessing_result`."""
+    get_default_client().delete_preprocessing_result(job_id)
+
+
+def whoami() -> dict:
+    """Return account email, token expiry, and remaining quotas. See :meth:`Qombra.whoami`."""
+    return get_default_client().whoami()