# Recomenda
**Recomenda** is **the most simple-to-use Recommender System** designed to seamlessly integrate with your projects. Powered by **OpenAI Embeddings**, Recomenda delivers accurate and efficient recommendations with minimal setup.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Synchronous Recommender](#synchronous-recommender)
- [Asynchronous Recommender](#asynchronous-recommender)
- [Configuration](#configuration)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
---
## Features
- **Simplicity:** Easy-to-use API with minimal configuration.
- **Powered by OpenAI:** Utilizes OpenAI Embeddings for high-quality recommendations.
- **Synchronous & Asynchronous:** Choose between synchronous and asynchronous operations based on your project needs.
- **Extensible:** Easily extend and customize the recommender to fit your specific requirements.
- **Robust Logging:** Comprehensive logging for debugging and monitoring.
- **Configuration Management:** Flexible configuration through environment variables.
---
## Installation
Ensure you have Python 3.8 or higher installed. You can install Recomenda via `pip`:
```bash
pip install recomenda
```
Alternatively, clone the repository and install manually:
```bash
git clone https://github.com/yourusername/recomenda.git
cd recomenda
pip install -r requirements.txt
```
---
## Quick Start
Here's a quick example to get you started with Recomenda.
### 1. Set Up Environment Variables
Ensure you have the `OPENAI_API_KEY` set in your environment. You can create a `.env` file or set it directly in your shell.
```bash
export OPENAI_API_KEY='your-openai-api-key'
```
### 2. Initialize the Recommender
```python
from recomenda import Recommender
# Define your options
options = [
{"id": 1, "name": "Option A"},
{"id": 2, "name": "Option B"},
{"id": 3, "name": "Option C"},
{"id": 4, "name": "Option D"},
{"id": 5, "name": "Option E"},
]
# Initialize the Recommender
recommender = Recommender(options=options)
# Generate recommendations based on a target
target = "Your target input here"
recommendations = recommender.generate_recommendations(to=target, how_many=3)
print("Top Recommendations:")
for rec in recommendations:
print(rec)
```
---
## Usage
Recomenda offers both synchronous and asynchronous Recommender interfaces to cater to different application needs.
### Synchronous Recommender
Ideal for applications where blocking operations are acceptable.
```python
from recomenda import Recommender
options = [
{"id": 1, "name": "Option A"},
{"id": 2, "name": "Option B"},
# Add more options
]
recommender = Recommender(options=options)
target = "Sample input for recommendation"
recommendations = recommender.generate_recommendations(to=target, how_many=5)
for rec in recommendations:
print(rec)
```
### Asynchronous Recommender
Perfect for high-performance applications requiring non-blocking operations.
```python
import asyncio
from recomenda import AsyncRecommender
async def main():
options = [
{"id": 1, "name": "Option A"},
{"id": 2, "name": "Option B"},
# Add more options
]
recommender = AsyncRecommender(options=options)
target = "Sample input for recommendation"
recommendations = await recommender.generate_recommendations(to=target, how_many=5)
for rec in recommendations:
print(rec)
asyncio.run(main())
```
---
## Configuration
Recommender is highly configurable through environment variables. Below are the primary configurations:
### Embedder Configuration
- `OPENAI_API_KEY`: **(Required)** Your OpenAI API key.
- `OPENAI_EMBEDDING_MODEL`: **(Optional)** The OpenAI embedding model to use. Defaults to `text-embedding-3-small`.
### Database Configuration
- `DATABASE_URL`: **(Optional)** The database URL for storing embeddings. Defaults to `sqlite:///./recomenda.db`.
Ensure these variables are set in your environment or defined in a `.env` file.
---
## API Reference
### `Recommender`
The synchronous recommender class.
**Initialization:**
```python
Recommender(
embedder: Optional[Embedder] = None,
how: str = "default",
how_many: int = 5,
options: Optional[List[Dict[str, Any]]] = None,
to: Optional[str] = None,
api_key: str = config.EMBEDDER.OPENAI_API_KEY,
model: str = config.EMBEDDER.OPENAI_EMBEDDING_MODEL
)
```
**Methods:**
- `generate_recommendations(to: Optional[str], how_many: Optional[int], force: bool = False) -> List[Dict[str, Any]]`
- `generate_recommendation() -> Optional[Dict[str, Any]]`
- `show_recommendations() -> None`
- `show_recommendation() -> None`
### `AsyncRecommender`
The asynchronous recommender class.
**Initialization:**
```python
AsyncRecommender(
embedder: Optional[Embedder] = None,
how: str = "default",
how_many: int = 5,
options: Optional[List[Dict[str, Any]]] = None,
to: Optional[str] = None,
api_key: str = config.EMBEDDER.OPENAI_API_KEY,
model: str = config.EMBEDDER.OPENAI_EMBEDDING_MODEL
)
```
**Methods:**
- `await generate_recommendations(to: Optional[str], how_many: Optional[int]) -> List[Dict[str, Any]]`
- `await generate_recommendation() -> Optional[Dict[str, Any]]`
- `await show_recommendations() -> None`
- `await show_recommendation() -> None`
- `await get_recommendations_str() -> str`
For detailed documentation, refer to the [docs](https://github.com/yourusername/recomenda/docs).
---
## Contributing
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. **Fork the Project**
2. **Create your Feature Branch**
```bash
git checkout -b feature/YourFeature
```
3. **Commit your Changes**
```bash
git commit -m "Add YourFeature"
```
4. **Push to the Branch**
```bash
git push origin feature/YourFeature
```
5. **Open a Pull Request**
Please ensure your contributions adhere to the project's code of conduct and guidelines.
---
## License
Distributed under the [MIT License](LICENSE). See `LICENSE` for more information.
---
## Support
If you encounter any issues or have questions, feel free to [open an issue](https://github.com/yourusername/recomenda/issues) or reach out via [email](mailto:support@yourdomain.com).
---
## Acknowledgements
- [OpenAI](https://openai.com/) for providing powerful embedding models.
- [Scipy](https://www.scipy.org/) for the cosine similarity implementation.
- [Python Logging](https://docs.python.org/3/library/logging.html) for robust logging capabilities.
---
*Happy Recommending! 🚀*
Raw data
{
"_id": null,
"home_page": "https://github.com/kevinqz/recomenda",
"name": "recomenda",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10.0",
"maintainer_email": null,
"keywords": "recommendation, openai, embeddings",
"author": "Kevin Saltarelli",
"author_email": "kevinqz@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/71/5aec302236d1f95c286edfb0b77dfee7e9ef7b28ec275d63bc8bff98699f/recomenda-0.1.5.tar.gz",
"platform": null,
"description": "# Recomenda\n\n\n\n\n\n**Recomenda** is **the most simple-to-use Recommender System** designed to seamlessly integrate with your projects. Powered by **OpenAI Embeddings**, Recomenda delivers accurate and efficient recommendations with minimal setup.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n - [Synchronous Recommender](#synchronous-recommender)\n - [Asynchronous Recommender](#asynchronous-recommender)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n---\n\n## Features\n\n- **Simplicity:** Easy-to-use API with minimal configuration.\n- **Powered by OpenAI:** Utilizes OpenAI Embeddings for high-quality recommendations.\n- **Synchronous & Asynchronous:** Choose between synchronous and asynchronous operations based on your project needs.\n- **Extensible:** Easily extend and customize the recommender to fit your specific requirements.\n- **Robust Logging:** Comprehensive logging for debugging and monitoring.\n- **Configuration Management:** Flexible configuration through environment variables.\n\n---\n\n## Installation\n\nEnsure you have Python 3.8 or higher installed. You can install Recomenda via `pip`:\n\n```bash\npip install recomenda\n```\n\nAlternatively, clone the repository and install manually:\n\n```bash\ngit clone https://github.com/yourusername/recomenda.git\ncd recomenda\npip install -r requirements.txt\n```\n\n---\n\n## Quick Start\n\nHere's a quick example to get you started with Recomenda.\n\n### 1. Set Up Environment Variables\n\nEnsure you have the `OPENAI_API_KEY` set in your environment. You can create a `.env` file or set it directly in your shell.\n\n```bash\nexport OPENAI_API_KEY='your-openai-api-key'\n```\n\n### 2. Initialize the Recommender\n\n```python\nfrom recomenda import Recommender\n\n# Define your options\noptions = [\n {\"id\": 1, \"name\": \"Option A\"},\n {\"id\": 2, \"name\": \"Option B\"},\n {\"id\": 3, \"name\": \"Option C\"},\n {\"id\": 4, \"name\": \"Option D\"},\n {\"id\": 5, \"name\": \"Option E\"},\n]\n\n# Initialize the Recommender\nrecommender = Recommender(options=options)\n\n# Generate recommendations based on a target\ntarget = \"Your target input here\"\nrecommendations = recommender.generate_recommendations(to=target, how_many=3)\n\nprint(\"Top Recommendations:\")\nfor rec in recommendations:\n print(rec)\n```\n\n---\n\n## Usage\n\nRecomenda offers both synchronous and asynchronous Recommender interfaces to cater to different application needs.\n\n### Synchronous Recommender\n\nIdeal for applications where blocking operations are acceptable.\n\n```python\nfrom recomenda import Recommender\n\noptions = [\n {\"id\": 1, \"name\": \"Option A\"},\n {\"id\": 2, \"name\": \"Option B\"},\n # Add more options\n]\n\nrecommender = Recommender(options=options)\ntarget = \"Sample input for recommendation\"\nrecommendations = recommender.generate_recommendations(to=target, how_many=5)\n\nfor rec in recommendations:\n print(rec)\n```\n\n### Asynchronous Recommender\n\nPerfect for high-performance applications requiring non-blocking operations.\n\n```python\nimport asyncio\nfrom recomenda import AsyncRecommender\n\nasync def main():\n options = [\n {\"id\": 1, \"name\": \"Option A\"},\n {\"id\": 2, \"name\": \"Option B\"},\n # Add more options\n ]\n\n recommender = AsyncRecommender(options=options)\n target = \"Sample input for recommendation\"\n recommendations = await recommender.generate_recommendations(to=target, how_many=5)\n\n for rec in recommendations:\n print(rec)\n\nasyncio.run(main())\n```\n\n---\n\n## Configuration\n\nRecommender is highly configurable through environment variables. Below are the primary configurations:\n\n### Embedder Configuration\n\n- `OPENAI_API_KEY`: **(Required)** Your OpenAI API key.\n- `OPENAI_EMBEDDING_MODEL`: **(Optional)** The OpenAI embedding model to use. Defaults to `text-embedding-3-small`.\n\n### Database Configuration\n\n- `DATABASE_URL`: **(Optional)** The database URL for storing embeddings. Defaults to `sqlite:///./recomenda.db`.\n\nEnsure these variables are set in your environment or defined in a `.env` file.\n\n---\n\n## API Reference\n\n### `Recommender`\n\nThe synchronous recommender class.\n\n**Initialization:**\n\n```python\nRecommender(\n embedder: Optional[Embedder] = None,\n how: str = \"default\",\n how_many: int = 5,\n options: Optional[List[Dict[str, Any]]] = None,\n to: Optional[str] = None,\n api_key: str = config.EMBEDDER.OPENAI_API_KEY,\n model: str = config.EMBEDDER.OPENAI_EMBEDDING_MODEL\n)\n```\n\n**Methods:**\n\n- `generate_recommendations(to: Optional[str], how_many: Optional[int], force: bool = False) -> List[Dict[str, Any]]`\n- `generate_recommendation() -> Optional[Dict[str, Any]]`\n- `show_recommendations() -> None`\n- `show_recommendation() -> None`\n\n### `AsyncRecommender`\n\nThe asynchronous recommender class.\n\n**Initialization:**\n\n```python\nAsyncRecommender(\n embedder: Optional[Embedder] = None,\n how: str = \"default\",\n how_many: int = 5,\n options: Optional[List[Dict[str, Any]]] = None,\n to: Optional[str] = None,\n api_key: str = config.EMBEDDER.OPENAI_API_KEY,\n model: str = config.EMBEDDER.OPENAI_EMBEDDING_MODEL\n)\n```\n\n**Methods:**\n\n- `await generate_recommendations(to: Optional[str], how_many: Optional[int]) -> List[Dict[str, Any]]`\n- `await generate_recommendation() -> Optional[Dict[str, Any]]`\n- `await show_recommendations() -> None`\n- `await show_recommendation() -> None`\n- `await get_recommendations_str() -> str`\n\nFor detailed documentation, refer to the [docs](https://github.com/yourusername/recomenda/docs).\n\n---\n\n## Contributing\n\nContributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. **Fork the Project**\n2. **Create your Feature Branch**\n ```bash\n git checkout -b feature/YourFeature\n ```\n3. **Commit your Changes**\n ```bash\n git commit -m \"Add YourFeature\"\n ```\n4. **Push to the Branch**\n ```bash\n git push origin feature/YourFeature\n ```\n5. **Open a Pull Request**\n\nPlease ensure your contributions adhere to the project's code of conduct and guidelines.\n\n---\n\n## License\n\nDistributed under the [MIT License](LICENSE). See `LICENSE` for more information.\n\n---\n\n## Support\n\nIf you encounter any issues or have questions, feel free to [open an issue](https://github.com/yourusername/recomenda/issues) or reach out via [email](mailto:support@yourdomain.com).\n\n---\n\n## Acknowledgements\n\n- [OpenAI](https://openai.com/) for providing powerful embedding models.\n- [Scipy](https://www.scipy.org/) for the cosine similarity implementation.\n- [Python Logging](https://docs.python.org/3/library/logging.html) for robust logging capabilities.\n\n---\n\n*Happy Recommending! \ud83d\ude80*",
"bugtrack_url": null,
"license": "MIT",
"summary": "A recommendation system package using OpenAI embeddings",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/kevinqz/recomenda",
"Repository": "https://github.com/kevinqz/recomenda"
},
"split_keywords": [
"recommendation",
" openai",
" embeddings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a5d3b0a9cd6be978f24e30964e2c7da3a0d1fed4333ce8d77e74767bfdef633",
"md5": "953683c0b9fa3a7435ea740ff2a71ee9",
"sha256": "9404cdd286cf869f5151b4961add77a5260049d580c891c232bc9950cc6e0b19"
},
"downloads": -1,
"filename": "recomenda-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "953683c0b9fa3a7435ea740ff2a71ee9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10.0",
"size": 16080,
"upload_time": "2024-09-24T11:40:50",
"upload_time_iso_8601": "2024-09-24T11:40:50.527547Z",
"url": "https://files.pythonhosted.org/packages/1a/5d/3b0a9cd6be978f24e30964e2c7da3a0d1fed4333ce8d77e74767bfdef633/recomenda-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "40715aec302236d1f95c286edfb0b77dfee7e9ef7b28ec275d63bc8bff98699f",
"md5": "170b616473331a02fcb9065da5ead495",
"sha256": "59b0c68d0b06d3f430b1a441f5cca8b1e14f14f4840e41411d6217a8c7be6aab"
},
"downloads": -1,
"filename": "recomenda-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "170b616473331a02fcb9065da5ead495",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10.0",
"size": 14105,
"upload_time": "2024-09-24T11:40:51",
"upload_time_iso_8601": "2024-09-24T11:40:51.964161Z",
"url": "https://files.pythonhosted.org/packages/40/71/5aec302236d1f95c286edfb0b77dfee7e9ef7b28ec275d63bc8bff98699f/recomenda-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-24 11:40:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kevinqz",
"github_project": "recomenda",
"github_not_found": true,
"lcname": "recomenda"
}
JSON
