entune 0.1.0__py3-none-any.whl

entune/__init__.py

@@ -0,0 +1,7 @@
+"""Entune: a personal dictation workbench.
+
+Record a clip, transcribe it with the speech-to-text model you pick, keep the
+history, retry with another model when one fails, copy the result.
+"""
+
+__version__ = "0.1.0"

entune/__main__.py

@@ -0,0 +1,3 @@
+from entune.cli import main
+
+main()

entune/api/common.py

@@ -0,0 +1,34 @@
+"""What the API modules share: error responses and the JSON forms of records."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from starlette.responses import PlainTextResponse, Response
+
+from entune.app.entune import Entune
+from entune.storage.records import Recording
+
+
+def bad(message: str, status: int = 400) -> Response:
+    return PlainTextResponse(message, status_code=status)
+
+
+def recording_json(recording: Recording) -> dict[str, Any]:
+    return asdict(recording)
+
+
+def shortcuts_json(app: Entune) -> dict[str, str | None]:
+    shortcuts = app.settings.shortcuts()
+    return {
+        "hold": "+".join(shortcuts.hold) if shortcuts.hold else None,
+        "toggle": "+".join(shortcuts.toggle) if shortcuts.toggle else None,
+        "cancel": "+".join(shortcuts.cancel) if shortcuts.cancel else None,
+    }
+
+
+def optional_text(value: object, name: str) -> str | None:
+    if value is not None and not isinstance(value, str):
+        raise ValueError(f"{name} must be a string or null")
+    return value

entune/api/data.py

@@ -0,0 +1,125 @@
+"""Local data: what is stored, exports, and deleting everything."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any
+from zipfile import ZipFile
+
+from starlette.background import BackgroundTask
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import FileResponse, JSONResponse, Response
+from starlette.routing import Route
+
+from entune.api.common import bad, recording_json
+from entune.app.entune import Entune
+from entune.app.operations import Busy
+from entune.app.suggestion_runs import JobConflict
+
+RESET_PHRASE = "delete everything"
+
+
+def routes(app: Entune) -> list[Route]:
+    # Deleting all local data: the page lists the scope first, then sends the phrase
+    # the person typed; the server checks it too.
+    def data_inventory(_: Request) -> Response:
+        return JSONResponse(app.data.data_inventory())
+
+    async def reset_data(request: Request) -> Response:
+        try:
+            body = await request.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict) or body.get("confirm") != RESET_PHRASE:
+            return bad(f'Type "{RESET_PHRASE}" to confirm', 400)
+        try:
+            result = await run_in_threadpool(app.data.reset_data)
+        except (JobConflict, Busy) as exc:
+            return bad(str(exc), 409)
+        except ValueError as exc:
+            return bad(str(exc), 409)
+        except OSError as exc:
+            return bad(
+                f"Could not delete everything: {exc}. What was already deleted is gone;"
+                " the rest is still there.",
+                500,
+            )
+        return JSONResponse(result)
+
+    def export_transcripts(_: Request) -> Response:
+        try:
+            with app.data.using_data("export"):
+                recordings = app.store.list_recordings()
+        except Busy as exc:
+            return bad(str(exc), 409)
+        return JSONResponse(
+            {"recordings": [recording_json(r) for r in recordings]},
+            headers={
+                "Content-Disposition": 'attachment; filename="entune-transcripts.json"',
+                "Cache-Control": "no-store",
+                "X-Content-Type-Options": "nosniff",
+            },
+        )
+
+    def export_audio(_: Request) -> Response:
+        # Build on disk, off the event loop: years of audio must not fill memory.
+        # FileResponse streams it; the temporary copy is removed after download.
+        directory = TemporaryDirectory(prefix="entune-export-")
+        path = Path(directory.name) / "entune-audio.zip"
+        try:
+            # A data reset waits until the archive is built; afterwards it has its own copy.
+            with (
+                app.data.using_data("export"),
+                ZipFile(path, "w", strict_timestamps=False) as archive,
+            ):
+                recordings = app.store.list_recordings()
+                imported = app.store.dictionary_audio()
+                manifest: dict[str, list[dict[str, Any]]] = {
+                    "recordings": [],
+                    "dictionary_audio": [],
+                }
+                for recording in recordings:
+                    source = app.store.audio_path(recording)
+                    name = f"audio/{source.name}"
+                    archive.write(source, name)
+                    manifest["recordings"].append(
+                        {
+                            "id": recording.id,
+                            "created_at": recording.created_at,
+                            "file": name,
+                            "mime": recording.mime,
+                        }
+                    )
+                for audio in imported:
+                    source = app.store.dictionary_audio_path(audio)
+                    name = f"dictionary-audio/{source.name}"
+                    archive.write(source, name)
+                    manifest["dictionary_audio"].append({**asdict(audio), "file": name})
+                archive.writestr(
+                    "manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2)
+                )
+        except Exception as exc:
+            directory.cleanup()
+            if isinstance(exc, Busy):
+                return bad(str(exc), 409)
+            if isinstance(exc, OSError):
+                return bad(f"Could not export audio: {exc}", 500)
+            raise
+        return FileResponse(
+            path,
+            media_type="application/zip",
+            filename="entune-audio.zip",
+            headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"},
+            background=BackgroundTask(directory.cleanup),
+        )
+
+    return [
+        Route("/api/exports/audio", export_audio),
+        Route("/api/exports/transcripts", export_transcripts),
+        Route("/api/data", data_inventory),
+        Route("/api/data/reset", reset_data, methods=["POST"]),
+    ]

