overview readme

README.md

@@ -1,8 +1,71 @@
-## TODO
+# Z-Number Decision Matrix Extraction
+
+How do you make decisions when your reasoning is messy and contains uncertainty, subjectivity, or contradictions? This project leverages large language models fine-tuned to extract Z-number decision matrix from natural language narrative. The extracted matrix is then analyzed using z-number-based Multi-Criteria Decision-Making (MCDM) methods (TOPSIS, PROMETHEE).
+
+## Usage
+
+```bash
+python text2mcdm.py --query "Your decision problem here" --method topsis
+```
+
+**Arguments:**
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--query`, `-q` | (built-in example) | Decision narrative |
+| `--method` | `topsis` | MCDM algorithm: `topsis` or `promethee` |
+
+**Example:**
+
+```bash
+python text2mcdm.py --query "I'm trying to decide between taking a train, flying, or driving for my upcoming trip from Paris to Amsterdam, and I need to figure out what actually matters here. Environmental impact is absolutely my top priority, like I cannot stress this enough, I've been trying to reduce my carbon footprint all year and this is non-negotiable for me. The train is obviously amazing for this, planes are a disaster environmentally, and driving alone isn't great either but better than flying I guess. Cost matters somewhat but honestly I have some savings and this is a special trip so I'm not going to stress about it too much—trains are reasonable, flights can be cheap with budget airlines, driving with gas and tolls probably adds up. Comfort is kind of important to me since I get motion sick and anxious in certain situations, and trains are super relaxing with legroom and wifi, planes make me nervous and cramped, cars are fine but I'd be exhausted from driving. Time efficiency barely matters since I'm not in a rush at all and I'm taking the whole week off anyway—I know planes are fastest at like an hour, trains take about 3 hours, driving is maybe 5 hours, but whatever, I have time. Oh and reliability is pretty important because I absolutely cannot miss my friend's wedding ceremony on Saturday, and trains are almost always on time, flights get delayed constantly especially budget ones, and driving you could hit traffic or car trouble." --method topsis
+```
+
+**Output:**
+
+Extracted decision matrix:
 
-- add adversarial training example
-    - user mentions alternative or criteria he doesn't want to include
+| | environmental_impact | travel_cost | comfort_level | time_efficiency | reliability |
+|---|---|---|---|---|---|
+| type | benefit | cost | benefit | benefit | benefit |
+| train | 5:5 | -3:4 | 4:4 | 2:5 | 5:5 |
+| flight | 1:5 | -2:4 | 2:4 | 5:5 | 2:4 |
+| driving | 3:4 | -4:3 | 3:3 | 3:4 | 3:3 |
+| weight | 5:5 | 3:4 | 4:4 | 1:5 | 5:5 |
+
+Ranking (TOPSIS):
+
+```
+1. train
+2. driving
+3. flight
+```
+
+## Directory Structure
+
+```
+.
+├── data/                         # Training data
+├── helpers/                      # Helper modules
+├── outputs/                      # Model checkpoints
+├── qwen3_finetune.ipynb          # Fine-tuning notebook
+├── znum_data_gen.py              # Data generation script
+├── validate_znum.py              # Data validation script
+└── text2mcdm.py                  # Inference and MCDM analysis
+```
+
+## Data Generation
+
+`znum_data_gen.py` generates training data using the Gemini API. `validate_znum.py` validates the generated data. See `--help` for options.
+
+## Model
+
+Fine-tuned model: [`nuriyev/Qwen3-4B-znum-decision-matrix`](https://huggingface.co/nuriyev/Qwen3-4B-znum-decision-matrix)
+
+## TODO
 
-- handle missing data from user_query
-    - by asking follow-up questions
-    - or by making assumptions based on context
+- Add adversarial training examples
+  - Handle cases where the user mentions alternatives or criteria to exclude
+- Handle missing data from user queries
+  - By asking follow-up questions
+  - Or by making assumptions based on context