NLPMed Portal Lite

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

⚠️ 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 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, which is also available from PyPI.

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:

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

Alternatively, install it inside an existing virtual environment:

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:

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

Alternatively:

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:

mkdir nlpmed-portal-lite
cd nlpmed-portal-lite

Create the environment file:

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:

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:

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:

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:

nlpmed-portal-lite manage createsuperuser

Start the application:

nlpmed-portal-lite run

The application will be available at 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:

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:

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:

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:

uv sync --locked --extra postgres

For SQL Server:

uv sync --locked --extra sqlserver

Create the source configuration:

cp .env.example .env

Edit .env, then apply migrations and start Django:

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:

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

Testing

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

uv run pytest

Run the test suite with coverage:

uv run coverage run -m pytest
uv run coverage report

Run all configured formatting, linting, and static checks:

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:

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.

License and research-use notice

NLPMed Portal Lite is licensed under the GNU Affero General Public License v3.0 or later.

Important research-use and deployment considerations are described in the Research Use and Deployment Notice. This notice does not modify or add restrictions to the AGPL.