parlando 0.4.0__tar.gz

parlando-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release to PyPI
+
+# Publishes ONLY when a GitHub Release is published, and only after a
+# Trusted Publisher is configured on PyPI for this repo (Settings on
+# pypi.org -> your project -> Publishing -> add GitHub publisher with this
+# repo, workflow file "release.yml" and environment "pypi"). Until both
+# happen, this workflow is inert. No API tokens are stored anywhere:
+# authentication uses GitHub's OIDC identity (PyPA's recommended setup).
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write  # OIDC: this is what replaces API tokens
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

parlando-0.4.0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Heavy dependencies (mlx, sounddevice, pyobjc...) are imported lazily
+      # inside parlando.py, so unit tests only need numpy + pytest.
+      - name: Install test deps
+        run: pip install numpy pytest
+
+      - name: Run unit tests
+        run: pytest tests -q
+
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      # Validate packaging metadata and the wheel build (nothing published).
+      - name: Build wheel and sdist
+        run: uv build

parlando-0.4.0/.gitignore

@@ -0,0 +1,208 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.idea

parlando-0.4.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.4.0 — 2026-09-09
+
+- **Cleanup**: unambiguous vocalized fillers (um, uh, eee, ııı) are removed
+  deterministically per language (`--no-cleanup` to keep them); stutter
+  runs of 3+ identical words collapse to one.
+- **Polish (`--polish`)**: optional local-LLM cleanup at finalize — drops
+  contextual fillers, stutters and false starts, fixes punctuation. Guarded
+  so the LLM can only edit the transcript, never answer or extend it
+  (falls back to the raw text otherwise). Default model Qwen3-1.7B-4bit
+  (10/11 on the built-in benchmark, ~0.4 s); Qwen3-4B-4bit scores 11/11.
+- New `scripts/eval_polish.py`: 11-case cleanup benchmark (fillers,
+  stutters, false starts, adversarial answer/injection guards, identity)
+  that runs against the real local LLM.
+- Brand assets: custom template menu bar icons (three-bar speech waveform)
+  and a README banner, generated by `scripts/make_icons.py`.
+
+## 0.3.1 — 2026-09-08
+
+- Restructured into a proper Python package (`src/parlando/`, hatchling,
+  `pyproject.toml`) with `parlando` and `parlando-menubar` entry points.
+- `install.sh` now uses `uv tool install` (uninstall with
+  `uv tool uninstall parlando`); start-at-login uses the installed command.
+- CI additionally validates the packaging build (`uv build`).
+- PyPI publication intentionally deferred; `uvx parlando` will work once
+  published.
+
+## 0.3.0 — 2026-09-08
+
+- Project renamed to **parlando**; full internationalization (all code,
+  CLI, menu bar, and docs in English).
+- Language-aware voice commands: English set by default, Turkish set with
+  `--language Turkish`.
+- `--version` flag; log moved to `~/Library/Logs/parlando.log`.
+- Repository prepared for open-source release (license attribution,
+  upstream site assets removed, English README, CI badge).
+
+## 0.2.0 — 2026-09-08
+
+- **Record mode (default)**: tap-speak-tap; the whole recording is
+  transcribed once and typed in one go. Long recordings split at silence.
+- Global hotkey: single tap of right Option (chord-aware), configurable.
+- Menu bar app (rumps) with start/stop, language switching, Enter mode,
+  and `--install-login` LaunchAgent.
+- Quartz CGEvent unicode typing with osascript fallback.
+- Audio-stream watchdog (sleep/device-change recovery); microphone and
+  Accessibility permission diagnostics; file logging.
+- Streaming stability: normalized LocalAgreement, stall safety valve,
+  asymmetric noise-floor learning (deafness fix), guarded event loop.
+- Optional hybrid Silero VAD (`--silero`); voice commands; 35 unit tests
+  and macOS CI.
+
+## 0.1.0 — 2026-09-08
+
+- Initial utterance-based dictation engine on top of the dictate.sh
+  Qwen3-ASR MLX engine: energy VAD, append-only word commits with
+  LocalAgreement-2, hallucination guards, safe peak normalization.

