og-cz/ivy

Purpose and Entry Points

Ivy is a primarily local Python voice assistant: it accepts spoken interaction, optionally activates on “Hey, Ivy,” interprets commands or conversation, performs local/device/web-backed actions, and returns voice/UI feedback. Launch is documented through run.py; application orchestration likely begins across run.py and main.py. Shared runtime settings are centralized in config.py.

Interaction Runtime

The assistant’s control loop is organized around command intake, feature execution, and response delivery:

• lib/main/command.py is the command interpretation/dispatch extension point.

• lib/main/features.py implements assistant capabilities.

• lib/main/response.py produces user-facing replies.

• lib/main/helper.py supports the main execution path.

The browser-based companion UI is static HTML/CSS/JavaScript, rooted at ui/index.html, with runtime behavior in ui/js/controller.js and ui/js/main.js. It supplies visual state and bundled audio/animations rather than defining the backend.

Speech and Local ML Boundary

Bundled models make key voice features locally deployable:

• model/hot-word-detection/hey-ivy_en_windows_v3_0_0.ppn provides the Windows hotword model.

• machine-learning/faster-whisper-small.en/model.bin and its tokenizer/config files provide a local Faster Whisper speech-recognition model.

• model/model.bin with model/tokenizer.json is another packaged model artifact.

These model directories are an inference-resource boundary: application code consumes their files, while model binaries and vocabularies should be treated as versioned runtime assets.

Command, Conversation, and NLP Routing

Conversational handling is separated from action-oriented commands:

• lib/conversations/router.py selects a conversation path.

• lib/conversations/ivy.py holds assistant-specific dialogue behavior.

• lib/conversations/casual.py, facts.py, fun.py, and history.py provide distinct conversational domains/state.

• lib/math/calculator.py supplies deterministic natural-language/math calculation.

This separation allows input to resolve either to conversational output or command/feature execution, avoiding a cloud LLM dependency.

External Information and Device Integrations

Feature execution crosses into local system services and internet-enabled providers:

• lib/utils/system_info.py collects device status.

• lib/utils/location.py and lib/utils/weather.py support location/weather lookup.

• lib/main/features.py is the likely integration layer for web search, Wikipedia, news, YouTube, application launch, and communication features described by the project.

Internet access is therefore optional but required for dynamic information; offline behavior is supported by local speech/models, conversational logic, math, and system-oriented actions.

Persistence and Personalization

SQLite-backed application data resides in database/ivy.db, accessed through database/db.py. This is the persistence boundary for user preferences/configuration and database-backed command mappings such as websites or applications. config.py likely provides environment- or deployment-specific values used by database and external-service integrations.

Authentication Subsystem

Face authentication is an isolated computer-vision workflow:

• lib/auth/sample.py captures training samples.

• lib/auth/trainer.py builds the recognizer model.

• lib/auth/recognize.py performs recognition at runtime.

• lib/auth/trainer/trainer.yml stores trained recognizer output; lib/auth/haarcascade_frontalface_default.xml provides face detection data.

This subsystem gates or personalizes assistant access without requiring a remote identity service.