Metadata-Version: 2.4
Name: datapoint-ai
Version: 0.1.0
Summary: Command-line tool for running human evaluation surveys with Datapoint AI
Project-URL: Homepage, https://trydatapoint.com
Project-URL: Repository, https://github.com/impel-intelligence/datapoint-cli
Project-URL: Issues, https://github.com/impel-intelligence/datapoint-cli/issues
Author: Impel Intelligence
License-Expression: MIT
License-File: LICENSE
Keywords: cli,datapoint,human-evaluation,labeling,survey
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Datapoint CLI

> Run human-evaluation surveys from your terminal: A/B preference tests, ratings,
> rankings, and classification — on text, images, audio, and video. Get real human
> opinions, then read aggregated results back in your shell.

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Powered by Datapoint AI](https://img.shields.io/badge/powered%20by-Datapoint%20AI-7c3aed)](https://trydatapoint.com)

`datapoint` is a command-line client for [Datapoint AI](https://trydatapoint.com).
It wraps the same public API used by the editor integrations, so you can design a
survey, launch it to a panel of real humans, and pick up results a few minutes
later — without leaving the terminal.

## Install

```bash
pip install datapoint-ai
# or, run without installing:
uvx --from datapoint-ai datapoint --help
# or, isolated install:
pipx install datapoint-ai
```

The PyPI package is `datapoint-ai`; the installed command is `datapoint`.
Requires Python 3.10+.

## Quick start

```bash
datapoint login                              # opens your browser to sign in
datapoint balance

datapoint media upload ./logo-a.png ./logo-b.png
datapoint survey plan "Compare logo A (dp://media/abc.png) and \
    logo B (dp://media/def.png). Target: software engineers." \
    --max-responses 20 --save plan.json
datapoint survey create plan.json            # shows cost, asks to confirm
datapoint survey status JOB_ID
datapoint survey responses JOB_ID
```

## Commands

```
datapoint login | logout | whoami
datapoint balance
datapoint subscription
datapoint credits buy [PRODUCT_ID] [--open]
datapoint billing portal [--open]
datapoint media upload FILES...
datapoint survey plan DESCRIPTION [--max-responses N] [--save FILE]
datapoint survey create PLAN_FILE [--yes]
datapoint survey list
datapoint survey status JOB_ID [--results]
datapoint survey responses JOB_ID [--page N] [--per-page N]
                                  [--include-abandoned] [--include-in-progress]
datapoint survey pause | resume | retry JOB_ID
datapoint survey cancel JOB_ID [--yes]
datapoint survey report JOB_ID
datapoint filters [--country C] [--region R] [--city K] [--postal P]
                  [--field F] [--offset N] [--limit N]
```

Every read command supports `--json` for machine-readable output you can pipe
into `jq` or another tool.

## How `survey create` works

`survey create` reserves credits and dispatches paid human work within seconds —
there is no draft or staging state. So it prints the plan summary and cost and
asks you to confirm before launching:

```
$ datapoint survey create plan.json
Survey: Logo memorability A vs B
Task type: comparison
Datapoints: 1
Responses per datapoint: 20
Estimated cost: 100 credits

This reserves 100 credits and dispatches paid human work. Continue? [y/N]:
```

Pass `--yes` to skip the prompt in scripts (after a human has reviewed the plan).

## Configuration

| Variable             | Description                                                              |
|----------------------|--------------------------------------------------------------------------|
| `DATAPOINT_API_KEY`  | API key (overrides saved config).                                        |
| `DATAPOINT_BASE_URL` | API base URL (default `https://api.trydatapoint.com/data-labelling/v1`). |

Your API key is saved to `~/.config/datapoint/config.json` (`%APPDATA%\datapoint\config.json`
on Windows) with owner-only permissions. The Datapoint editor integration reads
the same file, so logging in once authenticates both.

## Exit codes

| Code | Meaning              |
|------|----------------------|
| 0    | Success              |
| 1    | Generic error        |
| 2    | Not authenticated    |
| 3    | Insufficient credits |
| 4    | Rate limited         |

Set `DATAPOINT_DEBUG=1` to print full tracebacks on unexpected errors.

## License

MIT — see [LICENSE](LICENSE).
