qombra

Python client for Qombra — data analysis, AI-guided preprocessing, AutoML training, inference, and SHAP explainability, all running on the Qombra platform through your account.

pip install qombra

Quickstart

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

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):

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

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

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:

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 — or reach out at hey@qombra.com.