Metadata-Version: 2.4
Name: MLATE
Version: 0.1.2
Summary: Multi-dimensional Literature Analysis and Thematic Exploration
Author: naclcode
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: pandas>=1.0
Requires-Dist: openpyxl
Requires-Dist: xlrd
Requires-Dist: tqdm
Dynamic: license-file

# MLATE — Multi-dimensional Literature Analysis and Thematic Exploration

[中文版](README_zh.md) | English

---

MLATE is a CLI tool for literature deconstruction and taxonomy building using Large Language Models (LLMs). It assists researchers in extracting multi-dimensional features and organizing sub-categories from large bibliographic datasets.

## Features

- **One-by-One Discovery**: Extracts features and initial categories for each paper independently to capture fine details and reduce information loss or bias common in batch processing.
- **Two-Phase Convergence**: Decouples "spontaneous discovery" from "taxonomy convergence." The convergence process merges labels based on semantic similarity and sample popularity.
- **Incremental Iterative Tuning**: Supports repeated adjustment of convergence parameters for specific dimensions (e.g., "Application") while protecting existing data in other processed dimensions.
- **Dual-Category Labeling**: The final CSV report includes both `raw_labels` and `converged_categories`, allowing researchers to verify the AI's classification evolution logic.
- **Automated Translation Support**: Built-in translation module to convert paper titles, abstracts, and categories across multiple languages using LLMs.

## Quick Start

```bash
# 1. Filter: Score relevance and remove noise
mlate filter --input data.xls --topic "..." --output filtered.csv 

# 2. Explore: Generate raw classification drafts for each paper
mlate explore --input filtered.csv --output draft.json --dims "Application,Technology"

# 3. Converge: Merge trivial labels into a clean taxonomy and label the CSV
mlate converge --input draft.json --output taxonomy.json \
  --output-csv final_result.csv --limit-cats 5 --source-csv filtered.csv

# 4. Translate: (Optional) Translate abstracts, titles, or labels
mlate translate --input final_result.csv --output final_en.csv --lang "English" \
  --cols "Title,Abstract,Application_category"
```

## CLI Reference

| Command | Argument | Description |
| :--- | :--- | :--- |
| **Global** | `--model` | LLM model name (e.g., `deepseek-chat`, `gpt-4o`). |
| | `--source` | Data source format (`wos`, `scopus`, `standard`, `auto`). |
| **filter** | `--topic` | Topic keywords for relevance scoring. |
| | `--min-score` | Passing threshold (1-5, default 3.0). |
| | `--output-lang` | Language for scoring criteria and reasons. |
| **explore** | `--dims` | Initial discovery dimensions (e.g., Application, Technology). |
| | `--guide` | Researcher guidance to fine-tune AI discovery. |
| | `--output-lang` | Language for raw labels and reasons. |
| **converge** | `--limit-cats` | Max number of categories per dimension. |
| | `--dims` | Only process specified dimensions (incremental update). |
| | `--output-csv` | Path to save the dual-labeled CSV file. |
| | `--source-csv` | Source CSV path for title mapping. |
| | `--output-lang` | Language for category definitions. |
| **translate**| `--lang` | Target language for translation. |
| | `--cols` | Columns to translate (comma separated, CSV only). |
| **classify** | `--schema` | Predefined categories (JSON file, text file, or comma-separated). |
| | `--mode` | Classification mode: `single` (one per paper) or `multi` (multiple). |
| | `--guide` | Researcher guidance for fine-tuning. |
| **config** | `set/show` | Manage global settings (model, language, etc.). |

## Configuration

- **API Key**: Must be set via environment variable `MLATE_API_KEY`. Not stored on disk for security.
- **Global Language Setting**:
  ```bash
  mlate config set output_lang English
  ```

## Disclaimer

All results (relevance scores, categories, reasons, and translations) are generated by Large Language Models (LLMs). LLMs are prone to hallucinations and may produce inaccurate, biased, or entirely fabricated information. This tool is for research assistance only. Users must manually verify all AI-generated outputs before using them in academic publications or formal reports. The author is not responsible for any research errors, data misinterpretations, or losses resulting from the use of this tool.
