docs(medcat-trainer) docs improvement / overhaul

medcat-trainer/docs/admin_setup.md

@@ -1,25 +1,48 @@
 # Administrator Setup
 
-1\.  The container runs a vanilla [django](https://www.djangoproject.com/) app, that upon initially loaded
-will create a defaulted administrator user with details:
+This page covers first-login admin hardening and user setup.
 
-<pre>
-    username: admin
-    password: admin
-</pre>
+## 1) Configure bootstrap admin credentials
 
-2\. We strongly recommend creating a new admin user before using the trainer in 'production' and storing sensitive
-clinical documents on the trainer. To add a new user navigate to select `http://localhost:8001/admin/` and select 'Users'.
+Before first startup in production-like environments, set:
 
-![](_static/img/users-select.png)
+- `MCTRAINER_BOOTSTRAP_ADMIN_USERNAME`
+- `MCTRAINER_BOOTSTRAP_ADMIN_EMAIL`
+- `MCTRAINER_BOOTSTRAP_ADMIN_PASSWORD`
 
-3\. Select 'Add User' and complete the form with a new username / password.
+If not set, MedCATtrainer defaults to `admin` / `admin`, which is not suitable
+for production.
 
-![](_static/img/add-new-users.png)
+## 2) Sign in and create operational admin users
 
-4\. Once created, select the new user, and tick the 'Staff Status' or 'Superuser Status' to allow the user to
-access the admin app.
+You can manage users from:
 
-5\. Remove the default admin user by navigating to step 2, select the user and the action
+- **Project Admin UI** (`/project-admin`) for day-to-day project operations
+- **Django Admin** (`/admin`) for full platform administration
 
-![](_static/img/remove-default-user.png)
+In Django admin (`/admin`), create at least one dedicated administrator account
+and grant:
+
+- `Staff status` for admin access
+- `Superuser status` for full unrestricted access
+
+## 3) Create annotator users
+
+Create users for annotators and add them to project membership lists.
+Annotators do not need staff/superuser flags.
+
+## 4) Remove or rotate bootstrap credentials
+
+After creating named administrator accounts:
+
+- remove the default bootstrap account if it is no longer needed, or
+- rotate its password and store credentials securely.
+
+## 5) If using OIDC
+
+When `USE_OIDC=1`, user permissions are mapped from IdP roles:
+
+- `medcattrainer_superuser` -> Django superuser + staff
+- `medcattrainer_staff` -> Django staff
+
+Ensure role assignment is correct in Keycloak before onboarding users.

medcat-trainer/docs/advanced_usage.md

@@ -1,3 +1,78 @@
 # Advanced Usage
 
-- ReST API Usage for bulk dataset / project creation: available in: docs/API_Examples.ipynb
+This page covers API-first workflows and power-user features.
+
+## Notebook examples
+
+The repository includes notebook examples:
+
+- `notebook_docs/API_Examples.ipynb`
+- `notebook_docs/Processing_Annotations.ipynb`
+
+These are useful for bulk project creation, export processing, and automation.
+
+## REST API basics
+
+Base path: `/api/`
+
+Common endpoints:
+
+- `GET/POST /api/project-annotate-entities/`
+- `GET/POST /api/datasets/`
+- `GET/POST /api/modelpacks/`
+- `GET/POST /api/concept-dbs/`
+- `GET/POST /api/vocabs/`
+
+### Authentication
+
+- Local auth token: `POST /api/api-token-auth/`
+- OIDC bearer token (if enabled): send `Authorization: Bearer <token>`
+
+## Project Admin API endpoints
+
+Modern project-admin UI uses dedicated endpoints:
+
+- `GET /api/project-admin/projects/`
+- `POST /api/project-admin/projects/create/`
+- `GET/PUT/DELETE /api/project-admin/projects/<project_id>/`
+- `POST /api/project-admin/projects/<project_id>/clone/`
+- `POST /api/project-admin/projects/<project_id>/reset/`
+
+## Metrics APIs
+
+- `GET/POST /api/metrics-job/` (list jobs / submit new report)
+- `DELETE /api/metrics-job/<report_id>/` (remove report job)
+- `GET/PUT /api/metrics/<report_id>/` (fetch report / rename report)
+
+Only compatible projects should be combined (same underlying model
+configuration) when generating reports.
+
+## Concept exploration and filter export
+
+Use the **Concepts** view (`/model-explore`) to:
+
+- browse hierarchy paths,
+- choose parent concepts,
+- generate and export JSON filter lists for project CUI filters.
+
+Related API endpoints:
+
+- `POST /api/generate-concept-filter/`
+- `POST /api/generate-concept-filter-json/`
+- `GET /api/model-concept-children/<cdb_id>/`
+
+## Remote model service projects
+
+Projects can use a remote MedCAT model service instead of local model loading
+by setting:
+
+- `use_model_service = true`
+- `model_service_url = <service-base-url>`
+
+Operational note: train-on-submit updates are not applied for remote model
+service projects.
+
+## Python client
+
+For scripting and CI pipelines, see [client.md](client.md) and the `mctclient`
+package.

medcat-trainer/docs/annotator_guide.md

@@ -1,72 +1,93 @@
 # Annotation Interface
 
-The annotation interface can be split into 5 sections.
+The annotator view is designed for fast review and correction of model
+predictions.
 
 ![](_static/img/main-annotation-interface.png)
 
-## Section 1 - Document Summary List
-A list of documents to be completed in this project. Currently selected documents are highlighted in blue
-left border. Submitted documents are marked with a ![tick_mark](_static/img/tick_mark.png).
-
-## Section 2 - Clinical Text
-The selected documents text, highlighted with each concept recognised by the configured MedCAT model.
-Highlighted spans of text indicate status of the annotation:
-- Grey: A User has *not reviewed* this span that has been recognised and linked by MedCAT to a CDB concept.
-- Blue: A User has reviewed the span and marked it as ***correct*** in terms of its linked MedCAT concept.
-- Red: A User has reviewed the span and marked it as **incorrect** in terms of its linked MedCAT concept.
-- Dark Red: A User has reviewed the span and marked it to **terminate**, meaning the text span should never again
-  link to this text span, this informs MedCAT that
-- Turqoise: A User has reviewed the span and marked it as an  **alternative** linked concept. The user has used the
-  'Concept Picker' to choose the correct concept that should be linked.
-
-### Additional Annotations
-MedCAT may miss text spans that are acronyms, abbreviations or misspellings of concepts. Missing annotations can be
-added to the text by directly highlighting the text span, right clicking, selecting 'Add Term', searching for
-concept (via ID, or name), and selecting Add Term:
-
-![](_static/img/add-annotation-text.png) -> ![](_static/img/add-annotation-menu.png) -> ![](_static/img/add-annotation-concept-pick.png)
-
-Select:
-- Add Term: to add this annotation to the text span and link the selected concept
-- Cancel: (Shortcut esc): to cancel adding the annotation to the text.
-
-![](_static/img/add-annotation-select-concept.png)
-
-## Section 3 - Action Bar
-
-### Concept Navigation
-Navigating between the list of concepts as they appear in the document:
-- Action buttons, left and right
-- Left and right arrow keys on keyboard
-- Directly clicking on the concept within the text.
-
-
-### Concept Status Buttons
-A concept can be marked with only one status. Status is recorded but only sent to MedCAT for
-training on **submit** of the document and if the projects configured with "Train Model On Submit" is ticked.
-
-### Submit Button
-Submit is disabled until all concepts have been reviewed and marked with a status. Clicking submit will produce  
-a submission confirmation dialog with an annotation summary. Confirming submission will send all new annotations
-to MedCATTrainer middle tier, and re-train the MedCAT model. The following document will be selected and annotated
-by the newly trained MedCAT model
-
-## Section 4 - Header Toolbar
-Lists the current name of the document under review and the number of remaining documents to annotate in this project
-action buttons for:
-- ![](_static/img/summary-button.png): Summary of current annotations. f A similar view is shown before confirmation of submission of the annotations
-- ![](_static/img/help-button.png): Help dialog, showing shortcuts for document & concept navigation, concept annotation and submission.
-- ![](_static/img/reset-button.png): Reset document. If an annotation is incorrectly added, or incorrectly submitted resetting the document will
-  clear all previous annotations and their status.
-
-## Section 5 - Concept Summary
-Lists the current selected concepts details.
-
-|Concept Detail| Description |
-|--------------| ------------|
-|Annotated Text| The text span linked to the concept|
-|Name          | The linked concept name from within the MedCAT CDB|
-|Type ID       | The higher level group of concepts that this concept sits under. This may be 'N/A' depending if your CDB has Type IDs or not.|
-|Concept ID    | The unique identifier for this linked concept from the MedCAT CDB.|
-|Accuracy      | The MedCAT found accuracy of the linked concept for this span. Text spans will have an accuracy 1.0, if they are uniquely identified by that name in the CDB|
-|Description   | The MedCAT associated description of the concept. SNOMED-CT does not provide descriptions of concepts, only alternative names whereas UMLS does provide descriptions|
+## 1) Document list
+
+The left panel shows documents in the project dataset.
+
+- Current document is highlighted.
+- Prepared documents (model predictions generated) are marked.
+- Submitted/validated documents are marked as complete.
+
+## 2) Clinical text
+
+The center panel displays document text with detected concept spans.
+
+Select spans by clicking them directly, then apply one status from the task bar.
+
+### Supported concept statuses
+
+- **Correct**
+- **Incorrect**
+- **Terminate** (if enabled for project)
+- **Alternative** (choose a different concept)
+- **Irrelevant** (if enabled for project)
+
+Only one status can be active per concept at a time.
+
+### Adding missing annotations
+
+If the model missed a mention:
+
+1. Highlight text in the document.
+2. Right-click and choose **Add Term**.
+3. Search/select a concept in the concept picker.
+4. Confirm to create the annotation.
+
+Projects with `add_new_entities` enabled can also create brand-new concepts.
+
+Overlapping annotations are supported.
+
+## 3) Task bar and submission
+
+The task bar contains status buttons and the **Submit** button.
+
+- Submit is enabled only when required tasks are completed for all concepts.
+- On submit, a confirmation dialog shows an annotation summary.
+- If project `train_model_on_submit` is enabled, submitted annotations are used
+  for incremental model updates (except remote model-service projects).
+
+## 4) Header actions
+
+Top-right actions:
+
+- **Summary**: open document annotation summary.
+- **Help**: keyboard shortcuts and project guidance.
+- **Reset document**: re-prepare current document and clear document-level
+  annotation state.
+
+## 5) Right sidebar (concept details)
+
+The sidebar shows details for the currently selected concept, including:
+
+- concept name/CUI
+- type IDs/semantic type (if available)
+- synonyms and description
+- confidence score
+
+If enabled by project settings, a **Comment** field is also available.
+
+## Meta annotations and relations
+
+Depending on project configuration:
+
+- **Meta Annotation Tasks** appear for relevant concept statuses.
+- **Relation** tab appears to create/edit relations between annotated entities.
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|---|---|
+| Up / Down | Previous / next document |
+| Left / Right (or Space) | Previous / next concept |
+| `1` | Correct |
+| `2` | Incorrect |
+| `3` | Terminate (if enabled) |
+| `4` | Alternative |
+| `5` | Irrelevant (if enabled) |
+| Enter | Submit / confirm submit |
+| Esc | Close active modal/cancel active add-term flow |