Metadata-Version: 2.5
Name: qombra
Version: 0.3.0
Summary: Python client for Qombra — data analysis and QBrain model training for tabular data.
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: data-analysis,foundation-model,machine-learning,qbrain,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, 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.

```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

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

```python
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:

```bash
export QOMBRA_API_KEY=qbk_…
```

```python
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

```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 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](https://www.qombra.com) — or reach out
at [hey@qombra.com](mailto:hey@qombra.com).
