Merge pull request #6 from MobileTeleSystems/feature/prettify

Feature/prettify

.github/workflows/test.yml

@@ -28,6 +28,7 @@ jobs:
         run: make lint
 
   test:
+    name: test (${{ matrix.python-version }}, old-deps - ${{ matrix.old-deps }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## Unreleased
+
+### Added

README.md

@@ -1 +1,110 @@
-# RecTools
+# RecTools
+
+[![Python versions](https://img.shields.io/pypi/pyversions/rectools.svg)](https://pypi.org/project/rectools)
+[![PyPI](https://img.shields.io/pypi/v/rectools.svg)](https://pypi.org/project/rectools)
+[![Docs](https://img.shields.io/github/workflow/status/MobileTeleSystems/RecTools/Publish?label=docs)](https://rectools.readthedocs.io)
+
+[![License](https://img.shields.io/github/license/MobileTeleSystems/RecTools.svg)](https://github.com/MobileTeleSystems/RecTools/blob/main/LICENSE)
+[![Coverage](https://img.shields.io/codecov/c/github/MobileTeleSystems/RecTools.svg)](https://app.codecov.io/gh/MobileTeleSystems/RecTools)
+[![Tests](https://img.shields.io/github/workflow/status/MobileTeleSystems/RecTools/Test/main?label=tests)](https://github.com/MobileTeleSystems/RecTools/actions/workflows/test.yml?query=branch%3Amain++)
+
+[![Contributors](https://img.shields.io/github/contributors/MobileTeleSystems/RecTools.svg)](https://github.com/MobileTeleSystems/RecTools/graphs/contributors)
+[![Telegram](https://img.shields.io/badge/channel-telegram-blue)](https://t.me/RecTools_Support)
+
+RecTools is an easy-to-use Python library which makes the process of building recommendation systems easier, 
+faster and more structured than ever before.
+It includes built in toolkits for data processing and metrics calculation, 
+a variety of recommender models, some wrappers for already existing implementations of popular algorithms 
+and model selection framework.
+The aim is to collect ready-to-use solutions and best practices in one place to make processes 
+of creating your first MVP and deploying model to production as fast and easy as possible.
+
+RecTools allows to easily work with dense and sparse features.
+It features such basic models as ones based on random suggestions or popularity and more advanced ones, e.g. LightFM.
+It also contains a wide variety of metrics to choose from to better suit recommender system to your needs.
+
+For more details, see the [Documentation](https://rectools.readthedocs.io/) 
+and [Tutorials](https://github.com/MobileTeleSystems/RecTools/tree/main/examples).
+
+## Get started
+
+Prepare data with
+
+```shell
+wget https://files.grouplens.org/datasets/movielens/ml-1m.zip
+unzip ml-1m.zip
+```
+
+```python
+import pandas as pd
+from implicit.nearest_neighbours import TFIDFRecommender
+
+from rectools import Columns
+from rectools.dataset import Dataset
+from rectools.models import ImplicitItemKNNWrapperModel
+
+# Read the data
+ratings = pd.read_csv(
+    "ml-1m/ratings.dat", 
+    sep="::",
+    engine="python",  # Because of 2-chars separators
+    header=None,
+    names=[Columns.User, Columns.Item, Columns.Weight, Columns.Datetime],
+)
+
+# Create dataset
+dataset = Dataset.construct(ratings)
+
+# Fit model
+model = ImplicitItemKNNWrapperModel(TFIDFRecommender(K=10))
+model.fit(dataset)
+
+# Make recommendations
+recos = model.recommend(
+    users=ratings[Columns.User].unique(),
+    dataset=dataset,
+    k=10,
+    filter_viewed=True,
+)
+```
+
+## Installation
+
+RecTools is on PyPI, so you can use `pip` to install it.
+```
+pip install rectools
+```
+
+
+## Contribution
+
+To install all requirements run
+```
+make install
+```
+You must have `python3` and `poetry` installed.
+
+For autoformatting run 
+```
+make autoformat
+```
+
+For linters check run 
+```
+make lint
+```
+
+For tests run 
+```
+make test
+```
+
+For coverage run 
+```
+make coverage
+```
+
+To remove virtual environment run
+```
+make clean
+```

docs/source/tutorials.rst

@@ -1,6 +1,8 @@
 Tutorials
 =========
 
+See tutorials here: https://github.com/MobileTeleSystems/RecTools/tree/main/examples
+
 .. toctree::
    :maxdepth: 4
    :glob:

pyproject.toml

@@ -1,15 +1,33 @@
 [tool.poetry]
-name = "rectools"
+name = "RecTools"
 version = "0.0.3"
-repository = "https://github.com/MobileTeleSystems/RecTools"
-readme = "README.md"
 description = "An easy-to-use Python library for building recommendation systems"
 license = "Apache-2.0"
 authors = [
-    "Daniil Potapov <[email protected]>",
+    "Daniil Potapov <[email protected]>",
+    "Ildar Safilo <[email protected]>",
+    "Emiliy Feldman <[email protected]",
+    "Alexander Butenko <[email protected]>",
+    "Julia Karamnova <[email protected]>",
+    "Artem Senin <[email protected]>",
+    "Mikhail Khasykov <[email protected]>",
+    "Daria Tikhonovich <[email protected]>",
 ]
 maintainers = [
-    "Daniil Potapov <[email protected]>",
+    "Daniil Potapov <[email protected]>",
+    "Ildar Safilo <[email protected]>",
+    "Emiliy Feldman <[email protected]",
+]
+readme = "README.md"
+homepage = "https://github.com/MobileTeleSystems/RecTools"
+repository = "https://github.com/MobileTeleSystems/RecTools"
+documentation = "https://rectools.readthedocs.io"
+keywords = [
+    "recsys",
+    "recommendation systems",
+    "machine learning",
+    "AI",
+    "personalization",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

rectools/models/vector.py

@@ -99,7 +99,8 @@ def calc(self, subject_id: int) -> np.ndarray:
         elif self.distance == Distance.EUCLIDEAN:
             subject_dot = self.subjects_dots[subject_id]
             dot = self.objects_factors @ subject_factors
-            scores = np.sqrt(self.objects_dots + subject_dot - 2 * dot)
+            d2 = self.objects_dots + subject_dot - 2 * dot
+            scores = np.sqrt(np.maximum(d2, 0))  # Theoretically d2 >= 0, but can be <0 because of rounding errors
         elif self.distance == Distance.COSINE:
             subject_norm = self.subjects_norms[subject_id]
             if subject_norm == 0: