qombra

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

QBrain is Qombra's proprietary tabular foundation model: it reads the structure of your data directly, so fit() needs a dataframe and a target column — no architecture to pick, no hyperparameters to tune.

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

There are two ways to authenticate, for the two ways people use the API.

Interactive — qombra.login(). Opens a browser window where you sign in on the web app and approve the SDK; the resulting session lives in your OS keyring and expires after 12 hours. Close it explicitly, or scope it with with (leaving the block ends the session):

qombra.login()
with qombra.Qombra() as client:
    model = client.fit(df, target="price")
    print(client.whoami())   # remaining quotas
# session ended here

No browser available (SSH, CI)? Use qombra.login(headless=True) and copy-paste the code shown on the consent page.

Production — an API key. For systems that must run unattended, a key never expires and needs no browser. Create one in the Qombra app under Account → API keys, then put it in the environment or in a .env file in your project (the environment wins when both are set):

export QOMBRA_API_KEY=qbk_…

import qombra
preds = qombra.predict(model_id, new_rows)   # no login() call

The key is shown once at creation — store it in your secret manager. It stays valid until you revoke it in the same place; rotate by creating a new key, deploying it, then revoking the old one. close() never revokes an API key, so a with block cannot take your service offline.

API keys are available on accounts enabled for production access; the tab appears in the app once Qombra switches it on for you.

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 the same account limits the web app uses:

• preprocessing spends LLM output tokens (the AI agent's work) plus one chat message, charged once per call.
• fit creates one analysis, counted against your analysis limit. QBrain is not an LLM, so training spends no output tokens.
• auto_run spends all three: one analysis, plus the chat messages and output tokens the agent consumes across the run.
• analyze, predict, explain and the listing calls spend no quota; they are rate-limited instead.

Check what is left with qombra.whoami().

Support

Questions and issues: www.qombra.com — or reach out at hey@qombra.com.