graphShieldMistral/README.md

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

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

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

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.

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:

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.