entune/api/desktop.py

@@ -0,0 +1,65 @@
+"""The menu-bar app: its status, shortcut capture, permission requests, the window."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from entune import __version__
+from entune.api.common import bad, shortcuts_json
+from entune.app.entune import Entune
+
+
+def routes(app: Entune) -> list[Route]:
+    async def start_capture(_: Request) -> Response:
+        if not app.capture.can_capture():
+            return bad("Recording a shortcut needs the menu-bar app; type the keys instead.", 409)
+        return JSONResponse(asdict(app.capture.start_capture()), status_code=202)
+
+    async def capture_status(_: Request) -> Response:
+        return JSONResponse(asdict(app.capture.capture_status()))
+
+    async def cancel_capture(_: Request) -> Response:
+        app.capture.cancel_capture()
+        return JSONResponse({"ok": True})
+
+    def status(_: Request) -> Response:
+        return JSONResponse(
+            {
+                "version": __version__,
+                "shortcuts": shortcuts_json(app),
+                "defaultModel": app.models.default_model(),
+                **app.desktop.desktop_status(),
+            }
+        )
+
+    async def show_window(_: Request) -> Response:
+        if not app.desktop.show_window():
+            return bad("No desktop app is running to show a window", 409)
+        return JSONResponse({"ok": True})
+
+    async def request_permission(request: Request) -> Response:
+        name = request.path_params["name"]
+        if name not in {"microphone", "inputMonitoring", "accessibility"}:
+            return bad("Unknown permission")
+        try:
+            body = await request.json()
+        except ValueError:
+            return bad("Body must be JSON")
+        if not isinstance(body, dict) or not isinstance(body.get("openSettings", False), bool):
+            return bad("openSettings must be a boolean")
+        if not app.desktop.request_permission(name, body.get("openSettings", False)):
+            return bad("Open the Entune desktop app to set up permissions", 409)
+        return JSONResponse({"ok": True}, status_code=202)
+
+    return [
+        Route("/api/capture", start_capture, methods=["POST"]),
+        Route("/api/capture", capture_status, methods=["GET"]),
+        Route("/api/capture", cancel_capture, methods=["DELETE"]),
+        Route("/api/status", status),
+        Route("/api/window", show_window, methods=["POST"]),
+        Route("/api/permissions/{name}", request_permission, methods=["POST"]),
+    ]

entune/api/dictionary.py

@@ -0,0 +1,93 @@
+"""The dictionary: read and save the file, pin meanings, and corrections from other apps."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse, Response
+from starlette.routing import Route
+
+from entune.api.common import bad
+from entune.app.dictionary_file import DictionaryChanged
+from entune.app.entune import Entune
+from entune.app.operations import Busy
+
+
+def routes(app: Entune) -> list[Route]:
+    def _dictionary_response(app: Entune) -> Response:
+        text, version = app.dictionary.dictionary_snapshot()
+        return PlainTextResponse(
+            text,
+            media_type="application/json",
+            headers={"ETag": f'"{version}"'},
+        )
+
+    def get_dictionary(_: Request) -> Response:
+        try:
+            return _dictionary_response(app)
+        except ValueError as exc:
+            return bad(f"dictionary.json on disk is not usable: {exc}", 500)
+
+    async def put_dictionary(request: Request) -> Response:
+        expected = request.headers.get("if-match")
+        try:
+            await run_in_threadpool(
+                app.dictionary.set_dictionary,
+                (await request.body()).decode("utf-8"),
+                expected.strip('"') if expected else None,
+            )
+        except DictionaryChanged as exc:
+            return bad(str(exc), 409)
+        except ValueError as exc:
+            return bad(str(exc), 409 if isinstance(exc, Busy) else 400)
+        return await run_in_threadpool(_dictionary_response, app)
+
+    async def pin_meaning(request: Request) -> Response:
+        try:
+            body = await request.json()
+            version = request.headers.get("if-match")
+            if (
+                not isinstance(body, dict)
+                or set(body) not in ({"model"}, {"model", "group", "meaning"})
+                or not all(isinstance(v, str) and v for v in body.values())
+                or not version
+            ):
+                raise ValueError(
+                    "Pinning needs a model, optional group and meaning IDs, and If-Match"
+                )
+            await run_in_threadpool(
+                app.dictionary.pin_meaning,
+                body["model"],
+                body.get("group"),
+                body.get("meaning"),
+                version.strip('"'),
+            )
+        except DictionaryChanged as exc:
+            return bad(str(exc), 409)
+        except ValueError as exc:
+            return bad(str(exc), 409 if isinstance(exc, Busy) else 400)
+        return await run_in_threadpool(_dictionary_response, app)
+
+    def received_corrections(_: Request) -> Response:
+        return JSONResponse([asdict(c) for c in app.store.list_corrections()])
+
+    async def agent_corrections(request: Request) -> Response:
+        try:
+            body = await request.json()
+        except ValueError:
+            return bad("Body must be JSON")
+        try:
+            added = await run_in_threadpool(app.dictionary.add_agent_corrections, body)
+        except ValueError as exc:
+            return bad(str(exc), 409 if isinstance(exc, Busy) else 400)
+        return JSONResponse({"added": [e.as_json() for e in added]})
+
+    return [
+        Route("/api/dictionary", get_dictionary, methods=["GET"]),
+        Route("/api/dictionary/pin", pin_meaning, methods=["POST"]),
+        Route("/api/dictionary", put_dictionary, methods=["PUT"]),
+        Route("/api/dictionary/corrections", agent_corrections, methods=["POST"]),
+        Route("/api/dictionary/corrections", received_corrections, methods=["GET"]),
+    ]

