A Case Study in Multi-Environment AI System Deployment: Integrating a Python Engine into a Web Interface via Pyodide Using an AI to code it all up.

J. Rogers, 13 July 2025, 1736

https://buckrogers1965.github.io/Law-Discovery
https://buckrogers1965.github.io/LawForge

Abstract:
This paper documents the technical challenges and debugging methodologies employed in the deployment of a sophisticated Python-based AI system, the "Physics Disentangler," into a standard web browser environment. The goal was to create a serverless, client-side application using Pyodide to bridge a JavaScript front-end with a Python back-end responsible for complex symbolic mathematics. The process, initially estimated to be straightforward, revealed a series of layered, non-obvious challenges related to asynchronous loading, cross-language data type marshalling, and environment-specific performance bottlenecks. This case study provides a neutral, step-by-step description of the errors encountered and the iterative diagnostic process required to achieve a stable, functional system.

1. Introduction: The Architectural Goal

The objective was to take a pre-existing, functional Python script (law_discovery.py)—an engine capable of performing dimensional analysis using the NumPy and SymPy libraries on the command line—and make it accessible through a standard HTML/CSS/JavaScript web interface. The chosen technology for this task was Pyodide, a port of the CPython interpreter to WebAssembly, which allows for direct execution of Python code and scientific libraries within the browser. The design mandated that the UI logic (main.js) and the core engine (law_discovery.py) remain distinct, communicating through the Pyodide bridge.

2. Initial Deployment and First-Level Failures

The initial deployment consisted of a JavaScript function designed to load the Pyodide environment, install necessary packages, fetch the Python script, and instantiate the main EnhancedPhysicsDisentangler class. This immediately led to two distinct, sequential failures.

• Challenge 1: Missing Dependency (ModuleNotFoundError)

  • Symptom: The application failed to initialize, producing a clear ModuleNotFoundError for numpy in the browser console.

  • Analysis: The initial JavaScript setup call, pyodide.loadPackage("sympy"), did not account for SymPy's own dependency on NumPy. Although the error message was clear, it highlighted the first principle of Pyodide deployment: the developer is responsible for explicitly declaring and loading the full dependency tree for their Python code.

  • Resolution: The call was modified to pyodide.loadPackage(["numpy", "sympy"]).

• Challenge 2: The "Silent Hang" (Synchronous Blocking)

  • Symptom: After fixing the dependency issue, the application would consistently freeze during the initialization phase, with the UI displaying "Loading Physics Disentangler Engine..." indefinitely. No errors were produced in the console.

  • Analysis: This behavior is characteristic of a long-running synchronous task blocking the browser's main event loop. The investigation identified the line pyodide.runPython("engine = EnhancedPhysicsDisentangler()") as the culprit. The __init__ method of the Python class was performing a computationally heavy operation (building a large library of 47 PhysicalQuantity objects), which, while fast in a native environment, was slow enough in the WebAssembly sandbox to freeze the UI.

3. Second-Level Failures: Asynchronous Interface Mismatches

To address the "silent hang," the architecture was refactored. The heavy computation was moved from the Python class's synchronous __init__ method to a new, asynchronous async def initialize() method. The JavaScript was then modified to call this new method. This refactoring introduced a new class of errors stemming from the interface contract between the two languages.

• Challenge 3: Cross-Language async Method Invocation (TypeError: engine.initialize is not a function)

  • Symptom: The application failed with a TypeError, indicating the JavaScript engine proxy object did not possess the initialize method we had just added in Python.

  • Analysis: This revealed a subtle but critical feature of Pyodide's architecture. A Python async method is not automatically exposed to JavaScript as a native Promise-returning function. The direct invocation (engine.initialize()) from JavaScript failed because the bridge did not create a corresponding function on the JavaScript proxy. Initial attempts to fix this in JavaScript by wrapping the call in another runPythonAsync block led to further complexity and IndentationErrors due to how JavaScript template literals handle whitespace.

4. The Diagnostic Turning Point: The "Echo Test"

The escalating complexity and repeated failures necessitated a change in debugging strategy. On the lead developer's direction, the "top-down" approach of modifying the complex system was abandoned in favor of a "bottom-up" validation test.

• Methodology: The core principle was to isolate the problem by simplifying the most complex variable: the Python script itself. A new "echo" script was authored (echo_test.py). This script was designed to have the exact same public interface as the real engine (i.e., a class with a synchronous initialize() and discover_relationship() method) but with trivial internal logic that simply returned its input arguments.

• Initial Failure of the Test: The first implementation of this test also failed, producing TypeError: result.get is not a function. This was a crucial discovery. It proved that a fundamental bug existed in the unchanged main.js file's displayResult function, which was incorrectly trying to access properties of a plain JavaScript object as if it were a Map. This error had been present all along but was masked by the earlier, more catastrophic failures.

• Final Success of the Test: After correcting the main.js file and ensuring the echo script's methods correctly returned values, the echo test succeeded. This provided an infallible baseline: the HTML, CSS, and now-corrected JavaScript were proven to be 100% functional.

5. Final Diagnosis and Resolution

The success of the echo test proved definitively that the Pyodide internal error was not caused by the bridge, the initialization, or the data marshalling, but was located entirely within the complex execution path of the real discover_relationship method.

• Challenge 4: Low-Level Solver Crash (Pyodide internal error: no exception type or value)

  • Symptom: With the real Python engine restored, the application would initialize but crash with a non-recoverable internal error when asked to solve a real problem.

  • Analysis: This type of error indicates a crash in the underlying C/C++ code compiled to WebAssembly, likely within the NumPy or SymPy libraries. The most probable location was the highly-optimized but potentially unstable LUsolve matrix solver.

  • Resolution: The solve_and_diagnose function in Python was modified to replace the specialized A.LUsolve(b) call with the more general-purpose and robust symbolic solver, sp.linsolve((A, b)). This change avoided the low-level execution path that was unstable in the Pyodide environment.

6. Conclusion

The deployment of the Physics Law Discovery webpage, while ultimately successful, served as a powerful case study in the practical challenges of multi-language system integration. The key takeaway is that errors are layered, and a problem's initial symptom (a "silent hang") is often not its root cause. A disciplined, iterative debugging process, particularly the introduction of a minimal, interface-compliant "echo test" as directed by the lead developer, was essential. This strategy allowed us to peel back the layers of the problem—from dependency management, to synchronous blocking, to interface mismatches, to data-type handling in the front-end, and finally to a low-level bug in a scientific library—to achieve a stable and functional deployment.