core.ux¶
UX modules: first-run onboarding, accessibility checks, voice state machine, and secrets management.
Onboarding¶
core.ux.onboarding
¶
Onboarding manager for Vector Companion.
Handles first-run detection, guided onboarding steps, and persistence of user choices (capabilities, autonomy tier, privacy preferences).
Onboarding state is stored in .runtime/onboarding.json using atomic
temp-file-plus-rename writes.
OnboardingConfig
dataclass
¶
User's capability and autonomy choices.
Parameters¶
microphone_enabled : bool
Whether the microphone/recording feature is active.
screen_capture_enabled : bool
Whether screenshot capture and captioning is active.
memory_enabled : bool
Whether vector memory (ChromaDB) is active.
cloud_enabled : bool
Whether cloud model usage is allowed.
tools_enabled : bool
Whether tool execution (web search, file I/O, etc.) is active.
autonomy_tier : str
Selected autonomy tier name (e.g. "assistant").
capabilities_count: int
property
¶
Return the number of enabled capabilities.
total_capabilities: int
property
¶
Return the total number of capabilities.
from_dict(data: dict[str, Any]) -> OnboardingConfig
classmethod
¶
Deserialize from a plain dictionary.
to_dict() -> dict[str, Any]
¶
Serialize to a plain dictionary.
OnboardingManager
¶
Manages the onboarding flow and persists state to disk.
State is stored as JSON at the given path (typically
.runtime/onboarding.json). Writes use atomic temp-file-plus-rename.
Parameters¶
state_path : pathlib.Path
File path for persistent onboarding state.
auto_create_dir : bool
If True, the parent directory of state_path is created
on first write.
advance_step(choices: dict[str, Any] | None = None) -> OnboardingState
¶
Advance to the next onboarding step, optionally recording choices.
Returns a new OnboardingState at the next step.
If already at the last step, returns the current state unchanged.
complete(config: OnboardingConfig | None = None, choices: dict[str, Any] | None = None) -> OnboardingState
¶
Finish the onboarding flow and save the final configuration.
Parameters¶
config : Optional[OnboardingConfig]
Final user configuration. Defaults to OnboardingConfig().
choices : Optional[dict]
Additional choices to record before completion.
from_path(state_path: pathlib.Path, *, auto_create_dir: bool = True) -> OnboardingManager
classmethod
¶
Create an OnboardingManager for the given path.
get_config() -> OnboardingConfig | None
¶
Return the saved onboarding config, or None if not completed.
get_current_step() -> OnboardingStep | None
¶
Return the current onboarding step, or None if not started.
get_state() -> OnboardingState | None
¶
Return the current state (loads from disk if needed).
is_first_run() -> bool
¶
Return True if no onboarding file exists on disk.
load() -> OnboardingState | None
¶
Load onboarding state from disk into memory.
reset() -> None
¶
Delete the onboarding file, triggering first-run on next start.
start() -> OnboardingState
¶
Begin a new onboarding session.
Creates an OnboardingState at the WELCOME step and persists
it to disk.
OnboardingState
dataclass
¶
Immutable snapshot of the current onboarding progress.
Parameters¶
id : str
Unique identifier for this onboarding session.
completed : bool
Whether onboarding has been finished.
completed_at : Optional[str]
ISO-8601 timestamp when onboarding completed (None if in progress).
step : OnboardingStep
Current step in the flow.
choices : dict
Accumulated user choices keyed by step name.
config : Optional[OnboardingConfig]
Final configuration (set on completion).
started_at : str
ISO-8601 timestamp when onboarding started.
from_dict(data: dict[str, Any]) -> OnboardingState
classmethod
¶
Deserialize from a plain dictionary.
to_dict() -> dict[str, Any]
¶
Serialize to a plain dictionary.
with_choice(key: str, value: Any) -> OnboardingState
¶
Return a new state with an additional choice recorded.
with_config(config: OnboardingConfig) -> OnboardingState
¶
Return a new state with the final config set.
with_step(step: OnboardingStep) -> OnboardingState
¶
Return a new state advanced to the given step.
OnboardingStep
¶
Bases: Enum
Sequential steps in the onboarding flow.
AUTONOMY_TIER = auto()
class-attribute
instance-attribute
¶
Autonomy level selection: Companion, Assistant, Operator, Automation.
CAPABILITIES = auto()
class-attribute
instance-attribute
¶
Feature tour: microphone, screen, memory, cloud, tools, automation.
COMPLETE = auto()
class-attribute
instance-attribute
¶
Onboarding finished; all choices saved.
PRIVACY_SUMMARY = auto()
class-attribute
instance-attribute
¶
Local-first defaults: what is stored locally, what never leaves the device.
WELCOME = auto()
class-attribute
instance-attribute
¶
Introduction: what Vector Companion is and how it works.
next_step: OnboardingStep | None
property
¶
Return the next step, or None if this is the last one.
Voice State¶
core.ux.voice_state
¶
Voice-first desktop UX state machine.
Defines the conversational lifecycle states for a voice assistant: idle, listening, recording, transcribing, thinking, streaming, playing, interrupted, error, tool approval. Provides a state machine with validated transitions, event publication hooks, and UI rendering helpers.
Components
VoiceState— enum of conversational pipeline statesVoiceEvent— enum of state transition eventsVoiceStateInfo— frozen snapshot of current state for UI renderingVoiceStateMachine— state machine with validated transitionsToolApprovalRequest— dataclass for tool approval UI prompts
ToolApprovalRequest
dataclass
¶
Request for user approval before tool execution.
Parameters¶
tool_name : Name of the tool requesting approval. description : Human-readable description of what the tool will do. arguments : Tool arguments (for display). side_effect_level : Severity of potential side effects (read, write, destructive, network). timeout_seconds : How long to wait for approval before timing out. correlation_id : Request correlation ID for tracing.
VoiceEvent
¶
Bases: Enum
Events that trigger state transitions.
VoiceState
¶
Bases: Enum
Conversational pipeline states for the voice assistant.
VoiceStateInfo
dataclass
¶
Snapshot of current voice state for UI rendering.
Parameters¶
state : Current VoiceState. elapsed_ms : Milliseconds in current state. message : Human-readable status message for UI display. is_active : Whether the assistant is actively processing. can_interrupt : Whether the user can interrupt the current state. progress_hint : Optional progress indicator (0.0-1.0, None if unknown). metadata : Arbitrary additional context for the UI.
VoiceStateMachine
¶
State machine for voice assistant UI flows.
Manages state transitions with validation, timing, and callbacks.
Parameters¶
on_state_change : Optional callback invoked on every state change.
current_state: VoiceState
property
¶
Return the current state.
history: list[VoiceState]
property
¶
Return the state transition history.
current_info(**kwargs: Any) -> VoiceStateInfo
¶
Return a snapshot of the current state without transitioning.
reset() -> None
¶
Reset to IDLE state.
transition(event: VoiceEvent, **kwargs: Any) -> VoiceStateInfo
¶
Accessibility¶
core.ux.accessibility
¶
Accessibility baseline for Vector Companion desktop UI.
Defines the minimum accessibility requirements for all UI screens: keyboard navigation, screen-reader labels, focus order, high contrast, reduced motion, scalable text, captions/transcripts, visible permission states, and non-voice fallback flows.
Components
AccessibilityLevel— enum of WCAG conformance levelsAccessibilitySetting— user preferences for accessibility featuresAccessibilitySpec— specification for screen-level accessibilityAccessibilityChecker— validates UI components against requirementsFocusOrder— defines tab order for keyboard navigationHighContrastTheme— color scheme for high contrast modeReducedMotionPolicy— controls animation behavior
AccessibilityChecker
¶
Validates UI components against accessibility requirements.
Parameters¶
settings : User accessibility preferences. specs : Screen-level accessibility specifications.
check_contrast(foreground: str, background: str) -> bool
¶
Check if foreground/background colors meet minimum contrast ratio.
Returns True if the contrast ratio meets WCAG AA (4.5:1 for normal text).
check_focus_order(spec: AccessibilitySpec, elements: dict[str, Any]) -> list[AccessibilityViolation]
¶
Verify that focus order elements are focusable.
check_screen(spec: AccessibilitySpec, elements: dict[str, Any]) -> list[AccessibilityViolation]
¶
get_violations() -> list[AccessibilityViolation]
¶
Return all violations found so far.
reset() -> None
¶
Clear all violations.
AccessibilityLevel
¶
Bases: Enum
WCAG conformance levels.
AccessibilitySetting
dataclass
¶
User preferences for accessibility features.
Parameters¶
high_contrast : Whether high contrast mode is enabled. reduced_motion : Whether animations are reduced/disabled. font_scale : Font size multiplier (0.8-1.5). screen_reader_mode : Whether screen reader optimizations are enabled. keyboard_only : Whether mouse input is disabled (keyboard only). captions_always_visible : Whether captions/transcripts are always shown. focus_visible : Whether focus indicators are always visible.
AccessibilitySpec
dataclass
¶
Accessibility specification for a UI screen.
Parameters¶
screen_name :
Name of the screen (e.g. "chat_window").
level :
Required WCAG conformance level.
required_labels :
Set of elements that must have accessible labels.
focus_order :
Ordered list of focusable element IDs.
keyboard_shortcuts :
Set of keyboard shortcuts required on this screen.
high_contrast_required :
Whether high contrast mode is required.
captions_required :
Whether captions/transcripts are required.
AccessibilityViolation
dataclass
¶
A detected accessibility violation.
Parameters¶
screen_name :
Screen where the violation was detected.
rule :
Name of the violated rule.
severity :
Severity level (critical, major, minor).
message :
Human-readable description of the violation.
element :
Affected element ID (if applicable).
wcag_criterion :
Relevant WCAG criterion (e.g. "2.1.1").
FocusPolicy
¶
Bases: Enum
How focus is managed in a component.
HighContrastTheme
dataclass
¶
Color scheme for high contrast mode.
Parameters¶
background : Background color (hex). foreground : Text color (hex). accent : Accent color for interactive elements (hex). focus : Focus indicator color (hex). error : Error state color (hex). success : Success state color (hex). warning : Warning state color (hex). disabled : Disabled element color (hex).
KeyboardShortcut
¶
Bases: Enum
Standard keyboard shortcuts for the application.
ReducedMotionPolicy
dataclass
¶
Controls animation behavior for reduced motion.
Parameters¶
enabled : Whether reduced motion is enabled. max_duration_ms : Maximum allowed animation duration in milliseconds. allow_transitions : Whether CSS transitions are allowed. allow_transforms : Whether CSS transforms are allowed. allow_scroll_animation : Whether scroll animations are allowed.
default_chat_spec() -> AccessibilitySpec
¶
Default accessibility spec for the chat window.
default_settings_spec() -> AccessibilitySpec
¶
Default accessibility spec for the settings window.
default_specs() -> list[AccessibilitySpec]
¶
Return all default accessibility specifications.
Secrets Manager¶
core.ux.secrets_manager
¶
Secrets manager for OS credential storage.
Provides a unified interface for storing and retrieving secrets using the operating system's native credential store (Windows Credential Locker, macOS Keychain, Linux Secret Service), with fallback to encrypted file storage.
Components
SecretBackend— enum of backend typesSecretEntry— frozen dataclass for secret metadataSecretsManager— high-level secrets managercreate_secrets_manager()— factory function
Features¶
- OS keyring with index-based listing (keyring API lacks list support)
- Encrypted file backend via cryptography.fernet
- EventBus audit trail (never logs secret values)
- Per-username access history
SecretBackend
¶
Bases: Enum
Secret backend types.
SecretEntry
dataclass
¶
Metadata about a stored secret.
Parameters¶
service :
Service name (e.g. "vector_companion").
username :
Username for the secret.
has_value :
Whether a value is stored (never expose the actual value here).
created_at :
ISO-8601 timestamp of creation.
metadata :
Arbitrary additional context.
SecretsManager
¶
High-level secrets manager.
Wraps OS credential storage with a unified interface. Falls back to encrypted file storage if keyring is not available.
Parameters¶
service_name : Service name for credential store. backend : Secret backend type. event_bus : Optional event bus for audit trail publishing.
access_history() -> dict[str, list[str]]
¶
Return per-username access timestamps.
delete(username: str) -> bool
¶
Delete a secret.
is_available() -> bool
¶
Check if the backend is available.
list_entries() -> list[SecretEntry]
¶
List all stored secret entries.
retrieve(username: str) -> str | None
¶
Retrieve a secret.
store(username: str, value: str) -> None
¶
Store a secret.
create_secrets_manager(*, service_name: str = 'vector_companion', backend: SecretBackend | None = None, event_bus: Any = None) -> SecretsManager
¶
Create a secrets manager with the best available backend.