Metadata-Version: 2.4
Name: mmsscode
Version: 0.2.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
Provides-Extra: models
Requires-Dist: safetensors>=0.4; extra == 'models'
Requires-Dist: sentencepiece>=0.2; extra == 'models'
Requires-Dist: torch>=2.6; extra == 'models'
Requires-Dist: transformers<5,>=4.51; extra == 'models'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# mmsscode

`mmsscode` je lokální nástroj pro poloautomatické kódování otevřených odpovědí. Používá více embedding modelů, nevyžaduje API klíč ani generativní AI a ponechává nejednoznačné případy k rozhodnutí kodérovi.

Je určený pro běžný sociálněvědní workflow: metodicky vytvořený codebook, ručně zakódovaný vzorek a auditovatelný automatický krok nad zbývajícími odpověďmi.

## Instalace

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install ".[models]"
```

Pro vývoj a testy lze použít `pip install -e ".[models,test]"`.

## Tři kroky analýzy

1. **Stažení modelů** — obvykle jen při prvním použití nebo při výběru nového modelu.
2. **Příprava** — vytvoření codebooku a předlohy, případně segmentace odpovědí, poté ruční kódování vzorku.
3. **Analýza** — automatické přiřazení kódů; volitelně také holdout validace nad ručně zakódovaným vzorkem.

Vytvořte pracovní složku a skript:

```powershell
mmsscode init --directory "C:\projekty\moje_analyza"
cd "C:\projekty\moje_analyza"
```

V souboru `analyza.py` nastavte cesty, textové proměnné, kódové sloupce a vybrané modely. Potom vždy upravte pouze `ACTION` a spusťte:

```powershell
python analyza.py
```

Pro jednorázové stažení nastavte `ACTION = "download_models"`. Pro přípravu `ACTION = "prepare"`; po ručním doplnění `codebook.csv` a sloupce `manual_code_id` v předloze nastavte `ACTION = "analyze"`.

Chcete-li při analýze ověřit kvalitu pipeline na vlastních ručně zakódovaných datech, nastavte také `RUN_VALIDATION = True`. Tím vznikne holdout report před automatickým kódováním, ale vstupy ani ruční předloha se nemění.

`MODELS_DIRECTORY` a `CACHE_DIRECTORY` lze zvolit libovolně. Nastavte je jednou přímo v `analyza.py` a ponechte shodné pro stažení i další analýzy; úložiště modelů lze sdílet mezi projekty.

Úplný český návod k přípravě, segmentaci, validaci a interpretaci výstupů je v souboru [DOKUMENTACE.md](DOKUMENTACE.md).

## Výstupy

Analýza zapisuje zejména:

- `coded_data.csv` a případně `coded_data.sav` — data s doplněnými kódy;
- `segment_audit.csv` — predikce modelů, skóre a důvod rozhodnutí;
- `review_segments.csv` — případy ponechané pro ruční kontrolu;
- `aggregation_report.csv` — převod segmentů zpět k původním odpovědím;
- `validation_summary.csv` a `validation_detail.csv` — report holdout validace, je-li zapnutá.

## Ukázkový projekt

`demo_csda_2022/analyza.py` obsahuje referenční experiment s českými dotazníkovými odpověďmi. V horní části vyberte `PRESET` a `ACTION`; před spuštěním nastavte vlastní cestu ke společnému úložišti modelů.
