fahimtalking 0.1.0__tar.gz

fahimtalking-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+.venv/
+.uv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+models/**/*.onnx
+models/**/*.bin
+models/**/*.pt
+models/**/*.nemo
+models/**/*.tflite
+.env
+config/local.yaml
+recordings/
+cache/

fahimtalking-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: fahimtalking
+Version: 0.1.0
+Summary: Bootstrap installer/launcher for Fahim Talking. Downloads and verifies the real runtime on first run; ships no proprietary code, models, or heavy dependencies.
+Project-URL: Homepage, https://huggingface.co/sallout/fahimtalkingfiles
+Author: Tayseer
+License: Proprietary
+Requires-Python: <3.13,>=3.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fahimtalking
+
+Lightweight bootstrap/launcher for **Fahim Talking**, published by Tayseer.
+
+```
+py -3.12 -m pip install fahimtalking
+```
+
+This package is intentionally tiny: it contains no proprietary source code,
+no models, and no heavy dependencies (no PyTorch, no CUDA libraries). It
+only knows how to:
+
+1. Securely store a Hugging Face read token (`fahimtalking auth`).
+2. On first `fahimtalking run`, download the checksum-verified main and TTS
+   runtime archives from
+   [`sallout/fahimtalkingfiles`](https://huggingface.co/sallout/fahimtalkingfiles)
+   using that token, atomically extract them, download any missing Hugging
+   Face models into the standard user cache, and start the Admin and
+   WebSocket services.
+3. On every later run, reuse the already-verified runtimes and models
+   without downloading anything again.
+
+## Commands
+
+```
+fahimtalking help
+fahimtalking auth      Securely store your Hugging Face read token
+fahimtalking doctor    Check this machine and report runtime status
+fahimtalking ports      Show/change the Admin and WebSocket ports
+fahimtalking run        Install missing runtimes/models, then run
+fahimtalking stop       Stop the running services
+```
+
+## Where things live
+
+All writable application data (downloaded runtimes, the encrypted token,
+config, run-state) lives under:
+
+```
+C:\Users\<user>\AppData\Local\Tayseer\FahimTalking
+```
+
+Nothing is written to this package's own install location (site-packages);
+uninstalling with `pip uninstall fahimtalking` never touches that data
+directory - remove it by hand if you want a fully clean slate.
+
+## Security notes
+
+* The Hugging Face token is only ever stored encrypted at rest via the
+  Windows Data Protection API (DPAPI), scoped to your Windows user account
+  on this machine. It is never written to a config file, log, or the
+  package itself, and never accepted as a command-line argument (so it
+  never lands in shell history).
+* The two runtime archives are downloaded from a *fixed* URL
+  (`https://huggingface.co/sallout/fahimtalkingfiles/resolve/main`) baked
+  into this package at release time, authenticated with your token via an
+  `Authorization: Bearer` header, and verified against a bundled SHA-256
+  manifest before anything is extracted.
+* The proprietary application code inside the downloaded runtimes is
+  compiled (not shipped as plain `.py`) - see this repository's
+  `scripts/protect_source.ps1`. Obfuscation/compilation of *code* is not,
+  and is never treated as, protection for the token above; that's what
+  DPAPI is for.
+
+## For maintainers: building this package
+
+See `../../scripts/build_pypi_wheel.ps1` in this repository and the
+packaging runbook for the full release process (rebuilding the protected
+runtime archives, publishing them to Hugging Face, syncing this package's
+bundled manifest, building the wheel, and testing it in a clean virtual
+environment).

fahimtalking-0.1.0/README.md

@@ -0,0 +1,71 @@
+# fahimtalking
+
+Lightweight bootstrap/launcher for **Fahim Talking**, published by Tayseer.
+
+```
+py -3.12 -m pip install fahimtalking
+```
+
+This package is intentionally tiny: it contains no proprietary source code,
+no models, and no heavy dependencies (no PyTorch, no CUDA libraries). It
+only knows how to:
+
+1. Securely store a Hugging Face read token (`fahimtalking auth`).
+2. On first `fahimtalking run`, download the checksum-verified main and TTS
+   runtime archives from
+   [`sallout/fahimtalkingfiles`](https://huggingface.co/sallout/fahimtalkingfiles)
+   using that token, atomically extract them, download any missing Hugging
+   Face models into the standard user cache, and start the Admin and
+   WebSocket services.
+3. On every later run, reuse the already-verified runtimes and models
+   without downloading anything again.
+
+## Commands
+
+```
+fahimtalking help
+fahimtalking auth      Securely store your Hugging Face read token
+fahimtalking doctor    Check this machine and report runtime status
+fahimtalking ports      Show/change the Admin and WebSocket ports
+fahimtalking run        Install missing runtimes/models, then run
+fahimtalking stop       Stop the running services
+```
+
+## Where things live
+
+All writable application data (downloaded runtimes, the encrypted token,
+config, run-state) lives under:
+
+```
+C:\Users\<user>\AppData\Local\Tayseer\FahimTalking
+```
+
+Nothing is written to this package's own install location (site-packages);
+uninstalling with `pip uninstall fahimtalking` never touches that data
+directory - remove it by hand if you want a fully clean slate.
+
+## Security notes
+
+* The Hugging Face token is only ever stored encrypted at rest via the
+  Windows Data Protection API (DPAPI), scoped to your Windows user account
+  on this machine. It is never written to a config file, log, or the
+  package itself, and never accepted as a command-line argument (so it
+  never lands in shell history).
+* The two runtime archives are downloaded from a *fixed* URL
+  (`https://huggingface.co/sallout/fahimtalkingfiles/resolve/main`) baked
+  into this package at release time, authenticated with your token via an
+  `Authorization: Bearer` header, and verified against a bundled SHA-256
+  manifest before anything is extracted.
+* The proprietary application code inside the downloaded runtimes is
+  compiled (not shipped as plain `.py`) - see this repository's
+  `scripts/protect_source.ps1`. Obfuscation/compilation of *code* is not,
+  and is never treated as, protection for the token above; that's what
+  DPAPI is for.
+
+## For maintainers: building this package
+
+See `../../scripts/build_pypi_wheel.ps1` in this repository and the
+packaging runbook for the full release process (rebuilding the protected
+runtime archives, publishing them to Hugging Face, syncing this package's
+bundled manifest, building the wheel, and testing it in a clean virtual
+environment).

fahimtalking-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "fahimtalking"
+version = "0.1.0"
+description = "Bootstrap installer/launcher for Fahim Talking. Downloads and verifies the real runtime on first run; ships no proprietary code, models, or heavy dependencies."
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = { text = "Proprietary" }
+authors = [{ name = "Tayseer" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://huggingface.co/sallout/fahimtalkingfiles"
+
+[project.scripts]
+fahimtalking = "fahimtalking_bootstrap.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fahimtalking_bootstrap"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/fahimtalking_bootstrap",
+    "README.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fahimtalking-0.1.0/src/fahimtalking_bootstrap/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fahimtalking")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__all__ = ["__version__"]

fahimtalking-0.1.0/src/fahimtalking_bootstrap/__main__.py

@@ -0,0 +1,4 @@
+from fahimtalking_bootstrap.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fahimtalking-0.1.0/src/fahimtalking_bootstrap/assets/config/default.yaml

@@ -0,0 +1,157 @@
+# Default configuration for FahimTalking.
+# Override individual keys via config/local.yaml (gitignored) or environment
+# variables prefixed with FAHIM_ (e.g. FAHIM_AUDIO__SAMPLE_RATE=16000).
+
+resource_limits:
+  cpu_percent_max: 51 # ~10 threads on a 20-thread machine
+  cpu_threads_max: 10
+  ram_mb_max: 7168 # 7 GB hard ceiling
+  ram_mb_static_max: 5120 # 5 GB idle/static budget
+  gpu_percent_max: 60
+  vram_mb_max: 6656 # 6.5 GB
+  disk_mb_max: 51200 # 50 GB
+  gpu_device_index: null # set to 0/1/... to pin to one GPU on a multi-GPU machine
+
+audio:
+  sample_rate: 16000
+  channels: 1
+  frame_ms: 32 # fixed by Silero VAD: 512 samples @16kHz / 256 @8kHz = 32ms either way
+  dtype: int16
+  input_device: null # null = system default input device
+
+bg_speech:
+  # Background speech suppression - runs on every captured frame, before
+  # wake-word/VAD/STT ever see it, to suppress background noise and
+  # competing talkers. DTLN (breizhn/DTLN, MIT-licensed): chosen over
+  # DeepFilterNet3 because it has a real frame-by-frame streaming API
+  # (recurrent state carried explicitly between calls) and runs natively at
+  # 16kHz - no resampling, no isolated worker process, just onnxruntime -
+  # see bg_speech/dtln_model.py's module docstring for the full comparison.
+  enabled: true
+  model_1_path: "models/bg_speech/model_1.onnx"
+  model_2_path: "models/bg_speech/model_2.onnx"
+  model_1_url: "https://raw.githubusercontent.com/breizhn/DTLN/master/pretrained_model/model_1.onnx"
+  model_2_url: "https://raw.githubusercontent.com/breizhn/DTLN/master/pretrained_model/model_2.onnx"
+  auto_download: true # fetch both model_*_path files automatically on first run if missing
+
+wakeword:
+  enabled: true
+  keyword: "hi_moha" # maps to a model file in models/wakeword/
+  model_path: "models/wakeword/hi_moha.onnx"
+  inference_framework: "onnx"
+  detection_threshold: 0.5
+  trigger_cooldown_ms: 1500 # ignore repeat triggers within this window
+
+vad:
+  enabled: true
+  # Silero VAD (neural, ~2MB ONNX model) replaced webrtcvad: real desktop-mic
+  # testing showed webrtcvad reading room/fan noise as speech even at its
+  # most aggressive setting, which stopped silence_timeout_ms from ever
+  # triggering (utterances ran to the 30s hard cap instead of ~1s) and fed
+  # the STT model long noisy clips, which then hallucinated/repeated text.
+  threshold: 0.5 # speech probability above this counts as speech (Silero's own default)
+  model_path: "models/vad/silero_vad.onnx"
+  download_url: "https://raw.githubusercontent.com/snakers4/silero-vad/master/src/silero_vad/data/silero_vad.onnx"
+  auto_download: true # fetch model_path automatically on first run if missing
+  # Pure dead time in every response: the pipeline cannot even start
+  # transcribing until this much silence has elapsed, so it is a direct
+  # floor on time-to-first-audio. Lowered 800 -> 500 as part of latency
+  # tuning. The tradeoff is mid-sentence pauses: a user who stops to think
+  # for longer than this gets their utterance cut in two and transcribed as
+  # a partial question. Raise it back toward 800 if that starts happening.
+  silence_timeout_ms: 500 # ms of continuous silence that ends an utterance
+  min_utterance_ms: 250 # ignore utterances shorter than this (likely noise)
+  max_utterance_ms: 30000 # hard cap to force-finalize very long utterances
+  speech_pad_ms: 150 # padding kept before first detected speech frame
+
+stt:
+  # Phase 1 outcome: Qwen3-ASR-0.6B selected after live Arabic testing (fast,
+  # accurate, no native-Windows friction). NVIDIA Parakeet RNNT Multilingual
+  # was evaluated (see README) and set aside - not pursued further for now.
+  active_engine: "qwen3" # "qwen3" | null (null requires --engine flag)
+  candidates:
+    qwen3:
+      model_id: "Qwen/Qwen3-ASR-0.6B" # confirmed on HuggingFace, Arabic-capable
+      device: "cuda"
+      precision: "bf16" # official examples use bfloat16, not fp16
+
+language:
+  # "ar" | "en" | "both" - shared by the STT engine and KB matching (see
+  # LanguageConfig in config.py). "ar"/"en" lock both to just that language;
+  # "both" restores auto-detection across Arabic and English. Cached answer
+  # audio stays bilingual regardless - see admin: below.
+  mode: "ar"
+
+kb:
+  enabled: true
+  # Customer-owned content. The file is created when the first FAQ is added
+  # in the admin dashboard and is intentionally not included in the SDK.
+  data_path: "data/questions.json"
+  embedding_model: "intfloat/multilingual-e5-small" # bi-encoder, indexed via FAISS
+  reranker_model: "BAAI/bge-reranker-v2-m3" # cross-encoder, multilingual incl. Arabic
+  device: "cpu" # "cpu" | "cuda" - both models are small enough for CPU by default
+  top_k: 3 # FAISS candidates handed to the reranker
+  score_threshold: 0.5 # reranker_score must be >= this to return the matched answer
+  not_found_message: "لم أجد إجابة مناسبة"
+
+tts:
+  # Component 5: text-to-speech, NAMAA-Saudi-TTS (built on Chatterbox
+  # Multilingual) run in an isolated worker process - see tts_worker/ and
+  # fahim_talking/tts/. Isolated because chatterbox-tts needs
+  # transformers==5.2.0 exactly, which conflicts with stt.qwen3's
+  # transformers==4.57.6 exact pin; the two can't share one environment.
+  enabled: true # voice_pipeline.py only ever plays pre-generated cache audio (see admin: below) -
+                # it never loads the TTS worker and has no live-synthesis fallback on a cache miss.
+  model_id: "NAMAA-Space/NAMAA-Saudi-TTS"
+  ref_audio_path: "models/tts/ref_voice.wav" # cleaned via tts_transfer_v2/prepare_ref_audio.py
+  language_id: "ar"
+  # Generation params below are pinned to what the user benchmarked as the
+  # best-sounding Gulf-Arabic result with this reference voice - do not
+  # change without re-testing (see server_namaa.py in tts_transfer_v2/ for
+  # what each one does).
+  cfg_weight: 0.5
+  exaggeration: 0.5
+  temperature: 0.7
+  repetition_penalty: 1.2
+  min_p: 0.05
+  top_p: 1.0
+  worker_dir: "tts_worker" # separate uv sub-project; see its README/pyproject.toml
+  worker_startup_timeout_s: 1800 # first run downloads several GB from HF; cached after that
+  chunk_max_chars: 200 # answer text is split into sentence-sized chunks for low first-audio latency
+  first_chunk_max_chars: 40 # only the first chunk is capped this small, for fast first-audio on long answers; null disables
+  cache_dir: "cache/tts_answers" # pre-generated per-FAQ answer audio (q_{id}_{lang}.wav) - see admin: below
+
+admin:
+  # Component 6 (optional): standalone content-admin webpage for adding FAQ
+  # questions (Arabic + English) and pre-generating their cached answer
+  # audio. Runs as its own process - see scripts/run_admin.py. Do not run
+  # it at the same time as voice_pipeline.py while generating audio: both
+  # spawn the same isolated TTS worker subprocess and would compete for the
+  # GPU/VRAM budget.
+  enabled: true
+  host: "127.0.0.1"
+  port: 8080
+
+api:
+  # Component 7 (optional): client-facing WebSocket voice API - same
+  # wake-word -> STT -> KB -> cached-answer-audio pipeline as
+  # voice_pipeline.py, but behind a WebSocket instead of the local mic/
+  # speakers. Runs as its own process - see scripts/run_api.py. Loads the
+  # STT engine + KB once at startup and keeps them warm/shared across every
+  # connected client. Never loads the TTS worker - only plays cached answer
+  # audio, same rule as voice_pipeline.py (see admin: above).
+  enabled: true
+  host: "127.0.0.1"
+  port: 8090
+
+monitoring:
+  # Per-cycle usage/latency stats voice_pipeline.py writes and the admin
+  # webpage's Usage tab reads - see utils/pipeline_stats.py.
+  stats_path: "cache/pipeline_stats.jsonl"
+  # Detailed questions, answers, ranks, timings, and failures shown in Logs.
+  interaction_log_path: "cache/interaction_logs.jsonl"
+  stats_history_limit: 200
+
+logging:
+  level: "INFO"
+  json_output: false

fahimtalking-0.1.0/src/fahimtalking_bootstrap/assets/runtime-manifest.json

@@ -0,0 +1,24 @@
+{
+    "schema_version":  1,
+    "product":  "Fahim Talking",
+    "product_version":  "0.1.0",
+    "base_url":  "https://huggingface.co/sallout/fahimtalkingfiles/resolve/main",
+    "runtimes":  [
+                     {
+                         "name":  "main",
+                         "version":  "0.1.0",
+                         "archive":  "fahimtalking-main-runtime-0.1.0-win-x64.zip",
+                         "destination":  "runtime-main",
+                         "size_bytes":  3049943466,
+                         "sha256":  "CB71780A1E4EAB0B23AC0ACC9E9C0EE031B3BD369F3BE48EE5F2696A08D8C77B"
+                     },
+                     {
+                         "name":  "tts",
+                         "version":  "0.1.0",
+                         "archive":  "fahimtalking-tts-runtime-0.1.0-win-x64.zip",
+                         "destination":  "runtime-tts",
+                         "size_bytes":  3586532197,
+                         "sha256":  "C2033039144E4BD8049B63D3F3A77D2A569C1FF4FD44D1B415512DCEC5DE59A0"
+                     }
+                 ]
+}

fahimtalking-0.1.0/src/fahimtalking_bootstrap/banner.py

@@ -0,0 +1,9 @@
+BANNER = r"""
+███████╗ █████╗ ██╗  ██╗██╗███╗   ███╗████████╗ █████╗ ██╗██╗  ██╗██╗███╗   ██╗ ██████╗
+██╔════╝██╔══██╗██║  ██║██║████╗ ████║╚══██╔══╝██╔══██╗██║██║ ██╔╝██║████╗  ██║██╔════╝
+█████╗  ███████║███████║██║██╔████╔██║   ██║   ███████║██║█████╔╝ ██║██╔██╗ ██║██║  ███╗
+██╔══╝  ██╔══██║██╔══██║██║██║╚██╔╝██║   ██║   ██╔══██║██║██╔═██╗ ██║██║╚██╗██║██║   ██║
+██║     ██║  ██║██║  ██║██║██║ ╚═╝ ██║   ██║   ██║  ██║██║██║  ██╗██║██║ ╚████║╚██████╔╝
+╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝     ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝  ╚═════╝
+                                By Tayseer Innovations
+"""