Skip to content

Component: Config

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

python_core.config

Overview & Responsibilities

  • Maintains the Python Core configuration helpers, shipped defaults, and JSON schemas that keep runtime settings aligned with Smrt.Config conventions.
  • SmrtDetect indexer runtime settings live in smrtdetect_indexer_settings.py; per-space save-routing settings remain in smrtspace_config.py.
  • Global search locations used by SmrtDetect are configured separately (not SmrtSpace-scoped).
  • Provides convenience imports (load_or_seed_*) used by other modules to read or seed configuration in canonical SmrtHub locations.
  • Documents how Python Core stays in lockstep with the policies defined in README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md and README.Files/Reference-Guides/SmrtHub.Logging.README.md.
  • Exposes local source exclusion helpers (is_excluded_app, is_excluded_window) for filtering system apps and dev tools from clipboard source tracking.

Dependencies & Integrations

  • Depends on python_core.utils.config_path_resolver for canonical %AppData% path lookups.
  • Optionally validates payloads with jsonschema when the library is available; behavior degrades gracefully if it is not installed.
  • Consumed by runtime components (python_core.runtime, SmrtSpace management flows, and bridge listeners) as well as C# supervisors monitoring configuration files for changes.

Local Source Exclusion Framework

The localsource_exclusions.py module provides a robust exclusion framework that prevents system apps, dev tools, and SmrtHub's own components from appearing as clipboard sources.

Exported Functions

Function Purpose
load_local_exclusions() Load exclusion config from disk (seeding defaults if absent)
is_excluded_app(name) Check if an app name should be excluded (case-insensitive)
is_excluded_window(title) Check if a window title contains blacklisted keywords
clear_exclusion_cache() Force reload of exclusion sets (mainly for testing)

Exclusion Categories

Category Purpose Examples
excluded_app_names App executables to never track as sources PythonApp.exe, chrome.exe, code.exe
blacklisted_window_keywords Window title fragments to skip Developer, Terminal, Visual Studio
excluded_dirs Directory names to skip during file walks node_modules, .git, bin
excluded_extensions File extensions to ignore .tmp, .bak, .pyc

Defense-in-Depth

Exclusions are checked at multiple levels: 1. Early exit — track_local_source() returns immediately for excluded apps/windows 2. Commit guard — _commit_source_and_track() blocks excluded names even if they slip through

This layered approach ensures excluded apps never appear as clipboard sources, even when window titles contain app names (e.g., "PythonApp.exe - Windows Terminal").

Configuration & Log Paths

  • All user-editable configuration lives under %APPDATA%/SmrtHub/Config/<slug>/ in accordance with the Operational Data Policy:
  • %APPDATA%/SmrtHub/Config/smrt-detect/indexer-settings.json
  • %APPDATA%/SmrtHub/Config/smrt-detect/search-locations.json
    • %APPDATA%/SmrtHub/Config/smrt-space/<smrtspace>/smrtspace-config.json
  • %APPDATA%/SmrtHub/Config/smrt-detect/localsource-exclusions.json
  • %APPDATA%/SmrtHub/Config/python-net/bridge-settings.json
  • %APPDATA%/SmrtHub/Config/python-net/web-listener-settings.json
  • JSON defaults are stored in the defaults/ folder and validated against schema/ definitions before being seeded to disk.
  • SmrtSpace selection metadata is user-scoped (per Windows account) under %APPDATA%/SmrtHub/Config/smrt-space/active_smrtspace.json. When no selection exists, SmrtSpace config helpers return defaults in-memory and skip file writes.

Runtime Flows / Operational Workflows

  • On first access, load_or_seed_* helpers seed defaults from defaults/ to the canonical config paths and validate them with the peer schema files. SmrtSpace defaults are only seeded when an active SmrtSpace selection exists.
  • Configuration helpers return merged dictionaries so callers always see a complete contract even when files are partially populated.
  • Bridge and SmrtSpace helpers expose idempotent directory creation to ensure config folders exist before writes.

Search Locations UI Surface (HubWindow-only for now)

Search locations are global settings consumed by the SmrtDetect file indexer:

  • Current authoritative contract: %APPDATA%/SmrtHub/Config/smrt-detect/search-locations.json
  • Current editing posture: file-based (JSON) until a HubWindow-hosted surface is implemented.

Remaining work (tracked for implementation):

  • Add a HubWindow Quick Settings window for Search Locations (no Settings Host UI for this slice).
  • Implement a C# store that reads/writes search-locations.json via Smrt.Config canonical path helpers.
  • Support toggling built-in defaults on/off and adding/removing user directories.
  • Validate and normalize paths (existence checks, de-dupe, stable ordering).
  • Ensure writes are atomic and mutex-guarded (ConfigJson.WithNamedMutex(...)).
  • Add unit tests for the store and basic ViewModel behaviors.

Testing & Validation Expectations

  • Run existing configuration unit tests under tests/python_core when modifying schema or default content.
  • When schema changes occur, validate by running the optional jsonschema validation path locally and verify the seeded files load without warnings.

Support Bundle / Diagnostics Touchpoints

  • Support Bundles include the canonical configuration files referenced above; documentation updates must preserve those paths so bundles remain accurate.
  • No additional logging is emitted by this package beyond what consuming modules perform; rely on Smrt.Logging exports when troubleshooting.