# Configuration Wizard - Fixed and Working!

## Issue Found

The wizard was generating an incorrect format. It was creating a simple key-value configuration instead of the proper **mapping configuration** format that RDFMap expects.

### What Was Wrong

**Wizard Output (Before Fix):**
```yaml
data_source: examples/mortgage/data/loans.csv
format: csv
ontology: examples/mortgage/ontology/mortgage.ttl
target_class: http://example.com/MyClass
iri_template: http://example.com/MyClass/{id}
# ... more simple key-value pairs
```

**What RDFMap Needs:**
```yaml
namespaces:
  xsd: http://www.w3.org/2001/XMLSchema#
  ...
defaults:
  base_iri: http://example.com/
sheets:
  - name: loans
    source: examples/mortgage/data/loans.csv
    row_resource:
      class: ex:MortgageLoan
      iri_template: "{base_iri}loan/{LoanID}"
    columns: {}
    objects: {}
options:
  on_error: report
  ...
```

## Solution

The wizard now generates a **proper mapping skeleton** that:
1. Has the correct structure (`namespaces`, `defaults`, `sheets`, `options`)
2. Can be used directly with `convert` (after adding column mappings)
3. Is compatible with the `generate` command to auto-fill column mappings

## How It Works Now

### Two-Step Process

The wizard is designed to work as part of a two-step workflow:

```
Step 1: Wizard creates mapping skeleton
        ↓
   rdfmap init
        ↓
   mapping_config.yaml (skeleton)

Step 2: Generate fills in column mappings
        ↓
   rdfmap generate --ontology ... --spreadsheet ... --output ...
        ↓
   mapping_config_complete.yaml (full mapping)
```

### Wizard Output Structure

```yaml
# RDFMap Mapping Configuration
# Generated by Configuration Wizard
#
# Next steps:
#   1. Run the generate command to auto-map columns:
#      rdfmap generate --ontology examples/mortgage/ontology/mortgage.ttl \
#                      --spreadsheet examples/mortgage/data/loans.csv \
#                      --output test_wizard_output_generated.yaml
#
#   2. Or manually add column mappings below and convert directly:
#      rdfmap convert --mapping test_wizard_output.yaml

namespaces:
  xsd: http://www.w3.org/2001/XMLSchema#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  owl: http://www.w3.org/2002/07/owl#

defaults:
  base_iri: http://example.com/

sheets:
- name: loans
  source: examples/mortgage/data/loans.csv
  row_resource:
    class: http://example.com/MortgageLoan
    iri_template: '{base_iri}loan/{LoanID}'
  columns: {}    # To be filled by generate command
  objects: {}    # To be filled by generate command

options:
  on_error: report
  skip_empty_values: true
  delimiter: ','
  header: true

ontology: examples/mortgage/ontology/mortgage.ttl

validation:
  shacl:
    enabled: true
    shapes_file: examples/mortgage/shapes/mortgage_shapes.ttl
    inference: none

_wizard_config:
  priority: balanced
  use_semantic: true
  use_graph_reasoning: true
  use_history: true
  streaming: false
  output_format: turtle
  output: output.ttl
  enable_logging: true
  log_file: rdfmap.log
```

### Key Features

1. **Proper Structure** - Matches the format that `convert` and `generate` expect
2. **Helpful Comments** - Tells users exactly what to do next
3. **Wizard Metadata** - Preserves wizard settings in `_wizard_config` section
4. **Empty Mappings** - `columns: {}` and `objects: {}` await completion

## Complete Workflow

### Option 1: Automated (Recommended)

```bash
# Step 1: Create skeleton with wizard
rdfmap init --output my_mapping.yaml

# Step 2: Auto-generate column mappings
rdfmap generate \
  --ontology examples/mortgage/ontology/mortgage.ttl \
  --spreadsheet examples/mortgage/data/loans.csv \
  --output my_mapping_complete.yaml

# Step 3: Convert data
rdfmap convert --mapping my_mapping_complete.yaml
```

### Option 2: Manual

```bash
# Step 1: Create skeleton with wizard
rdfmap init --output my_mapping.yaml

# Step 2: Manually edit my_mapping.yaml to add column mappings
# (edit the columns: {} and objects: {} sections)

# Step 3: Convert data
rdfmap convert --mapping my_mapping.yaml
```

## Comparison with Manual Files

### Manual Mapping (mortgage_mapping.yaml)
- **Created by:** Human, manually written
- **Has:** Complete column mappings
- **Use:** Directly with `convert` command
- **Status:** Ready to use immediately

### Generated Mapping (generated_mapping.yaml)
- **Created by:** `generate` command
- **Has:** Auto-mapped columns with AI matching
- **Use:** Directly with `convert` command
- **Status:** Ready to use immediately

### Wizard Mapping (wizard output)
- **Created by:** `init` wizard
- **Has:** Skeleton structure, no column mappings yet
- **Use:** With `generate` command to complete, then `convert`
- **Status:** Needs completion (empty columns/objects)

## Why This Design?

### Separation of Concerns

1. **Wizard** = Collect basic info (data source, ontology, target class)
2. **Generate** = Intelligent column-to-property matching (complex AI/ML)
3. **Convert** = Transform data to RDF (fast processing)

### Benefits

- **Simpler Wizard** - Focuses on essentials, quick to complete
- **Reusable Generate** - Can run multiple times with different settings
- **Clear Workflow** - Each step has a clear purpose
- **Flexibility** - Can skip wizard and write config manually

## Updated Documentation

All documentation has been updated to reflect this workflow:

- **README.md** - Shows two-step process
- **CONFIGURATION_WIZARD.md** - Explains the workflow
- **CLI help** - `rdfmap init --help` shows correct usage

## CLI Messages

The wizard now shows clear next steps:

```
✓ Configuration skeleton created!

⚠️  Important: The wizard creates a base configuration.
You now need to complete it by mapping columns to properties.

Recommended next steps:
  1. Auto-generate column mappings:
     rdfmap generate --ontology examples/mortgage/ontology/mortgage.ttl \
                      --spreadsheet examples/mortgage/data/loans.csv \
                      --output mapping_config_complete.yaml

  2. Then convert your data:
     rdfmap convert --mapping mapping_config_complete.yaml

  Or manually edit the config file to add column mappings
```

## Tests Updated

All tests have been updated to verify:
- Proper mapping structure generation
- Correct namespaces and defaults
- Empty columns/objects sections
- Wizard metadata preservation

**Result: All 22 tests passing ✅**

## Summary

**Problem:** Wizard generated incompatible format  
**Solution:** Now generates proper mapping skeleton  
**Workflow:** Wizard → Generate → Convert  
**Status:** Fixed and working correctly!

The wizard is now a valuable first step in the mapping process, creating a well-structured foundation that can be completed automatically with the `generate` command or manually by editing the file.

