Metadata-Version: 2.4
Name: toktagger
Version: 0.4.0
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn[standard]
Requires-Dist: fsspec
Requires-Dist: xarray
Requires-Dist: s3fs
Requires-Dist: zarr>=3
Requires-Dist: scipy
Requires-Dist: pyarrow<26
Requires-Dist: pymongo
Requires-Dist: requests
Requires-Dist: numpy<3
Requires-Dist: scikit-learn
Requires-Dist: pandas<=3.1.0
Requires-Dist: pillow
Requires-Dist: ruptures>=1.1.10
Requires-Dist: psutil>=7.0.0
Requires-Dist: mongita>=1.2.0
Requires-Dist: filelock>=3.19.1
Requires-Dist: hmmlearn>=0.3.3
Requires-Dist: shapely>=2.0.7
Requires-Dist: scikit-image>=0.24.0
Requires-Dist: uda-xarray>=0.2.1
Requires-Dist: sal-xarray>=0.2.1
Requires-Dist: bump-my-version>=1.2.7
Requires-Dist: platformdirs>=4.4.0
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: itsdangerous>=2.0.0
Requires-Dist: uda-mast>=1.4.1
Requires-Dist: authlib>=1.8.0
Requires-Dist: cryptography>=48.0.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: canaille[front,oidc,server,sqlite]>=0.2.7
Requires-Dist: joserfc<1.8,>=1.6
Provides-Extra: models
Requires-Dist: torch; extra == "models"
Requires-Dist: ray>=2.49.1; extra == "models"
Requires-Dist: ultralytics==8.4.98; extra == "models"
Requires-Dist: mlflow>=3.1.4; extra == "models"
Requires-Dist: safetensors>=0.7.0; extra == "models"
Requires-Dist: huggingface-hub>=1.22.0; extra == "models"
Dynamic: license-file

# TokTagger

![TokTagger Logo](docs/assets/logo_small.png)

An open source, interactive annotation platform for Tokamak diagnostic data.

[![Workflow: CI](https://github.com/ukaea/toktagger/actions/workflows/ci.yml/badge.svg)](https://github.com/ukaea/toktagger/actions/workflows/ci.yml)
[![Workflow: Dependabot](https://img.shields.io/badge/Dependabot-enabled-34d058?logo=github)](https://github.com/ukaea/toktagger/actions/workflows/dependabot/dependabot-updates)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Linting: ruff](https://img.shields.io/badge/linting-ruff-purple)](https://github.com/astral-sh/ruff)
[![Testing: pytest](https://img.shields.io/badge/testing-pytest-red)](https://github.com/pylint-dev/pylint-pytest)


## What It Does

TokTagger is a web-based platform for curating labeled datasets from tokamak diagnostics. It lets users browse shots, inspect signals and images, apply consistent labels, and manage annotations in one place. The Python API and React UI support local or team workflows, making it straightforward to create datasets for downstream analysis and machine-learning models.

It currently supports the following features:

- **Data Browsing**: Explore tokamak shots, signals, and images through an intuitive interface.
- **Annotation Tools**: Apply consistent labels to signals and images using a customizable tagging system.
- **ML Models**: Train and infer from ML models within the UI.
- **Dataset Management**: Organize and manage annotations in a central repository.
- **Multi-User Support**: Role-based access control with per-project membership, suitable for team annotation workflows.
- **Extensible API**: A Python API for integrating with existing workflows and tools.


## Installation

To run the application locally:

### Install via pip
To install the package via `pip` (or similarly via `Poetry` or `uv` package managers):
```sh
python -m venv .venv
source .venv/bin/activate
```
To install the package for labelling only (without ML Model functionality):
```sh
pip install toktagger
```
Or to include the ML models:
```sh
pip install toktagger[models]
```
If you intend to add custom data loaders or models to your TokTagger instance, this is the recommended route.

### Install as a uv tool
Alternatively, it can be installed as a tool using `uv`. To install the package for labelling only (without ML Model functionality):

```sh
uv tool install --python 3.12.6 toktagger
```
Or to include the ML models:
```sh
uv tool install --python 3.12.6 toktagger[models]
```

## Quick Start

To start a local single-user instance:

```sh
toktagger
```

This starts a single-process instance at `http://localhost:8002`. On the first start, TokTagger creates a local identity provider and prints the user name and the password of the first administrator to the terminal. See [User Management](docs/user_management.md).

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--workers N` | `1` | Number of uvicorn worker processes |
| `--host HOST` | `localhost` | Host to bind to |
| `--port PORT` | `8002` | Port to listen on |
| `--no-browser` | off | Suppress automatic browser launch |
| `--reload` | off | Auto-reload on code changes (single-worker dev mode only) |

### Development Mode

For local development with automatic reload on code changes, use a single worker:

```sh
toktagger --workers 1 --reload
```

### Multi-User / Team Deployment

For server deployments, run with multiple workers and disable the automatic browser launch. Multiple workers operate on Linux, macOS and Windows:

```sh
toktagger --workers 4 --no-browser
```

The default host is `localhost`. Only the local machine can connect to it. To let other users on the network connect, add `--host 0.0.0.0`.

> [!WARNING]
> `--host 0.0.0.0` makes TokTagger available to all devices that can reach the machine on port 8002. The traffic is not encrypted. Use it only on a trusted network. For other deployments, use the `docker-compose.yml` stack, which puts TokTagger behind a TLS proxy.

Or directly via uvicorn (use `python -m uvicorn` to make sure that the correct virtual environment is used):

```sh
python -m uvicorn toktagger.api.asgi:app --workers 4 --host 0.0.0.0 --port 8002
```

`docker-compose.yml` is the production stack. It runs TokTagger with Keycloak, MongoDB and a Caddy proxy that handles TLS. See the [Deployment](docs/deployment.md) guide.

See the [User Management](docs/user_management.md) guide for creating accounts, assigning roles, and managing project membership.
