Launch PolyTalk Community Edition

Author: bizzappdev

.coveragerc

@@ -0,0 +1,33 @@
+[run]
+source = app
+omit =
+    app/tests/*
+    app/log/*
+    */migrations/*
+    */__pycache__/*
+    */site-packages/*
+branch = True
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise AssertionError
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    @abstractmethod
+
+precision = 2
+show_missing = True
+fail_under = 0
+
+[html]
+directory = htmlcov
+show_contexts = True
+
+[xml]
+output = coverage.xml
+
+[lcov]
+output = lcov.info

.dockerignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.eggs
+*.egg-info
+dist
+build
+
+# Virtual environments
+venv
+env
+.venv
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# Testing
+.pytest_cache
+.ruff_cache
+.coverage
+coverage.xml
+lcov.info
+htmlcov
+.tox
+
+
+# Local configuration and generated data
+.env
+.env.*
+!.env.example
+config/config.yaml
+media
+tts/voices/*
+!tts/voices/.gitkeep
+
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile
+docker-compose*.yml
+.dockerignore
+
+# Documentation
+*.md
+docs
+
+# Development files
+.env.local
+*.local
+
+# Tests (not needed in container)
+tests/

.env.example

@@ -0,0 +1,142 @@
+# PolyTalk Environment Variables
+# Copy this file to .env and update values as needed
+# All ${VAR} references in config/config.yaml will use these values
+
+# ============================================================================
+# APPLICATION LOGGING
+# ============================================================================
+# Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_LEVEL=INFO
+
+# ============================================================================
+# STT SERVICE (Local Speech-to-Text with faster-whisper)
+# ============================================================================
+# STT model to use: small, small-v3, medium, large-v3
+STT_MODEL=small
+
+# Device to run STT: cpu or cuda
+STT_DEVICE=cpu
+
+# Compute type: int8 (CPU) or float16 (CUDA)
+STT_COMPUTE_TYPE=int8
+
+# Number of STT web workers. Each worker loads its own Whisper model.
+STT_WORKERS=1
+
+# Load the Whisper model during STT service startup instead of on first stream.
+STT_PRELOAD_MODEL=true
+
+# Max file upload size in MB
+STT_MAX_UPLOAD_MB=200
+
+# Streaming audio window in seconds. Lower values reduce latency but can reduce
+# transcript stability. 3.0 gives Whisper more context while pause flush handles utterance endings.
+STT_STREAM_CHUNK_SECONDS=3.0
+
+# Audio overlap between STT windows. Helps avoid missing words at chunk boundaries.
+# Keep this modest; too much overlap can increase repeated/hallucinated text.
+STT_CHUNK_OVERLAP_SECONDS=0.25
+
+# Parallel STT queue workers. Increase to 2 when STT inference is slower than
+# incoming audio windows and the GPU has spare compute.
+STT_TRANSCRIBE_WORKERS=2
+STT_TRANSCRIBE_QUEUE_SIZE=8
+STT_MODEL_WORKERS=2
+
+# Transcript emit batching. STT may infer more often than it emits to PolyTalk.
+# Increase these values if live transcript/translation/TTS chunks are too small.
+STT_EMIT_MIN_CHARS=120
+STT_EMIT_INTERVAL_SECONDS=4.5
+# Flush the current speech window after this much trailing silence, even if the
+# normal stream window or emit thresholds have not been reached. Set 0 to disable.
+STT_PAUSE_FLUSH_SECONDS=1.2
+
+# Silence/hallucination guards for streaming STT. These balanced defaults work
+# well for typical microphone input: raise RMS/no-speech strictness if Whisper
+# hallucinates during silence; lower them if quiet speech is missed.
+STT_SILENCE_RMS_THRESHOLD=0.003
+STT_NO_SPEECH_PROB_THRESHOLD=0.50
+STT_LOG_PROB_THRESHOLD=-1.0
+STT_MAX_CROSS_DELTA_WORD_REPEATS=6
+
+# faster-whisper decoding/VAD knobs. Keep previous-text conditioning disabled
+# by default for streaming because it can repeat or invent text during silence.
+STT_VAD_FILTER=true
+STT_VAD_MIN_SILENCE_MS=500
+STT_VAD_SPEECH_PAD_MS=200
+STT_WORD_TIMESTAMPS=true
+STT_CONDITION_ON_PREVIOUS_TEXT=false
+STT_TEMPERATURE=0.0
+# Optional domain/context prompt for Whisper, for example names or product terms.
+# STT_INITIAL_PROMPT=
+
+# ============================================================================
+# WHISPER SERVICE CONFIGURATION (Points to local STT or external)
+# ============================================================================
+# Base URL for Whisper API (defaults to local STT service in Docker)
+# For external service, use: https://whisper.your-domain.com
+WHISPER_BASE_URL=http://stt:8000
+
+# WebSocket endpoint for streaming transcription (used by PolyTalk)
+WHISPER_WS_ENDPOINT=/v1/stream/transcriptions
+
+# Optional: API key for external Whisper API (e.g., OpenAI, custom deployment)
+# Set this if your Whisper service requires authentication
+# WHISPER_API_KEY=your-api-key-here
+
+# ============================================================================
+# TRANSLATION SERVICE (AI Translation)
+# ============================================================================
+# Translation API format: openai_chat, openai_responses, anthropic_messages,
+# or gemini_generate_content.
+TRANSLATION_API_FORMAT=openai_chat
+
+# Base URL and endpoint for Translation API. Use your self-hosted AI server
+# URL here, or an OpenAI-compatible provider URL.
+TRANSLATION_BASE_URL=https://ai.example.com
+TRANSLATION_ENDPOINT=/v1/chat/completions
+
+# API key for Translation service
+TRANSLATION_API_KEY=your_translation_api_key_here
+
+# AI model to use for translation. For self-hosted translation, use models such
+# as qwen3-8b, TranslateGama, or other open-source/open-weight models supported
+# by your model server.
+TRANSLATION_MODEL=qwen3-8b
+
+# Maximum translation output tokens. Keep this bounded for live streaming, but
+# allow enough room for Indic-script targets and longer sentence buffers.
+TRANSLATION_MAX_TOKENS=240
+
+# ============================================================================
+# TTS SERVICE (Local Text-to-Speech with Piper)
+# ============================================================================
+# Piper model to use (voice model name in tts/voices directory)
+TTS_MODEL=en_GB-jenny_dioco-medium
+
+# Base URL for TTS API (local Piper service in Docker)
+# For external service, use: https://tts.your-domain.com
+TTS_BASE_URL=http://tts:5000
+
+# ============================================================================
+# APPLICATION SETTINGS
+# ============================================================================
+# Host to bind the application (0.0.0.0 for all interfaces)
+APP_HOST=0.0.0.0
+
+# Port to run the application
+APP_PORT=9000
+
+# Enable debug mode (set to false for production)
+APP_DEBUG=true
+
+# Comma-separated browser origins allowed to call the app.
+# Use the exact HTTPS origin in production, for example:
+# ALLOWED_ORIGINS=https://polytalk.example.com
+ALLOWED_ORIGINS=http://localhost:9000,http://127.0.0.1:9000
+
+# Translate partial speech after this many buffered characters or seconds.
+# Lower values reduce latency; higher values improve context and quality.
+TRANSLATION_FLUSH_CHARS=300
+TRANSLATION_FLUSH_SECONDS=5.0
+TRANSLATION_FLUSH_MIN_CHARS=120

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report a reproducible PolyTalk problem
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly.
+
+## Environment
+
+- PolyTalk commit/release:
+- Deployment mode: local Python / Docker CPU / Docker GPU / external services
+- Browser and OS:
+- STT provider/model:
+- Translation provider/model:
+- TTS provider/voice:
+
+## Configuration
+
+Paste relevant `.env` and `config/config.yaml` values with secrets removed.
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Logs
+
+Paste relevant logs with secrets and user data removed.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: mailto:security@bizzappdev.com
+    about: Please report vulnerabilities privately.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an improvement for PolyTalk
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem should this solve?
+
+## Proposal
+
+Describe the behavior or interface you want.
+
+## Alternatives
+
+What workarounds or alternatives have you considered?
+
+## Deployment Impact
+
+Does this affect STT, translation, TTS, Docker, frontend, or documentation?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+- 
+
+## Testing
+
+- [ ] `pre-commit run --all-files`
+- [ ] `pytest tests/ -v`
+- [ ] Manual Docker or browser testing, if relevant
+
+## Configuration Impact
+
+Describe any `.env`, `config/config.yaml`, Docker, model, or deployment changes.
+
+## Checklist
+
+- [ ] I did not commit secrets, generated media, downloaded voices, or local config.
+- [ ] Documentation was updated for user-facing or deployment-facing changes.
+- [ ] Logs are appropriate for the configured log level.

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    name: Pre-commit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install pre-commit
+        run: |
+          python -m pip install --upgrade pip
+          pip install pre-commit
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r test-requirements.txt
+
+      - name: Run tests
+        run: pytest tests/ -v