Docs (#12)

* Create readme.md

* Create 1_connection.md

* Create 2_add_items.md

* Create 3_train.md

* Create 4_recommend.md

* Create 5_search.md

* Create 6_research.md

* Rename 6_research.md to roadmap.md

* Create 1+_create_schema.md

* Rename 1+_create_schema.md to 2+_CRUD.md

* Update 2+_CRUD.md

* Rename 2+_CRUD.md to 2+_create_schema.md

* Rename 2+_create_schema.md to 2_create_schema.md

* Update and rename 2_add_items.md to 3_add_items.md

* Update and rename 3_train.md to 4_train.md

* Update and rename 4_recommend.md to 5_recommend.md

* Rename 5_search.md to 6_personalized_search.md

* Update 3_add_items.md

* Update readme.md

* Update readme.md

* Update readme.md

* Create 7_configured_endpoints.md

* Update readme.md

* Update readme.md

* Rename 3_add_items.md to 3_add_items_and_interactions.md

* Update 1_connection.md

* Update 2_create_schema.md

* Update 3_add_items_and_interactions.md

* Update 4_train.md

* Update 4_train.md

* Update 5_recommend.md

* Update 6_personalized_search.md

* Update 7_configured_endpoints.md

* Update 6_personalized_search.md

* Update 3_add_items_and_interactions.md

@cdpierse What do you think of this description? What would be a better way to phrase this?

* Update 1_connection.md

* Update 1_connection.md

* Update 2_create_schema.md

* Update 2_create_schema.md

* Update 3_add_items_and_interactions.md

* Update 4_train.md

* Update 5_recommend.md

* Update 6_personalized_search.md

* Update 7_configured_endpoints.md

docs/1_connection.md

@@ -0,0 +1,46 @@
+# Connect to Weaviate Recommender
+
+This guide explains how to establish a connection to the Weaviate Recommender Service using the `WeaviateRecommendClient`.
+
+## Prerequisites
+- Python 3.7 or higher
+- `weaviate-recommend` package installed
+
+## Connecting to the Service
+
+To connect to the Recommender Service, use the `WeaviateRecommendClient` class:
+
+```python
+from weaviate_recommend import WeaviateRecommendClient
+
+# Replace with your service URL
+service_url = "YOUR_SERVICE_URL"
+
+# Create a client instance
+client = WeaviateRecommendClient(service_url)
+```
+
+To get an API key for the Weaviate Recommender service, please sign up for our [Beta testing program here](https://weaviate.io/workbench/recommender)!
+
+## Verifying the Connection
+
+After creating the client instance, you can verify the connection by checking the service details:
+
+```python
+details = client.details()
+print(details)
+```
+
+This will return information about the current state of the recommender, including the collection names, interaction properties, and training state.
+
+## Next Steps
+
+Once connected, you can proceed to create your recommender schema, add items, and start generating recommendations.
+
+## Troubleshooting
+
+If you encounter connection issues:
+1. Verify that the service URL is correct.
+2. Ensure that the service is running and accessible from your network.
+
+For persistent issues, please open an issue on the `weaviate-recommend-python-client` repository!

docs/2_create_schema.md

@@ -0,0 +1,76 @@
+# Creating the Recommender Schema
+
+## Overview
+This guide explains how to create and configure the schema for your recommender system using the `WeaviateRecommendClient`.
+
+## Prerequisites
+- Established connection to the Recommender Service (see `1_connection.md`)
+- Understanding of your data model and recommendation requirements
+
+## Creating the Schema
+
+To create the recommender schema, use the `create` method of your `WeaviateRecommendClient` instance:
+
+```python
+import weaviate.classes.config as wvcc
+
+client.create(
+    collection_name="MyCollection",
+    properties={
+        "property1": wvcc.DataType.TEXT,
+        "property2": wvcc.DataType.NUMBER,
+        "property3": wvcc.DataType.TEXT_ARRAY,
+        # Add more properties as needed
+    },
+    trainable_properties=[
+        "property1",
+        "property2"
+    ]
+    user_properties={
+        "user_property1": wvcc.DataType.NUMBER,
+        # Add more user properties as needed
+    },
+    user_interaction_property_names=["purchase", "like", "view"],
+    text_search_property_name="property1"
+)
+```
+
+### Parameters:
+
+- `collection_name`: Name of your item collection.
+- `properties`: Dictionary of item properties and their data types.
+- `trainable_properties`: Properties used to compute the item vector representation.
+- `user_properties`: Dictionary of user properties and their data types.
+- `user_interaction_property_names`: List of interaction types you want to track.
+- `text_search_property_name`: Property to be used for text-based searches.
+
+## Verifying the Schema
+
+After creating the schema, you can verify it using the `details` method:
+
+```python
+details = client.details()
+print(details)
+```
+
+This will show you the current configuration of your recommender.
+
+## Modifying the Schema
+
+To modify an existing schema, you need to delete the current recommender and create a new one:
+
+```python
+client.delete()
+# Then create a new schema as shown above
+```
+
+## Best Practices
+
+1. Plan your schema carefully before creation, as changing it requires recreating the recommender.
+2. Include all relevant properties that might influence recommendations.
+3. Choose appropriate data types for each property to ensure efficient processing.
+4. Consider future needs when defining user interaction types.
+
+## Next Steps
+
+Once your schema is set up, you can proceed to add items and user interactions to your recommender system. See `3_add_items_and_interactions.md` for more information.

docs/3_add_items_and_interactions.md

@@ -0,0 +1,92 @@
+# Adding Items and User Interactions
+
+## Overview
+This guide explains how to add items to your recommender system and record user interactions using the `WeaviateRecommendClient`.
+
+## Prerequisites
+- Established connection to the Recommender Service (see `1_connection.md`)
+- Created recommender schema (see `2_create_schema.md`)
+
+## Adding Items
+
+This ensures items stored in Weaviate are represented with the vector from the Recommender model.
+
+### Adding a Single Item
+
+To add a single item:
+
+```python
+item_id = "unique_item_id"
+item_properties = {
+    "property1": "value1",
+    "property2": 42,
+    "property3": ["array", "value"],
+    # Include all properties defined in your schema
+}
+
+response = client.item.add(item_id, item_properties)
+print(response)
+```
+
+### Adding Multiple Items
+
+To add multiple items efficiently:
+
+```python
+from weaviate_recommend.models.data import RecommenderItem
+
+items = [
+    RecommenderItem(uuid="id1", properties={"property1": "value1", ...}),
+    RecommenderItem(uuid="id2", properties={"property1": "value2", ...}),
+    # Add more items as needed
+]
+
+response = client.item.add_batch(items)
+print(response)
+```
+
+## Recording User Interactions
+
+To record a single user interactions with an item:
+
+```python
+from weaviate_recommend.models.data import UserInteraction
+
+user_id = "user123"
+item_id = "item456"
+interaction_type = "purchase"  # Or "like", "view", etc. as defined in your schema
+weight = 1.0  # Interaction strength, typically between -1 and 1
+
+response = client.user.add_interaction(
+    user_id=user_id,
+    item_id=item_id,
+    interaction_property_name=interaction_type,
+    weight=weight
+)
+print(response)
+```
+
+### Adding Multiple Interactions
+
+For bulk addition of user interactions:
+
+```python
+interactions = [
+    UserInteraction(user_id="user1", "item_id": "1", "interaction_property_name": "purchase", "weight": 1.0},
+    UserInteraction(user_id="user1", "item_id": "4", "interaction_property_name": "purchase", "weight": 0.5},
+    # add more items as needed
+]
+
+client.user.add_interactions(interactions)
+```
+
+## Best Practices
+
+1. Ensure all required properties are included when adding items.
+2. Use batch operations for adding multiple items or user interactions efficiently.
+3. Choose appropriate weights for user interactions to reflect their importance.
+4. Regularly add user interactions to keep the recommender system up-to-date.
+
+## Next Steps
+
+After adding items and user interactions, you can train your recommender system to generate personalized recommendations. See `4_train.md` for information on training the system.

docs/4_train.md

@@ -0,0 +1,71 @@
+# Training the Recommender System
+
+## Overview
+This guide explains how to train your recommender system using the `WeaviateRecommendClient`.
+
+## Prerequisites
+- Established connection to the Recommender Service (see `1_connection.md`)
+- Created recommender schema (see `2_create_schema.md`)
+- Added items and user interactions (see `3_add_items_and_interactions.md`)
+
+## Training Process
+
+Training the recommender system is an asynchronous process. Here's how to initiate and monitor the training:
+
+### Initiating Training
+
+To start the training process:
+
+```python
+response = client.train()
+print(response)
+```
+
+This will return a message indicating that training has started.
+
+### Overwrite Trained Model
+
+Pass in an extra `overwrite=True` flag to overwrite the currently trained model and create a new one.
+
+```python
+response = client.train(overwrite=True)
+print(response)
+```
+
+### Checking Training Status
+
+To check if the training is complete:
+
+```python
+is_trained = client.is_trained()
+print(is_trained)  # Returns True if trained, False otherwise
+```
+
+If there is an error, it can be seen with:
+
+```python
+status = client.train_status()
+print(status)
+```
+
+You can use this in a loop to wait for training completion:
+
+```python
+import time
+
+while not client.is_trained():
+    print("Training in progress...")
+    time.sleep(10)  # Wait for 10 seconds before checking again
+
+print("Training completed!")
+```
+
+## When to Train
+
+- After initial setup and adding a substantial number of items
+- Periodically to incorporate new items and user interactions
+- After significant changes in your data or user behavior patterns
+
+## Next Steps
+
+Once your recommender system is trained, you can start generating recommendations. See `recommend.md` for information on how to request and use recommendations.

docs/5_recommend.md

@@ -0,0 +1,61 @@
+# Generating Recommendations
+
+## Overview
+This guide explains how to generate recommendations using the trained recommender system via the `WeaviateRecommendClient`.
+
+## Prerequisites
+- Established connection to the Recommender Service (see `1_connection.md`)
+- Trained recommender system (see `4_train.md`)
+
+## Types of Recommendations
+
+### Item-to-Item Recommendations
+
+To get recommendations based on a single item:
+
+```python
+recommendations = client.recommendation.item.from_item(item_id="1", limit=10, remove_reference=True)
+print(recommendations)
+```
+
+### Multi-Item Recommendations
+
+To get recommendations based on multiple items:
+
+```python
+recommendations = clielnt.recommendation.item.from_items(item_ids["1", "2", "3"], limit=10, remove_references=True)
+print(recommendations)
+```
+
+### User-Based Recommendations
+
+To get recommendations for a specific user:
+
+```python
+recommendations = client.recommendations.item.from_user(user_id="user1", limit=10,
+                                                        remove_reference=True, top_n_interactions=100)
+print(recommendations)
+```
+
+### Multi-User Recommendations
+
+To get recommendations based on multiple users' preferences:
+
+```python
+recommendations = client.recommendations.item.from_user(user_id=["user1","user2","user3"], limit=10,
+                                                        remove_reference=True, top_n_interactions=100)
+print(recommendations)
+```
+
+## Interpreting Results
+
+Recommendation results include:
+- Item UUID
+- Relevance score or distance
+- Item properties
+
+You can process these results to display or use in your application as needed.
+
+## Next Steps
+
+Explore more advanced features like personalized search (`personalized_search.md`) and configured endpoints (`configured_endpoints.md`) to further enhance your recommendation system.