Skip to content

Detection & Flow Enhancements

Machine vision, source tracking, and flow helpers that bridge clipboard, local, and web captures.

python_core.smrtdetect

Detection helpers that expose filename, filetype detection, and source tracking APIs.

Importing this package re-exports the common entry points and wires component loggers. Detailed flows live in README.md.

clean_filename 

clean_filename(filename: str) -> str

Strip disallowed characters and normalize dot/space usage.

:param filename: Raw filename candidate that may contain invalid characters. :returns: Sanitized filename safe for filesystem usage.

detect_extension 

detect_extension(text: str) -> str

Detect the appropriate file extension for text content.

Convenience wrapper that returns just the extension string.

:param text: Raw text content to analyze. :returns: File extension including the leading dot (e.g., ".py").

Example

detect_extension('{"key": "value"}') '.json'

detect_extension_from_bytes 

detect_extension_from_bytes(
    data: bytes, encoding: str = "utf-8"
) -> str

Detect the appropriate file extension for binary content.

Attempts to decode the bytes as text using the specified encoding, then delegates to the standard text detection pipeline. For content that cannot be decoded (true binary files), returns a generic binary extension.

:param data: Raw bytes to analyze. :param encoding: Text encoding to attempt (default: utf-8). :returns: File extension including the leading dot (e.g., ".py", ".bin").

Example

detect_extension_from_bytes(b'{"key": "value"}') '.json' detect_extension_from_bytes(b'\x89PNG\r\n') '.bin'

detect_filename_and_strip 

detect_filename_and_strip(
    content: str,
) -> Tuple[Optional[str], str]

Extract a leading filename token from the content when present.

:param content: Clipboard payload to inspect for an embedded filename. :returns: Tuple of (detected_filename, remaining_content) with None when no filename is found.

get_fallback_filename 

get_fallback_filename(
    content: str, extension: str = ".txt"
) -> str

Build a readable filename from the first few suitable words or use untitled.

:param content: Clipboard text used to derive candidate words. :param extension: Preferred extension (with or without leading dot). :returns: Generated filename string suitable for saving downstream.

handle_tab_info 

handle_tab_info(payload: Dict[str, Any]) -> bool

Upsert web source data from SmrtChrome payloads with sane fallbacks.

:param payload: Browser tab metadata emitted by the SmrtChrome extension. :returns: True when shared state updates succeed, otherwise False.

resolve_adobe_malformed 

resolve_adobe_malformed(title: str) -> Optional[str]

Extract a cleaned filename from an Adobe window title.

:param title: Raw window title captured from the foreground Adobe application. :returns: Sanitized filename when heuristics succeed, otherwise None.

track_local_source 

track_local_source(start_hwnd: int) -> None

Resolve the active document backing the foreground window.

:param start_hwnd: Window handle captured at trigger time. :returns: None.

python_core.smrtdetect.localsource

Local source tracker orchestrating Explorer → Recent → Index → Walk resolution.

Deep dives live beside this module in README.md to avoid duplicating policy.

fallback_os_walk 

fallback_os_walk(
    filename: str, search_dirs: List[str], start_hwnd: int
) -> Optional[str]

Traverse directories with cancellation, junk pruning, and index warming.

get_foreground_hwnd 

get_foreground_hwnd() -> int

Return the handle for the current foreground window.

:returns: Window handle integer provided by Win32 APIs.

scan_explorer_for_exact_filename 

scan_explorer_for_exact_filename(
    filename: str, start_hwnd: int
) -> Optional[str]

Resolve exact variants inside Explorer windows and warm the index.

scan_recent_for_exact_filename 

scan_recent_for_exact_filename(
    filename: str, start_hwnd: int
) -> Optional[str]

Resolve exact variants in recent folders while keeping tracker state fresh.

start_mousehook_pipe_listener 

start_mousehook_pipe_listener()

Launch the mouse-hook listener once; later calls are no-ops.

:returns: None.

track_local_source 

track_local_source(start_hwnd: int) -> None

Resolve the active document backing the foreground window.

:param start_hwnd: Window handle captured at trigger time. :returns: None.

python_core.smrtdetect.websource

Normalize SmrtChrome tab metadata into shared-state web source entries.

Long-form notes: README.md.

get_web_source_stats 

get_web_source_stats() -> Dict[str, Any]

Return static metadata summarizing web source capabilities.

:returns: Dictionary describing supported browsers, fields, and features.

handle_tab_info 

handle_tab_info(payload: Dict[str, Any]) -> bool

Upsert web source data from SmrtChrome payloads with sane fallbacks.

:param payload: Browser tab metadata emitted by the SmrtChrome extension. :returns: True when shared state updates succeed, otherwise False.

validate_tab_payload 

validate_tab_payload(payload: Dict[str, Any]) -> bool

Basic payload sanity check to guard against malformed requests.

:param payload: Browser metadata payload supplied by the extension. :returns: True when the payload meets basic sanity checks.

python_core.smrtdetect.recent_folder_tracker

Persist frequently used directories so smrtdetect can bias searches smartly.

See README.md for schema and retention guidance.

add 

add(directory_path: Path) -> None

Record directory_path at the front of the LRU list when valid.

:param directory_path: Directory path to add to the recent list. :returns: None.

clear 

clear() -> None

Wipe the cache and delete the persisted JSON if present.

:returns: None.

force_reload 

force_reload() -> None

Reload the cache from disk, discarding in-memory state first.

:returns: None.

get_cache_stats 

get_cache_stats() -> dict

Expose cache metrics and storage metadata for diagnostics.

:returns: Dictionary describing cache size, storage path, and contents.

get_recent 

get_recent() -> List[str]

Return validated recent directories ordered most-recent first.

:returns: List of normalized directory paths with the most recent first.

python_core.flow_enhance.smrtsearch

SmrtSearch helpers for clipboard-driven navigation.

Functions here wrap hotkey registration, clipboard reads, and metadata used by the clipboard-driven navigation flow. Behavioral notes live in README.md.

get_clipboard_text 

get_clipboard_text(simulate_copy: bool = True) -> str

Return the current clipboard text, optionally copying the selection first.

:param simulate_copy: When True the routine issues Ctrl+C before reading the clipboard so the caller's active selection is captured. :returns: Trimmed Unicode text or "" if the clipboard held no text.

get_module_info 

get_module_info() -> dict[str, Any]

Return metadata describing the SmrtSearch enhancement subsystem.

:returns: Mapping consumed by diagnostics and Support Bundle exporters.

on_smrtsearch_trigger 

on_smrtsearch_trigger() -> None

Launch the default browser using the current clipboard contents.

The handler mirrors the SmrtSearch hotkey workflow: URLs are opened directly while everything else is URL-encoded into a Google search query.

:returns: None. Side effects are limited to browser launches and log output.

start_listener 

start_listener() -> None

Register the SmrtSearch global hotkey defined in :data:DEFAULT_HOTKEY.

:returns: None. Registration success or failure is communicated through structured logs and lightweight console prompts.

stop_listener 

stop_listener() -> None

Undo :func:start_listener by removing the global hotkey binding.

:returns: None. Errors during removal are emitted through the module logger.