abdullah61305/bruno

Purpose and Entry Points

Bruno is a Windows tray-resident voice companion: push-to-talk or hands-free speech is transcribed locally, sent to an LLM, optionally augmented with screen/browser tools, then spoken as streamed sentences. Runtime entry is bruno/__main__.py, which delegates application composition and CLI behavior to bruno/app.py; the packaged Windows build is produced by scripts/build.py.

Application Composition and Lifecycle

bruno/app.py is the composition root: it selects concrete implementations for protocol-defined stages, initializes UI and persistent services, and coordinates startup/shutdown. bruno/pipeline.py owns the request lifecycle across capture, transcription, model response, tool execution, and speech. Shared lifecycle/state contracts live in bruno/core/protocols.py and bruno/core/state.py. A single-instance guard prevents competing tray processes in bruno/core/single_instance.py.

User Interaction and UI State

Global keyboard capture turns Alt+Space into press-to-record/release-to-send and interruption behavior through bruno/input/hotkey.py and Windows bindings in bruno/input/win32.py. Hands-free mode is coordinated in bruno/hands_free.py, using speech endpointing rather than key release. The tray UI and visual state indicators are implemented by bruno/ui/tray.py, bruno/ui/orb/window.py, and the embedded WebGL orb at bruno/ui/orb/index.html.

Audio and Local Speech Runtime

The microphone remains open and records with pre-roll buffering via bruno/audio/recorder.py; device discovery is in bruno/audio/devices.py. Hands-free end-of-speech detection uses Silero VAD in bruno/audio/endpointing.py. Local STT is encapsulated by bruno/stt/runtime.py and bruno/stt/whisper.py (faster-whisper). Responses are segmented for low time-to-first-word in bruno/tts/chunker.py, synthesized by Piper in bruno/tts/piper.py, and output through bruno/audio/player.py.

LLM Conversation and Provider Failover

Conversation history, prompts, and streaming/tool-call orchestration are centered in bruno/llm/conversation.py, bruno/llm/prompt.py, and bruno/llm/chain.py. bruno/llm/factory.py instantiates configured backends; bruno/llm/providers.py, bruno/llm/groq.py, and bruno/llm/openai_compatible.py support multiple hosted providers and failover when quota or provider failures occur. Text—and screenshots only when requested—crosses this external-service boundary; audio transcription stays local.

Explicit Capabilities: Screen and Browser

LLM tool calls are registered and dispatched through bruno/tools/registry.py. Screen capture is an on-demand tool in bruno/tools/screen.py; browser control of the user’s existing browser is in bruno/tools/browser.py. This isolates privileged desktop actions from the audio/LLM pipeline and makes tools the extension boundary for new actions.

Persistence, Onboarding, and Runtime Infrastructure

First-run setup and provider/key collection are handled by bruno/onboarding.py. Configuration and user profile persist under %LOCALAPPDATA%\Bruno through bruno/core/config.py, bruno/core/profile.py, and bruno/core/paths.py; API credentials are encrypted with the Windows account via bruno/core/credentials.py and bruno/core/secrets.py. Logging—including screen-capture records—uses bruno/core/logging.py. Runtime assets such as Whisper/Piper models are managed by bruno/core/assets.py.