> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Role-Aware Adverse Media Guide
> How to configure role-aware adverse media labels and filtering across Minerva screening workflows.
export const StorybookFrame = ({storyId, title, version = "20260419-1", height, zoom = 0.7, preferLocalPreview = false}) => {
const HOSTED_STORYBOOK_BASE_URL = "https://minerva-storybook.s3.ca-central-1.amazonaws.com/iframe.html";
const isLocalDocsPreview = typeof window !== "undefined" && ["localhost", "127.0.0.1"].includes(window.location.hostname);
const storybookBaseUrl = preferLocalPreview && isLocalDocsPreview ? "http://localhost:6006/iframe.html" : HOSTED_STORYBOOK_BASE_URL;
const params = new URLSearchParams({
id: storyId,
viewMode: "story",
singleStory: "true",
shortcuts: "false",
toolbar: "0",
nav: "0",
panel: "0"
});
params.set("v", version);
const src = `${storybookBaseUrl}?${params.toString()}`;
const unscaledHeight = `${Math.ceil(height / zoom)}px`;
const unscaledWidth = `${100 / zoom}%`;
return ;
};
Role-aware adverse media helps Minerva distinguish adverse media articles that appear to involve the screened subject from articles that only mention the same or a similar name.
**Access:** Requires the Admin role or above. In the sidebar, go to Administration > Configuration, then open Role-Aware Adverse Media under Screening behaviours.
Use this guide when you need to:
* understand what role-aware adverse media controls
* choose between Hint Mode and Decision Mode
* tune confidence thresholds by workflow
* understand the visible article labels and API metadata
* review, audit, or roll back role-aware changes
Role-aware adverse media is workspace-scoped. Use a Calibration workspace to
review labels and thresholds before applying stricter behavior in Live.
Decision Mode can change which adverse-media potential matches analysts see.
Start in Hint Mode when calibrating, review examples, and save clear change
descriptions before moving to automatic filtering.
## How Role-Aware Adverse Media Works
Role-aware adverse media runs after Minerva has retrieved and analyzed news or open-source articles. It does not broaden article retrieval on its own.
At a high level, Minerva:
1. retrieves articles from the selected adverse media sources
2. identifies negative or risky articles through adverse-media analysis
3. checks whether each qualifying article appears related to the screened subject
4. either shows the result as an article label or uses it to filter unrelated adverse-media hits, depending on the workflow configuration
Role-aware adverse media complements match scoring. Match scoring controls
candidate thresholds; role-aware adverse media controls confident
article-subject relevance signals after article analysis.
## Main Configuration Page
The Role-Aware Adverse Media page is organized by workflow, so each screening path can have its own posture.
Minerva currently separates:
| Workflow | What it covers |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| Onboarding | Screening performed during customer or profile onboarding. |
| Ongoing monitoring | Background monitoring checks for existing profiles. |
| Direct API calls | API-driven screening submissions. |
| Risk assessments | Risk assessment searches, including adverse-media-only and combined source searches. |
## Controls
### Enable Role-Aware Insights
Turn on Enable role-aware insights when you want Minerva to run role-aware checks for a workflow. When this setting is off, role-aware thresholds do not affect that workflow.
### Automatic Role-Based Filtering
After role-aware insights are enabled, choose how Minerva should use the output:
| Mode | Behavior | When to use it |
| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Hint Mode | Shows qualifying role-aware article labels while keeping adverse media alerts unchanged. | Use first when calibrating or when analysts should see the model output as review context. |
| Decision Mode | Shows qualifying labels and filters unrelated adverse-media hits above the confidence threshold. | Use after reviewing examples and deciding that confident non-subject articles should not create alerts. |
### Role-Aware Confidence Threshold
The Role-aware confidence threshold controls when labels and Decision Mode removals apply.
* range: 0.00 to 1.00
* default: 0.50
* higher values are stricter and require stronger model confidence
* lower values are broader and can show or filter more articles
## Analyst-Facing Labels
When role-aware output is visible, Minerva can show these adverse-media article labels:
| Label | Meaning |
| --------------------------------------- | ------------------------------------------------------------------- |
| Potentially implicated | The article appears related to the screened subject. |
| Secondary mention | This person appears in the article, but not as the primary subject. |
These labels are review aids. They do not replace analyst review of the article, source context, and full screening result.
## API and Export Output
When role-aware metadata is present, returned adverse-media articles can include a role\_aware\_prediction object.
```json theme={null}
{
"role_aware_prediction": {
"label": "non-suspect",
"related_to_subject": false,
"score": 0.91,
"suspect_prob": 0.09,
"non_suspect_prob": 0.91
}
}
```
The label is suspect or non-suspect. The related\_to\_subject field is the boolean form of that label, and score is the confidence score for the selected label.
Role-aware metadata is optional. It appears only when the workflow is configured to run role-aware checks, the article qualifies for analysis, and the model confidence meets the configured threshold.
## Relationship to Match Scoring
News and adverse-media tuning has three related layers:
| Layer | What it controls |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| News retrieval controls | Which articles are retrieved, admitted, capped, or location-enriched before scoring. |
| Match scoring | Which source candidates survive pre-resolution and post-resolution thresholds. |
| Role-aware adverse media | Whether adverse articles appear to involve the screened subject or only mention a name. |
For threshold and News retrieval details, see the [Match Scoring Guide](/match-scoring-guide).
## Recommended Tuning Approach
Use this sequence when calibrating role-aware adverse media:
1. Start in Hint Mode for the workflow you want to evaluate.
2. Review common-name and article-mention false positives.
3. Compare role-aware labels against the underlying articles and analyst decisions.
4. Raise the threshold if labels feel too uncertain.
5. Lower the threshold only after reviewing representative examples.
6. Move to Decision Mode when confident non-subject articles should stop contributing to adverse-media alerts.
7. Tune one workflow at a time and save a clear change description.
## Reviewing and Confirming Changes
When you click Review changes, Minerva shows a grouped confirmation view before anything is saved.
The review dialog shows:
* the number of changes and sections affected
* each workflow with changed role-aware insight settings
* each changed Hint Mode or Decision Mode setting
* each changed confidence threshold
* an optional Change Description field
Use the change description to capture the reason for the calibration, such as a false-positive review, a Calibration-to-Live rollout, or a post-launch monitoring adjustment.
## Deployment History and Rollback
The Role-Aware Adverse Media page includes history and rollback tools so you can audit prior deployments and restore an older configuration when needed.
The full history page includes:
* Changed: when the configuration was saved or rolled back
* Action: whether the event was an update or rollback
* Summary: the key role-aware changes
* Changed by: the user who performed the change
* Actions: rollback entry points for older deployments
Rollback restores a previous deployment by writing a new history entry. It does not delete prior history.
## Related Guides
* [Adverse Media](/concepts/adverse-media)
* [Match Scoring Guide](/match-scoring-guide)
* [Screening Guide](/screening-guide)
* [Repeated Alert Suppression Guide](/alert-suppression-guide)
* [Workspaces Guide](/workspaces-guide)
* [Risk Assessment Flow](/risk-assessment-flow)