Skip to content

Component: PythonApp (python_core)

Canonical source: SmrtApps/PythonApp/python_core/README.md (mirrored below)

python_core

Overview

  • Location: SmrtApps/PythonApp/python_core
  • Purpose: Orchestrates the Python side of SmrtHub's hybrid runtime, covering configuration, runtime state, networking bridges, SmrtSpace management, ML-powered detection, and workflow enhancers.
  • Entrypoints: python_core/__init__.py (package surface) and python_core/__main__.py (bootstrap executable).

Responsibilities

  • utils: Shared logging, path resolution, heartbeat, HTML generation, file helpers, and shared state window. See python_core/utils/README.md.
  • config: Loads/seeds component settings (bridge, web listener, runtime constants) using canonical SmrtHub paths.
  • runtime: Tracks shared state, save worker, clipboard buffer, and HTML template assets consumed by UI integrations, now supporting text, image, and CF_HDROP document/file fragments so SmrtSave persists artifacts into SmrtSpace and appends SmartSpace Archive records. File fragments always enter the canonical Documents source folder before any filetype grouping to prevent stale source attribution.
  • net: Hosts the Flask bridge and web listener apps; exports Waitress-ready WSGI entrypoints.
  • smrtdetect: File indexing, Magika classification, and duplicate handling for SmrtSpace content.
  • smrtspace_mgt: Workspace validation and configuration bridging between Python, C#, and operational data.
  • flow_enhance: UX automation helpers used by the desktop host.

Services & Threads

python_core/__main__.py spins up the following long-lived services (all using Smrt.Logging plus health markers):

  • Web Listener (start_web_listener) - Waitress-hosted Flask server on port 5000 for browser extension payloads; settings via load_or_seed_web_listener_settings.
  • Flask Bridge (start_flask_bridge) - Waitress-hosted bridge on port 5001 for C# SmrtHub IPC; configurable host/port via load_or_seed_bridge_settings and exposes a shutdown test hook at /__shutdown_bridge__.
  • Save Worker (launch_save_worker -> runtime.save_worker) - Persists captured data, respecting duplicate detection and Operational Data Policy paths.
  • Local Source Pipe Listener (start_mousehook_pipe_listener) - Handles clipboard/file automation events from the Windows hook service.
  • Heartbeat/Health (python_core.utils.heartbeat) - Emits python-core-health.json under the component config tree to signal supervisors.

Threads are launched through start_named_thread, which adds automatic restart with backoff, retry limits, and structured logging. The module publishes the active SESSION_ID in python_core.runtime.shared_state for consumers.

Configuration & Logging

  • Config files resolve through python_core.utils.config_path_resolver, keeping parity with the C# resolver (%AppData%/SmrtHub/Config/<slug> for roaming, %LocalAppData% for local scope).
  • Logging uses python_core.utils.logger, which writes <slug>-log.txt and <slug>-log.json alongside structured correlation metadata. See README.Files/Reference-Guides/SmrtHub.Logging.README.md.
  • Health markers live next to config roots as <slug>-health.json; heartbeat refreshes them every cycle.
  • Supports SMRTHUB_HOME overrides for dev/test path redirection.

Runtime Flow

  1. main() starts without prompting; SmrtSpace selection is checked only when a save is requested.
  2. smrtdetect.file_index.startup_index() primes detection caches.
  3. save_worker_ready event unblocks launch_save_worker before threads fan out.
  4. start_named_thread launches the save worker, web listener, local source pipe, and Flask bridge (all restartable).
  5. The foreground thread blocks indefinitely, emitting console diagnostics until interrupted.
  6. _run_cli_or_start() exposes --version and --smoke-check for lightweight automation without binding ports.

Integrations

  • C# SmrtHub: Communicates over the Flask bridge (127.0.0.1:5001) and shared operational directories.
  • Browser Extensions: Use the web listener for captures and metadata relay.
  • SmrtSpace: Central workspace configuration and bridge injection.
  • Support Bundle & Operational Data: All emitted files follow README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md to ensure exports pick them up.
  • External Services: Magika ML models, clipboard hook executable, local filesystem watchers.

Testing

  • Python unit tests live under python_core/tests; see that README for module coverage and commands.
  • CI smoke checks should invoke _run_cli_or_start --smoke-check to verify dependencies without starting servers.
  • Logging tests (test_logger.py, test_logger_factory.py) expect writable log/config directories resolved by the config path resolver.

Notable Updates

  • 2025-11-08: Added reST metadata to __main__ bootstrap APIs and refreshed package docstrings; no runtime changes.
  • README.Files/Reference-Guides/SmrtHub.Logging.README.md
  • README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md
  • README.Files/Reference-Guides/Smrt.SupportBundle.README.md
  • SmrtApps/PythonApp/python_core/utils/README.md
  • SmrtApps/PythonApp/python_core/smrtdetect/README.md