Merge pull request #36 from weaviate/release/v0.2.x

Author: dannyjameswilliams

.env.example

@@ -1,6 +1,10 @@
 # WCD_URL=
 # WCD_API_KEY=
 
+#WEAVIATE_IS_LOCAL
+#LOCAL_WEAVIATE_PORT
+#LOCAL_WEAVIATE_GRPC_PORT
+
 # OPENROUTER_API_KEY=
 
 # ANTHROPIC_API_KEY=

README.md

@@ -101,10 +101,11 @@ Done! You can now use the Elysia python package
 
 ### Configuring Settings
 
-To use Elysia with Weaviate, i.e. for agentic searching and retrieval, you need a Weaviate cluster api key and URL. This can be specific in the app directly, or by creating a `.env` file with
+To use Elysia with Weaviate, i.e. for agentic searching and retrieval, you need to either have a *locally running* instance of Weaviate, or access to a *Weaviate cloud cluster* via an api key and URL. This can be specific in the app directly, or by creating a `.env` file with
 ```
 WCD_URL=...
 WCD_API_KEY=...
+WEAVIATE_IS_LOCAL=... # True or False
 ```
 Elysia will automatically detect these when running locally, and this will be the default Weaviate cluster for all users logging into the Elysia app. But these can be configured on a user-by-user basis through the config.
 
@@ -181,3 +182,13 @@ There are no 'huge' new features we are planning for Elysia (for the moment). Yo
 
 </details>
 
