Metadata-Version: 2.4
Name: tekvwa
Version: 0.1.0
Summary: Official Python client for the Tekvwa Analysis REST API
Author: Tekvwa IT Solutions LTD
License-Expression: MIT
Project-URL: Homepage, https://tekvwaanalysis.com
Project-URL: Documentation, https://github.com/EfeObus/TekVwarho-Analysis/blob/main/docs/API.md
Project-URL: Repository, https://github.com/EfeObus/TekVwarho-Analysis
Keywords: tekvwa,data-analysis,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: responses>=0.25; extra == "test"
Dynamic: license-file

# tekvwa

Official Python client for the [Tekvwa Analysis](https://tekvwaanalysis.com) REST API.

## Install

```bash
pip install tekvwa
```

(Until the first PyPI release is published, install straight from this repo:
`pip install "git+https://github.com/EfeObus/TekVwarho-Analysis.git#subdirectory=sdk/python"`.)

## Quickstart

```python
from tekvwa import TekvwaClient

# Create a token at Account menu -> API Tokens (/api-tokens) in the app.
client = TekvwaClient(api_token="tva_...")
# Or set TEKVWA_API_TOKEN in the environment and omit api_token entirely.

me = client.whoami()
print(f"Logged in as {me['email']} ({me['plan']} plan)")

dataset = client.upload_csv("sales.csv")
print(f"Uploaded dataset {dataset['id']}: {dataset['rows']} rows, {dataset['columns']} columns")

workbooks = client.list_workbooks()
report = client.get_report(workbooks[0]["id"])
if report["generated"]:
    for block in report["blocks"]:
        print(block.get("html_content", ""))

result = client.analyze(
    workbooks[0]["id"],
    analysis_type="compare_means",
    method="independent_t",
    params={"dependent_var": "spend", "grouping_var": "plan"},
)
print(result["interpretation"]["headline"])
```

## API surface

Five endpoints, matching [`docs/API.md`](https://github.com/EfeObus/TekVwarho-Analysis/blob/main/docs/API.md) exactly:

| Method | Endpoint | REST route |
|---|---|---|
| `whoami()` | Confirm the token, get the account | `GET /api/v1/me` |
| `list_datasets()` | List your datasets | `GET /api/v1/datasets` |
| `upload_csv(file, name=None)` | Import a CSV (path or file object) | `POST /api/v1/datasets` |
| `list_workbooks()` | List your workbooks (projects) | `GET /api/v1/workbooks` |
| `get_report(workbook_id)` | The workbook's resolved Report sheet | `GET /api/v1/workbooks/<id>/report` |
| `analyze(workbook_id, analysis_type, method, params=None)` | Run one analysis, one-shot | `POST /api/v1/workbooks/<id>/analyze` |

`upload_csv` and `analyze` are rate-limited server-side (30/hour and 60/hour respectively) —
a `TekvwaAPIError` with `status_code == 429` means you've hit that limit.

## Errors

- `TekvwaAPIError` — the API responded with a non-2xx status. `.message` is the server's own
  plain-language error text; `.status_code` is the HTTP status (`401` no/invalid token, `404` not
  found or not yours, `400` a bad request, `429` rate-limited).
- `TekvwaConnectionError` — the request never reached the API (network error, timeout, DNS).

## Development

```bash
cd sdk/python
pip install -e ".[test]"
pytest
```

## License

MIT — see [`LICENSE`](LICENSE). (The Tekvwa Analysis application itself is proprietary; this
client library is a separate, permissively-licensed piece, the same way most SaaS products ship
an open client SDK alongside a closed-source product.)
