Python Worker Bridge (Local Evaluator)

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/vite.config.ts
• frontend/scanner_worker.py
• frontend/scanner_bridge.py
• frontend/README.md
• frontend/publish_snapshot.py

The Python Worker Bridge facilitates the execution of complex technical and fundamental equity screens that exceed the capabilities of the browser-based snapshot engine. It operates as a persistent background process during local development and preview, translating frontend filter expressions into Python-based evaluations against local historical data.

This system bridges the React-based frontend and the Python-heavy analytical backend. It ensures that custom conditions requiring deep history or complex calculations—such as multi-period moving average stacks or financial growth comparisons—return accurate results by leveraging the same evaluation logic used during the pipeline's static publication phase.

System Architecture

The bridge architecture consists of three primary layers: a Vite-integrated middleware, a persistent Python worker process, and a translation bridge that interfaces with the core scanner logic.

Vite Integration Middleware

The scannerBridge plugin in Vite configures a middleware to intercept POST requests at the /api/screens/run endpoint. It manages the lifecycle of the python3 worker process, spawning it with unbuffered I/O (-u) to ensure immediate communication. The middleware tracks pending requests using a Map of sequence IDs and enforces a 120-second timeout for every request.

Key behaviors of the middleware include:

• Worker Management: It spawns scanner_worker.py and restarts it if the process crashes or if watched Python source files change.
• Request Handling: It consumes the request body (capped at 100,000 characters) and writes it to the worker's stdin.
• Response Mapping: It matches incoming lines from the worker's stdout to pending HTTP responses via sequence IDs.

Sources: frontend/vite.config.ts:18-87

Persistent Python Worker

The scanner_worker.py script acts as a long-running wrapper around the evaluation logic. It listens for JSON-formatted requests on stdin and writes results to stdout. This design prevents the overhead of re-initializing the Python interpreter and reloading data caches for every individual screen request.

Sources: frontend/scanner_worker.py:1-20, frontend/README.md:310-313

Evaluation Logic and Data Flow

The scanner_bridge.py module contains the core translation and evaluation logic. It converts the declarative JSON expressions sent by the frontend into executable Python operations.

Data Model and Mapping

The bridge transforms raw stock data into a standardized stock_row format compatible with the scanner interface. It calculates technical metrics such as SMAs, relative volume (RVOL), and percentage changes if the history is properly aligned with the requested session date.

Component	Description
Expression Translation	Maps frontend operators (e.g., above, crosses_above) to Python evaluation functions.
Numeric History	Loads historical OHLCV data from .scanner_cache/history.npz for fast vectorised lookups.
Context Loading	Aggregates fundamental data, RS ratings, and F&O status from the local pipeline artifacts.

Sources: frontend/scanner_bridge.py:177-248, frontend/publish_snapshot.py:65-117

Sequence of Evaluation

When a request is received, the bridge follows a strict evaluation sequence:

Configuration and Implementation

Supported Expressions

The bridge supports a variety of condition families, including trend comparisons, momentum bursts, and fundamental growth metrics. It handles boolean logic through Match All (AND) and Match Any (OR) groupings.

• Technical Indicators: SMA, EMA, RSI, and Pivot Points.
• Price Action: Gap Up %, returns over periods (1D, 1W, 1M, etc.), and distance from 52-week highs.
• Fundamentals: P/E ratios, TTM revenue growth, and OPM trends.

Sources: frontend/README.md:144-165, frontend/scanner_bridge.py:24-60

Local Development Setup

To enable the Python Worker Bridge locally, you must have the pipeline dependencies installed and a valid data snapshot generated.

1. Environment: Activate the Python virtual environment containing the requirements from DO NOT DELETE EDL PIPELINE/requirements.txt.
2. Data: Run publish_snapshot.py to generate the necessary .scanner_cache and public/data/ files.
3. Vite: Start the development server using npm run dev. Vite will automatically spawn the bridge if VITE_USE_MOCK is not set to true.

Sources: frontend/README.md:73-95, frontend/vite.config.ts:92-98

Summary

The Python Worker Bridge is a critical runtime component for the Nexus Scanner's local evaluation capabilities. By establishing a persistent bidirectional communication channel between Vite and Python, it enables high-performance screening against large historical datasets without the latency of repeated process initialization. It ensures that the local development environment perfectly mirrors the production data transformation and evaluation logic.