entune/api/learning.py

@@ -0,0 +1,179 @@
+"""Dictionary suggestions: runs and their proposals, and audio imported to learn from."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict
+
+from starlette.concurrency import run_in_threadpool
+from starlette.datastructures import UploadFile
+from starlette.requests import Request
+from starlette.responses import FileResponse, JSONResponse, Response
+from starlette.routing import Route
+
+from entune.api.common import bad
+from entune.app import audio_import
+from entune.app.dictionary_file import DictionaryChanged
+from entune.app.entune import Entune
+from entune.app.operations import Busy
+from entune.app.suggestion_runs import JobConflict
+from entune.audio.formats import extension_for, safe_mime
+
+
+def routes(app: Entune) -> list[Route]:
+    def build_status(request: Request) -> Response:
+        try:
+            return JSONResponse(
+                app.learning.dictionary_build_status(request.path_params.get("job_id"))
+            )
+        except (JobConflict, Busy) as exc:
+            return bad(str(exc), 409)
+
+    async def start_build(request: Request) -> Response:
+        try:
+            body = await request.json()
+            if (
+                not isinstance(body, dict)
+                or set(body) - {"source", "mode", "scope", "audio_ids"}
+                or body.get("source") not in ("history", "audio")
+            ):
+                raise ValueError("Choose source history or audio")
+            if body.get("mode") not in ("generate", "refine"):
+                raise ValueError("Choose mode generate or refine")
+            ids = body.get("audio_ids")
+            if ids is not None and (
+                not isinstance(ids, list) or not all(isinstance(i, str) for i in ids)
+            ):
+                raise ValueError("audio_ids must list saved recording IDs")
+            state = await run_in_threadpool(
+                app.learning.start_dictionary_build,
+                body["source"],
+                mode=body["mode"],
+                scope=body.get("scope", "new"),
+                audio_ids=ids,
+            )
+        except (JobConflict, Busy) as exc:
+            return bad(str(exc), 409)
+        except ValueError as exc:
+            return bad(str(exc))
+        return JSONResponse(state, status_code=202)
+
+    async def act_on_build(request: Request) -> Response:
+        action = request.path_params.get("action", "discard")
+        methods = {
+            "cancel": app.learning.cancel_dictionary_build,
+            "accept": app.learning.accept_dictionary_build,
+            "discard": app.learning.discard_dictionary_build,
+            "retry": app.learning.retry_dictionary_build,
+        }
+        if action not in methods:
+            return bad("Unknown dictionary job action", 404)
+        try:
+            if action == "accept":
+                body = await request.json() if await request.body() else {}
+                if not isinstance(body, dict) or set(body) - {"selected"}:
+                    raise ValueError("Apply a list of selected proposals")
+                await run_in_threadpool(
+                    app.learning.accept_dictionary_build,
+                    request.path_params["job_id"],
+                    body.get("selected"),
+                )
+            else:
+                await run_in_threadpool(methods[action], request.path_params["job_id"])
+        except (JobConflict, DictionaryChanged, Busy) as exc:
+            return bad(str(exc), 409)
+        except ValueError as exc:
+            return bad(str(exc))
+        return JSONResponse(app.learning.dictionary_build_status())
+
+    def dictionary_audio(_: Request) -> Response:
+        with app.data.using_data("audio listing"):
+            # Which speech models already transcribed each recording, so the page can offer
+            # recordings the selected model has not heard. Imported audio has none.
+            models = {f"recording:{r}": names for r, names in app.store.recording_models().items()}
+            # Sources are chosen separately in the page: this app's recordings, another
+            # dictation app's imports, or files imported from a folder.
+            items = [
+                {
+                    **asdict(item),
+                    "models": models.get(item.id, []),
+                    # Imports made before the source was kept fall back to the Wispr file name.
+                    "source": "entune"
+                    if item.id.startswith("recording:")
+                    else item.source or ("wispr" if item.name.startswith("wispr-") else "folder"),
+                }
+                for item, _ in app.store.learning_audio()
+            ]
+        return JSONResponse(
+            {
+                "apps": [{"id": a.id, "name": a.name, "note": a.note} for a in audio_import.APPS],
+                "count": len(items),
+                "items": items,
+                "seconds": sum(item["seconds"] or 0 for item in items),
+                "unknownDurations": sum(item["seconds"] is None for item in items),
+            }
+        )
+
+    def imported[T](action: Callable[..., T], *args: object) -> T:
+        """An import runs whole or not at all around a data reset."""
+        with app.data.using_data("audio import"):
+            return action(*args)
+
+    async def import_dictionary_audio(request: Request) -> Response:
+        async with request.form() as form:
+            audio = form.get("audio")
+            if not isinstance(audio, UploadFile):
+                return bad("No audio file in request")
+            # The file's modification time, in milliseconds, is the best recording date
+            # a folder offers; without it the import is undated.
+            modified = form.get("modified")
+            try:
+                added = await run_in_threadpool(
+                    imported,
+                    audio_import.import_audio,
+                    app.store,
+                    await audio.read(),
+                    audio.filename or "audio",
+                    audio_import.recorded_at(float(modified))
+                    if isinstance(modified, str)
+                    else None,
+                )
+            except (ValueError, OSError) as exc:
+                return bad(str(exc))
+        return JSONResponse({"added": added})
+
+    async def import_app(request: Request) -> Response:
+        try:
+            result = await run_in_threadpool(
+                imported, audio_import.import_app, app.store, request.path_params["app"]
+            )
+        except (ValueError, OSError) as exc:
+            return bad(str(exc))
+        return JSONResponse(result)
+
+    def imported_audio(request: Request) -> Response:
+        # Resolve only through the saved catalog; the identifier never becomes a path.
+        item = next(
+            (a for a in app.store.dictionary_audio() if a.id == request.path_params["id"]), None
+        )
+        if item is None or not (path := app.store.dictionary_audio_path(item)).is_file():
+            return bad("No such imported audio", 404)
+        return FileResponse(
+            path,
+            media_type=safe_mime(item.mime),
+            filename=f"imported.{extension_for(item.mime)}",
+            content_disposition_type="inline",
+            headers={"X-Content-Type-Options": "nosniff", "Content-Security-Policy": "sandbox"},
+        )
+
+    return [
+        Route("/api/dictionary/build", build_status, methods=["GET"]),
+        Route("/api/dictionary/build", start_build, methods=["POST"]),
+        Route("/api/dictionary/build/{job_id}", build_status, methods=["GET"]),
+        Route("/api/dictionary/build/{job_id}", act_on_build, methods=["DELETE"]),
+        Route("/api/dictionary/build/{job_id}/{action}", act_on_build, methods=["POST"]),
+        Route("/api/dictionary/audio", dictionary_audio, methods=["GET"]),
+        Route("/api/dictionary/audio", import_dictionary_audio, methods=["POST"]),
+        Route("/api/dictionary/audio/apps/{app:str}", import_app, methods=["POST"]),
+        Route("/api/dictionary/audio/{id:str}/file", imported_audio, methods=["GET"]),
+    ]

entune/api/models.py

@@ -0,0 +1,47 @@
+"""Speech models: the model list, local model downloads, and performance."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from entune.api.common import bad
+from entune.app.entune import Entune
+from entune.app.metrics import model_metrics
+
+
+def routes(app: Entune) -> list[Route]:
+    def models(_: Request) -> Response:
+        return JSONResponse([asdict(m) for m in app.models.available_models()])
+
+    def local_models(_: Request) -> Response:
+        return JSONResponse([asdict(m) for m in app.models.local_models()])
+
+    async def download_local_model(request: Request) -> Response:
+        try:
+            await run_in_threadpool(app.models.download_local_model, request.path_params["name"])
+        except ValueError as exc:
+            return bad(str(exc), 404)
+        return JSONResponse({"ok": True})
+
+    async def remove_local_model(request: Request) -> Response:
+        try:
+            await run_in_threadpool(app.models.remove_local_model, request.path_params["name"])
+        except ValueError as exc:
+            return bad(str(exc), 404)
+        return JSONResponse({"ok": True})
+
+    def metrics(_: Request) -> Response:
+        return JSONResponse([asdict(m) for m in model_metrics(app.store, app.providers)])
+
+    return [
+        Route("/api/models", models),
+        Route("/api/metrics", metrics),
+        Route("/api/local/models", local_models),
+        Route("/api/local/models/{name}/download", download_local_model, methods=["POST"]),
+        Route("/api/local/models/{name}", remove_local_model, methods=["DELETE"]),
+    ]