OwnAssistant

OwnAssistant

A customizable AI Home Assistant that integrates ollama with multiple functionalities using MCP.

[!NOTE] Currently it is advised to only prompt for one tool call. Multiple tool calls can lead to hallucination. This will be improved in the future

Functionalities and Tools

• Get the Current Datetime:
  • get_current_datetime
• Work with Google Calendar - Setup
  • create_event
  • get_events
• Get Weather
  • get_weather_forecast
  • get_weather_current
• Shopping List
  • create_shoppinglist_entry
  • get_shoppinglist_entries
  • set_shoppinglist_done_status
  • clear_done_shoppinglist
• ToDo List
  • create_todolist_entry
  • get_todolist_entries
  • set_todolist_done_status
  • clear_done_todolist
• Web Search - Setup
  • web_search_overview
  • web_page_content

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

What things you need to install the software and how to install them

• node.js
• Docker (To install and run ollama)

Installing

Installing Dependencies

In the root directory run the command

npm install

Setting Environment Variables

In the root directory copy .env.example to .env and change the values. Find a list of all Environment Variables here.

It is important to decide on a LLM you want to use. You can see a list of recommended models here. It is strongly advised to choose at least a model from the "Medium" Category.

Setting up Ollama

To initially create an Ollama Docker container run the following command

npm run ollama-init

To start or stop Ollama run the corresponding of the following commands:

npm run ollama-start # Start Ollama
npm run ollama-stop  # Stop Ollama 

Start the Application

To start the application run the following commands

npm run build
npm run start

[!NOTE] When starting the application for the first time and when you change the used model, the startup can take several minutes, since the model has to be downloaded.

Running the tests

End to End Tests

[!NOTE] To be done

Integration Tests

[!NOTE] To be done

Unit Tests

[!NOTE] To be done

Static Code Checks

[!NOTE] To be done

Deployment

[!NOTE] To be done

Functionality Setup

Google Calendar

To connect Google Calendar, the Google Cloud is used. For this you need a Google Account with Google Calendar enabled. To get started, create a Google Cloud Project. Follow this guide. Setting up billing is not necessary.

In the hamburger menu on the left side of the screen select "APIs and services".

Now select "Enable APIs and services" and search for "google calendar api". Click on the corresponding entry and enable the API for Google Calendar.

Now visit https://console.cloud.google.com/apis/credentials. Click on "Create credentials" and select "Service account".

Fill the input fields and keep the created email address in mind for later.

In step 2 choose "Editor" as the assigned role for this account. Back on the overview page https://console.cloud.google.com/apis/credentials click on your newly created service account. Navigate to the "Keys" section and select "Add key" and "Create new key". In the popup menu select JSON as the file type and download the key file.

Move the json file to the root directory of this repo and rename it to google_auth.json. You can also copy google_auth_example.json and rename it to google_auth.json. Make sure not to add this file to version control as it contains your credentials. Keep it safe!

This whole process created a service Google account. It can be treated as any other Google account for this use case. You can now choose to either

• share your personal Google calendar with the email address of this service account. This allows OwnAssistant to create and read events from this calendar.
• create a new, separate Google calendar and share it with the email address of this service account. This allows OwnAssistant to only create and read events from this specific calendar and not your main calendar. All events you create in this calendar can be accessed. Follow this guide if you need help.

On this settings page scroll down to "Integrate calendar" and copy the calendar-id. This is used to identify the specific calendar you want to access in this application. Copy this value to the environment variable GOOGLE_SHARED_CALENDAR_ID in .env.

The setup is now complete. You can now start to use the google calendar functionalities.

Serper

To use the web search functionality, a Search Engine API is used. Currently only Serper is supported, since it offers a free tier and offers sufficient functionalities.

To acquire an API Key visit https://serper.dev/ and create an account. After signing in copy the API Key from the dashboard to the .env file.

Technical Details

Built With

• Model Context Protocol (MCP) - The connection layer between LLM and functionalities in backend
• Ollama JS - The local LLM platform used

Environment Variables

Variable	Description	Default
SERPER_SEARCH_API_KEY	SERPER API KEY for Web Searches	none
GOOGLE_SHARED_CALENDAR_ID	Google Calendar ID to identify the google calendar used with this application	none
LATITUDE	Your local latitude rounded to two decimals	none
LONGITUDE	Your local longitude rounded to two decimals	none
MAX_CHAT_ITERATIONS	Maximum Number of Iterations and Tool Calls the LLM is allowed to take	6
MODEL	Model used to orchestrate tools. See List of Recommended Models	llama3.1:8b-instruct-q4_0
NUM_GPU	The number of layers of the model will be executed on the GPU	15
TIMEZONE	Your local timezone of this list	Europe/Berlin

Recommended Models

Small

• qwen2.5:3b-instruct-q4_K_M
• llama3.2:3b-instruct-q4_K_M

Medium

• llama3.1:8b-instruct-q4_0

Planned Architecture

DB Schema

[!NOTE] To be done

Contributing

Since the project is its very early stages, I am not open to contributions at the moment. But thank you none the less for your interest :)

Versioning

[!NOTE] To be done

Authors

• EinfachNiklas - Initial work

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 only, as published by the Free Software Foundation. See the LICENSE file for details

Acknowledgments

• Thanks to PurpleBooth for the README.md template