stave 0.0.2.dev1 on PyPI

This project is currently under development.

Stave is a fast, lightweight, extensible web-based text annotation and visualization tool designed to support a wide range of data types and NLP tasks. Stave offers the following features:

Semantic Annotation: supports both template and custom data types
Multi-document Annotation: supports cross-document annotations and coreference
Customizable Interface: supports creation of task-specific interface with independently developed plugins
Machine-Human Collaboration: keeps human in the loop to verify and correct machine suggestions
Easy Integration: supports seamless integration with pre-built NLP workflows
Safe Data Serialization: supports a JSON-serializable format for easy data saving, loading and distribution

Stave was originally developed and is actively contributed by Petuum in collaboration with other institutes. A mirror of this repository is maintained by Petuum Open Source.

Get Started

Installation

pip install stave

Quick Start

stave -s start -l -o

This will start the Stave server with example project loaded. -s allows Stave to run with all the default configuration. -l will load example projects and -o will open a browser window. If you want to start Stave as a headless server, simply remove the -o flag. You can log in with default user name admin and default password admin. You can start viewing the projects and some annotations/applications that we have prepared.

Or if you just want to start Stave from scratch, you can:

stave start

You can still log in with default user name admin and default password admin, which leads you to an empty project page.

At any time, you can still load the example projects:

stave load-samples

By default the Stave server runs at http://localhost:8888. If you need to switch the port, you can add -n to specify the port number. For example, the following command will start a Stave service at http://localhost:8002.

stave start -n 8002

For more options to start Stave server, refer to:

stave start -h

Stave Configuration

After you start the Stave server, a .stave/ folder is automatically created under your home directory ~. It has the following structure:

~/.stave/
---- stave.conf
---- db.sqlite3
---- log

stave.conf holds a json object of configurations.
db.sqlite3 is the default database for Stave server.
log is the default logging file.

You can view or update the configuration by running the subcommand config. You may follow the prompts to interactively set up the configuration:

stave config -i

Stave CLI allows you to configure the database file, log file, the allowed hosts, etc. For more options, run

stave config -h

and you shall see the following help message:

usage: stave config [-h] [-i] [-s DJANGO_SETTINGS_MODULE] [-d DB_FILE]
                    [-l LOG_FILE] [-a ALLOWED_HOSTS [ALLOWED_HOSTS ...]]

optional arguments:
  -h, --help            show this help message and exit
  -i, --interact-config
                        Interactively set up the configuration
  -s DJANGO_SETTINGS_MODULE, --django-settings-module DJANGO_SETTINGS_MODULE
                        Module path to settings.py of django project. If you
                        have not set up any django project, you should leave
                        this field empty and stave will use its default
                        configuration. To set this field you should already
                        have a django project and the 'settings.py' file under
                        your project must be accessible from PYTHONPATH so
                        that django can import it as a module. Example:
                        'myproject.settings'
  -d DB_FILE, --db-file DB_FILE
                        Path to database file of Stave
  -l LOG_FILE, --log-file LOG_FILE
                        Path to log file for logging
  -a ALLOWED_HOSTS [ALLOWED_HOSTS ...], --allowed-hosts ALLOWED_HOSTS [ALLOWED_HOSTS ...]
                        A list of strings representing the host/domain names
                        that stave can serve.

For example, you can change the path of database file by running:

stave config -d ~/db.sqlite3

You may also add your own host names to the allowed hosts that Stave can serve:

stave config -a localhost myhost1.com myhost2.com

Import and Export

Stave provides a set of interfaces that allow you to import/export projects from/to disk. This is useful when you need to transfer Stave projects between backend database and local storage.

To export a project, you need to specify the path to store the project and its database id (which can be retrieved from URL, e.g., the id of project at http://localhost:8888/project/3 is 3). For example, the following command will save project with id=3 to ~/project_3:

stave export ~/project_3 3

Note that you will be prompted to enter your username and password before moving forward.

Now that you've saved a Stave project to a directory, you can either render this project in viewer mode

stave start -o -p ~/project_3

or import it to the database (which also requires authentication with username and password)

stave import ~/project_3

stave import is also useful when you use StaveProcessor inside a forte pipeline and want to save the generated visualization to database. StaveProcessor normally would save a Stave project to a folder (by default the name of folder is Auto generated project), and you can import this folder into stave backend by running

stave import PATH_TO_STAVE_PROJECT

More about the command line tool

To learn more about Stave CLI, run the following command to see the help message:

stave -h

Developer Quick Start

Environment

The project is tested on:

Python 3.6+ Django 3.2.4 yarn 1.22.10

Run Django server

cd simple-backend
make sure your python command is using python3, or use a virtual env by:
- python3 -m venv venv create virtual env (skip if already created)
- . venv/bin/activate use virtual env
make sure django is installded, or install it by:
- python -m pip install Django
./start-dev.sh
- This script will create an example sqlite3 DB from SQL: db.sqlite3