# Django RecomPI
*Django RecomPI* is a Django model mixin that integrates functionalities of RecomPI (Recommender System API) with Django models, enabling easy recommendation and tracking capabilities within Django applications.
## Installation
You can install *Django RecomPI* via pip. Here's how:
```bash
pip install django-recompi
```
---
## Quick Start
### Setting up a Django model with RecomPI integration
1. **Define your Django model** (e.g., `Product`) and use `RecomPIModelMixin` as a mixin.
```python
from typing import List
from django.db import models
from django_recompi.models import RecomPIModelMixin
class Product(models.Model, RecomPIModelMixin):
RECOMPI_DATA_FIELDS = [
"name", # current model's field
"reviews__comment", # join operation
"reviews__counter.count", # join and `dot` operations
"callable_method_single_return", # callable method with signle return
"callable_method_list_return", # callable method with list return
"reviews__counter.callable_method", # join and method-call operations
]
name = models.CharField(max_length=100, db_index=True)
description = models.TextField()
def callable_method_single_return(self) -> str:
return "a-value"
def callable_method_list_return(self) -> List[str]:
return ["list", "of", "values"]
def __str__(self):
return self.name
```
2. **Define related models** such as `Review` and `ReviewCounter` with appropriate fields.
```python
from django.db import models
class Review(models.Model):
product = models.ForeignKey(Product, related_name="reviews", on_delete=models.CASCADE)
comment = models.CharField(max_length=200, db_index=True)
rating = models.CharField(choices=RatingChoices.choices, max_length=1, db_index=True)
counter = models.ForeignKey("ReviewCounter", related_name="reviews", on_delete=models.CASCADE, default=None, null=True, blank=True)
def __str__(self):
return f"Review of {self.product.name} - {self.rating}"
class ReviewCounter(models.Model):
count = models.IntegerField(default=0)
```
### Tracking interactions
```python
# Track user interaction with a product
product = Product.objects.first()
# Using SecureProfile to hash profile identifiers before sending to RecomPI
profile = SecureProfile("profile_id", "user_profile_id")
# Providing location information including optional data
location = Location(
ip="1.1.1.1", # Optional: IP address of the user
url="https://www.example.com/products/1",
referer="REFERER_URL", # Optional: Referring URL
useragent="USERAGENT" # Optional: User agent of the client
)
# Tracking the interaction using RecomPI integration
product.recompi_track(
"product-view", # Interaction label
profile, # SecureProfile instance
location # Location instance
)
```
This revised version clarifies the usage of `SecureProfile` and `Location` classes while also providing a clear example of how to track user interactions with a product using the `recompi_track` method. We encourage you to refer to the original [RecomPI package documentation](https://pypi.org/project/recompi/) for detailed information on these classes and other useful utilities like `Profile`.
### Getting recommendations
```python
# Get product recommendations for a user
recommendations = Product.recompi_recommend(
"product-view",
SecureProfile("profile_id", "user_profile_id"),
)
# Example of printing recommendations
print(
{
k: {"name": p.name, "recommedation-rank": p.recompi_rank}
for k, pp in recommendations.items()
for p in pp
}
)
```
---
## RecomPI as a Recommendation-Based Search Engine
The `django-recompi` package provides a fast, reliable, and secure recommendation-based search engine.
### Perform a Search
```python
results = Product.recompi_search(
query="awesome product",
labels="product-view"
)
```
### Track a Click
```python
product = Product.objects.get(pk=1395)
product.recompi_search_track(
query="awesome product",
location=Location(url="https://www.example.com/search-page"),
labels="product-view"
)
```
For more detailed information, check out our [advanced documentation](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#6-search-methods-in-recompimodelmixin). You can also learn how to pre-train RecomPI's A.I. to boost results from day one with a single script [here](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#pre-train-data-for-optimal-search-engine-performance).
### Examples and Use Cases
Explore these examples to understand how *Django RecomPI* can be applied:
- **E-commerce Recommendation**: Track user interactions on product pages and recommend related products based on their behavior.
- **Content Personalization**: Customize content recommendations based on user preferences and historical interactions.
---
## Linking two objects with each other using recommendation system
Linking two models requires additional data fields to create a `SecureProfile` instance. By default, the package uses the primary key (`pk`) as the profile ID. However, in scenarios where linking models based on a series of fields is necessary—such as suggesting products based on client attributes like gender, age, and tourist status—using `pk` as the profile ID may not be suitable. For instance, if a user is a one-time visitor unlikely to return soon, a more tailored approach is needed.
### Example: Customizing `Client` Profile Fields
```python
class Client(AbstractUser, RecomPIModelMixin):
RECOMPI_PROFILE_ID = [
"gender",
"age",
"if_tourist",
# Add more relevant fields as needed
]
```
### Recommending Products to Clients
To recommend products to a given `Client`, use the following example:
```python
client = Client.objects.get(**criteria)
recommended_products = client.recompi_recommend_links(
model_class=Product,
labels=["buy", "interested"]
)
for label, products in recommended_products.items():
for product in products:
print("Recommend Product #{} for '{}'".format(product.pk, label))
```
### Linking Client Interests to Products
After gathering client information and observing their interactions, link clients to products:
```python
products_bought = Product.objects.filter(pk__in=BOUGHT_PRODUCT_IDS)
products_of_interest = Product.objects.filter(pk__in=INTERESTED_PRODUCT_IDS)
for product in products_bought:
client.recompi_link(
instance=product,
label="buy",
location="https://www.example.com/product/{}".format(product.pk),
)
for product in products_of_interest:
client.recompi_link(
instance=product,
label="interested",
location="https://www.example.com/product/{}".format(product.pk),
)
```
This example can be extended to any scenario where you need to establish links between two models and receive recommended objects in return.
### Benefits of Linked Objects Using RecomPI
- **Enhanced Personalization:** Tailor recommendations based on user interactions.
- **Improved Engagement:** Guide users through related items for increased interaction.
- **Behavioral Insights:** Understand user preferences to refine recommendations.
- **Optimized Search:** Deliver precise search results by understanding item relationships.
- **Accelerated Learning:** Quickly optimize recommendations by pre-training with linked objects.
- **Detailed Analytics:** Analyze user interactions to inform decision-making and strategy.
### Example Use Cases
1. **E-commerce:** Enhance product discovery with complementary item recommendations.
2. **Content Platforms:** Keep users engaged with relevant articles or videos based on interests.
3. **Social Networks:** Foster community engagement by suggesting connections based on shared interests.
For advanced features and more detailed information, refer to our [advanced documentation](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#7-linking-two-records-from-two-different-models).
---
## Settings Configuration
*Django RecomPI* can be customized through the following settings in your `settings.py` file, you can read the full documentation [here](https://github.com/recompi/django-recompi/blob/main/docs/settings.md); but the most important settings you **much set** in your `settings.py` is `RECOMPI_API_KEY`:
### `RECOMPI_API_KEY`
- **Type:** `str`
- **Description:** API key for accessing the RecomPI service. Required for integration.
- **Note:** To obtain `RECOMPI_API_KEY`, register on the [RecomPI panel](https://panel.recompi.com/clients/sign_in). After registration, [add a campaign](https://panel.recompi.com/campaigns/new) in the panel, and a campaign token will be generated instantly. Use this token as your API key in the code.
---
## Security Considerations
Ensure the following security best practices when using *Django RecomPI*:
- **Secure API Key Handling**: Keep `RECOMPI_API_KEY` secure and avoid exposing it in version control or public repositories.
- **Data Encryption**: Use HTTPS (`RECOMPI_SECURE_API`) to encrypt data transmitted between your Django application and the RecomPI service.
- **Secure Profile Hashing**: Utilize `RECOMPI_SECURE_HASH_SALT` to hash profile IDs and other data obscuring before sending them to RecomPI servers. This helps protect user data by obscuring identifiable information during transmission and afterward.
---
## In-Depth Guide
Explore our in-depth guide to uncover advanced topics and features of the `django-recompi` package. This section provides essential insights for developing sophisticated recommendation systems using RecomPI. For detailed information, visit the [Advanced Documentation](https://github.com/recompi/django-recompi/blob/main/docs/advanced.md).
---
## Basic Usage
The `django-recompi` package is built on top of the core `recompi` package. Therefore, understanding the foundational concepts and functionalities in the `recompi` package is essential. For an introduction to the basic usage of `django-recompi`, including how to work with essential classes like `SecureProfile` and `Profile`, please refer to our [PyPI page](https://pypi.org/project/recompi/). This resource offers comprehensive examples and instructions to help you get started with implementing fundamental features of the RecomPI recommendation system.
---
## Contributing and Development
We welcome contributions to *Django RecomPI*! If you'd like to contribute, please follow these steps:
- Fork the repository and clone it to your local environment.
- Install dependencies and set up a development environment.
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt
pre-commit install --hook-type pre-commit --hook-type pre-push
```
- Make changes, write tests, and ensure all tests pass.
- Submit a pull request with a detailed description of your changes.
## Support
For support or questions, please submit a [ticket](https://panel.recompi.com/tickets/new) or [open an issue](https://github.com/recompi/django-recompi/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-recompi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "django, recompi, recommendation, tracking, recommender system, machine learning, data science, web development",
"author": null,
"author_email": "RecomPI <tech@recompi.com>",
"download_url": "https://files.pythonhosted.org/packages/e0/b8/d4160ad98e6bf223f159863506177ebfe9fe0bc96f7b6526e56c362a798f/django_recompi-2.2.1.tar.gz",
"platform": null,
"description": "# Django RecomPI\n\n*Django RecomPI* is a Django model mixin that integrates functionalities of RecomPI (Recommender System API) with Django models, enabling easy recommendation and tracking capabilities within Django applications.\n\n## Installation\n\nYou can install *Django RecomPI* via pip. Here's how:\n\n```bash\npip install django-recompi\n```\n\n---\n\n## Quick Start\n\n### Setting up a Django model with RecomPI integration\n\n1. **Define your Django model** (e.g., `Product`) and use `RecomPIModelMixin` as a mixin.\n\n```python\nfrom typing import List\nfrom django.db import models\nfrom django_recompi.models import RecomPIModelMixin\n\nclass Product(models.Model, RecomPIModelMixin):\n RECOMPI_DATA_FIELDS = [\n \"name\", # current model's field\n \"reviews__comment\", # join operation\n \"reviews__counter.count\", # join and `dot` operations\n \"callable_method_single_return\", # callable method with signle return\n \"callable_method_list_return\", # callable method with list return\n \"reviews__counter.callable_method\", # join and method-call operations\n ]\n name = models.CharField(max_length=100, db_index=True)\n description = models.TextField()\n\n def callable_method_single_return(self) -> str:\n return \"a-value\"\n\n def callable_method_list_return(self) -> List[str]:\n return [\"list\", \"of\", \"values\"]\n\n def __str__(self):\n return self.name\n```\n\n2. **Define related models** such as `Review` and `ReviewCounter` with appropriate fields.\n\n```python\nfrom django.db import models\n\nclass Review(models.Model):\n product = models.ForeignKey(Product, related_name=\"reviews\", on_delete=models.CASCADE)\n comment = models.CharField(max_length=200, db_index=True)\n rating = models.CharField(choices=RatingChoices.choices, max_length=1, db_index=True)\n counter = models.ForeignKey(\"ReviewCounter\", related_name=\"reviews\", on_delete=models.CASCADE, default=None, null=True, blank=True)\n\n def __str__(self):\n return f\"Review of {self.product.name} - {self.rating}\"\n\nclass ReviewCounter(models.Model):\n count = models.IntegerField(default=0)\n```\n\n### Tracking interactions\n\n```python\n# Track user interaction with a product\nproduct = Product.objects.first()\n\n# Using SecureProfile to hash profile identifiers before sending to RecomPI\nprofile = SecureProfile(\"profile_id\", \"user_profile_id\")\n\n# Providing location information including optional data\nlocation = Location(\n ip=\"1.1.1.1\", # Optional: IP address of the user\n url=\"https://www.example.com/products/1\",\n referer=\"REFERER_URL\", # Optional: Referring URL\n useragent=\"USERAGENT\" # Optional: User agent of the client\n)\n\n# Tracking the interaction using RecomPI integration\nproduct.recompi_track(\n \"product-view\", # Interaction label\n profile, # SecureProfile instance\n location # Location instance\n)\n```\n\nThis revised version clarifies the usage of `SecureProfile` and `Location` classes while also providing a clear example of how to track user interactions with a product using the `recompi_track` method. We encourage you to refer to the original [RecomPI package documentation](https://pypi.org/project/recompi/) for detailed information on these classes and other useful utilities like `Profile`.\n\n### Getting recommendations\n\n```python\n# Get product recommendations for a user\nrecommendations = Product.recompi_recommend(\n \"product-view\",\n SecureProfile(\"profile_id\", \"user_profile_id\"),\n)\n\n# Example of printing recommendations\nprint(\n {\n k: {\"name\": p.name, \"recommedation-rank\": p.recompi_rank}\n for k, pp in recommendations.items()\n for p in pp\n }\n)\n```\n---\n\n## RecomPI as a Recommendation-Based Search Engine\n\nThe `django-recompi` package provides a fast, reliable, and secure recommendation-based search engine.\n\n### Perform a Search\n```python\nresults = Product.recompi_search(\n query=\"awesome product\",\n labels=\"product-view\"\n)\n```\n\n### Track a Click\n```python\nproduct = Product.objects.get(pk=1395)\nproduct.recompi_search_track(\n query=\"awesome product\",\n location=Location(url=\"https://www.example.com/search-page\"),\n labels=\"product-view\"\n)\n```\n\nFor more detailed information, check out our [advanced documentation](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#6-search-methods-in-recompimodelmixin). You can also learn how to pre-train RecomPI's A.I. to boost results from day one with a single script [here](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#pre-train-data-for-optimal-search-engine-performance).\n\n### Examples and Use Cases\n\nExplore these examples to understand how *Django RecomPI* can be applied:\n\n- **E-commerce Recommendation**: Track user interactions on product pages and recommend related products based on their behavior.\n- **Content Personalization**: Customize content recommendations based on user preferences and historical interactions.\n\n---\n\n## Linking two objects with each other using recommendation system\n\nLinking two models requires additional data fields to create a `SecureProfile` instance. By default, the package uses the primary key (`pk`) as the profile ID. However, in scenarios where linking models based on a series of fields is necessary\u2014such as suggesting products based on client attributes like gender, age, and tourist status\u2014using `pk` as the profile ID may not be suitable. For instance, if a user is a one-time visitor unlikely to return soon, a more tailored approach is needed.\n\n### Example: Customizing `Client` Profile Fields\n\n```python\nclass Client(AbstractUser, RecomPIModelMixin):\n RECOMPI_PROFILE_ID = [\n \"gender\",\n \"age\",\n \"if_tourist\",\n # Add more relevant fields as needed\n ]\n```\n\n### Recommending Products to Clients\n\nTo recommend products to a given `Client`, use the following example:\n\n```python\nclient = Client.objects.get(**criteria)\nrecommended_products = client.recompi_recommend_links(\n model_class=Product,\n labels=[\"buy\", \"interested\"]\n)\n\nfor label, products in recommended_products.items():\n for product in products:\n print(\"Recommend Product #{} for '{}'\".format(product.pk, label))\n```\n\n### Linking Client Interests to Products\n\nAfter gathering client information and observing their interactions, link clients to products:\n\n```python\nproducts_bought = Product.objects.filter(pk__in=BOUGHT_PRODUCT_IDS)\nproducts_of_interest = Product.objects.filter(pk__in=INTERESTED_PRODUCT_IDS)\n\nfor product in products_bought:\n client.recompi_link(\n instance=product,\n label=\"buy\",\n location=\"https://www.example.com/product/{}\".format(product.pk),\n )\n\nfor product in products_of_interest:\n client.recompi_link(\n instance=product,\n label=\"interested\",\n location=\"https://www.example.com/product/{}\".format(product.pk),\n )\n```\n\nThis example can be extended to any scenario where you need to establish links between two models and receive recommended objects in return.\n\n### Benefits of Linked Objects Using RecomPI\n\n- **Enhanced Personalization:** Tailor recommendations based on user interactions.\n- **Improved Engagement:** Guide users through related items for increased interaction.\n- **Behavioral Insights:** Understand user preferences to refine recommendations.\n- **Optimized Search:** Deliver precise search results by understanding item relationships.\n- **Accelerated Learning:** Quickly optimize recommendations by pre-training with linked objects.\n- **Detailed Analytics:** Analyze user interactions to inform decision-making and strategy.\n\n### Example Use Cases\n\n1. **E-commerce:** Enhance product discovery with complementary item recommendations.\n2. **Content Platforms:** Keep users engaged with relevant articles or videos based on interests.\n3. **Social Networks:** Foster community engagement by suggesting connections based on shared interests.\n\nFor advanced features and more detailed information, refer to our [advanced documentation](https://github.com/recompi/django-recompi/blob/develop/docs/advanced.md#7-linking-two-records-from-two-different-models).\n\n---\n\n## Settings Configuration\n\n*Django RecomPI* can be customized through the following settings in your `settings.py` file, you can read the full documentation [here](https://github.com/recompi/django-recompi/blob/main/docs/settings.md); but the most important settings you **much set** in your `settings.py` is `RECOMPI_API_KEY`:\n\n### `RECOMPI_API_KEY`\n\n- **Type:** `str`\n- **Description:** API key for accessing the RecomPI service. Required for integration.\n- **Note:** To obtain `RECOMPI_API_KEY`, register on the [RecomPI panel](https://panel.recompi.com/clients/sign_in). After registration, [add a campaign](https://panel.recompi.com/campaigns/new) in the panel, and a campaign token will be generated instantly. Use this token as your API key in the code.\n\n---\n\n## Security Considerations\n\nEnsure the following security best practices when using *Django RecomPI*:\n\n- **Secure API Key Handling**: Keep `RECOMPI_API_KEY` secure and avoid exposing it in version control or public repositories.\n- **Data Encryption**: Use HTTPS (`RECOMPI_SECURE_API`) to encrypt data transmitted between your Django application and the RecomPI service.\n- **Secure Profile Hashing**: Utilize `RECOMPI_SECURE_HASH_SALT` to hash profile IDs and other data obscuring before sending them to RecomPI servers. This helps protect user data by obscuring identifiable information during transmission and afterward.\n\n---\n\n## In-Depth Guide\n\nExplore our in-depth guide to uncover advanced topics and features of the `django-recompi` package. This section provides essential insights for developing sophisticated recommendation systems using RecomPI. For detailed information, visit the [Advanced Documentation](https://github.com/recompi/django-recompi/blob/main/docs/advanced.md).\n\n---\n\n## Basic Usage\n\nThe `django-recompi` package is built on top of the core `recompi` package. Therefore, understanding the foundational concepts and functionalities in the `recompi` package is essential. For an introduction to the basic usage of `django-recompi`, including how to work with essential classes like `SecureProfile` and `Profile`, please refer to our [PyPI page](https://pypi.org/project/recompi/). This resource offers comprehensive examples and instructions to help you get started with implementing fundamental features of the RecomPI recommendation system.\n\n---\n\n## Contributing and Development\n\nWe welcome contributions to *Django RecomPI*! If you'd like to contribute, please follow these steps:\n\n- Fork the repository and clone it to your local environment.\n- Install dependencies and set up a development environment.\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements-dev.txt\npre-commit install --hook-type pre-commit --hook-type pre-push\n```\n\n- Make changes, write tests, and ensure all tests pass.\n- Submit a pull request with a detailed description of your changes.\n\n## Support\n\nFor support or questions, please submit a [ticket](https://panel.recompi.com/tickets/new) or [open an issue](https://github.com/recompi/django-recompi/issues) on GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "Integration of RecomPI with Django models for recommendation and tracking functionalities.",
"version": "2.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/recompi/django-recompi/issues",
"Panel": "https://panel.recompi.com",
"RecomPI Package": "https://pypi.org/project/recompi",
"Source": "https://github.com/recompi/django-recompi",
"Use Cases": "https://www.recompi.com/category/use-cases/documents-use-cases",
"Website": "https://www.recompi.com",
"Wordpress Plugin": "https://www.zhaket.com/web/recompi-plugin"
},
"split_keywords": [
"django",
" recompi",
" recommendation",
" tracking",
" recommender system",
" machine learning",
" data science",
" web development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2c4903be42d00c332d888f042c986bfd0bf90d4129058737f806c49018bc3ad",
"md5": "ea2ea0ae38bb530094aed33affd85080",
"sha256": "90ab6aba45f6cf84450ad1bf30c841f6dfd67fdeaeb1ec8079a2b10d73431719"
},
"downloads": -1,
"filename": "django_recompi-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea2ea0ae38bb530094aed33affd85080",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 13717,
"upload_time": "2024-07-12T13:14:26",
"upload_time_iso_8601": "2024-07-12T13:14:26.775659Z",
"url": "https://files.pythonhosted.org/packages/d2/c4/903be42d00c332d888f042c986bfd0bf90d4129058737f806c49018bc3ad/django_recompi-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0b8d4160ad98e6bf223f159863506177ebfe9fe0bc96f7b6526e56c362a798f",
"md5": "54141c3e6e51ab542c627196b974a36f",
"sha256": "c800741709636c93e072c05802eb873556460c723dbba2b5f3b14579838e7b7b"
},
"downloads": -1,
"filename": "django_recompi-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "54141c3e6e51ab542c627196b974a36f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 24523,
"upload_time": "2024-07-12T13:14:28",
"upload_time_iso_8601": "2024-07-12T13:14:28.978349Z",
"url": "https://files.pythonhosted.org/packages/e0/b8/d4160ad98e6bf223f159863506177ebfe9fe0bc96f7b6526e56c362a798f/django_recompi-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-12 13:14:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "recompi",
"github_project": "django-recompi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "django-recompi"
}
JSON
