Metadata-Version: 2.4
Name: mmsscode
Version: 0.3.0
Summary: Local multi-model semantic-similarity coding of open-ended answers.
Author: mmsscode contributors
License: MIT
License-File: LICENSE
Requires-Python: <3.13,>=3.11
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas<3,>=2.2
Requires-Dist: pyreadstat>=1.2
Requires-Dist: safetensors>=0.4
Requires-Dist: sentencepiece>=0.2
Requires-Dist: torch>=2.6
Requires-Dist: transformers<5,>=4.51
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# mmsscode

`mmsscode` is a local, semi-automated tool for coding open-ended survey responses. It compares responses with a human-defined codebook using several embedding models. It requires neither an API key nor generative AI, and it leaves uncertain cases for human review.

The workflow is designed for an auditable social-science process: define a codebook, manually code informative examples, validate the procedure, and apply it to the remaining responses.

## Installation

Install the complete package from PyPI:

```powershell
python -m pip install mmsscode
```

mmsscode supports Python 3.11 and 3.12. The first model download can be large; downloaded models remain available locally for later offline analyses.

## Quick start in an IDE

Create a small Python script and run each command separately in an IDE such as VS Code or Spyder:

```python
import mmsscode

PROJECT = r"C:\projects\my_analysis"

mmsscode.create(PROJECT)
mmsscode.set_models(
    PROJECT,
    directory=r"D:\mmsscode_models",
    models=["simcse", "gte", "bge_m3"],
)
mmsscode.download_models(PROJECT)

mmsscode.set_data(PROJECT, path=r"C:\data\responses.csv")
mmsscode.prepare(
    PROJECT,
    text_columns={"open_answer_1": "code_1", "open_answer_2": "code_2"},
    id_column="id",
)
```

`prepare()` creates `codebook.csv` and `manual_codes.csv` in the project directory. When the input contains no manual codes, it randomly selects at most 500 source rows. Complete the codebook, then manually enter `manual_code_id` values for as many selected texts as needed to reach theoretical saturation. The remaining rows may stay blank.

After manual coding, run the remaining steps independently:

```python
mmsscode.validate(PROJECT)  # optional repeated holdout report
mmsscode.analyze(PROJECT)   # code the full dataset and write audit files
```

The project settings, sample seed, and selected source rows are stored in `mmsscode-project.json`. Re-running `prepare()` preserves the existing manual-coding template by default.

## Interactive setup

If you prefer prompts instead of writing the initial commands, run:

```python
import mmsscode

mmsscode.setup(r"C:\projects\my_analysis")
```

The wizard stores the same project settings and creates the codebook and manual-coding template. Later, use `download_models`, `validate`, and `analyze` with the same project directory.

## Existing manual codes

For non-segmented responses, existing manual codes can be read directly from the input data:

```python
mmsscode.prepare(
    PROJECT,
    text_columns={"open_answer": "code"},
    id_column="id",
    manual_code_columns={"open_answer": "manual_code"},
)
```

Non-empty `manual_code` values become the training examples. When segmentation is enabled, use `manual_codes.csv` instead, because a single response can produce more than one segment.

## Outputs

`analyze()` writes:

- `coded_data.csv` and, when applicable, `coded_data.sav`: input data with assigned codes;
- `segment_audit.csv`: model proposals, scores, and decision reasons;
- `review_segments.csv`: responses that need manual review;
- `aggregation_report.csv`: segment-to-source-row aggregation results.

`validate()` additionally writes `validation_summary.csv` and `validation_detail.csv`.

## Further documentation

See [DOCUMENTATION.md](DOCUMENTATION.md) in the source distribution for the complete workflow, segmentation guidance, validation interpretation, and reproducibility notes.
