Metadata-Version: 2.4
Name: chakatastat
Version: 0.15.0
Summary: Python client for the ChakataStat analysis engine, over MCP.
Author: Edward Amani
License: LicenseRef-Proprietary — see the bundled LICENSE
Project-URL: Homepage, https://chakatastat.app
Project-URL: Documentation, https://chakatastat.app/docs/advanced/reproducibility/
Keywords: statistics,analysis,mcp,polars,ChakataStat
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: polars
Requires-Dist: polars>=0.20; extra == "polars"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# ChakataStat — Python client

A thin Python client for the ChakataStat analysis engine. It drives the same analyses the desktop app's menus, AI
assistant and MCP server run — from real Python, with loops, comprehensions and
the whole data-analysis ecosystem one `to_polars()` away.

It is a **client, not an engine**: it spawns `ChakataStat --mcp <file>` (the
app's headless [MCP](https://modelcontextprotocol.io/) launch mode) as a
subprocess and talks JSON-RPC to it over stdio. The dataset stays in the one
native Rust engine; nothing statistical runs in Python — so the numbers this
client returns can never drift from the desktop app's. No embedded
interpreter, no second copy of the data.

> **This package requires the ChakataStat desktop application.** It contains
> no statistics of its own — it drives an installed copy of the app, and does
> nothing without one. Get the app (free) from
> [chakatastat.app](https://chakatastat.app) — Microsoft Store, Snap Store or
> `.deb`.

## Install

```sh
pip install chakatastat              # no required dependencies
pip install "chakatastat[polars]"    # also pull in polars, for to_polars()
```

The client's version tracks the app's: install the client version that matches
the app you have (e.g. client 0.11.0 pairs with app 0.11.0).

The client finds the **ChakataStat binary** from, in order: the `binary=`
argument to `open()`, the `ChakataStat_BIN` environment variable, or
`ChakataStat` on your `PATH`.

```sh
export ChakataStat_BIN=/path/to/ChakataStat     # e.g. the release bundle
```

## Use

```python
import chakatastat as ig

with ig.open("survey.ckd") as ds:
    # Each analysis tool is a method; arguments are the tool's parameters.
    print(ds.descriptives(variables=["income", "age"]))
    ds.regression(dependent="sales", predictors=["price", "ads"])

    # Real Python around the calls:
    for col in ds.numeric_vars():
        ds.frequencies(variables=[col])

    # The escape hatch into the full ecosystem:
    df = ds.to_polars()
    print(df.describe())
```

`open()` accepts any format the app's File → Open does (`.ckd`, CSV/TSV, Excel,
Parquet), or no path for an empty dataset. Pass `read_only=True` to forbid the
data-mutating transforms.

A call returns a `Result` whose text is the engine's result tables; `print(...)`
or `str(...)` shows them. A call the engine cannot run (a bad variable name, a
wrong type) raises `ChakataStat.ToolError` with the engine's own message.

`ds.tools` lists every available tool name; `ds.call(name, **args)` is the
explicit form behind the generated methods.

## Generating a script from the app

The desktop app's Syntax Console can **Export as Python**, turning a recorded
session into a runnable script that uses this client — so a point-and-click
analysis becomes reproducible Python with no language to learn.

## License

Three things, licensed three ways (the long form is the bundled `LICENSE`
file):

- **This client** may be installed, used and redistributed freely, including
  commercially.
- **The ChakataStat application** it drives is proprietary — free to use for
  any purpose, including commercially, but not open source.
- **The name and logo** are reserved.
