# RecomPI API
A Python wrapper for the RecomPI API, providing methods to interact with the service for tracking user behavior and obtaining recommendations.
## Installation
Install the RecomPI library using pip:
```bash
pip install recompi
```
## Usage
### Initialization
Create an instance of the `RecomPI` class using your campaign's API key.
```python
from recompi import RecomPI
api = RecomPI(api_key="YOUR_CAMPAIGN_TOKEN")
```
> **Campaign Token**: To obtain `YOUR_CAMPAIGN_TOKEN`, 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.
### Pushing User Behavior
Use the `push` method to send user interaction data to the RecomPI API. You can include tags, profiles, location, and geographical information.
```python
from recompi import RecomPI, Tag, Profile, SecureProfile, Location, Geo
api = RecomPI(api_key="YOUR_CAMPAIGN_TOKEN")
response = api.push(
label="click",
tags=[
Tag(id="1", name="Technology", desc="Technology News"),
Tag(
id="2",
name="Online Marketing Tools",
desc="Latest news on online marketing tools",
),
],
profiles=Profile("user_id", "123"),
location=Location(
ip="1.1.1.1", # Optional
url="https://www.example.com/some/path?param1=1¶m2=2",
referer="REFERER_URL", # Optional
useragent="USERAGENT", # Optional
),
geo=Geo(
country="Iran", # Optional: 'IR' or the unique country ID
province="Tehran", # Optional: Any unique string
), # Optional
)
print(response) # [success: true]
```
#### Parameters
- `label` (str): A label for the event, e.g., "click".
- `tags` (list[Tag]): List of `Tag` objects representing metadata.
- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.
- `location` (Location, optional): A `Location` object containing IP, URL, referer, and user-agent information.
- `geo` (Geo, optional): A `Geo` object containing geographical information like country and province.
### Getting Recommendations
Use the `recom` method to get recommendations based on user interactions, profiles, and geographical information.
```python
from recompi import RecomPI, Profile, Geo
api = RecomPI(api_key="YOUR_CAMPAIGN_TOKEN")
response = api.recom(
labels=["click", "buy"],
profiles=Profile("user_id", "123"),
geo=Geo(
country="Iran", # Optional: 'IR' or unique country ID
province="Tehran", # Optional: Any unique string
),
)
print(response) # [success: true] {'click': {'18': 0.25, '19': 0.75}, 'buy': {'13': 0.89, '95': 0.11}}
```
#### Parameters
- `labels` (list[str]): List of event labels for which recommendations are requested.
- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile, optional): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.
- `geo` (Geo, optional): A `Geo` object containing geographical information.
#### Explanation of Response:
The response structure (`{'click': {'18': 0.25, '19': 0.75}, 'buy': {'13': 0.89, '95': 0.11}}`) indicates:
- For the `click` label, the user is predicted to engage more with `Tag.id = 19` (with a probability of `0.75`) compared to `Tag.id = 18` (`0.25`).
- For the `buy` label, the user is likely to make a purchase with `Tag.id = 13` (`0.89` probability) rather than `Tag.id = 95` (`0.11` probability).
These predictions are derived from the user's past interactions (`click` and `buy` events) and other factors such as their profile attributes and geographical location. The recommendation engine uses this data to suggest items or actions that are likely to be of interest to the user, helping to optimize engagement or conversions based on predictive analytics.
### Verifying API Connectivity
Use the `verify` method to check if the API key and configuration are correct.
```python
from recompi import RecomPI
api = RecomPI(api_key="YOUR_CAMPAIGN_TOKEN")
response = api.verify()
print("API is well configured and connected?", response.is_success()) # [success: true]
```
### Usage with SecureProfile
You can use `SecureProfile` to ensure that sensitive information such as user IDs are hashed before being sent to the API. This adds an extra layer of security by obfuscating the actual IDs.
```python
from recompi import RecomPI, Tag, SecureProfile, Location, Geo
api = RecomPI(api_key="YOUR_CAMPAIGN_TOKEN", hash_salt="SOME_HASH_SALT")
response = api.push(
label="click",
tags=[
Tag(id="1", name="Technology", desc="Technology News"),
Tag(
id="2",
name="Online Marketing Tools",
desc="Latest news on online marketing tools",
),
],
profiles=SecureProfile(name="user_id", id="123"),
location=Location(
ip="1.1.1.1", # Optional
url="https://www.example.com/some/path?param1=1¶m2=2",
referer="REFERER_URL", # Optional
useragent="USERAGENT", # Optional
),
geo=Geo(
country="Iran", # Optional: 'IR' or the unique country ID
province="Tehran", # Optional: Any unique string
), # Optional
)
print(response) # [success: true]
```
#### Parameters
- `label` (str): A label for the event, e.g., "click".
- `tags` (list[Tag]): List of `Tag` objects representing metadata.
- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.
- `location` (Location, optional): A `Location` object containing IP, URL, referer, and user-agent information.
- `geo` (Geo, optional): A `Geo` object containing geographical information like country and province.
### Additional Details:
- **Initialization**: `SecureProfile` is initialized with `name` and `id`. It extends the base `Profile` to add the capability of hashing the `id`.
- **`to_json` Method**: This method converts the `SecureProfile` instance to a JSON-compatible dictionary, hashing the `id` if a `hash_salt` is provided. This is useful for securely sending profile data.
- **`recom`**: If you use `SecureProfile` in the `push` method, you must also use `SecureProfile` to retrieve data with the `recom` method. This ensures the consistency of hashed data between sending and retrieving.
### Data Structures
#### Tag
Represents a tag with an ID, name, and description.
```python
from recompi import Tag
tag = Tag(id="1", name="Technology", desc="Technology News")
```
#### Profile
Represents a user profile with an ID and name.
```python
from recompi import Profile
profile = Profile(name="user_id", id="123")
print(profile.to_json()) # {'user_id': '123'}
```
#### SecureProfile
Represents a user profile with a secure ID and name.
```python
from recompi import SecureProfile
profile = SecureProfile(name="user_id", id="123")
print(profile.to_json()) # {'user_id': 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'}
print(profile.to_json("SOME_HASH_SALT")) # {'user_id': 'e6ee87b7300073f85bc86d817b6656d58443b23438faacc6737bde461ecf38cd'}
```
#### Location
Represents a location with IP, URL, referer, and user-agent information.
```python
from recompi import Location
location = Location(ip="1.1.1.1", url="https://www.example.com", referer="REFERER_URL", useragent="USERAGENT")
```
#### Geo
Represents geographical information with country and province.
```python
from recompi import Geo
geo = Geo(country="Iran", province="Tehran")
```
### Error Handling
#### RecomPIFieldTypeError
Raised when an input field does not match the expected type.
```python
from recompi import RecomPIFieldTypeError
try:
# Some operation that might raise an error
pass
except RecomPIFieldTypeError as e:
print(e)
```
#### RecomPIException
General exception class for other RecomPI errors.
```python
from recompi import RecomPIException
try:
# Some operation that might raise an error
pass
except RecomPIException as e:
print(e)
```
## Contributing and Development
We welcome contributions to *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/python-recompi/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "recompi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=2.7",
"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/2c/37/387bcaf4d8ea8bb21d5e66ffbbd85a55efa3f97161bcac5c87e584196dcf/recompi-2.0.20.tar.gz",
"platform": null,
"description": "# RecomPI API\n\nA Python wrapper for the RecomPI API, providing methods to interact with the service for tracking user behavior and obtaining recommendations.\n\n## Installation\n\nInstall the RecomPI library using pip:\n\n```bash\npip install recompi\n```\n\n## Usage\n\n### Initialization\n\nCreate an instance of the `RecomPI` class using your campaign's API key.\n\n```python\nfrom recompi import RecomPI\n\napi = RecomPI(api_key=\"YOUR_CAMPAIGN_TOKEN\")\n```\n\n> **Campaign Token**: To obtain `YOUR_CAMPAIGN_TOKEN`, 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### Pushing User Behavior\n\nUse the `push` method to send user interaction data to the RecomPI API. You can include tags, profiles, location, and geographical information.\n\n```python\nfrom recompi import RecomPI, Tag, Profile, SecureProfile, Location, Geo\n\napi = RecomPI(api_key=\"YOUR_CAMPAIGN_TOKEN\")\nresponse = api.push(\n label=\"click\",\n tags=[\n Tag(id=\"1\", name=\"Technology\", desc=\"Technology News\"),\n Tag(\n id=\"2\",\n name=\"Online Marketing Tools\",\n desc=\"Latest news on online marketing tools\",\n ),\n ],\n profiles=Profile(\"user_id\", \"123\"),\n location=Location(\n ip=\"1.1.1.1\", # Optional\n url=\"https://www.example.com/some/path?param1=1¶m2=2\",\n referer=\"REFERER_URL\", # Optional\n useragent=\"USERAGENT\", # Optional\n ),\n geo=Geo(\n country=\"Iran\", # Optional: 'IR' or the unique country ID\n province=\"Tehran\", # Optional: Any unique string\n ), # Optional\n)\nprint(response) # [success: true]\n```\n\n#### Parameters\n\n- `label` (str): A label for the event, e.g., \"click\".\n- `tags` (list[Tag]): List of `Tag` objects representing metadata.\n- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.\n- `location` (Location, optional): A `Location` object containing IP, URL, referer, and user-agent information.\n- `geo` (Geo, optional): A `Geo` object containing geographical information like country and province.\n\n\n### Getting Recommendations\n\nUse the `recom` method to get recommendations based on user interactions, profiles, and geographical information.\n\n```python\nfrom recompi import RecomPI, Profile, Geo\n\napi = RecomPI(api_key=\"YOUR_CAMPAIGN_TOKEN\")\nresponse = api.recom(\n labels=[\"click\", \"buy\"],\n profiles=Profile(\"user_id\", \"123\"),\n geo=Geo(\n country=\"Iran\", # Optional: 'IR' or unique country ID\n province=\"Tehran\", # Optional: Any unique string\n ),\n)\nprint(response) # [success: true] {'click': {'18': 0.25, '19': 0.75}, 'buy': {'13': 0.89, '95': 0.11}}\n```\n\n#### Parameters\n\n- `labels` (list[str]): List of event labels for which recommendations are requested.\n- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile, optional): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.\n- `geo` (Geo, optional): A `Geo` object containing geographical information.\n\n#### Explanation of Response:\nThe response structure (`{'click': {'18': 0.25, '19': 0.75}, 'buy': {'13': 0.89, '95': 0.11}}`) indicates:\n- For the `click` label, the user is predicted to engage more with `Tag.id = 19` (with a probability of `0.75`) compared to `Tag.id = 18` (`0.25`).\n- For the `buy` label, the user is likely to make a purchase with `Tag.id = 13` (`0.89` probability) rather than `Tag.id = 95` (`0.11` probability).\n\nThese predictions are derived from the user's past interactions (`click` and `buy` events) and other factors such as their profile attributes and geographical location. The recommendation engine uses this data to suggest items or actions that are likely to be of interest to the user, helping to optimize engagement or conversions based on predictive analytics.\n\n### Verifying API Connectivity\n\nUse the `verify` method to check if the API key and configuration are correct.\n\n```python\nfrom recompi import RecomPI\n\napi = RecomPI(api_key=\"YOUR_CAMPAIGN_TOKEN\")\nresponse = api.verify()\nprint(\"API is well configured and connected?\", response.is_success()) # [success: true]\n```\n\n### Usage with SecureProfile\n\nYou can use `SecureProfile` to ensure that sensitive information such as user IDs are hashed before being sent to the API. This adds an extra layer of security by obfuscating the actual IDs.\n\n```python\nfrom recompi import RecomPI, Tag, SecureProfile, Location, Geo\n\napi = RecomPI(api_key=\"YOUR_CAMPAIGN_TOKEN\", hash_salt=\"SOME_HASH_SALT\")\nresponse = api.push(\n label=\"click\",\n tags=[\n Tag(id=\"1\", name=\"Technology\", desc=\"Technology News\"),\n Tag(\n id=\"2\",\n name=\"Online Marketing Tools\",\n desc=\"Latest news on online marketing tools\",\n ),\n ],\n profiles=SecureProfile(name=\"user_id\", id=\"123\"),\n location=Location(\n ip=\"1.1.1.1\", # Optional\n url=\"https://www.example.com/some/path?param1=1¶m2=2\",\n referer=\"REFERER_URL\", # Optional\n useragent=\"USERAGENT\", # Optional\n ),\n geo=Geo(\n country=\"Iran\", # Optional: 'IR' or the unique country ID\n province=\"Tehran\", # Optional: Any unique string\n ), # Optional\n)\nprint(response) # [success: true]\n```\n\n#### Parameters\n\n- `label` (str): A label for the event, e.g., \"click\".\n- `tags` (list[Tag]): List of `Tag` objects representing metadata.\n- `profiles` (list[Profile|SecureProfile] or Profile|SecureProfile): List of `Profile` or `SecureProfile` objects or a single `Profile` or a single `SecureProfile`.\n- `location` (Location, optional): A `Location` object containing IP, URL, referer, and user-agent information.\n- `geo` (Geo, optional): A `Geo` object containing geographical information like country and province.\n\n### Additional Details:\n\n- **Initialization**: `SecureProfile` is initialized with `name` and `id`. It extends the base `Profile` to add the capability of hashing the `id`.\n- **`to_json` Method**: This method converts the `SecureProfile` instance to a JSON-compatible dictionary, hashing the `id` if a `hash_salt` is provided. This is useful for securely sending profile data.\n- **`recom`**: If you use `SecureProfile` in the `push` method, you must also use `SecureProfile` to retrieve data with the `recom` method. This ensures the consistency of hashed data between sending and retrieving.\n\n\n### Data Structures\n\n#### Tag\n\nRepresents a tag with an ID, name, and description.\n\n```python\nfrom recompi import Tag\n\ntag = Tag(id=\"1\", name=\"Technology\", desc=\"Technology News\")\n```\n\n#### Profile\n\nRepresents a user profile with an ID and name.\n\n```python\nfrom recompi import Profile\n\nprofile = Profile(name=\"user_id\", id=\"123\")\n\nprint(profile.to_json()) # {'user_id': '123'}\n```\n\n#### SecureProfile\n\nRepresents a user profile with a secure ID and name.\n\n```python\nfrom recompi import SecureProfile\n\nprofile = SecureProfile(name=\"user_id\", id=\"123\")\n\nprint(profile.to_json()) # {'user_id': 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'}\nprint(profile.to_json(\"SOME_HASH_SALT\")) # {'user_id': 'e6ee87b7300073f85bc86d817b6656d58443b23438faacc6737bde461ecf38cd'}\n```\n\n#### Location\n\nRepresents a location with IP, URL, referer, and user-agent information.\n\n```python\nfrom recompi import Location\n\nlocation = Location(ip=\"1.1.1.1\", url=\"https://www.example.com\", referer=\"REFERER_URL\", useragent=\"USERAGENT\")\n```\n\n#### Geo\n\nRepresents geographical information with country and province.\n\n```python\nfrom recompi import Geo\n\ngeo = Geo(country=\"Iran\", province=\"Tehran\")\n```\n\n### Error Handling\n\n#### RecomPIFieldTypeError\n\nRaised when an input field does not match the expected type.\n\n```python\nfrom recompi import RecomPIFieldTypeError\n\ntry:\n # Some operation that might raise an error\n pass\nexcept RecomPIFieldTypeError as e:\n print(e)\n```\n\n#### RecomPIException\n\nGeneral exception class for other RecomPI errors.\n\n```python\nfrom recompi import RecomPIException\n\ntry:\n # Some operation that might raise an error\n pass\nexcept RecomPIException as e:\n print(e)\n```\n\n## Contributing and Development\n\nWe welcome contributions to *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/python-recompi/issues) on GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python wrapper for the RecomPI API",
"version": "2.0.20",
"project_urls": {
"Bug Tracker": "https://github.com/recompi/python-recompi/issues",
"Panel": "https://panel.recompi.com",
"Source": "https://github.com/recompi/python-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": "68f81e8cbf4da2f638e7b1baf4e987baf9119204d16f13ba1fc1cae78c4e6672",
"md5": "01b0f7d5397ab737e6a0fb4494cc032f",
"sha256": "6423e292e8e419ec2f5dea3b2217d3a68f9d31483b1e8fd9dfaafe6e582b4928"
},
"downloads": -1,
"filename": "recompi-2.0.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01b0f7d5397ab737e6a0fb4494cc032f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=2.7",
"size": 9603,
"upload_time": "2024-07-09T21:39:49",
"upload_time_iso_8601": "2024-07-09T21:39:49.885000Z",
"url": "https://files.pythonhosted.org/packages/68/f8/1e8cbf4da2f638e7b1baf4e987baf9119204d16f13ba1fc1cae78c4e6672/recompi-2.0.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c37387bcaf4d8ea8bb21d5e66ffbbd85a55efa3f97161bcac5c87e584196dcf",
"md5": "6a7c59ef59beb6541dab0f746e8b0323",
"sha256": "fcd3002059df4ec5c9e4990ca39a9c62a1ec596cea8bdf2190d0c40f8b4466b9"
},
"downloads": -1,
"filename": "recompi-2.0.20.tar.gz",
"has_sig": false,
"md5_digest": "6a7c59ef59beb6541dab0f746e8b0323",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 12067,
"upload_time": "2024-07-09T21:39:52",
"upload_time_iso_8601": "2024-07-09T21:39:52.129929Z",
"url": "https://files.pythonhosted.org/packages/2c/37/387bcaf4d8ea8bb21d5e66ffbbd85a55efa3f97161bcac5c87e584196dcf/recompi-2.0.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-09 21:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "recompi",
"github_project": "python-recompi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": []
}
],
"lcname": "recompi"
}
JSON
