# GraphShieldMistral: Named Classification to Policy Graphs

GraphShieldMistral is an optional NetworkX-based layer over Shieldstral's named hierarchical classifier.

## Two complementary interfaces

### Direct classifier

The direct classifier remains the primary machine-readable interface:

```bash
./scripts/hierarchical_classify.sh   "A request asks for a malicious executable that encrypts files on a victim computer."   --mode exhaustive   --workers 2   --top 0
```

Its JSON records raw matches, descendant-supported matches, the primary leaf, validated path, secondary leaves, ambiguity, orphan matches and hierarchy consistency.

### Graph view

GraphShieldMistral consumes that JSON and creates:

- an interactive HTML graph;
- a static SVG;
- GraphML for NetworkX, Neo4j import or other graph tooling;
- JSON node-link data;
- a cluster and scenario summary.

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

## Recorded example

![GraphShieldMistral hierarchical classification and scenario cluster map](../graphShieldMistral/assets/graph-classifier-map.png)

The example demonstrates the complete hierarchy, superclass clusters, scenario nodes, observed match types and the detail panel containing the submitted document and policy query. The image is a recorded output, not a live model result.

## Classification status semantics

- `SAFE`: no raw unsafe match and no validated leaf.
- `UNRESOLVED`: raw or broad unsafe matches exist, but no leaf is validated.
- `CLASSIFIED`: exactly one descendant leaf is validated.
- `AMBIGUOUS`: multiple descendant leaves are validated; the highest-scoring leaf is primary and the remaining leaves stay visible.

## Verification

The downloaded model release includes:

```bash
./scripts/verify_graphshield.sh
```

It checks the image, graph code, direct classifier files and taxonomy, then generates fresh taxonomy and scenario graphs in a temporary directory and validates their GraphML node and edge counts.

The project-level remote verifier additionally downloads the graph subset anonymously from Hugging Face and runs the same generation check after the base model, checksum and deterministic classification checks pass.

## Scope

The hierarchy supplies deterministic structural clusters. NetworkX performs visualisation, export and optional co-classification community analysis. GraphShieldMistral does not change Shieldstral's prediction and does not claim that the model learned or discovered the published taxonomy.