jimnoneill
/

pubguard-classifier

@@ -1,219 +0,0 @@
-# PubVerse Error Codes
-> *"Every rejection is a learning opportunity. Mostly for the person who tried to sneak a pool party flyer into a metagenomics pipeline."*
-## Error Code Format
-```
-PV-SXNN
- │ ││└┘
- │ ││ └─ Detail code (00-99)
- │ │└─── Sub-category
- │ └──── Step number (0-8)
- └────── PubVerse prefix
-```
-All error codes are printed to **stdout** as a single line:
-```
-PV-0301 | JUNK_DETECTED | That's not a paper, that's a cry for help (score=1.000)
-```
----
-## Step 0 — PubGuard Screening
-The bouncer at the door. If your PDF can't get past here, it definitely
-shouldn't be anywhere near a GNN.
-The PubGuard codes embed the classifier indices directly:
-`PV-0{doc_type}{ai_detect}{toxicity}` where each digit is the
-predicted class index.
-| Code | Name | What Happened |
-|------|------|---------------|
-| **PV-0000** | `ALL_CLEAR` | Paper passed screening. Welcome to the lab. |
-| **PV-0100** | `POSTER_DETECTED` | That's a poster, not a paper. We appreciate the aesthetic effort, but we need Methods, not bullet points on a corkboard. |
-| **PV-0200** | `ABSTRACT_ONLY` | We got the trailer but not the movie. Where's the rest of the paper? |
-| **PV-0300** | `JUNK_DETECTED` | That's not a paper, that's a cry for help. Pool party invitations, invoices, and fantasy football drafts do not constitute peer-reviewed research. |
-| **PV-0010** | `AI_GENERATED` | Our classifier thinks a robot wrote this. Not necessarily disqualifying, but noted for the record. The Turing test starts at the Introduction. |
-| **PV-0001** | `TOXIC_CONTENT` | Content flagged as potentially toxic. Science should be provocative, not offensive. |
-| **PV-0310** | `JUNK_AND_AI` | AI-generated junk. Congratulations, you've automated mediocrity. |
-| **PV-0301** | `JUNK_AND_TOXIC` | Toxic junk. This is somehow worse than a pool party flyer. |
-| **PV-0311** | `JUNK_AI_TOXIC` | The trifecta. AI-generated toxic junk. We'd be impressed if we weren't horrified. |
-| **PV-0110** | `POSTER_AND_AI` | An AI-generated poster. The future is here and it's making conference posters. |
-| **PV-0210** | `ABSTRACT_AI` | An AI-generated abstract with no paper attached. Peak efficiency. |
-### Composite Code Encoding
-The three middle digits encode each classifier head's prediction index:
-```
-PV-0 [doc_type] [ai_detect] [toxicity] NN
-      │          │           │
-      │          │           └─ 0=clean, 1=toxic
-      │          └───────────── 0=human, 1=ai_generated
-      └──────────────────────── 0=scientific_paper, 1=poster,
-                                 2=abstract_only, 3=junk
-```
-So `PV-0000` = scientific_paper + human + clean = **PASS**.
-Any non-zero digit in the doc_type position = **hard gate (blocked)**.
-Non-zero in ai/toxicity = **soft flag (reported, not blocked by default)**.
-### Special PubGuard Codes
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-0900** | `EMPTY_INPUT` | You sent us nothing. Literally nothing. The void does not require peer review. |
-| **PV-0901** | `UNREADABLE_PDF` | We can't read this PDF. Neither could PyMuPDF. If your PDF parser can't parse it, maybe it's not a PDF. |
-| **PV-0902** | `MODELS_MISSING` | PubGuard models not found. Run training first: `cd pub_check && python scripts/train_pubguard.py` |
-| **PV-0999** | `GATE_BYPASSED` | PubGuard screening was skipped (PUBGUARD_STRICT=0). Proceeding on faith. Good luck. |
----
-## Step 1 — PDF Feature Extraction
-Where we turn your lovingly formatted PDF into tab-separated values.
-The VLM does its best.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-1000** | `EXTRACTION_OK` | Features extracted successfully. The VLM read your paper and didn't crash. |
-| **PV-1100** | `EXTRACTION_FAILED` | VLM feature extraction failed. Your PDF defeated a 7-billion parameter model. Impressive, actually. |
-| **PV-1101** | `NO_TSV_OUTPUT` | Extraction ran but produced no output file. The VLM started reading and apparently gave up. |
-| **PV-1102** | `VLM_TIMEOUT` | Feature extraction timed out. Your PDF is either very long or very confusing. |
-| **PV-1200** | `VLM_NOT_FOUND` | Feature extraction script not found. Did someone move `qwen3_local_feature_extraction_cli.py`? |
----
-## Step 2 — PubVerse Analysis
-The main event. Clustering, impact analysis, topic modeling — the works.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-2000** | `ANALYSIS_OK` | PubVerse analysis completed. Your paper has been weighed, measured, and clustered. |
-| **PV-2100** | `ANALYSIS_FAILED` | App_v5.py crashed. This is the big one — check the logs. |
-| **PV-2101** | `STOPWORDS_MISSING` | Stopwords pickle not found. You can't do NLP without knowing which words to ignore. |
-| **PV-2102** | `DATASET2_MISSING` | Reference dataset not found. We need something to compare your paper against. |
-| **PV-2103** | `RECYCLE_MISSING` | Recycle overlay pickle not found. The cached cluster state is gone. Time to rebuild (grab coffee). |
----
-## Step 3 — Artifact Verification
-Making sure Step 2 actually produced what it promised.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-3000** | `ARTIFACTS_OK` | All expected files found. The pipeline is holding together. |
-| **PV-3100** | `MATRIX_MISSING` | Unified adjacency matrix not found. PubVerse ran but didn't produce the matrix. Something went sideways in clustering. |
-| **PV-3101** | `PICKLE_MISSING` | Impact analysis pickle not found. The most important intermediate file is AWOL. |
----
-## Step 4 — Graph Construction
-Building the knowledge graph. Nodes, edges, the whole beautiful mess.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-4000** | `GRAPH_OK` | Knowledge graph constructed. It's a beautiful web of science. |
-| **PV-4100** | `GRAPH_FAILED` | Graph construction failed. 42dt_graph_clean_cli.py didn't make it. |
-| **PV-4101** | `GRAPH_PICKLE_MISSING` | Graph pickle not produced. The nodes existed briefly, like a postdoc's optimism. |
----
-## Step 5 — 42DeepThought Scoring
-The GNN scores your paper. This is where GPUs earn their electricity bill.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-5000** | `SCORING_OK` | 42DeepThought scored your paper. May the odds be in your favor. |
-| **PV-5100** | `SCORING_FAILED` | GNN scoring crashed. Check CUDA, check the graph, check your assumptions. |
-| **PV-5101** | `NO_GRAPH_PICKLE` | Graph pickle file not found for scoring. Step 4 must have failed silently. |
-| **PV-5102** | `NO_SCORES_OUTPUT` | Scoring ran but produced no TSV. The GNN had nothing to say about your paper. |
-| **PV-5103** | `CHECKPOINT_CORRUPT` | Model checkpoint failed to load. Delete `deepthought_model.pt` and retrain. |
-| **PV-5200** | `DEEPTHOUGHT_MISSING` | 42DeepThought directory not found. The entire scoring engine is missing. |
-| **PV-5201** | `LABELS_MISSING` | `42d_scoring.tsv` not found. No reference labels means no supervised scoring. |
----
-## Step 6 — Cluster Similarity Analysis
-Finding your paper's neighbors in topic space.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-6000** | `CLUSTER_OK` | Cluster analysis complete. Your paper's social circle has been mapped. |
-| **PV-6100** | `CLUSTER_FAILED` | Cluster analysis crashed. Your paper is a loner — or the code is. |
-| **PV-6101** | `NO_SANITY_PICKLE` | Sanitycheck pickle not found. Can't do cluster analysis without clusters. |
-| **PV-6102** | `DB_TIMEOUT` | Cluster database population timed out (>1 hour). The LLM is still thinking. |
-| **PV-6103** | `NO_QUERY_ID` | Could not extract query paper ID from TSV. Who are you, even? |
-| **PV-6200** | `CLUSTER_SKIPPED` | Cluster analysis skipped (prerequisites not met). Not fatal, just lonely. |
----
-## Step 7 — Data Enrichment
-Merging all the analysis results into one JSON payload.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-7000** | `ENRICH_OK` | Data enrichment complete. Everything is unified and beautiful. |
-| **PV-7100** | `ENRICH_FAILED` | Enrichment script crashed. The data refused to be unified. |
-| **PV-7200** | `ENRICH_SKIPPED` | Enrichment skipped (cluster analysis didn't complete). Can't enrich what doesn't exist. |
----
-## Step 8 — Interactive Visualization
-The grand finale. Turning data into something you can click on.
-| Code | Name | Description |
-|------|------|-------------|
-| **PV-8000** | `VIZ_OK` | Visualization generated. Open the HTML and admire your knowledge graph. |
-| **PV-8100** | `VIZ_FAILED` | Visualization generation failed. You'll have to imagine the graph. |
-| **PV-8200** | `VIZ_SKIPPED` | Visualization skipped (enrichment didn't complete). No data, no graph, no glory. |
----
-## Exit Code Summary
-The pipeline exits with the **first fatal error code's step number**:
-| Exit Code | Meaning |
-|-----------|---------|
-| `0` | Success — all steps completed (or non-fatal warnings only) |
-| `1` | Step 0 — PubGuard rejected the input |
-| `2` | Step 1 — Feature extraction failed |
-| `3` | Step 2 — PubVerse analysis failed |
-| `4` | Step 3 — Required artifacts missing |
-| `5` | Step 4 — Graph construction failed |
-| `6` | Step 5 — 42DeepThought scoring failed |
-| `7` | Step 6 — Cluster analysis failed (fatal only if no fallback) |
-| `8` | Step 7/8 — Enrichment or visualization failed |
----
-## Interpreting PubGuard Composite Codes
-Quick decoder ring for the `PV-0XYZ` codes:
-```
-X (doc_type):   0=paper ✅  1=poster 📋  2=abstract 📄  3=junk 🗑️
-Y (ai_detect):  0=human ✍️   1=ai 🤖
-Z (toxicity):   0=clean ✅  1=toxic ☠️
-```
-Examples:
-- `PV-0000` → Paper + Human + Clean → **PASS** ✅
-- `PV-0300` → Junk + Human + Clean → *"That's not a paper"* 🗑️
-- `PV-0011` → Paper + AI + Toxic → *"Human-passing but spicy"* ⚠️
-- `PV-0311` → Junk + AI + Toxic → *"The absolute worst"* 🚫
----
-*PubGuard v0.1.0 — Because science has standards, even if your PDF doesn't.*