shadow-perception-kaggle

Shadow Perception — Kaggle vertical

Five-voice deterministic pre-submit council for Kaggle notebooks. Deterministic — no LLM call in the verdict path.

When to use

The user's request is any variant of:

• "Should I submit this notebook to Kaggle?"
• "Any leakage in this notebook?"
• "Is my Kaggle submission reproducible?"
• "Did I accidentally use protected-class features?"

Or the user points at a .ipynb file and asks for feedback before submit.

What it does

1. shadow_perception_scan(notebook_path) — parses the .ipynb into a structured observation (imports, function definitions, seed pinning, file reads/writes, detected leakage patterns).
2. shadow_perception_council(observation) — runs the 5-voice council:
   • Leakage — 5 heuristic patterns (fit_transform on test, fit before split, target in features, temporal shuffle, future data in training).
   • Fairness — flags protected-class proxy terms in source.
   • Reproducibility — checks seed pinning + kernel spec + imports.
   • Compliance — flags external data reads outside standard competition paths.
   • Ops — checks for submission artifact.
3. shadow_perception_attest(observation, verdict) — Ed25519 signs the verdict so it can be shared with a teammate or attached to a Kaggle submission as proof of pre-submit review.

The named invariants

1. Leakage detector is heuristic + advisory. REWORK, not BLOCK. Missing hits are possible; false positives are possible. Do not claim "no leakage" on the basis of this scan alone.
2. Fairness voice is US-ECOA / GDPR Art. 9 flavored. Kaggle competitions may use public-data features that would be prophylactically blocked in production; that mismatch is intentional. Human review remains load-bearing.
3. Ops voice BLOCK on missing submission — this is the one BLOCK-authority voice. All others are REWORK-authority.
4. Deterministic council. Same notebook + same code path = same verdict, always. No LLM randomness.

Non-goals