Metadata-Version: 2.4
Name: nlpmed-portal-lite
Version: 1.0.0
Summary: A lightweight, self-hosted clinical NLP and annotation research platform.
Project-URL: Homepage, https://github.com/omid-jf/NLPMed-Portal-Lite
Project-URL: Documentation, https://omid-jf.github.io/NLPMed-Portal-Lite/
Project-URL: Repository, https://github.com/omid-jf/NLPMed-Portal-Lite
Project-URL: Issues, https://github.com/omid-jf/NLPMed-Portal-Lite/issues
Project-URL: Demo, https://nlpmed.demo.angli-lab.com
Author-email: Omid Jafari <omid.jafari@bcm.edu>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: annotation,clinical-nlp,django,natural-language-processing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: <3.15,>=3.12
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: crispy-bootstrap5>=2026.3
Requires-Dist: django-allauth>=65.18.0
Requires-Dist: django-auditlog>=3.4.1
Requires-Dist: django-compressor>=4.6.0
Requires-Dist: django-cors-headers>=4.9.0
Requires-Dist: django-crispy-forms>=2.6
Requires-Dist: django-environ>=0.14.0
Requires-Dist: django-hijack>=3.7.8
Requires-Dist: django-nested-admin>=4.1.6
Requires-Dist: django-simple-history>=3.13.0
Requires-Dist: django<6.1,>=6.0.7
Requires-Dist: djangorestframework<4,>=3.17.1
Requires-Dist: drf-spectacular>=0.30.0
Requires-Dist: drf-writable-nested>=0.7.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas<4,>=3.0.5
Requires-Dist: pyarrow>=25.0.0
Requires-Dist: rcssmin>=1.2.2
Requires-Dist: uvicorn[standard]>=0.51.0
Requires-Dist: whitenoise>=6.12.0
Provides-Extra: postgres
Requires-Dist: psycopg[binary,pool]<4,>=3.3.4; extra == 'postgres'
Provides-Extra: sqlserver
Requires-Dist: mssql-django==1.7.4; extra == 'sqlserver'
Requires-Dist: pyodbc<6,>=5.3.0; extra == 'sqlserver'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: Copyright (C) 2026 Omid Jafari <omidjafari.com>
SPDX-License-Identifier: AGPL-3.0-or-later

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-->

# NLPMed Portal Lite

A lightweight, self-hosted research platform for clinical
natural language processing and annotation workflows.

