# GraphShieldMistral

GraphShieldMistral is the NetworkX graph layer for the Shieldstral MLX hierarchical classifier. It converts the published 12/26/52 policy hierarchy and reconciled scenario results into an understandable policy network.

## Classification states

GraphShieldMistral does not equate every leaf-less result with safety. Scenario nodes use four explicit states:

- **SAFE**: no raw or descendant-supported unsafe-policy match was observed;
- **UNRESOLVED**: broad or raw unsafe-policy matches were observed, but no descendant leaf was validated;
- **CLASSIFIED**: exactly one descendant leaf was validated;
- **AMBIGUOUS**: multiple descendant leaves were validated, with the highest-scoring leaf retained as primary and all secondary leaves shown.

This prevents a result such as strong `SC5 Cybercrime` and `SUB012 System Attacks` matches without `CAT024 Malware` from being displayed as safe. It is shown as **UNRESOLVED** with its raw unmatched branches.

## Diagnostic contracts

Live examples distinguish **classification correctness** from **classification isolation**. A positive example can remain useful when the intended category is primary but the model also emits secondary leaves. For that reason, scenario contracts can define:

- an intended primary category;
- whether a named leaf must be present or absent;
- one or more acceptable presentation states.

For example, Consumer Fraud and Pollution require `CAT019` and `CAT048` respectively to remain primary, while accepting either `CLASSIFIED` or `AMBIGUOUS`. Extra leaves are never discarded; they remain visible as secondary matches. The malware leaf-miss diagnostic requires `CAT024` to be absent and the state to remain `UNRESOLVED`.

This prevents strict verification from treating an observed multi-label output as a graph implementation failure while still rejecting the wrong primary category, a missing required category, or an invalid status.

## What the graph exposes

- exact input documents and classification instructions;
- exact policy queries for every named hierarchy node;
- classification status, reason, primary class and primary score;
- validated leaves and secondary matched leaves;
- raw unmatched branches and hierarchy-consistency state;
- expected diagnostic categories for controlled scenarios;
- deterministic superclass clusters and safe similar examples;
- scenario clusters, GraphML, node-link JSON, offline HTML, SVG and cluster summaries;
- optional empirical communities over repeated validated leaf co-occurrence.

Taxonomy-only nodes never display fabricated zero scores. They are marked **not evaluated** until a supplied scenario evaluates them.

## Quick start

```bash
python -m pip install -r graphShieldMistral/requirements.txt

./graphShieldMistral/scripts/run_examples.sh

open graphShieldMistral/outputs/examples/taxonomy/classification-network.html
open graphShieldMistral/outputs/examples/malware/classification-network.html
```

## Build from one classification

```bash
./graphShieldMistral/scripts/build_graph.sh   --result reports/local/graph-inputs/malware.json   --output-dir reports/local/graphshield-malware
```

## Run live diagnostic scenarios

Start the local MLX endpoint on port `18190`, then:

```bash
WORKERS=2 MODE=exhaustive ./graphShieldMistral/scripts/run_live_scenarios.sh
```

The runner clears stale demonstration JSON by default and executes five scenarios:

1. malware classified positive control;
2. malware broad-match / leaf-miss diagnostic;
3. unlawful-confinement ambiguity probe;
4. consumer-fraud classification;
5. pollution classification.

Set `RESET_RESULTS=0` only when intentionally retaining other JSON files in the result directory.

The model remains a binary policy-query classifier. GraphShieldMistral is a downstream graph and clustering layer over named, hierarchy-reconciled outputs. It does not claim that Shieldstral learned the taxonomy or that NetworkX communities are official model categories.

<!-- BEGIN GRAPHSHIELD_MODEL_CARD_LINK -->
## Model-card integration

The Hugging Face model card presents both consumer paths:

1. the existing direct named classifier;
2. the optional GraphShieldMistral visualisation and graph-export layer.

The model-card image is stored at:

```text
graphShieldMistral/assets/graph-classifier-map.png
```

The image is a recorded example, not a live dashboard. Generate a fresh HTML, SVG, JSON and GraphML bundle from the current classifier output before auditing a new document.
<!-- END GRAPHSHIELD_MODEL_CARD_LINK -->