From cb85d9f13631b03e54a542b0be74f5761aca4374 Mon Sep 17 00:00:00 2001 From: Andrej Schwanke Date: Wed, 11 Sep 2024 17:38:43 +0200 Subject: [PATCH] Add: More detailed README.md --- README.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 173 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index add803e..dab592d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,180 @@ # PyAssist -PyAssist is a virtual assistant similar to Alexa or Siri. +PyAssist is a open-source virtual voice assistant built using Python. It uses the OpenAI's ChatGPT API to handle natural language requests in german. +## Table of Contents -## What you need +- [Capabilities](#capabilities) +- [Installation and Setting Up](#installation-and-setting-up) +- [Writing Your Own Assistant](#writing-your-own-assistant) +- [Configuration Options](#configuration-options) + + +## Capabilities + +PyAssist currently supports the following functionalities: + +- Todo management through integration with Todoist +- Timer functionality +- Joke telling +- Simple chat conversations +- Get the current time + + +## Installation and Setting Up + +To install and set up PyAssist, follow these steps: + +1. Clone the repository: + ```bash + git clone https://github.com/yourusername/PyAssist.git + cd PyAssist + ``` +2. Create a virtual environment via `pyvenv` or `conda`: + ```bash + # pyvenv + python -m venv venv` + source venv/bin/activate + + # conda + conda create -n pyassist python=3.11 + conda activate pyassist + ``` + +3. Install the required packages: + ```bash + pip install -r requirements.txt + ``` + +4. Set up the necessary environment variables: + - Create a file named `env.py` in the root directory + - Add the following variables: + ```python + OPEN_AI_API_KEY="your_openai_api_key" + TODOIST_API_KEY ="your_todoist_api_key" + ``` + +5. Configure the Todoist project ID: + - Open `utils/settings/todoist_settings.py` + - Set the `PROJECT_ID` variable to your desired project in which PyAssist will create tasks + The project ID can be retrieved from your todoist project url: https://app.todoist.com/app/project/test-projekt-api-[PROJECT_ID]. + +6. Run PyAssist by executing: + ```bash + python main.py + ``` + +## Writing Your Own Assistant + +PyAssist is designed to be extensible, allowing you to create custom assistants. To write your own assistant, you'll need to implement a few key components and derive from specific classes. +For a full implementation look the assistants and LLMs in the directories `assistant/` and `LLM/`. + +### 1. Derive from AbstractAssistant + +Your custom assistant should derive from the `AbstractAssistant` class. This class provides basic functionality for speech recognition, text-to-speech conversion, and logging. + +```python +from assistant.abstract_assistant import AbstractAssistant +from LLM.my_custom_llm import MyCustomLLM + +class MyCustomAssistant(AbstractAssistant): + def init(self): + super().init() + # Initialize the name of the Assistant. + # Note: This name has to match with the one you use in `utils/settings/assistant_settings.py`! + self.assistant_id = "MyCustomAssistant" + + # Define your custom llm class which you have to implement + self.my_custom_llm = MyCustomLLM() + + def respond(self, speech: Optional[str] = "") -> None: + # Implement your custom logic here + pass +``` + +### 2. Implement the respond Method + +The `respond` method is the core of your assistant. It should process the user's speech and determine the appropriate action. + +```python +def respond(self, speech: Optional[str] = "") -> None: + if not speech: + return + # Process the speech and determine the action. The speech is the raw text spoken by the user. + action = self.my_custom_llm.process(speech=speech) + + if action == "custom_action": + self.perform_custom_action() + elif action == "another_action": + self.perform_another_action() + else: + self.say(DEFAULT_RESPONSES.get("ERROR", "")) +``` + + +### 3. Create a Language Model (LLM) for Your Assistant + +You'll need to create a custom LLM to process user input and generate responses. This should derive from the `LLM` class. -- OpenAI api key -- create a `env.py` with the following variables: ```python -OPEN_AI_API_KEY="your_api_key" + from LLM.abstract_llm import LLM + +class MyCustomLLM(LLM): def init(self): super().init() + + def process(self, *args, **kwargs): + speech = kwargs.get("speech", "") + if not speech: + return + + prompt = self.format_prompt(speech) + response = self.ask(prompt) + # If you specify that the LLM should return a JSON response you should to the self.to_json() function. + # Otherwise return the plain text. + return self.to_json(response) + + def format_prompt(self, prompt: str = ""): + # Implement your custom prompt formatting logic here + return prompt +``` + +### 4. Register Your Assistant + +To make your assistant available to PyAssist, you need to register it in the `ASSISTANTS` dictionary in `utils/settings/assistant_settings.py`. +```python +from assistant.simple_chat_assistant import SimpleChatAssistant +# ... +from assistant.my_custom_assistant import MyCustomAssistant # Import your custom assistant + +ASSISTANTS = { + "Unknown": UnknownAssistant(), + # ... + "MyCustom": MyCustomAssistant(), # Add your custom assistant here +} + ``` -## Notes -- Don't use the 2.1.6 version of the todoist api as it has the issue that project wont be correctly fetched -- The project id can be retrieved from the todoist page and is in the url: https://app.todoist.com/app/project/test-projekt-api-2337762329 -> 2337762329 \ No newline at end of file +## Configuration Options + +PyAssist offers several configuration options to customize its behavior: + +### Audio Settings + +Modify `utils/settings/audio_settings.py` to adjust microphone input parameters and wake word detection thresholds. These settings allow you to fine-tune the assistant's responsiveness to voice commands and improve overall audio quality. + +### Language Model Settings + +Configure the language model and history length in `utils/settings/llm_settings.py`. This allows you to: + +- Choose between different pre-trained language models from OpenAI + + +### Assistant Settings + +Customize available assistants in `utils/settings/assistant_settings.py`. This allows you to: + +- Enable or disable specific assistants (e.g., Todoist, timer, joke teller) +- Add custom assistants or modify existing ones + +### Additional Configuration + +- **Logging**: Modify `utils/logging_config.py` to adjust log levels and output formats. +- **Default response messages**: Update `utils/settings/default_messages_settings.py` to change the format and content of assistant responses. \ No newline at end of file