File size: 4,542 Bytes
e6d9aa8 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | # 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 -->
|