Metadata-Version: 2.4
Name: HeyMilo
Version: 0.1.0
Summary: Lightweight Hey Milo voice-assistant host and guided setup for PCs and Raspberry Pi
Author: Hey Milo contributors
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: voice
Requires-Dist: vosk<0.4,>=0.3.45; extra == "voice"
Requires-Dist: sounddevice<0.6,>=0.4.6; extra == "voice"
Requires-Dist: pyttsx3<3,>=2.90; extra == "voice"

# Hey Milo

A lightweight Python assistant host for Windows 10/11 PCs and Raspberry Pi 4. Running `heymilo` opens a local setup guide. Version 0.1.0 is an initial alpha: it provides basic offline commands, optional online AI conversation, and optional local microphone recognition and speech output.

## Install

**Publication status:** this source release must be published to PyPI before the name-based commands below will work. Until then install the supplied wheel with `python -m pip install path/to/heymilo-0.1.0-py3-none-any.whl`.

After publication:

```console
python -m pip install HeyMilo
heymilo
```

Package installation does not launch a browser or record audio. Run `heymilo` after installing to open the guide. If the command is not on PATH, use `python -m heymilo`.

### Windows 10 / 11 (Dell Latitude)

Install 64-bit Python 3.11 or 3.12 from python.org. In PowerShell:

```powershell
py -3.11 -m venv "$HOME\heymilo-env"
& "$HOME\heymilo-env\Scripts\python.exe" -m pip install HeyMilo
& "$HOME\heymilo-env\Scripts\heymilo.exe"
```

Use `-3.12` if that is the version you installed. Using full executable paths avoids PowerShell activation-policy changes.

### Raspberry Pi 4 with 1 GB RAM

Recommended starting system: Raspberry Pi OS Lite **64-bit**, Python 3.11/3.12. The base package supports Python 3.10+; optional voice wheels and system libraries have their own platform support.

```sh
sudo apt update
sudo apt install python3-venv libportaudio2 espeak-ng
python3 -m venv ~/heymilo-env
. ~/heymilo-env/bin/activate
python -m pip install HeyMilo
heymilo guide --no-browser --port 8765
```

View the Pi's guide from the Dell using an SSH tunnel:

```powershell
ssh -L 8765:127.0.0.1:8765 YOUR_PI_USER@YOUR_PI_HOST
```

Then open `http://127.0.0.1:8765` on the Dell. Keep both terminal processes running. The guide listens only on loopback; it does not expose a LAN administration interface.

## Commands

```console
heymilo                         # open the setup guide
heymilo doctor                  # inspect configuration and dependencies
heymilo run                     # terminal conversation; /quit exits
heymilo run --ask "What time is it?"
heymilo devices                 # list microphones; voice extra required
heymilo listen                  # opt-in microphone listening; Ctrl+C stops
```

Local commands: `help`, `what time is it`, `what is today's date`, `system status`, and greetings. This alpha does not control home devices or execute computer actions.

## Online AI

Choose **Online AI + local basic commands** in the guide. The default endpoint is OpenAI's `/v1` API and the suggested model is `gpt-4.1-mini`; select a model your provider/account supports. Provider billing and network access are separate from this package.

Set `OPENAI_API_KEY` locally in the terminal before starting Milo. The guide accepts the environment variable's **name**, never the key itself. On PowerShell use `$env:OPENAI_API_KEY="your-key"`. On Linux you can use `read -rsp 'API key: ' OPENAI_API_KEY; echo; export OPENAI_API_KEY` to avoid putting the secret in command history. Do not share the key in chat or commit it.

Non-local questions send text to the configured provider. Terminal conversation history is limited to three turns in memory, and requested responses are capped at 256 tokens. Basic local commands never make an AI request. Guide test conversations are stateless. No local LLM is loaded on the 1 GB Pi.

## Voice

```console
python -m pip install "HeyMilo[voice]==0.1.0"
```

Before PyPI publication use `python -m pip install "./path/to/heymilo-0.1.0-py3-none-any.whl[voice]"` instead. Voice extras are Vosk, sounddevice and pyttsx3; Linux also needs PortAudio and espeak-ng. Download a **small** language model from https://alphacephei.com/vosk/models, review its license, extract it and select the folder containing `am/final.mdl` in the guide. Models are not bundled or automatically downloaded.

Select the microphone using `heymilo devices`, then `heymilo listen --device INDEX`. Say “Hey Milo, what time is it?” or “Hey Milo” followed by a question within 20 seconds. If needed, try `--sample-rate 48000` for a device that rejects 16000 Hz. Enable speech output in the guide; output uses the OS default speaker. Windows requires microphone permission for desktop apps.

Audio recognition happens locally. Only wake-accepted text is forwarded to online AI; audio is neither uploaded nor saved. Audio capture pauses during replies. The wake phrase is recognized through Vosk, not a trained dedicated wake-word engine, and may miss or falsely detect speech. The input queue is bounded. Model memory usage and real-time performance depend on model/hardware; this release has not been benchmarked on the user's Pi or Dell.

## ReSpeaker / ESP32-S3

This package is the **Pi/PC host application**. Use the board's supported USB-audio firmware and verify that the ReSpeaker appears as an input device. ESP32 flashing, microphone-array DSP/AEC tuning, pin assignments, home-device integrations and automatic boot startup are future work. Do not infer USB power isolation from software support; the mechanical project's independent-power limitation is unchanged.

## Configuration and development

Settings: `%APPDATA%\heymilo\config.json` on Windows or `~/.config/heymilo/config.json` on Linux. Override with `HEYMILO_CONFIG` for testing. API secrets are not written to configuration. The setup service checks its Host/Origin and a session token before accepting changes; do not proxy it publicly.

```sh
python -m pip install -e .
python -m unittest discover -s tests -v
python -m pip install build twine
python -m build
python -m twine check dist/*
```

See `PUBLISHING.md` for the PyPI publishing procedure. No account ownership or PyPI registration is implied by the package metadata.
