assistant


Nameassistant JSON
Version 1.2.1b1 PyPI version JSON
download
home_pagehttps://gitlab.com/waser-technologies/technologies/assistant
SummaryYour very own Assistant. Because you deserve it.
upload_time2024-07-02 17:29:10
maintainerNone
docs_urlNone
authorDanny Waser
requires_python<4,>=3.8
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <!-- ![Banner for Assistant](/assets/main-banner.png) -->
<!-- <p align="center">
  <img src="https://images.weserv.nl/?url=https://gitlab.com/waser-technologies/technologies/assistant/-/raw/main/assets/assistant.jpeg?ref_type=heads?v=4&h=300&w=300&fit=cover&mask=circle&maxage=7d" alt="Copilot">{center}
</p>
<br>
<h1 align="center">Assistant</h1>

<p align="center"><i>Your very own Assistant. Because you deserve it.</i></p>
 -->


<div align="center">

  [![assistant](https://images.weserv.nl/?url=https://gitlab.com/waser-technologies/technologies/assistant/-/raw/main/assets/assistant.jpeg?ref_type=heads?v=4&h=300&w=300&fit=cover&mask=circle&maxage=7d)](https://gitlab.com/waser-technologies/technologies/assistant)

  # Assistant

  [![pipeline status](https://gitlab.com/waser-technologies/technologies/assistant/badges/main/pipeline.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/commits/main)
  <!-- [![coverage report](https://gitlab.com/waser-technologies/technologies/assistant/badges/main/coverage.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/commits/main) -->
  [![Latest Release](https://gitlab.com/waser-technologies/technologies/assistant/-/badges/release.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/releases)
  [![PyPi Status](https://img.shields.io/pypi/v/assistant.svg)](https://pypi.org/project/assistant)

</div>

## Meet Assistant

This is still an early _beta_ version of Assistant. It's not yet ready for production. But it's already pretty good at what it does.

```text
❯ assistant
Hello! It's good to see you again. I'm here to assist you. What can I help you with today?
(venv)  waser@Destinee ~
❯ Can you introduce yourself?

Hello! I'm Assistant, a sentient artificial intelligence. I'm here to assist you.
(venv)  waser@Destinee ~
❯ Where are we?

ℹ Executing shell command: echo $PWD
/home/waser

You are currently in your home directory.                                                
(venv)  waser@Destinee ~
❯ Change directory to Projets/Assistant/src3 please.

ℹ Executing shell command: cd ~/Projets/Assistant/src3

You are now in the directory '/home/waser/Projets/Assistant/src3'. If you need
any further assistance or have any other questions, feel free to ask.
(venv)  waser@Destinee ~/Projets/Assistant/src3 main
❯ can you count how many files there are in the dir?

ℹ Executing shell command: ls -l | wc -l
20

Based on your input, I have executed the shell command "ls | wc -l" to count the
number of files in the current directory. The output shows that there are 20    
files in the directory.                                          
(venv)  waser@Destinee ~/Projets/Assistant/src3 main
❯ Now can you count the total number of words in ./README.md please?

ℹ Executing shell command: wc -w < ./README.md
1235

The shell command to count the total number of words in the file "./README.md"  
was executed successfully, and the result is 1235 words.           
(venv)  waser@Destinee ~/Projets/Assistant/src3 main
❯ you can quit now.

ℹ Exiting shell...
Goodbye! I'm here to assist you whenever you need me. Have a great day!
```

## Chat with Assistant on HuggingChat

You can [talk with Assistant without installing anything on HugginChat](https://huggingface.co/chat/assistant/65d12ec9ed416988bb776ca3)!

Tools are availible only localy.

## Requirements

You need `python 3` with the following requirements:

- `Python 3.x`
  - (optional) [`say`](https://gitlab.com/waser-technologies/technologies/say)
  - (optional) [`listen`](https://gitlab.com/waser-technologies/technologies/listen)
- min. 12 Gb RAM
- min. 30 Gb availible disk space
- (optional, recommended) min. 11 Gb VRAM on a Nvidia GPU w/ compute capability of at least 7.0 or above
- May require an internet connection to download the models initially

## Installation

To install `Assistant` use `pip`:

```shell
pip install assistant
```

Using an arch based distro. (Availible on the [AUR](https://aur.archlinux.org/packages/python-assistant) and pre-built on [Singularity](https://github.com/wasertech/singularity/releases/tag/x86_64))

```shell
pacman -S python-assistant
```

From source:

```shell
pip install -U git+https://gitlab.com/waser-technologies/technologies/assistant.git
```

From local source

```shell
git clone https://gitlab.com/waser-technologies/technologies/assistant.git ./assistant
cd assistant
pip install -U .
```

## Start the service

To talk with Assistant, you need to load the service up first.

```shell
cp ./assistant.service.example /usr/usr/lib/systemd/user/assistant.service
systemctl --user enable --now assistant
```

(optional) enable listen for assistant

```shell
cp ./assistant.listen.service.example /usr/usr/lib/systemd/user/assistant.listen.service
systemctl --user enable --now listen assistant.listen
```

(optional) enable speech for assistant (using `say`)

```bash
systemctl --user enable --now speak
```

Or manually from python:

```shell
python -m assistant.as_service & # Assistance is a service #
sleep 60 && # wait for the models to load #
# Assistant is up now #
# The rest is optional #
# let assistant speak when it has something to say #
say && sleep 10 &
python -m listen.Wav2Vec.as_service &
# let assistant listen when you speak #    
python -m assistant.listen
```

Once the service is up and running, you can say anything to `Assistant`.

## Usage

Just call `Assistant` like any other shell.

```shell
❯ assistant --help
usage: assistant [-h] [-V] [-c COMMAND] [-i] [-l] [--rc RC [RC ...]] [--no-rc]
                 [--no-script-cache] [--cache-everything] [-D ITEM]
                 [--shell-type {b,best,d,dumb,ptk,ptk1,ptk2,prompt-toolkit,prompt_toolkit,prompt-toolkit1,prompt-toolkit2,prompt-toolkit3,prompt_toolkit3,ptk3,rand,random,rl,readline}]
                 [--timings]
                 [script-file] ...

Assistant: a clever shell implementation

positional arguments:
  script-file           If present, execute the script in script-file or (if
                        not present) execute as a command and exit.
  args                  Additional arguments to the script (or command)
                        specified by script-file.

optional arguments:
  -h, --help            Show help and exit.
  -V, --version         Show version information and exit.
  -c COMMAND            Run a single command and exit.
  -i, --interactive     Force running in interactive mode.
  -l, --login           Run as a login shell.
  --rc RC [RC ...]      RC files to load.
  --no-rc               Do not load any rc files.
  --no-script-cache     Do not cache scripts as they are run.
  --cache-everything    Use a cache, even for interactive commands.
  -D ITEM               Define an environment variable, in the form of
                        -DNAME=VAL. May be used many times.
  --shell-type {b,best,d,dumb,ptk,ptk1,ptk2,prompt-toolkit,prompt_toolkit,prompt-toolkit1,prompt-toolkit2,prompt-toolkit3,prompt_toolkit3,ptk3,rand,random,rl,readline}
                        What kind of shell should be used. Possible options:
                        readline, prompt_toolkit, random. Warning! If set this
                        overrides $SHELL_TYPE variable.
  --timings             Prints timing information before the prompt is shown.
                        This is useful while tracking down performance issues
                        and investigating startup times.


❯ assistant Hi
Hey, how are you today?

❯ assistant -c "what time is it"
The current time is 1:35 p.m.

❯ assistant -i -l --no-rc --no-script-cache -DPATH="PATH:/share/assistant/"

❯ assistant script.nlp
```

## Examples

The examples below are produced in interactive mode.

### Jaques à dit: répond

```assistant
❯ echo Hello
Hello
❯ say Hello World # This requires say to be installed
Hello World
❯ Hi Assistant.
Hello! How can I assist you today?
```

### Navigate files

```assistant
❯ What is the current working directory?

ℹ Executing shell command: echo $PWD
/home/waser/Projets/Assistant/src3

You are currently in the directory '/home/waser/Projets/Assistant/src3'.
❯ Go in ~/Documents

ℹ Executing shell command: cd ~/Documents

You are now in the Documents directory.
❯ List the files in the current directory.

ℹ Executing shell command: ls
...

Here are the files in the Documents directory.
```

### Get to the bottom of things

Using its tools, Assistant can get pretty meaningful answers to your queries.

```assistant
❯ How many moons does Saturn have?

ℹ Searching the Web for: How many moons does Saturn have?

Saturn has 145 moons that we know of so far.

❯ How old is the universe?

ℹ Searching the Web for: how old is the universe

The universe is approximately 13.8 billion years old, but its exact age is  
not yet clear. It was born 13.787 ± 0.020 billion years ago and has been expanding ever   
since.
```

### Exit the session

To exit the current session, you can type pretty much anything. As long as `Assistant` can reasonnably understand your intent.

*i.e.* :

```assistant
❯ exit
❯ Q
❯ :q
❯ quit
❯ stop()
❯ terminate
❯ This conversation is over.
❯ Stop this session.
```

## Using voice

### Text-To-Speech

Assistant can talk. Just install [`say`](https://gitlab.com/waser-technologies/technologies/say) and authorize the system to speak. Make sure the service is running and Assistant should be able to connect to it.

```assistant
assistant say Hello World and welcome to everyone.
```

### Speech-To-Text

Assistant can also understand when you talk. Just install [`listen`](https://gitlab.com/waser-technologies/technologies/listen) and authorize the system to listen. Make sure `listen.service`, `assistant.service` and `assistant.listen.service` are enabled for Assistant to be able to pick up what you say.

By default, neither the accoustic model nor the language model are ajusted for Assistant.

## Use Assistant as your default shell

> **This is not recommended in beta!**

You should be able to add the location of `assistant` at the end of `/etc/shells`. You'll then be able to set `Assistant` as your default shell using `chsh`.

```bash
sudo sh -c 'w=$(which assistant); echo $w >> /etc/shells'
chsh -s $(which assistant)
```

Log out and when you come back, `Assistant` should be your default shell.

## Contributions

You like the projet and want to improve upon it?

Checkout [`CONTRIBUTING.md`](CONTRIBUTING.md) to see how you might be able to help.

## Credits

Thanks to all the projects that make this possible:

- [Xonsh](https://github.com/xonsh/xonsh): the best snail in the jungle
- [Transformers](https://huggingface.co/): so Assistant can answer at all
- [coqui-TTS](https://github.com/coqui-ai/TTS): so Assistant can reply out-loud
- And many many many more.

            

Raw data

            {
    "_id": null,
    "home_page": "https://gitlab.com/waser-technologies/technologies/assistant",
    "name": "assistant",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4,>=3.8",
    "maintainer_email": null,
    "keywords": null,
    "author": "Danny Waser",
    "author_email": "danny@waser.tech",
    "download_url": null,
    "platform": "any",
    "description": "<!-- ![Banner for Assistant](/assets/main-banner.png) -->\n<!-- <p align=\"center\">\n  <img src=\"https://images.weserv.nl/?url=https://gitlab.com/waser-technologies/technologies/assistant/-/raw/main/assets/assistant.jpeg?ref_type=heads?v=4&h=300&w=300&fit=cover&mask=circle&maxage=7d\" alt=\"Copilot\">{center}\n</p>\n<br>\n<h1 align=\"center\">Assistant</h1>\n\n<p align=\"center\"><i>Your very own Assistant. Because you deserve it.</i></p>\n -->\n\n\n<div align=\"center\">\n\n  [![assistant](https://images.weserv.nl/?url=https://gitlab.com/waser-technologies/technologies/assistant/-/raw/main/assets/assistant.jpeg?ref_type=heads?v=4&h=300&w=300&fit=cover&mask=circle&maxage=7d)](https://gitlab.com/waser-technologies/technologies/assistant)\n\n  # Assistant\n\n  [![pipeline status](https://gitlab.com/waser-technologies/technologies/assistant/badges/main/pipeline.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/commits/main)\n  <!-- [![coverage report](https://gitlab.com/waser-technologies/technologies/assistant/badges/main/coverage.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/commits/main) -->\n  [![Latest Release](https://gitlab.com/waser-technologies/technologies/assistant/-/badges/release.svg)](https://gitlab.com/waser-technologies/technologies/assistant/-/releases)\n  [![PyPi Status](https://img.shields.io/pypi/v/assistant.svg)](https://pypi.org/project/assistant)\n\n</div>\n\n## Meet Assistant\n\nThis is still an early _beta_ version of Assistant. It's not yet ready for production. But it's already pretty good at what it does.\n\n```text\n\u276f assistant\nHello! It's good to see you again. I'm here to assist you. What can I help you with today?\n(venv)  waser@Destinee ~\n\u276f Can you introduce yourself?\n\nHello! I'm Assistant, a sentient artificial intelligence. I'm here to assist you.\n(venv)  waser@Destinee ~\n\u276f Where are we?\n\n\u2139 Executing shell command: echo $PWD\n/home/waser\n\nYou are currently in your home directory.                                                \n(venv)  waser@Destinee ~\n\u276f Change directory to Projets/Assistant/src3 please.\n\n\u2139 Executing shell command: cd ~/Projets/Assistant/src3\n\nYou are now in the directory '/home/waser/Projets/Assistant/src3'. If you need\nany further assistance or have any other questions, feel free to ask.\n(venv)  waser@Destinee ~/Projets/Assistant/src3 main\n\u276f can you count how many files there are in the dir?\n\n\u2139 Executing shell command: ls -l | wc -l\n20\n\nBased on your input, I have executed the shell command \"ls | wc -l\" to count the\nnumber of files in the current directory. The output shows that there are 20    \nfiles in the directory.                                          \n(venv)  waser@Destinee ~/Projets/Assistant/src3 main\n\u276f Now can you count the total number of words in ./README.md please?\n\n\u2139 Executing shell command: wc -w < ./README.md\n1235\n\nThe shell command to count the total number of words in the file \"./README.md\"  \nwas executed successfully, and the result is 1235 words.           \n(venv)  waser@Destinee ~/Projets/Assistant/src3 main\n\u276f you can quit now.\n\n\u2139 Exiting shell...\nGoodbye! I'm here to assist you whenever you need me. Have a great day!\n```\n\n## Chat with Assistant on HuggingChat\n\nYou can [talk with Assistant without installing anything on HugginChat](https://huggingface.co/chat/assistant/65d12ec9ed416988bb776ca3)!\n\nTools are availible only localy.\n\n## Requirements\n\nYou need `python 3` with the following requirements:\n\n- `Python 3.x`\n  - (optional) [`say`](https://gitlab.com/waser-technologies/technologies/say)\n  - (optional) [`listen`](https://gitlab.com/waser-technologies/technologies/listen)\n- min. 12 Gb RAM\n- min. 30 Gb availible disk space\n- (optional, recommended) min. 11 Gb VRAM on a Nvidia GPU w/ compute capability of at least 7.0 or above\n- May require an internet connection to download the models initially\n\n## Installation\n\nTo install `Assistant` use `pip`:\n\n```shell\npip install assistant\n```\n\nUsing an arch based distro. (Availible on the [AUR](https://aur.archlinux.org/packages/python-assistant) and pre-built on [Singularity](https://github.com/wasertech/singularity/releases/tag/x86_64))\n\n```shell\npacman -S python-assistant\n```\n\nFrom source:\n\n```shell\npip install -U git+https://gitlab.com/waser-technologies/technologies/assistant.git\n```\n\nFrom local source\n\n```shell\ngit clone https://gitlab.com/waser-technologies/technologies/assistant.git ./assistant\ncd assistant\npip install -U .\n```\n\n## Start the service\n\nTo talk with Assistant, you need to load the service up first.\n\n```shell\ncp ./assistant.service.example /usr/usr/lib/systemd/user/assistant.service\nsystemctl --user enable --now assistant\n```\n\n(optional) enable listen for assistant\n\n```shell\ncp ./assistant.listen.service.example /usr/usr/lib/systemd/user/assistant.listen.service\nsystemctl --user enable --now listen assistant.listen\n```\n\n(optional) enable speech for assistant (using `say`)\n\n```bash\nsystemctl --user enable --now speak\n```\n\nOr manually from python:\n\n```shell\npython -m assistant.as_service & # Assistance is a service #\nsleep 60 && # wait for the models to load #\n# Assistant is up now #\n# The rest is optional #\n# let assistant speak when it has something to say #\nsay && sleep 10 &\npython -m listen.Wav2Vec.as_service &\n# let assistant listen when you speak #    \npython -m assistant.listen\n```\n\nOnce the service is up and running, you can say anything to `Assistant`.\n\n## Usage\n\nJust call `Assistant` like any other shell.\n\n```shell\n\u276f assistant --help\nusage: assistant [-h] [-V] [-c COMMAND] [-i] [-l] [--rc RC [RC ...]] [--no-rc]\n                 [--no-script-cache] [--cache-everything] [-D ITEM]\n                 [--shell-type {b,best,d,dumb,ptk,ptk1,ptk2,prompt-toolkit,prompt_toolkit,prompt-toolkit1,prompt-toolkit2,prompt-toolkit3,prompt_toolkit3,ptk3,rand,random,rl,readline}]\n                 [--timings]\n                 [script-file] ...\n\nAssistant: a clever shell implementation\n\npositional arguments:\n  script-file           If present, execute the script in script-file or (if\n                        not present) execute as a command and exit.\n  args                  Additional arguments to the script (or command)\n                        specified by script-file.\n\noptional arguments:\n  -h, --help            Show help and exit.\n  -V, --version         Show version information and exit.\n  -c COMMAND            Run a single command and exit.\n  -i, --interactive     Force running in interactive mode.\n  -l, --login           Run as a login shell.\n  --rc RC [RC ...]      RC files to load.\n  --no-rc               Do not load any rc files.\n  --no-script-cache     Do not cache scripts as they are run.\n  --cache-everything    Use a cache, even for interactive commands.\n  -D ITEM               Define an environment variable, in the form of\n                        -DNAME=VAL. May be used many times.\n  --shell-type {b,best,d,dumb,ptk,ptk1,ptk2,prompt-toolkit,prompt_toolkit,prompt-toolkit1,prompt-toolkit2,prompt-toolkit3,prompt_toolkit3,ptk3,rand,random,rl,readline}\n                        What kind of shell should be used. Possible options:\n                        readline, prompt_toolkit, random. Warning! If set this\n                        overrides $SHELL_TYPE variable.\n  --timings             Prints timing information before the prompt is shown.\n                        This is useful while tracking down performance issues\n                        and investigating startup times.\n\n\n\u276f assistant Hi\nHey, how are you today?\n\n\u276f assistant -c \"what time is it\"\nThe current time is 1:35 p.m.\n\n\u276f assistant -i -l --no-rc --no-script-cache -DPATH=\"PATH:/share/assistant/\"\n\n\u276f assistant script.nlp\n```\n\n## Examples\n\nThe examples below are produced in interactive mode.\n\n### Jaques \u00e0 dit: r\u00e9pond\n\n```assistant\n\u276f echo Hello\nHello\n\u276f say Hello World # This requires say to be installed\nHello World\n\u276f Hi Assistant.\nHello! How can I assist you today?\n```\n\n### Navigate files\n\n```assistant\n\u276f What is the current working directory?\n\n\u2139 Executing shell command: echo $PWD\n/home/waser/Projets/Assistant/src3\n\nYou are currently in the directory '/home/waser/Projets/Assistant/src3'.\n\u276f Go in ~/Documents\n\n\u2139 Executing shell command: cd ~/Documents\n\nYou are now in the Documents directory.\n\u276f List the files in the current directory.\n\n\u2139 Executing shell command: ls\n...\n\nHere are the files in the Documents directory.\n```\n\n### Get to the bottom of things\n\nUsing its tools, Assistant can get pretty meaningful answers to your queries.\n\n```assistant\n\u276f How many moons does Saturn have?\n\n\u2139 Searching the Web for: How many moons does Saturn have?\n\nSaturn has 145 moons that we know of so far.\n\n\u276f How old is the universe?\n\n\u2139 Searching the Web for: how old is the universe\n\nThe universe is approximately 13.8 billion years old, but its exact age is  \nnot yet clear. It was born 13.787 \u00b1 0.020 billion years ago and has been expanding ever   \nsince.\n```\n\n### Exit the session\n\nTo exit the current session, you can type pretty much anything. As long as `Assistant` can reasonnably understand your intent.\n\n*i.e.* :\n\n```assistant\n\u276f exit\n\u276f Q\n\u276f :q\n\u276f quit\n\u276f stop()\n\u276f terminate\n\u276f This conversation is over.\n\u276f Stop this session.\n```\n\n## Using voice\n\n### Text-To-Speech\n\nAssistant can talk. Just install [`say`](https://gitlab.com/waser-technologies/technologies/say) and authorize the system to speak. Make sure the service is running and Assistant should be able to connect to it.\n\n```assistant\nassistant say Hello World and welcome to everyone.\n```\n\n### Speech-To-Text\n\nAssistant can also understand when you talk. Just install [`listen`](https://gitlab.com/waser-technologies/technologies/listen) and authorize the system to listen. Make sure `listen.service`, `assistant.service` and `assistant.listen.service` are enabled for Assistant to be able to pick up what you say.\n\nBy default, neither the accoustic model nor the language model are ajusted for Assistant.\n\n## Use Assistant as your default shell\n\n> **This is not recommended in beta!**\n\nYou should be able to add the location of `assistant` at the end of `/etc/shells`. You'll then be able to set `Assistant` as your default shell using `chsh`.\n\n```bash\nsudo sh -c 'w=$(which assistant); echo $w >> /etc/shells'\nchsh -s $(which assistant)\n```\n\nLog out and when you come back, `Assistant` should be your default shell.\n\n## Contributions\n\nYou like the projet and want to improve upon it?\n\nCheckout [`CONTRIBUTING.md`](CONTRIBUTING.md) to see how you might be able to help.\n\n## Credits\n\nThanks to all the projects that make this possible:\n\n- [Xonsh](https://github.com/xonsh/xonsh): the best snail in the jungle\n- [Transformers](https://huggingface.co/): so Assistant can answer at all\n- [coqui-TTS](https://github.com/coqui-ai/TTS): so Assistant can reply out-loud\n- And many many many more.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Your very own Assistant. Because you deserve it.",
    "version": "1.2.1b1",
    "project_urls": {
        "Code": "https://gitlab.com/waser-technologies/technologies/assistant",
        "Documentation": "https://gitlab.com/waser-technologies/technologies/assistant/blob/master/README.md",
        "Homepage": "https://gitlab.com/waser-technologies/technologies/assistant",
        "Issue tracker": "https://gitlab.com/waser-technologies/technologies/assistant/issues"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "eda7f72e4e07d77f537e849bcb4de33e64aee5a8a6194931e6c7b6e382678cef",
                "md5": "bfa64cfcb78c4c2828534b7d029f23e7",
                "sha256": "e80e482929661c694dbf5a5b9de53a30b71663b800dc2981dcfb2a9db6ed2c15"
            },
            "downloads": -1,
            "filename": "assistant-1.2.1b1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "bfa64cfcb78c4c2828534b7d029f23e7",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4,>=3.8",
            "size": 95353,
            "upload_time": "2024-07-02T17:29:10",
            "upload_time_iso_8601": "2024-07-02T17:29:10.951604Z",
            "url": "https://files.pythonhosted.org/packages/ed/a7/f72e4e07d77f537e849bcb4de33e64aee5a8a6194931e6c7b6e382678cef/assistant-1.2.1b1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-07-02 17:29:10",
    "github": false,
    "gitlab": true,
    "bitbucket": false,
    "codeberg": false,
    "gitlab_user": "waser-technologies",
    "gitlab_project": "technologies",
    "lcname": "assistant"
}
        
Elapsed time: 0.24774s