Improve installation process for Hermes package on macOS

[RayFernando1337]

Improve installation process for Hermes package on macOS

The current installation process for the Hermes package on macOS faces several obstacles that could be streamlined for a better user experience. Here's a summary of the issues encountered:

1. Initial installation attempt fails due to zsh interpreting square brackets as wildcard characters.
2. After resolving the zsh issue, the installation fails due to a missing 'yaml' module.
3. After installing PyYAML, the installation fails again while building PyAudio, specifically due to a missing 'portaudio.h' file.
4. The installation succeeds only after manually installing PortAudio via Homebrew.

Suggested improvements:

1. Update the installation instructions to include necessary prerequisites:

   • Recommend using quotes around the installation command to prevent zsh interpretation issues.
   • List PyYAML and PortAudio as required dependencies.

2. Consider bundling PyYAML with the package or adding it as a dependency in the setup file.

3. For macOS users, provide clear instructions on installing PortAudio via Homebrew before attempting to install Hermes.

4. If possible, implement a check in the setup process to detect if PortAudio is installed and provide a helpful error message with installation instructions if it's missing.

5. Update the package's setup.py or pyproject.toml to handle the PyAudio dependency more gracefully, possibly by including the necessary compiler flags for macOS systems.

6. Consider creating a separate requirements file for different operating systems to handle system-specific dependencies like PortAudio.

By addressing these issues, we can significantly improve the user experience for macOS users installing the Hermes package.

Steps to reproduce:

1. Attempt to install Hermes on a fresh macOS system using pip.
2. Follow the error messages and install missing dependencies as described in the attached flow.

Environment:

• Operating System: macOS 14.6.1 (23G93)
• Python version: 3.12
• pip version: pip 24.2
• Conda environment

Attachments:

• Detailed installation flow with error messages (see below)

Detailed Installation Flow:

The square brackets [] are being treated as wildcard characters by zsh, which is causing the "no matches found" error.

The following kicked off the install pip install "git+https://github.com/unclecode/hermes.git@main#egg=hermes[mlx]"

I'm now seeing the following error:

pip install "git+https://github.com/unclecode/hermes.git@main#egg=hermes[mlx]"
DEPRECATION: git+https://github.com/unclecode/hermes.git@main#egg=hermes[mlx] contains an egg fragment with a non-PEP 508 name pip 25.0 will enforce this behaviour change. A possible replacement is to use the req @ url syntax, and remove the egg fragment. Discussion can be found at https://github.com/pypa/pip/issues/11617
Collecting hermes (from hermes[mlx])
  Cloning https://github.com/unclecode/hermes.git (to revision main) to /private/var/folders/gf/74t2xp_90_bgkn8nhp74xkn00000gn/T/pip-install-wi4y5tpg/hermes_cc82a739553447798a5cdfb0428e00c7
  Running command git clone --filter=blob:none --quiet https://github.com/unclecode/hermes.git /private/var/folders/gf/74t2xp_90_bgkn8nhp74xkn00000gn/T/pip-install-wi4y5tpg/hermes_cc82a739553447798a5cdfb0428e00c7
  Resolved https://github.com/unclecode/hermes.git to commit 806e1833167bc7735d470d3ab37f1f566b6aa463
  Preparing metadata (setup.py) ... error
  error: subprocess-exited-with-error

  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [6 lines of output]
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 34, in <module>
        File "/private/var/folders/gf/74t2xp_90_bgkn8nhp74xkn00000gn/T/pip-install-wi4y5tpg/hermes_cc82a739553447798a5cdfb0428e00c7/setup.py", line 4, in <module>
          import yaml
      ModuleNotFoundError: No module named 'yaml'
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

Successfully I installed the missing dependency pip install PyYAML

Then tried install again with pip install "git+https://github.com/unclecode/hermes.git@main#egg=hermes[mlx]" Seeing the following

Building wheels for collected packages: hermes, PyAudio, pyperclip
  Building wheel for hermes (setup.py) ... done
  Created wheel for hermes: filename=hermes-0.1.0-py3-none-any.whl size=23077 sha256=e3303be06b050ec41d25221984b97add988b5fd36df40b813c4da3c624975313
  Stored in directory: /private/var/folders/gf/74t2xp_90_bgkn8nhp74xkn00000gn/T/pip-ephem-wheel-cache-q___mv9q/wheels/d0/55/7e/419bcb8c34bda2f74fb19be8ccd8fbd1ddce9a55da73703d20
  Building wheel for PyAudio (pyproject.toml) ... error
  error: subprocess-exited-with-error

  × Building wheel for PyAudio (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [18 lines of output]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build/lib.macosx-11.0-arm64-cpython-312
      creating build/lib.macosx-11.0-arm64-cpython-312/pyaudio
      copying src/pyaudio/__init__.py -> build/lib.macosx-11.0-arm64-cpython-312/pyaudio
      running build_ext
      building 'pyaudio._portaudio' extension
      creating build/temp.macosx-11.0-arm64-cpython-312
      creating build/temp.macosx-11.0-arm64-cpython-312/src
      creating build/temp.macosx-11.0-arm64-cpython-312/src/pyaudio
      clang -fno-strict-overflow -Wsign-compare -Wunreachable-code -DNDEBUG -O2 -Wall -fPIC -O2 -isystem /Users/ray/miniforge3/envs/hermes/include -arch arm64 -fPIC -O2 -isystem /Users/ray/miniforge3/envs/hermes/include -arch arm64 -DMACOS=1 -I/usr/local/include -I/usr/include -I/opt/homebrew/include -I/Users/ray/miniforge3/envs/hermes/include/python3.12 -c src/pyaudio/device_api.c -o build/temp.macosx-11.0-arm64-cpython-312/src/pyaudio/device_api.o
      src/pyaudio/device_api.c:9:10: fatal error: 'portaudio.h' file not found
      #include "portaudio.h"
               ^~~~~~~~~~~~~
      1 error generated.
      error: command '/usr/bin/clang' failed with exit code 1
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for PyAudio
  Building wheel for pyperclip (setup.py) ... done
  Created wheel for pyperclip: filename=pyperclip-1.9.0-py3-none-any.whl size=11004 sha256=d030ef57899acfb77b2a89b0ecf0f1abb00a4ba187c86bfc422aaca2bc91b18e
  Stored in directory: /Users/ray/Library/Caches/pip/wheels/e0/e8/fc/8ab8aa326e33bc066ccd5f3ca9646eab4299881af933f94f09
Successfully built hermes pyperclip
Failed to build PyAudio
ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (PyAudio)

Successfully installed the following because I'm on a Mac brew install portaudio

Re-ran pip install "git+https://github.com/unclecode/hermes.git@main#egg=hermes[mlx]"

Success!!