parlando-0.4.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Furkan Can (parlando)
+Copyright (c) 2026 Marc Puig (original dictate.sh ASR engine, stt.py)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parlando-0.4.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.5
+Name: parlando
+Version: 0.4.0
+Summary: Local voice dictation for macOS (Apple Silicon): tap a key, speak, and your words are typed into any app. 100% on-device.
+Project-URL: Homepage, https://github.com/furkanc/parlando
+Project-URL: Issues, https://github.com/furkanc/parlando/issues
+Project-URL: Changelog, https://github.com/furkanc/parlando/blob/main/CHANGELOG.md
+Author: Furkan Can
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apple-silicon,asr,dictation,macos,mlx,speech-to-text,voice-typing,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub
+Requires-Dist: mlx-lm>=0.22.0
+Requires-Dist: mlx>=0.22.0
+Requires-Dist: numpy
+Requires-Dist: onnxruntime
+Requires-Dist: pynput
+Requires-Dist: pyobjc-framework-applicationservices
+Requires-Dist: pyobjc-framework-quartz
+Requires-Dist: rich
+Requires-Dist: rumps
+Requires-Dist: setuptools
+Requires-Dist: sounddevice
+Requires-Dist: transformers
+Requires-Dist: webrtcvad
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.png" alt="parlando — local voice dictation for macOS" width="720">
+</p>
+
+**Local voice dictation for macOS (Apple Silicon).** Tap a key, speak, tap
+again — your words are typed into whatever window has focus. 100% on-device:
+audio never leaves your machine.
+
+[![Tests](https://github.com/furkanc/parlando/actions/workflows/tests.yml/badge.svg)](https://github.com/furkanc/parlando/actions/workflows/tests.yml)
+
+## Features
+
+- **Fully local & offline** — MLX-accelerated Qwen3-ASR on the Apple Neural
+  stack; works on a plane, nothing is uploaded, no API keys.
+- **Tap-to-dictate** — single tap of right ⌥ Option starts/stops recording
+  (the same pattern superwhisper and Wispr Flow use). No always-on mic.
+- **Types anywhere** — text is delivered as native keyboard events (Quartz
+  CGEvent unicode), so it works in any app, editor, terminal, or chat box.
+- **30 languages** — English by default; switch instantly (e.g. `--language
+  Turkish`) with no model reload.
+- **Voice commands** — "period", "comma", "question mark", "new line",
+  "send" (presses Enter). A Turkish command set activates with
+  `--language Turkish`.
+- **Cleanup & polish** — vocalized fillers ("um", "uh", "eee") are removed
+  automatically; optional `--polish` runs a small local LLM that drops
+  contextual fillers ("you know", "yani"), stutters and false starts, and
+  fixes punctuation — guarded so it can only *edit* your words, never
+  answer them.
+- **Menu bar app** — <img src="assets/menubar-states.png" alt="menu bar icon states: idle, recording, paused" height="26" align="top"> (idle · recording · paused) with start/stop, language switcher, and start-at-login support.
+- **Self-healing** — audio watchdog survives sleep/wake and device changes;
+  inference errors never kill the session.
+- **Streaming mode (optional)** — words appear as you speak, stabilized with
+  LocalAgreement-2 and append-only commits (typed text is never retracted).
+
+## Requirements
+
+- macOS on Apple Silicon
+- [`uv`](https://docs.astral.sh/uv/) installed
+- ~2 GB disk for the default ASR model (downloaded once from Hugging Face)
+
+## Install
+
+One-liner (installs [`uv`](https://docs.astral.sh/uv/) if needed, puts
+`parlando` on your PATH):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/furkanc/parlando/main/install.sh | sh
+```
+
+Then:
+
+```bash
+parlando            # terminal
+parlando-menubar    # menu bar app
+```
+
+Click the window you want to type into → tap **right ⌥ Option** → speak →
+tap again. Your words appear at the cursor. The speech model (~1-2 GB)
+downloads once on first run; after that everything is offline.
+
+<details>
+<summary>Run from source / uninstall</summary>
+
+```bash
+git clone https://github.com/furkanc/parlando && cd parlando
+uv run parlando              # run without installing
+uv tool install .           # or install the commands from the checkout
+
+# uninstall
+uv tool uninstall parlando
+```
+</details>
+
+### Permissions (one-time)
+
+macOS will ask for two permissions, granted to the app that runs parlando
+(Terminal, iTerm, VS Code, ...):
+
+| Permission | Why | Where |
+|------------|-----|-------|
+| Microphone | hear you | Settings → Privacy & Security → Microphone |
+| Accessibility | type keystrokes + global hotkey | Settings → Privacy & Security → Accessibility |
+
+parlando detects missing permissions and tells you explicitly instead of
+failing silently.
+
+## Usage
+
+```bash
+parlando --language Turkish   # dictate in another language
+parlando --polish             # LLM cleanup (fillers, false starts, punctuation)
+parlando --enter              # press Enter after each utterance
+parlando --mode stream        # live word-by-word streaming
+parlando --pipe               # print to stdout (scriptable)
+parlando --hotkey cmd_r       # tap right Command instead
+parlando --list-devices       # list microphones
+parlando-menubar --install-login   # start at login
+```
+
+### Voice commands
+
+| Say (English) | Say (Turkish) | Result |
+|---|---|---|
+| period / comma | nokta / virgül | `.` `,` appended to previous word |
+| question mark | soru işareti | `?` appended |
+| new line / new paragraph | yeni satır / yeni paragraf | line break |
+| send | gönder | presses Enter |
+
+Disable with `--no-commands`.
+
+### Models
+
+**Speech recognition** (`--model`, MLX Qwen3-ASR — 30 languages):
+
+| Model | Size | Notes |
+|---|---|---|
+| `mlx-community/Qwen3-ASR-1.7B-8bit` | ~2 GB | **default** — best accuracy, recommended |
+| `mlx-community/Qwen3-ASR-0.6B-8bit` | ~700 MB | good balance for low-RAM machines |
+| `mlx-community/Qwen3-ASR-0.6B-4bit` | ~400 MB | fastest, lowest accuracy |
+| `mlx-community/Qwen3-ASR-0.6B-bf16` | ~1.3 GB | higher fidelity 0.6B, more RAM |
+
+**Polish LLM** (`--polish-model`, used only with `--polish`; scores from
+`scripts/eval_polish.py`, an 11-case cleanup benchmark):
+
+| Model | Size | Eval | Latency | Notes |
+|---|---|---|---|---|
+| `mlx-community/Qwen3-1.7B-4bit` | ~1 GB | 10/11 | ~0.4 s | **default** — fast, safe |
+| `mlx-community/Qwen3-4B-4bit` | ~2.3 GB | 11/11 | ~0.9 s | best quality; use on 16 GB+ Macs |
+| `mlx-community/Qwen3-0.6B-4bit` | ~350 MB | — | ~0.2 s | minimal RAM, weakest cleanup |
+
+```bash
+parlando --polish --polish-model mlx-community/Qwen3-4B-4bit
+```
+
+All models download once from Hugging Face and are cached in
+`~/.cache/huggingface`; everything runs on-device.
+
+### The two modes
+
+**`record` (default)** — tap, speak freely (pauses are fine), tap again; the
+whole recording is transcribed once and typed in one go. Recordings longer
+than 28 s are split at natural silence points (2 min cap). This mode has no
+VAD guessing, so it is the most robust.
+
+**`stream`** — always listening; an energy VAD (hysteresis, adaptive noise
+floor, optional `--silero` hybrid) segments utterances and words appear as
+you speak. More "live", more sensitive to room noise.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Nothing typed, "only silence" warning | Grant microphone permission, restart |
+| Nothing typed, no warning | Grant Accessibility permission (see startup warning) |
+| Stalls after sleep | The watchdog reopens the stream within ~5 s automatically |
+| Ghost text while silent (stream mode) | `--energy-floor 0.008` or `--silero` |
+| Missing soft speech (stream mode) | `--energy-floor 0.002` |
+| Wrong words | Move closer to the mic; prefer the built-in mic over AirPods (Bluetooth input drops to a low-quality codec) |
+| Detailed trace | `~/Library/Logs/parlando.log` |
+
+Note: `--device` indices shift when devices connect/disconnect, and virtual
+devices ("Microsoft Teams Audio", "ZoomAudioDevice") are not microphones.
+Prefer the default device.
+
+## Architecture
+
+```
+microphone ── 30 ms frames ──▶ hotkey-gated recorder (record mode)
+                              or energy VAD w/ hysteresis + adaptive floor,
+                              optional Silero hybrid, 300 ms pre-roll (stream)
+                │ segment boundaries
+                ▼
+        segment audio only ──▶ Qwen3-ASR (MLX, on-device GPU)
+                │ readings
+                ▼
+        LocalAgreement-2 ──▶ append-only word commits ──▶ CGEvent unicode
+        (commit on 2-reading    (typed text is never        keyboard events
+         agreement)              retracted)
+```
+
+Key decisions (each one earned by a real failure during development):
+
+- **Segment-based ASR, not a rolling window** — re-decoding a growing window
+  revises earlier words (visible flicker) and hallucinates on silence.
+- **Append-only, word-count-based commits** — exact-prefix matching stalls
+  permanently when the ASR reshapes punctuation on committed words.
+- **Normalized agreement + stall safety valve** — punctuation/case flapping
+  between readings must not freeze the stream.
+- **Asymmetric noise-floor learning** — a symmetric EMA lets speech scraps
+  poison the floor and the app goes progressively deaf.
+- **Every loop iteration guarded** — a single ASR exception must not silently
+  kill the pipeline.
+- **Chord-aware hotkey** — ⌥+Q-style character chords never toggle dictation.
+
+## Development
+
+```bash
+uvx --with numpy pytest tests -q   # unit tests; no model/mic needed
+uv run scripts/eval_polish.py      # polish quality benchmark (real local LLM)
+uv build                           # build the wheel/sdist
+```
+
+Package layout: `src/parlando/` (engine, menubar, ASR engine), entry points
+`parlando` and `parlando-menubar`. CI runs the test suite and a packaging
+build on macOS via GitHub Actions.
+
+## Roadmap
+
+- [x] One-line installer (`install.sh`) with `parlando` launcher command
+- [x] Proper Python package (`uv tool install`, entry points) — PyPI
+      publication pending, after which `uvx parlando` will work
+- [ ] Publish to PyPI
+- [ ] Homebrew tap (`brew install parlando`)
+- [ ] End-to-end regression tests with recorded WAV fixtures
+- [ ] Custom vocabulary / context biasing
+
+## License & credits
+
+MIT. The Qwen3-ASR MLX engine (`stt.py`) is from
+[dictate.sh](https://github.com/mpuig/dictate.sh) by Marc Puig (MIT), with
+local modifications (partial streaming, energy gating, error hardening).
+Turn-taking research: [Whisper-Streaming /
+LocalAgreement-2](https://arxiv.org/abs/2307.14743). VAD:
+[Silero VAD](https://github.com/snakers4/silero-vad).