docs/GRAPHSHIELD_MISTRAL.md

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:

./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.

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

Recorded example

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:

./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.