Metadata-Version: 2.4
Name: flocke
Version: 0.1.1
Summary: Analyze latent group patterns based on annotator behavior
License-File: LICENSE
Author: Michele Lombardi
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: numpy (>=2.3.2,<3.0.0)
Requires-Dist: torch (>=2.7.1,<3.0.0)
Requires-Dist: tqdm (>=4.68.2,<5.0.0)
Description-Content-Type: text/markdown

# FLOCKE

A framework to discover latent groups of users from their behavior.

FLOCKE groups users into a fixed number of latent *types* according to how they respond to the same kind of input. Users can be annotators labeling data, customers making choices, or anyone else whose behavior you observe. FLOCKE trains a type-conditioned PyTorch model and, at the same time, estimates each user's probability of belonging to each type.

## Installation

```bash
pip install flocke
```

## Usage

Each example is one observation: which user it comes from (`u`), the input they saw (`x`), and how they responded (`y`).

```python
from flocke import Flocke, FlockeData, MLPClassifier

data = FlockeData(u, x, y, remap_user_ids=True)  # remap if ids aren't 0..n-1

flocke = Flocke(MLPClassifier(ninputs=x.shape[1], ntypes=3, nclasses=2, hidden=[32, 16]), p_reoptimization_period=10)
flocke.fit(data, max_epochs=50)

# Average log-likelihood, plus one type-distribution per user
score, types = flocke.score(data, return_proba=True)

# Most likely type of a new user, from their own observations
flocke.predict(x_new, y_new)

# Responses predicted for a user of type 0
flocke.mdl.restrict(0).predict(x)

# Save the model
flocke.save("flocke.pt")

# Load a saved model
flocke = Flocke.load("flocke.pt")
```

For multi-label data, pass `multilabel=True` to `MLPClassifier`.