+
+<details>
+<summary><b>Can I run Elysia completely locally? (Locally running Weaviate, local models)</b></summary>
+
+Yes!
+
+You can connect to a locally running Weaviate instance in Docker, and connect to Ollama for locally running language models.
+[See the setup page to get started.](https://weaviate.github.io/elysia/setting_up/)
+
+</details>

docs/Examples/query_weaviate.md

@@ -11,30 +11,31 @@ This example will walk through using Elysia to:
 
 Before setting up your environment and connecting to Weaviate, make sure you have the necessary API keys and access credentials for both your language models and your Weaviate instance. This will ensure a smooth setup process in the following steps.
 
-1. [You should have a Weaviate cloud cluster - see Step 1.1 in the Weaviate quickstart guide.](https://docs.weaviate.io/weaviate/quickstart#step-1-set-up-weaviate)
-2. [You need to find your REST endpoint URL and Admin API key for your cluster - see Step 1.3 in the Weaviate quickstart guide](https://docs.weaviate.io/weaviate/quickstart#13-connect-to-weaviate)
-3. You additionally need API keys for any LLMs you want to use. We recommend [OpenRouter](https://openrouter.ai/) to gain access to a range of models.
+1. You should have a Weaviate cloud cluster or locally running Weaviate instance - [see Step 1.1 in the Weaviate quickstart guide for cloud](https://docs.weaviate.io/weaviate/quickstart#step-1-set-up-weaviate) and [see here for running Weaviate locally with Docker](https://docs.weaviate.io/deploy/installation-guides/docker-installation).
+2. [You need to find your REST endpoint URL and Admin API key for your cloud cluster - see Step 1.3 in the Weaviate quickstart guide](https://docs.weaviate.io/weaviate/quickstart#13-connect-to-weaviate), or 
+3. You additionally need API keys for any LLMs you want to use. We recommend [OpenRouter](https://openrouter.ai/) to gain access to a range of models, or [Ollama](https://ollama.com/) for locally running models.
 
 ## Setting up
 
-Let's use the basic elysia `configure` to both *set up your models* and *connect to your Weaviate cluster*.
+Let's use the basic elysia `configure` to both *set up your models* and *connect to your Weaviate instance*.
 
 ```python
 from elysia import configure
 configure(
+    weaviate_is_local = False, # replace with True if locally running Weaviate
     wcd_url = "...", # replace with your Weaviate REST endpoint URL
     wcd_api_key = "..." # replace with your Weaviate cluster API key,
-    base_model = "gemini-2.0.flash-001",
-    base_provider = "gemini",
+    base_model = "gemini-2.0.flash-001", # replace with whichever model you are using
+    base_provider = "gemini", # replace with your model provider or 'ollama' for locally running ollama models
     complex_model = "gemini-2.5.flash-001",
     complex_provider = "gemini",
-    gemini_api_key = "..." # replace with your GEMINI_API_KEY from Google AI studio
+    gemini_api_key = "..." # replace with your GEMINI_API_KEY from Google AI studio, or whichever API key you need for Weaviate/your LLMs
 )
 ```
 Alternatively, you can use different models, such as `gpt-4.1-mini`, `gpt-4.1`, with `base_provider="openai"` and `complex_provider="openai"`, as well as an `openai_api_key`. Or any model/provider combination that you wish, [see the full LiteLLM docs for all API keys and models/providers](https://docs.litellm.ai/docs/providers).
 
-## Optional: Add some data to your Weaviate cluster
 
+## Optional: Add some data to your Weaviate cluster
 
 We're going to create some basic data and an example collection for this demo. This is based on [this example in the Weaviate docs](https://docs.weaviate.io/weaviate/recipes/generative_search_aws_bedrock).
 

docs/index.md

@@ -46,13 +46,13 @@ Unlike other agent-based packages, Elysia is pre-configured to run a wide range
 
 Or you could customise Elysia to your liking, create your own custom tools and add them to the Elysia decision tree.
 
-To use Elysia to search your data, you need a Weaviate cluster (or you can define your own custom tool to search another data source!).
+To use Elysia to search your data, you need to either have [a Weaviate cloud cluster or a locally running Weaviate instance](setting_up.md#weaviate-integration) (or you can define your own custom tool to search another data source!).
 
-[Sign up to Weaviate! A 14 day sandbox cluster is free.](https://weaviate.io/deployment/serverless)
+[Sign up to Weaviate Cloud! A 14 day sandbox cluster is free.](https://weaviate.io/deployment/serverless)
 
-For more information on signing up to Weaviate, [click here](https://weaviate.io/developers/wcs/platform/create-account). 
+For more information on signing up to Weaviate Cloud, [click here](https://weaviate.io/developers/wcs/platform/create-account). 
 
-From your weaviate cluster, you can upload data via a CSV on the cloud console, or [you can upload via the Weaviate APIs](https://weaviate.io/developers/academy/py/zero_to_mvp/schema_and_imports/import).
+From your Weaviate cloud cluster, you can upload data via a CSV on the cloud console, or [you can upload via the Weaviate APIs](https://weaviate.io/developers/academy/py/zero_to_mvp/schema_and_imports/import).
 
 ## About
 
@@ -64,7 +64,6 @@ Check out the Github Repositories for the backend and the frontend
 
 Elysia was developed by Edward Schmuhl (frontend) and Danny Williams (backend). Check out our socials below:
 
-
 - [Edward's Linkedin](https://www.linkedin.com/in/edwardschmuhl/)
 
 - [Danny's Linkedin](https://www.linkedin.com/in/dannyjameswilliams/)

docs/setting_up.md

@@ -66,18 +66,22 @@ configure(
 
 On the app side, this is configurable via the 'Api Base URL' parameter in the Settings. Set both of your providers to `ollama`, and your base and complex model to whatever model you are currently hosting, and this should work out-of-the-box.
 
-Warning: Elysia uses a *long context*, quite long context, due to the nature of the collection schemas, environment and more being included in every prompt. So these models will run quite slowly. However, on the backend, you can configure this to be faster by disabling connection to your Weaviate cluster, if applicable, by removing your weaviate api key and url. Also, there is an optional setting
+**Warning**: Elysia uses a *long context*, quite long context, due to the nature of the collection schemas, environment and more being included in every prompt. So these models will run quite slowly. However, on the backend, you can configure this to be faster by disabling connection to your Weaviate cluster, if applicable, by removing your weaviate api key and url. There is an optional setting
 ```python
 settings.configure(
 	base_use_reasoning=False,
 	complex_use_reasoning=False
 )
 ```
-which will remove chain of thought prompting for the base and complex model, respectively. Use this with caution though, as it will degrade accuracy significantly. Additionally, some smaller models struggle with the complex nature of multiple outputs in DSPy and Elysia, so you might encounter some errors. In testing, the `gpt-oss` models work relatively well.
+which will remove chain of thought prompting for the base and complex model, respectively. *Use this with caution though*, as it will degrade accuracy significantly. Additionally, some smaller models struggle with the complex nature of multiple outputs in DSPy and Elysia, so you might encounter some errors. In testing, the `gpt-oss` models work relatively well.
+
+*Note: Simplifying model outputs and reducing the context window size for local models is planned for a future version of Elysia. Stay tuned!*
 
 ## Weaviate Integration
 
-To use Elysia with Weaviate, you need to specify your Weaviate cluster details. These can be set via the Weaviate Cluster URL (`WCD_URL`) and the Weaviate Cluster API Key (`WCD_API_KEY`). To set these values, you can use `configure` on the settings:
+### Weaviate Cloud 
+
+To use Elysia with Weaviate cloud, you need to specify your Weaviate cluster details. These can be set via the Weaviate Cluster URL (`WCD_URL`) and the Weaviate Cluster API Key (`WCD_API_KEY`). To set these values, you can use `configure` on the settings:
 ```python
 from elysia import configure
 configure(
@@ -91,9 +95,46 @@ WCD_URL=... # replace with your WCD_URL
 WCD_API_KEY=... # replace with your WCD_API_KEY
 ```
 
+[You can sign up for a 14-day sandbox to Weaviate cloud for free.](https://weaviate.io/deployment/serverless)
+
+### Local Weaviate
+
+You can run Elysia with a locally running Weaviate (e.g. Docker), making Elysia able to be run with *completely open source* software. To do so, you only need to set your local Weaviate instance variables. Configure Elysia to use the local instance by setting in the `.env` file:
+
+```
+WEAVIATE_IS_LOCAL=True
+
+# URL can be just a host or full URL; defaults shown below
+WCD_URL=localhost            # or http://localhost:8080
+LOCAL_WEAVIATE_PORT=8080     # optional override
+LOCAL_WEAVIATE_GRPC_PORT=50051  # optional override
+
+# No API key required for local unless you enabled local auth
+WCD_API_KEY=
+```
+
+Or within Python via:
+
+```python
+from elysia import configure
+configure(
+    weaviate_is_local=True,
+    wcd_url="http://localhost:8080",  # or "localhost"
+    local_weaviate_port=8080,
+    local_weaviate_grpc_port=50051,
+)
+```
+
+Notes:
+- If `WEAVIATE_IS_LOCAL=True` and no URL is provided, Elysia defaults to `localhost` with ports shown above.
+- Local mode can work without an API key; if you enable auth locally, set `WCD_API_KEY` accordingly.
+
+The easiest way to set up a local Weaviate instance is via Docker, [see here for detailed instructions.](https://docs.weaviate.io/deploy/installation-guides/docker-installation)
+
 Additionally, you need to _preprocess_ your collections for Elysia to use the built in Weaviate-based tools, see below for details.
 
-*Note: using a local Weaviate instance is currently not supported. This is coming soon! [You can sign up for a 14-day sandbox for free.](https://weaviate.io/deployment/serverless)
+*Note: Using a local Weaviate instance is experimental. If you run into any issues, please open a [Github Issue](https://github.com/weaviate/elysia/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen)!*
+
 
 ## Preprocessing Collections
 

elysia/api/routes/user_config.py

@@ -145,16 +145,16 @@ async def load_a_config(
         user = await user_manager.get_user_local(user_id)
         frontend_config = user["frontend_config"]
 
-        # check if the user has a valid save location
-        if (
-            frontend_config.save_location_wcd_url == ""
-            or frontend_config.save_location_wcd_api_key == ""
+        # check if the user has a valid save location (allow local without API key)
+        if frontend_config.save_location_wcd_url == "" or (
+            frontend_config.save_location_wcd_api_key == ""
+            and not frontend_config.save_location_weaviate_is_local
         ):
             raise Exception("WCD URL or API key not found.")
 
-        if (
-            frontend_config.save_location_wcd_url == ""
-            or frontend_config.save_location_wcd_api_key == ""
+        if frontend_config.save_location_wcd_url == "" or (
+            frontend_config.save_location_wcd_api_key == ""
+            and not frontend_config.save_location_weaviate_is_local
         ):
             raise Exception(
                 "No valid destination for config load location found. "
@@ -257,10 +257,6 @@ async def new_user_config(
             branch_initialisation="one_branch",
         )
 
-        frontend_config.save_location_wcd_url = frontend_config.save_location_wcd_url
-        frontend_config.save_location_wcd_api_key = (
-            frontend_config.save_location_wcd_api_key
-        )
         frontend_config.config = {
             "save_trees_to_weaviate": True,
             "save_configs_to_weaviate": True,
@@ -445,10 +441,13 @@ async def save_config_user(
         end_goal = user["tree_manager"].config.end_goal
         branch_initialisation = user["tree_manager"].config.branch_initialisation
 
-        # Check if the user has a valid save location
-        if (
-            user["frontend_config"].save_location_wcd_url == ""
-            or user["frontend_config"].save_location_wcd_api_key == ""
+        # Do not override frontend storage settings with backend settings here;
+        # storage cluster for configs/conversations is controlled via frontend payload
+
+        # Check if the user has a valid save location (allow local without API key)
+        if user["frontend_config"].save_location_wcd_url == "" or (
+            user["frontend_config"].save_location_wcd_api_key == ""
+            and not user["frontend_config"].save_location_weaviate_is_local
         ):
             warnings.append(
                 "No valid destination for config save location found. "
@@ -776,9 +775,11 @@ async def list_configs(
             or "save_location_wcd_url" not in user["frontend_config"].__dict__
             or "save_location_wcd_api_key" not in user["frontend_config"].__dict__
             or user["frontend_config"].save_location_wcd_url is None
-            or user["frontend_config"].save_location_wcd_api_key is None
             or user["frontend_config"].save_location_wcd_url == ""
-            or user["frontend_config"].save_location_wcd_api_key == ""
+            or (
+                user["frontend_config"].save_location_wcd_api_key in [None, ""]
+                and not user["frontend_config"].save_location_weaviate_is_local
+            )
         ):
             logger.warning(
                 "In /list_configs API, "

elysia/api/services/user.py

@@ -129,6 +129,9 @@ async def update_config(
             wcd_url=local_user["tree_manager"].settings.WCD_URL,
             wcd_api_key=local_user["tree_manager"].settings.WCD_API_KEY,
             api_keys=local_user["tree_manager"].settings.API_KEYS,
+            weaviate_is_local=local_user["tree_manager"].settings.WEAVIATE_IS_LOCAL,
+            local_weaviate_port=local_user["tree_manager"].settings.LOCAL_WEAVIATE_PORT,
+            local_weaviate_grpc_port=local_user["tree_manager"].settings.LOCAL_WEAVIATE_GRPC_PORT,
         )
 
     async def update_frontend_config(