[![CI](https://github.com/omid-jf/NLPMed-Portal-Lite/actions/workflows/ci.yml/badge.svg)](https://github.com/omid-jf/NLPMed-Portal-Lite/actions/workflows/ci.yml)
[![Codecov](https://codecov.io/gh/omid-jf/NLPMed-Portal-Lite/graph/badge.svg)](https://codecov.io/gh/omid-jf/NLPMed-Portal-Lite)
[![PyPI](https://img.shields.io/pypi/v/nlpmed-portal-lite.svg)](https://pypi.org/project/nlpmed-portal-lite/)
![Python](https://img.shields.io/badge/Python-3.12%20%7C%203.13%20%7C%203.14-blue)
![Django](https://img.shields.io/badge/Django-6.0-0C4B33)
![License](https://img.shields.io/badge/license-AGPLv3-blue)

> ⚠️ **Important:**
> NLPMed Portal Lite is research software. It has not been designed, validated,
> or approved for diagnosis, treatment, or other clinical decision-making.

## Features

- Clinical project, patient, note, and label management
- Patient-level, note-level, and named-entity annotation
- Annotation assignment, adjudication, history, import, and export workflows
- NLP preprocessing and model-inference integration
- Role-based access, project membership, auditing, and user management
- REST API with an OpenAPI schema and interactive API documentation
- PostgreSQL and SQL Server database support
- Installable command-line application

NLPMed Portal Lite preserves the annotation and portal functionality of the
[Full edition](https://github.com/omid-jf/NLPMed-Portal) while removing:

- LLM functionality and its dependencies
- Celery workers
- Redis
- Flower
- Distributed caching
- The Docker production stack

Background operations are executed synchronously. This makes the Lite edition
suitable for one or a few users and for environments where external services
cannot be installed.

## Optional NLP backend

External NLP preprocessing and model inference can be provided by
[NLPMed Engine](https://github.com/omid-jf/NLPMed-Engine), which is also
available from [PyPI](https://pypi.org/project/nlpmed-engine/).

The Portal and Engine are deployed separately. Set `DJANGO_NLP_API_URL` to
the Engine endpoint when enabling these features. Engine installation,
model configuration, and sentence-segmentation requirements are documented
in the NLPMed Engine repository.

## Requirements

- Python 3.12, 3.13, or 3.14
- An existing PostgreSQL or SQL Server database
- The appropriate database driver

SQLite is not supported because the application relies on transactional and
concurrent-write behavior intended for a server database.

## Installation

Choose the extra for the database backend you intend to use.

### PostgreSQL

Install the application and PostgreSQL driver with
[uv](https://docs.astral.sh/uv/):

```bash
uv tool install "nlpmed-portal-lite[postgres]"
```

Alternatively, install it inside an existing virtual environment:

```bash
python -m pip install "nlpmed-portal-lite[postgres]"
```

### SQL Server

First install Microsoft ODBC Driver 18 for SQL Server using the instructions
for your operating system.

Then install the application and SQL Server dependencies:

```bash
uv tool install "nlpmed-portal-lite[sqlserver]"
```

Alternatively:

```bash
python -m pip install "nlpmed-portal-lite[sqlserver]"
```

The SQL Server backend is tested against SQL Server 2025.

## Initial setup

Create a directory for the local configuration and runtime data:

```bash
mkdir nlpmed-portal-lite
cd nlpmed-portal-lite
```

Create the environment file:

```bash
nlpmed-portal-lite init
```

This creates `.env` without overwriting an existing configuration.

Edit `.env` and configure the application secret, database connection, allowed
hosts, CSRF origins, and registration behavior.

The database itself must already exist, and the configured database user must
have permission to create and modify its tables and indexes.

### PostgreSQL configuration

Use a PostgreSQL URL:

```dotenv
DJANGO_SECRET_KEY=replace-with-a-long-random-secret-key

DATABASE_URL=postgresql://nlpmed_portal:replace-with-a-database-password@127.0.0.1:5432/nlpmed_portal
DB_POOL=False
DB_ATOMIC_REQUESTS=True
```

### SQL Server configuration

Leave `DATABASE_URL` empty and configure the SQL Server connection:

```dotenv
DJANGO_SECRET_KEY=replace-with-a-long-random-secret-key

DATABASE_URL=
DB_ENGINE=mssql
DB_NAME=nlpmed_portal
DB_HOST=127.0.0.1
DB_PORT=1433
DB_USER=sa
DB_PASSWORD=replace-with-a-database-password
DB_POOL=False
DB_ATOMIC_REQUESTS=True
MSSQL_DRIVER=ODBC Driver 18 for SQL Server
MSSQL_EXTRA_PARAMS=Encrypt=yes;TrustServerCertificate=yes
```

For a production database, review the encryption and certificate options
instead of automatically trusting the server certificate.

## Running the application

Apply migrations and prepare the static assets:

```bash
nlpmed-portal-lite setup
```

This command:

1. Applies the existing Django migrations.
2. Collects static files.
3. Builds the compressed static assets.

Create the initial administrator:

```bash
nlpmed-portal-lite manage createsuperuser
```

Start the application:

```bash
nlpmed-portal-lite run
```

The application will be available at
[http://127.0.0.1:9090](http://127.0.0.1:9090).

The default server configuration is:

- Host: `127.0.0.1`
- Port: `9090`
- Workers: `2`

These values can be changed:

```bash
nlpmed-portal-lite run --host 127.0.0.1 --port 9090 --workers 2
```

## Application home

By default, NLPMed Portal Lite uses the current directory as its application
home. This directory stores:

- `.env`
- `staticfiles/`, created by `setup`
- `media/`, created when uploaded or generated files are first stored

A different directory can be selected with `--home`:

```bash
nlpmed-portal-lite --home /path/to/nlpmed-home init
nlpmed-portal-lite --home /path/to/nlpmed-home setup
nlpmed-portal-lite --home /path/to/nlpmed-home manage createsuperuser
nlpmed-portal-lite --home /path/to/nlpmed-home run
```

The global `--home` option must appear before the command.

The same directory can instead be selected with the
`NLPMED_PORTAL_HOME` environment variable.

## Django management commands

Use the `manage` command to run any Django management command:

```bash
nlpmed-portal-lite manage check
nlpmed-portal-lite manage migrate
nlpmed-portal-lite manage createsuperuser
nlpmed-portal-lite manage shell
```

## Network access and HTTPS

The application binds to `127.0.0.1` by default and is not exposed to other
machines.

If it must be accessed over a network:

1. Place it behind a properly configured HTTPS reverse proxy.
2. Set `DJANGO_ALLOWED_HOSTS`.
3. Set `DJANGO_CSRF_TRUSTED_ORIGINS`.
4. Set `DJANGO_ACCOUNT_ALLOW_REGISTRATION=False` unless public registration is
   explicitly required.
5. Enable `DJANGO_SECURE_SSL_REDIRECT` after HTTPS forwarding is working.
6. Protect the database and application-home directories.

The Lite package does not install or configure a database server, TLS
certificate, reverse proxy, or operating-system service.

## Source development

Clone the repository and install the locked dependencies with the required
database extra.

For PostgreSQL:

```bash
uv sync --locked --extra postgres
```

For SQL Server:

```bash
uv sync --locked --extra sqlserver
```

Create the source configuration:

```bash
cp .env.example .env
```

Edit `.env`, then apply migrations and start Django:

```bash
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver
```

The packaged CLI can also be exercised from the source checkout:

```bash
uv run nlpmed-portal-lite --version
uv run nlpmed-portal-lite init
```

## Testing

Run the test suite using the database configured in `.env`:

```bash
uv run pytest
```

Run the test suite with coverage:

```bash
uv run coverage run -m pytest
uv run coverage report
```

Run all configured formatting, linting, and static checks:

```bash
uv run pre-commit run --all-files
```

SQL Server compatibility is also tested separately in CI against SQL Server
2025.

## API documentation

When the application is running:

- API root: `/api/`
- OpenAPI schema: `/api/schema/`
- Interactive API documentation: `/api/docs/`

The interactive API documentation is restricted according to the configured
Django REST Framework permissions.

## Sphinx documentation

Install the documentation dependencies and build the Python API reference:

```bash
uv sync --locked --no-dev --group docs
uv run --locked --no-dev --group docs sphinx-build \
  -W \
  --keep-going \
  -b html \
  docs \
  docs/_build/html
```

Open `docs/_build/html/index.html` in a browser to inspect the generated
documentation.

The `docs/api` directory is generated automatically during the Sphinx build
and should not be edited manually.

## Demo

A public demonstration of selected NLPMed Portal features is available at
[https://nlpmed.demo.angli-lab.com](https://nlpmed.demo.angli-lab.com).

## License and research-use notice

NLPMed Portal Lite is licensed under the
[GNU Affero General Public License v3.0 or later](https://github.com/omid-jf/NLPMed-Portal-Lite/blob/HEAD/LICENSE).

Important research-use and deployment considerations are described in the
[Research Use and Deployment Notice](https://github.com/omid-jf/NLPMed-Portal-Lite/blob/HEAD/TERMS.md).
This notice does not modify or add restrictions to the AGPL.
