scimapper 1.0.1__tar.gz

scimapper-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Andrés Futo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scimapper-1.0.1/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: scimapper
+Version: 1.0.1
+Summary: An automated scientific mapping and systematic literature review framework with dense semantic clustering and PRISMA 2020 compliance.
+Author-email: Gustavo Andrés Futo <gustavoandresfu@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/gustavoandresfu/SciMapper
+Project-URL: Bug Tracker, https://github.com/gustavoandresfu/SciMapper/issues
+Keywords: systematic-literature-review,systematic-mapping-study,scimapper,scientific-mapping,topic-modeling,sentence-transformers,bertopic,prisma-2020,openalex,evidence-synthesis,nlp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Provides-Extra: web
+Requires-Dist: streamlit>=1.30.0; extra == "web"
+Provides-Extra: dependencies
+Requires-Dist: requests>=2.28.0; extra == "dependencies"
+Requires-Dist: pandas>=1.5.0; extra == "dependencies"
+Requires-Dist: numpy>=1.23.0; extra == "dependencies"
+Requires-Dist: scikit-learn>=1.2.0; extra == "dependencies"
+Requires-Dist: scipy>=1.10.0; extra == "dependencies"
+Requires-Dist: sentence-transformers>=2.2.0; extra == "dependencies"
+Requires-Dist: torch>=2.0.0; extra == "dependencies"
+Requires-Dist: plotly>=5.13.0; extra == "dependencies"
+Requires-Dist: python-docx>=0.8.11; extra == "dependencies"
+Requires-Dist: tqdm>=4.65.0; extra == "dependencies"
+Dynamic: license-file
+
+<div align="center">
+
+# 🚀 SciMapper
+### Automated Scientific Mapping & Systematic Literature Reviews with Dense Semantic Clustering
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PRISMA 2020](https://img.shields.io/badge/PRISMA-2020%20Compliant-green.svg)](https://www.prisma-statement.org/)
+[![OpenAlex API](https://img.shields.io/badge/Data%20Source-OpenAlex%20API-orange.svg)](https://openalex.org/)
+[![NLP Engine](https://img.shields.io/badge/NLP-Sentence--Transformers-purple.svg)](https://www.sbert.net/)
+
+**An end-to-end, domain-agnostic framework designed to conduct reproducible Systematic Literature Reviews (SLR) and Systematic Mapping Studies (SMS).**  
+It automates academic corpus harvesting, deduplication, dense semantic embedding, unsupervised clustering, taxonomic discovery, interactive 2D cartography, and manuscript drafting—while keeping **researchers firmly in the loop**.
+
+🌐 **Languages:** **English** • [Español (Guía en Castellano)](README_ES.md)
+
+[Quickstart](#-quickstart-in-3-steps) • [Architecture](#-framework-architecture) • [Comparison](#-comparison-with-the-state-of-the-art) • [Theoretical Foundation](#-theoretical-foundations) • [Citation](#-citation)
+
+</div>
+
+---
+
+## 🌟 Key Features
+
+* 📡 **Automated Scholarly Harvesting:** Direct connection to the **OpenAlex API** (*Polite Pool* with 250M+ works) executing boolean queries and reconstructing inverted-index abstracts in $O(N \log N)$.
+* 🧹 **Bidirectional Deduplication:** Collapses duplicates across arXiv, IEEE, ACM, Springer, and PubMed via canonical lowercase DOI and normalized lexical title hashing.
+* 🧠 **Domain-Specific Transformer Presets:** Plug-and-play dense representations via `Sentence-Transformers`:
+  * `software_engineering`: `sentence-transformers/all-MiniLM-L6-v2`
+  * `biomedical_health`: `microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract`
+  * `scientific_general`: `allenai/scibert_scivocab_uncased`
+  * `finance_business`: `ProsusAI/finbert`
+  * `multilingual`: `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`
+* 🔬 **Unsupervised Topic Discovery ($c$-TF-IDF):** Discovers latent research themes without generative hallucination, extracting mathematically distinctive n-grams using *Class-based TF-IDF*.
+* 🗺️ **Interactive Cartography & Cluster Hulls:** Produces publication-grade 2D HTML dashboards (Plotly) featuring:
+  * Regional boundaries via **Convex Hulls** with smoothed spline contours.
+  * Cluster centroids with real-time metadata cards ($N$, percentage, top keywords).
+  * Layer switching (*Full View*, *Cluster Boundaries Only*, *Paper Scatter Points*).
+* 📈 **Temporal Dynamics & Hot Topic Radar:** Computes Compound Annual Growth Rates (CAGR) per cluster to classify topics into 🚀 *Emerging*, ⚖️ *Mature*, or 📉 *Declining*.
+* 🛡️ **Mathematical PRISMA 2020 Audit:** Objective isolation of out-of-scope or foreign language clusters as documented exclusion criteria.
+* 📝 **Automated Manuscript Generation:** Compiles an executive Microsoft Word (`.docx`) template complete with cover page, research questions (RQs), PRISMA summary tables, taxonomy distribution, and structured discussion sections.
+
+---
+
+## 🏗️ Framework Architecture
+
+```mermaid
+graph TD
+    A["⚙️ 1. Project Configuration<br><code>scimapper_config.json</code>"] --> B["📡 2. Harvester & Deduplicator<br><code>collector.py (OpenAlex API)</code>"]
+    B --> C["🧠 3. Semantic Embeddings<br><code>embedder.py (SBERT / MiniLM)</code>"]
+    C --> D["🔬 4. Clustering & c-TF-IDF<br><code>clusterer.py (PCA + t-SNE)</code>"]
+    D --> E1["🗺️ 5a. Interactive Cartography<br><code>visualizer.py (Plotly 2D + Hulls)</code>"]
+    D --> E2["⚖️ 5b. Human-in-the-Loop Review<br><code>discovered_topics.json</code>"]
+    E2 --> F["📝 6. Automated Manuscript<br><code>doc_builder.py (.docx Output)</code>"]
+```
+
+---
+
+## ⚡ Quickstart in 3 Steps
+
+### 1. Installation
+
+Clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/gustavoandresfu/SciMapper.git
+cd SciMapper
+pip install -r requirements.txt
+```
+
+*(Optional)* Install as an editable command-line utility:
+```bash
+pip install -e .
+```
+
+---
+
+### 2. Initialize a Project
+
+Launch the interactive configuration wizard (prompts for domain preset, search queries, and project metadata):
+
+```bash
+python main.py --init
+# Or if installed via pip:
+scimapper --init
+```
+*(Or use `python main.py --init --quick` to generate the baseline template directly without prompts).*
+
+The generated `sms_config.json` is ready to inspect and refine:
+
+```json
+{
+  "project_metadata": {
+    "title": "Systematic Literature Review: Generative AI in Healthcare",
+    "short_name": "SciMapper_GenAI_Health",
+    "authors": ["Your Name"],
+    "temporal_window": [2019, 2026],
+    "output_dir": "./output"
+  },
+  "research_questions": {
+    "RQ1": "What foundational architectures and LLMs are predominantly adopted in clinical workflows?",
+    "RQ2": "What empirical metrics and validation benchmarks are reported for diagnostic accuracy?",
+    "RQ3": "What open challenges regarding hallucinations and ethical safety remain unaddressed?"
+  },
+  "search_strategy": {
+    "openalex_email": "researcher@university.edu",
+    "max_results_per_query": 100,
+    "queries": [
+      "\"generative ai\" AND \"clinical diagnostics\"",
+      "\"large language models\" AND \"medical decision support\""
+    ]
+  },
+  "nlp_tuning": {
+    "domain_preset": "biomedical_health",
+    "n_clusters": 5
+  }
+}
+```
+
+---
+
+### 3. Run the Automated Pipeline
+
+Execute the discovery phase:
+
+```bash
+python main.py --run-discovery --config sms_config.json
+```
+
+1. Review and refine taxonomic names in `output/discovered_topics.json`.
+2. Inspect the pre-selected seminal papers in `output/candidatos_discusion.csv`.
+3. Compile the interactive dashboard and Word document:
+
+```bash
+python main.py --compile --config sms_config.json
+python main.py --build-doc --config sms_config.json
+```
+
+Or execute everything end-to-end in a single run:
+
+```bash
+python main.py --all --config sms_config.json
+```
+
+---
+
+## 📊 Comparison with the State-of-the-Art
+
+| Capability | ASReview | Generic BERTopic | Manual Review Tools (Covidence / Rayyan) | **SciMapper** |
+| :--- | :---: | :---: | :---: | :---: |
+| **Academic Ingestion** | ❌ Manual (CSV/RIS) | ❌ None | ❌ Manual Import | **✅ Automated OpenAlex API** |
+| **Deduplication** | ⚠️ Basic | ❌ None | ⚠️ Exact match | **✅ Canonical DOI + Title Hash** |
+| **Semantic Representations** | ✅ Optional | ✅ Native | ❌ None | **✅ Pre-tuned Domain Transformers** |
+| **Topic Modeling ($c$-TF-IDF)** | ❌ Binary only | ✅ Yes | ❌ None | **✅ Mathematical $c$-TF-IDF** |
+| **Objective PRISMA Exclusion** | ❌ Human judgment | ❌ None | ❌ Human labeling | **✅ Algorithmic Outlier Clustering** |
+| **Cartography with Convex Hulls** | ❌ None | ⚠️ Scatter only | ❌ None | **✅ 2D Hulls + Centroids + Density** |
+| **Temporal CAGR Tracking** | ❌ None | ❌ Manual | ❌ None | **✅ Automated Hot-Topic Radar** |
+| **Automated Manuscript (.docx)** | ❌ None | ❌ None | ❌ Export tables | **✅ Formatted PRISMA Word Paper** |
+
+---
+
+## 🔬 Theoretical Foundations
+
+The framework's methodological and algorithmic foundations are grounded in established literature:
+
+1. **Topic Modeling & Semantic Representation:**  
+   Based on the modular architecture described by **Jay Alammar and Maarten Grootendorst** in *Hands-On Large Language Models* (O'Reilly, Chapter 5: *Text Clustering and Topic Modeling*), decoupling dense vector embeddings, dimensionality reduction, clustering, and class-based TF-IDF ($c$-TF-IDF).
+2. **Systematic Mapping Methodology:**  
+   Follows the seminal guidelines of **Petersen et al. (2008)** (*Systematic Mapping Studies in Software Engineering*) and **Kitchenham & Charters (2007)**.
+3. **Auditability & Reporting Standards:**  
+   Strict adherence to the **PRISMA 2020** statement (*Preferred Reporting Items for Systematic Reviews and Meta-Analyses*), ensuring transparent and reproducible record accounting.
+
+---
+
+## 📁 Repository Structure
+
+```text
+SciMapper/
+├── config_template.json    # Master template for project setup
+├── test_config.json        # Quick verification test suite
+├── main.py                 # Unified CLI orchestrator
+├── requirements.txt        # Python dependency specification
+├── pyproject.toml          # Standard packaging & CLI entry point (scimapper)
+├── CITATION.cff            # Academic citation metadata
+├── LICENSE                 # MIT Open Source License
+└── core/
+    ├── collector.py        # OpenAlex API ingestion & abstract reconstruction
+    ├── embedder.py         # Multi-domain Sentence-Transformer pipeline
+    ├── clusterer.py        # Dimensionality reduction (PCA+t-SNE) & c-TF-IDF
+    ├── selector.py         # Stratified seminal paper recommendation
+    ├── visualizer.py       # Plotly 2D interactive maps with Convex Hulls
+    └── doc_builder.py      # Automated PRISMA Word manuscript generation
+```
+
+---
+
+## 📖 Citation
+
+If you use **SciMapper** in your research, academic reviews, or dissertations, please cite it as:
+
+```bibtex
+@software{futo_scimapper_2026,
+  author       = {Gustavo Andrés Futo},
+  title        = {SciMapper: Automated Scientific Mapping & Systematic Literature Reviews with Dense Semantic Clustering and PRISMA 2020 Compliance},
+  year         = {2026},
+  publisher    = {GitHub},
+  journal      = {GitHub repository},
+  howpublished = {\url{https://github.com/gustavoandresfu/SciMapper}}
+}
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.  
+Author: **Gustavo Andrés Futo** (2026).

scimapper-1.0.1/README.md

@@ -0,0 +1,216 @@
+<div align="center">
+
+# 🚀 SciMapper
+### Automated Scientific Mapping & Systematic Literature Reviews with Dense Semantic Clustering
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PRISMA 2020](https://img.shields.io/badge/PRISMA-2020%20Compliant-green.svg)](https://www.prisma-statement.org/)
+[![OpenAlex API](https://img.shields.io/badge/Data%20Source-OpenAlex%20API-orange.svg)](https://openalex.org/)
+[![NLP Engine](https://img.shields.io/badge/NLP-Sentence--Transformers-purple.svg)](https://www.sbert.net/)
+
+**An end-to-end, domain-agnostic framework designed to conduct reproducible Systematic Literature Reviews (SLR) and Systematic Mapping Studies (SMS).**  
+It automates academic corpus harvesting, deduplication, dense semantic embedding, unsupervised clustering, taxonomic discovery, interactive 2D cartography, and manuscript drafting—while keeping **researchers firmly in the loop**.
+
+🌐 **Languages:** **English** • [Español (Guía en Castellano)](README_ES.md)
+
+[Quickstart](#-quickstart-in-3-steps) • [Architecture](#-framework-architecture) • [Comparison](#-comparison-with-the-state-of-the-art) • [Theoretical Foundation](#-theoretical-foundations) • [Citation](#-citation)
+
+</div>
+
+---
+
+## 🌟 Key Features
+
+* 📡 **Automated Scholarly Harvesting:** Direct connection to the **OpenAlex API** (*Polite Pool* with 250M+ works) executing boolean queries and reconstructing inverted-index abstracts in $O(N \log N)$.
+* 🧹 **Bidirectional Deduplication:** Collapses duplicates across arXiv, IEEE, ACM, Springer, and PubMed via canonical lowercase DOI and normalized lexical title hashing.
+* 🧠 **Domain-Specific Transformer Presets:** Plug-and-play dense representations via `Sentence-Transformers`:
+  * `software_engineering`: `sentence-transformers/all-MiniLM-L6-v2`
+  * `biomedical_health`: `microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract`
+  * `scientific_general`: `allenai/scibert_scivocab_uncased`
+  * `finance_business`: `ProsusAI/finbert`
+  * `multilingual`: `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`
+* 🔬 **Unsupervised Topic Discovery ($c$-TF-IDF):** Discovers latent research themes without generative hallucination, extracting mathematically distinctive n-grams using *Class-based TF-IDF*.
+* 🗺️ **Interactive Cartography & Cluster Hulls:** Produces publication-grade 2D HTML dashboards (Plotly) featuring:
+  * Regional boundaries via **Convex Hulls** with smoothed spline contours.
+  * Cluster centroids with real-time metadata cards ($N$, percentage, top keywords).
+  * Layer switching (*Full View*, *Cluster Boundaries Only*, *Paper Scatter Points*).
+* 📈 **Temporal Dynamics & Hot Topic Radar:** Computes Compound Annual Growth Rates (CAGR) per cluster to classify topics into 🚀 *Emerging*, ⚖️ *Mature*, or 📉 *Declining*.
+* 🛡️ **Mathematical PRISMA 2020 Audit:** Objective isolation of out-of-scope or foreign language clusters as documented exclusion criteria.
+* 📝 **Automated Manuscript Generation:** Compiles an executive Microsoft Word (`.docx`) template complete with cover page, research questions (RQs), PRISMA summary tables, taxonomy distribution, and structured discussion sections.
+
+---
+
+## 🏗️ Framework Architecture
+
+```mermaid
+graph TD
+    A["⚙️ 1. Project Configuration<br><code>scimapper_config.json</code>"] --> B["📡 2. Harvester & Deduplicator<br><code>collector.py (OpenAlex API)</code>"]
+    B --> C["🧠 3. Semantic Embeddings<br><code>embedder.py (SBERT / MiniLM)</code>"]
+    C --> D["🔬 4. Clustering & c-TF-IDF<br><code>clusterer.py (PCA + t-SNE)</code>"]
+    D --> E1["🗺️ 5a. Interactive Cartography<br><code>visualizer.py (Plotly 2D + Hulls)</code>"]
+    D --> E2["⚖️ 5b. Human-in-the-Loop Review<br><code>discovered_topics.json</code>"]
+    E2 --> F["📝 6. Automated Manuscript<br><code>doc_builder.py (.docx Output)</code>"]
+```
+
+---
+
+## ⚡ Quickstart in 3 Steps
+
+### 1. Installation
+
+Clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/gustavoandresfu/SciMapper.git
+cd SciMapper
+pip install -r requirements.txt
+```
+
+*(Optional)* Install as an editable command-line utility:
+```bash
+pip install -e .
+```
+
+---
+
+### 2. Initialize a Project
+
+Launch the interactive configuration wizard (prompts for domain preset, search queries, and project metadata):
+
+```bash
+python main.py --init
+# Or if installed via pip:
+scimapper --init
+```
+*(Or use `python main.py --init --quick` to generate the baseline template directly without prompts).*
+
+The generated `sms_config.json` is ready to inspect and refine:
+
+```json
+{
+  "project_metadata": {
+    "title": "Systematic Literature Review: Generative AI in Healthcare",
+    "short_name": "SciMapper_GenAI_Health",
+    "authors": ["Your Name"],
+    "temporal_window": [2019, 2026],
+    "output_dir": "./output"
+  },
+  "research_questions": {
+    "RQ1": "What foundational architectures and LLMs are predominantly adopted in clinical workflows?",
+    "RQ2": "What empirical metrics and validation benchmarks are reported for diagnostic accuracy?",
+    "RQ3": "What open challenges regarding hallucinations and ethical safety remain unaddressed?"
+  },
+  "search_strategy": {
+    "openalex_email": "researcher@university.edu",
+    "max_results_per_query": 100,
+    "queries": [
+      "\"generative ai\" AND \"clinical diagnostics\"",
+      "\"large language models\" AND \"medical decision support\""
+    ]
+  },
+  "nlp_tuning": {
+    "domain_preset": "biomedical_health",
+    "n_clusters": 5
+  }
+}
+```
+
+---
+
+### 3. Run the Automated Pipeline
+
+Execute the discovery phase:
+
+```bash
+python main.py --run-discovery --config sms_config.json
+```
+
+1. Review and refine taxonomic names in `output/discovered_topics.json`.
+2. Inspect the pre-selected seminal papers in `output/candidatos_discusion.csv`.
+3. Compile the interactive dashboard and Word document:
+
+```bash
+python main.py --compile --config sms_config.json
+python main.py --build-doc --config sms_config.json
+```
+
+Or execute everything end-to-end in a single run:
+
+```bash
+python main.py --all --config sms_config.json
+```
+
+---
+
+## 📊 Comparison with the State-of-the-Art
+
+| Capability | ASReview | Generic BERTopic | Manual Review Tools (Covidence / Rayyan) | **SciMapper** |
+| :--- | :---: | :---: | :---: | :---: |
+| **Academic Ingestion** | ❌ Manual (CSV/RIS) | ❌ None | ❌ Manual Import | **✅ Automated OpenAlex API** |
+| **Deduplication** | ⚠️ Basic | ❌ None | ⚠️ Exact match | **✅ Canonical DOI + Title Hash** |
+| **Semantic Representations** | ✅ Optional | ✅ Native | ❌ None | **✅ Pre-tuned Domain Transformers** |
+| **Topic Modeling ($c$-TF-IDF)** | ❌ Binary only | ✅ Yes | ❌ None | **✅ Mathematical $c$-TF-IDF** |
+| **Objective PRISMA Exclusion** | ❌ Human judgment | ❌ None | ❌ Human labeling | **✅ Algorithmic Outlier Clustering** |
+| **Cartography with Convex Hulls** | ❌ None | ⚠️ Scatter only | ❌ None | **✅ 2D Hulls + Centroids + Density** |
+| **Temporal CAGR Tracking** | ❌ None | ❌ Manual | ❌ None | **✅ Automated Hot-Topic Radar** |
+| **Automated Manuscript (.docx)** | ❌ None | ❌ None | ❌ Export tables | **✅ Formatted PRISMA Word Paper** |
+
+---
+
+## 🔬 Theoretical Foundations
+
+The framework's methodological and algorithmic foundations are grounded in established literature:
+
+1. **Topic Modeling & Semantic Representation:**  
+   Based on the modular architecture described by **Jay Alammar and Maarten Grootendorst** in *Hands-On Large Language Models* (O'Reilly, Chapter 5: *Text Clustering and Topic Modeling*), decoupling dense vector embeddings, dimensionality reduction, clustering, and class-based TF-IDF ($c$-TF-IDF).
+2. **Systematic Mapping Methodology:**  
+   Follows the seminal guidelines of **Petersen et al. (2008)** (*Systematic Mapping Studies in Software Engineering*) and **Kitchenham & Charters (2007)**.
+3. **Auditability & Reporting Standards:**  
+   Strict adherence to the **PRISMA 2020** statement (*Preferred Reporting Items for Systematic Reviews and Meta-Analyses*), ensuring transparent and reproducible record accounting.
+
+---
+
+## 📁 Repository Structure
+
+```text
+SciMapper/
+├── config_template.json    # Master template for project setup
+├── test_config.json        # Quick verification test suite
+├── main.py                 # Unified CLI orchestrator
+├── requirements.txt        # Python dependency specification
+├── pyproject.toml          # Standard packaging & CLI entry point (scimapper)
+├── CITATION.cff            # Academic citation metadata
+├── LICENSE                 # MIT Open Source License
+└── core/
+    ├── collector.py        # OpenAlex API ingestion & abstract reconstruction
+    ├── embedder.py         # Multi-domain Sentence-Transformer pipeline
+    ├── clusterer.py        # Dimensionality reduction (PCA+t-SNE) & c-TF-IDF
+    ├── selector.py         # Stratified seminal paper recommendation
+    ├── visualizer.py       # Plotly 2D interactive maps with Convex Hulls
+    └── doc_builder.py      # Automated PRISMA Word manuscript generation
+```
+
+---
+
+## 📖 Citation
+
+If you use **SciMapper** in your research, academic reviews, or dissertations, please cite it as:
+
+```bibtex
+@software{futo_scimapper_2026,
+  author       = {Gustavo Andrés Futo},
+  title        = {SciMapper: Automated Scientific Mapping & Systematic Literature Reviews with Dense Semantic Clustering and PRISMA 2020 Compliance},
+  year         = {2026},
+  publisher    = {GitHub},
+  journal      = {GitHub repository},
+  howpublished = {\url{https://github.com/gustavoandresfu/SciMapper}}
+}
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.  
+Author: **Gustavo Andrés Futo** (2026).

scimapper-1.0.1/core/__init__.py

@@ -0,0 +1,11 @@
+"""Core modules for SciMapper."""
+
+import sys
+
+try:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8")
+except Exception:
+    pass

scimapper-1.0.1/core/clusterer.py

@@ -0,0 +1,178 @@
+"""
+AutoSMS Framework - Módulo de Clustering, c-TF-IDF y Dinámica Temporal
+=====================================================================
+Ejecuta la reducción bidimensional (PCA + t-SNE), agrupamiento semántico,
+extracción formal de palabras clave diferenciales (c-TF-IDF) y el cálculo
+del Radar de Madurez Temporal (CAGR y clasificación de tendencias).
+"""
+
+import os
+import json
+import logging
+import numpy as np
+import pandas as pd
+from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+from sklearn.cluster import KMeans
+from sklearn.feature_extraction.text import CountVectorizer
+
+logger = logging.getLogger("scimapper.clusterer")
+
+class AutoClusterer:
+    def __init__(self, config: dict):
+        self.config = config
+        self.nlp_cfg = config.get("nlp_tuning", {})
+        self.output_dir = config.get("project_metadata", {}).get("output_dir", "./output")
+        os.makedirs(self.output_dir, exist_ok=True)
+        self.k = self.nlp_cfg.get("n_clusters", 6)
+
+    def reduce_2d(self, embeddings: np.ndarray) -> np.ndarray:
+        logger.info("Reduciendo dimensionalidad a espacio bidimensional (PCA + t-SNE)...")
+        n_samples = embeddings.shape[0]
+        if n_samples <= 2:
+            return np.zeros((n_samples, 2))
+
+        pca_dims = min(50, embeddings.shape[1], n_samples - 1)
+        pca = PCA(n_components=pca_dims, random_state=42)
+        pca_feats = pca.fit_transform(embeddings)
+
+        perp = min(30, max(2, (n_samples - 1) // 3))
+        tsne = TSNE(n_components=2, perplexity=perp, learning_rate="auto", init="pca", random_state=42)
+        coords = tsne.fit_transform(pca_feats)
+        return coords
+
+    def cluster(self, embeddings: np.ndarray) -> np.ndarray:
+        n_samples = embeddings.shape[0]
+        actual_k = min(self.k, max(1, n_samples // 2))
+        logger.info("Ejecutando agrupamiento no supervisado en k=%d clusters...", actual_k)
+        if actual_k <= 1:
+            return np.zeros(n_samples, dtype=int)
+        kmeans = KMeans(n_clusters=actual_k, random_state=42, n_init=10)
+        labels = kmeans.fit_predict(embeddings)
+        return labels
+
+    def extract_c_tf_idf(self, texts: list, labels: np.ndarray, top_n: int = 8) -> dict:
+        logger.info("Calculando Class-based TF-IDF (c-TF-IDF) para extraccion lexica...")
+        unique_labels = sorted(list(set(labels)))
+        docs_per_cluster = []
+        for l in unique_labels:
+            cluster_docs = [texts[i] for i in range(len(texts)) if labels[i] == l]
+            docs_per_cluster.append(" ".join(cluster_docs))
+
+        stop_words = self.nlp_cfg.get("stop_words", "english")
+        if isinstance(stop_words, str) and stop_words.lower() in ("none", "null", ""):
+            stop_words = None
+
+        vec = CountVectorizer(ngram_range=(1, 2), stop_words=stop_words, min_df=1, max_df=1.0)
+        X = vec.fit_transform(docs_per_cluster)
+        words = vec.get_feature_names_out()
+
+        tf = X.toarray().astype(float)
+        w_sum = tf.sum(axis=1, keepdims=True)
+        tf_norm = tf / np.maximum(w_sum, 1)
+
+        # IDF clásico por documento (cluster): log(1 + N / (df + 1))
+        doc_freq = (tf > 0).sum(axis=0).astype(float)
+        n_clusters = max(1, len(docs_per_cluster))
+        idf = np.log(1.0 + (n_clusters / (doc_freq + 1.0)))
+        c_tf_idf = tf_norm * idf
+
+        keywords_dict = {}
+        for idx, l in enumerate(unique_labels):
+            top_idx = np.argsort(c_tf_idf[idx])[::-1][:top_n]
+            top_words = [words[i] for i in top_idx if len(words[i]) > 2]
+            keywords_dict[int(l)] = top_words
+
+        return keywords_dict
+
+    def compute_temporal_dynamics(self, df: pd.DataFrame, labels: np.ndarray) -> dict:
+        logger.info("Calculando Radar de Madurez Temporal y CAGR por Topico...")
+        dynamics = {}
+        unique_labels = sorted(list(set(labels)))
+
+        # Convertir años a enteros válidos
+        years_series = pd.to_numeric(df["publication_year"], errors="coerce").dropna()
+        if years_series.empty:
+            min_year, max_year = 2018, 2026
+        else:
+            min_year, max_year = int(years_series.min()), int(years_series.max())
+
+        span = max(1, max_year - min_year)
+
+        for l in unique_labels:
+            sub = df[df["topic_id"] == l]
+            sub_years = pd.to_numeric(sub["publication_year"], errors="coerce").dropna().astype(int)
+
+            yearly_counts = {}
+            for y in range(min_year, max_year + 1):
+                yearly_counts[y] = int((sub_years == y).sum())
+
+            # Cálculo de CAGR suavizado (Laplace +1 para evitar ceros)
+            start_val = yearly_counts.get(min_year, 0) + yearly_counts.get(min_year + 1, 0)
+            end_val = yearly_counts.get(max_year, 0) + yearly_counts.get(max_year - 1, 0)
+            
+            cagr = ((end_val + 1.0) / (start_val + 1.0)) ** (1.0 / max(1, span - 1)) - 1.0
+            cagr_pct = round(cagr * 100, 1)
+
+            # Proporción de producción en los últimos 3 años
+            recent_years = [max_year, max_year - 1, max_year - 2]
+            recent_count = sum(yearly_counts.get(y, 0) for y in recent_years)
+            recent_ratio = round((recent_count / max(1, len(sub))) * 100, 1)
+
+            # Clasificación de la dinámica
+            if cagr_pct >= 12.0 or recent_ratio >= 45.0:
+                category = "Emergente (Hot Topic)"
+                badge = "🚀 Emergente"
+            elif cagr_pct <= -8.0 and recent_ratio <= 22.0:
+                category = "En Declive"
+                badge = "📉 En Declive"
+            else:
+                category = "Maduro / Consolidado"
+                badge = "⚖️ Maduro"
+
+            dynamics[int(l)] = {
+                "cagr_percent": cagr_pct,
+                "recent_ratio_percent": recent_ratio,
+                "trend_category": category,
+                "badge": badge,
+                "yearly_distribution": yearly_counts
+            }
+
+        return dynamics
+
+    def run(self, df: pd.DataFrame, embeddings: np.ndarray) -> tuple:
+        df = df.reset_index(drop=True).copy()
+        coords = self.reduce_2d(embeddings)
+        df["coord_x"] = coords[:, 0]
+        df["coord_y"] = coords[:, 1]
+
+        labels = self.cluster(embeddings)
+        df["topic_id"] = labels
+
+        texts = (df["title"] + ". " + df["abstract"]).tolist()
+        keywords = self.extract_c_tf_idf(texts, labels, top_n=8)
+        temporal_info = self.compute_temporal_dynamics(df, labels)
+
+        # Generar JSON de tópicos descubiertos enriquecido
+        topics_summary = {}
+        for l in sorted(keywords.keys()):
+            sub = df[df["topic_id"] == l]
+            sample_titles = sub["title"].head(4).tolist()
+            t_dyn = temporal_info.get(l, {})
+
+            topics_summary[l] = {
+                "count": len(sub),
+                "percentage": round(len(sub) / len(df) * 100, 1),
+                "keywords": keywords[l],
+                "sample_titles": sample_titles,
+                "assigned_name": f"Tópico {l}: {', '.join(keywords[l][:3]).title()}",
+                "exclude_prisma": False,
+                "temporal_dynamics": t_dyn
+            }
+
+        topics_json_path = os.path.join(self.output_dir, "discovered_topics.json")
+        with open(topics_json_path, "w", encoding="utf-8") as f:
+            json.dump(topics_summary, f, indent=2, ensure_ascii=False)
+
+        logger.info("Archivo de ajuste humano generado en: %s", topics_json_path)
+        return df, topics_summary