# Aplikacja do Kategoryzacji Ludzi

Aplikacja w Go zbudowana w architekturze czystej (Clean Architecture), która pobiera dane ludzi z pliku CSV i kategoryzuje je przy użyciu LLM.

## Funkcjonalności

- Projekt oparty na Clean Architecture
- Pobieranie danych ludzi ze zdalnego pliku CSV
- **Inteligentne filtrowanie**: Filtruje dane na podstawie określonych kryteriów:
  - Płeć: Mężczyzna (M)
  - Wiek w 2026 roku: 20-40 lat (urodzeni 1986-2006)
  - Miasto: Grudziądz
  - Branża: Transport (na podstawie słów kluczowych w opisie zawodu)
- **Przetwarzanie wsadowe**: Przetwarza ludzi w konfigurowalnych partiach (np. 1000 dla OpenRouter, 10 dla lokalnego)
- **Wznowienie**: Może kontynuować od miejsca przerwania - pomija już przetworzone partie
- **Śledzenie postępu**: Pokazuje postęp w czasie rzeczywistym z informacjami o ETA i czasie
- **Logowanie statystyk**: Pokazuje liczbę oryginalnych rekordów vs. przefiltrowanych
- Kategoryzuje ludzi używając LLM ze strukturyzowanym wyjściem
- Obsługuje wielu dostawców LLM:
  - OpenRouter API (zalecany batch_size: 1000)
  - Lokalne LM Studio (zalecany batch_size: 10)
- Konfiguracja poprzez plik JSON
- Tagi: IT, transport, edukacja, medycyna, praca z ludźmi, praca z pojazdami, praca fizyczna

## Struktura Projektu

```
.
├── cmd/app/              # Punkt wejścia aplikacji
├── internal/
│   ├── domain/          # Encje domenowe i interfejsy
│   ├── usecase/         # Logika biznesowa
│   ├── infrastructure/  # Usługi zewnętrzne
│   │   ├── csv/        # Pobieranie danych CSV
│   │   └── llm/        # Dostawcy LLM
│   └── config/          # Obsługa konfiguracji
├── config.json          # Twój plik konfiguracyjny
└── output.json          # Wygenerowane wyniki
```

## Konfiguracja

Utwórz plik `config.json` na podstawie jednego z przykładów:

### Użycie OpenRouter

```json
{
  "data_source": {
    "url": "https://hub.ag3nts.org/data/b8307041-adb1-4101-bc7a-b0533e93078a/people.csv"
  },
  "llm": {
    "provider": "openrouter",
    "model": "anthropic/claude-3.5-sonnet",
    "api_key": "TWOJ_KLUCZ_API_OPENROUTER"
  },
  "output_dir": "./output",
  "batch_size": 1000
}
```

### Użycie LM Studio

```json
{
  "data_source": {
    "url": "https://hub.ag3nts.org/data/b8307041-adb1-4101-bc7a-b0533e93078a/people.csv"
  },
  "llm": {
    "provider": "lmstudio",
    "model": "local-model",
    "base_url": "http://localhost:1234"
  },
  "output_dir": "./output",
  "batch_size": 10
}
```

**Uwaga dotycząca batch_size:**
- Dla dostawców chmurowych jak OpenRouter: Używaj większych partii (500-1000) dla lepszej wydajności i efektywności kosztowej
- Dla modeli lokalnych z ograniczonym kontekstem: Używaj mniejszych partii (10-50) aby uniknąć błędów przekroczenia długości kontekstu

## Użycie

1. Zainstaluj zależności:
```bash
go mod tidy
```

2. Utwórz plik konfiguracyjny:
```bash
cp config.example.openrouter.json config.json
# lub
cp config.example.lmstudio.json config.json
```

3. Edytuj `config.json` z własnymi ustawieniami

4. Uruchom aplikację:
```bash
go run cmd/app/main.go
```

Lub z niestandardową ścieżką do konfiguracji:
```bash
go run cmd/app/main.go -config=mojakonfiguracja.json
```

5. Zbuduj aplikację:
```bash
go build -o categorizer cmd/app/main.go
./categorizer
```

## Wyjście

Aplikacja:
- Zapisuje każdą partię do oddzielnego pliku JSON w katalogu `output_dir`
- Każdy plik jest nazwany: `batch_{start}_{end}.json` (np. `batch_0_999.json`)
- Wyświetla końcowe połączone wyniki na stdout
- Zapisuje połączone wyniki do `output.json`

Format pliku partii:
```json
[
  {
    "name": "Jan",
    "surname": "Kowalski",
    "gender": "M",
    "born": 1987,
    "city": "Warszawa",
    "tags": ["IT", "praca z ludźmi"]
  },
  {
    "name": "Anna",
    "surname": "Nowak",
    "gender": "F",
    "born": 1993,
    "city": "Kraków",
    "tags": ["medycyna"]
  }
]
```

Format końcowego wyjścia:
```json
{
  "answer": [
    {
      "name": "Jan",
      "surname": "Kowalski",
      "gender": "M",
      "born": 1987,
      "city": "Warszawa",
      "tags": ["IT", "praca z ludźmi"]
    }
  ]
}
```

## Wznawialne Przetwarzanie

Aplikacja jest w pełni wznawialna:
1. Każda partia jest zapisywana natychmiast po przetworzeniu
2. Po ponownym uruchomieniu, sprawdza które pliki partii już istnieją
3. Pomija już przetworzone partie
4. Kontynuuje z pozostałymi partiami

To oznacza, że możesz:
- Zatrzymać aplikację w dowolnym momencie (Ctrl+C)
- Uruchomić ją ponownie później i będzie kontynuować od miejsca przerwania
- Uruchamiać wielokrotnie bez ponownego przetwarzania wszystkiego
- Dostosować batch_size między uruchomieniami (ale już przetworzone partie nie będą przetwarzane ponownie)

## Rozwój

### Dodawanie Nowych Dostawców LLM

1. Zaimplementuj interfejs `domain.LLMProvider` w `internal/infrastructure/llm/`
2. Dodaj inicjalizację dostawcy w `cmd/app/main.go`
3. Zaktualizuj walidację konfiguracji w `internal/config/config.go`

## Licencja

MIT