How jgitsol/universal_solver works
Project Type & Purpose
• Universal Solver is a Python-based, full-stack research and tooling platform for advanced mathematical problem solving.
• It exposes multiple interfaces—CLI, GUI (CustomTkinter), and Jupyter/Colab notebooks—and orchestrates a modular “core engine” (adv_resolver_math + KAN) that plugs into external AI/math services, local symbolic engines, caches, and benchmarking/reporting pipelines.
High-Level File-Structure Analysis
• Top-level interfaces
– benchmark_cli.py, universal_solver_gui.py, collab_training_ntbks/, benchmark_showcase_colab.ipynb
• Core engine modules
– adv_resolver_math/
– KAN/ (symbolic regression via Kolmogorov-Arnold Networks)
• Supporting subsystems
– math_cache/, model/ (state, configs, history), benchmark_datasets.py
– project_guidelines/, docs/, tests/
• Configuration & CI
– pyproject.toml, setup.py, requirements.txt, .github/workflows/ci.yml, pytest.ini
Key README Insights
• Extensible plugin-friendly architecture (solver_registry, memory, symbolic_engine, proofs, ensemble_iterations)
• Multiple external/third-party integrations: LangChain, Ollama, OpenRouter, Google Gemini, SymPy, HuggingFace Datasets, GCP/Azure/Kaggle I/O.
• Benchmarking & reporting outputs: Excel (xlsx), Parquet, cloud uploads.
Diagramming Strategy
a. Main Components
1) Interfaces
• CLI Adapter (benchmark_cli.py + cli.py)
• GUI Adapter (universal_solver_gui.py + CustomTkinter)
• Notebook Adapter (collab_training_ntbks/*, Jupyter)
2) Core Engine
• Solver Registry & Orchestrator (solver_registry.py)
• Ensemble Iterations (ensemble_iterations/*)
• Universal Solver Facade (universal_math_solver.py)
• Symbolic Engine & Proof Assistant (symbolic_engine.py, proof_assistant_interface.py)
• Memory & Cache Manager (memory.py, math_cache/)
3) KAN Module (KAN/SimpleSymbolicRegressionProject.py)
4) Benchmarking & Reporting
• benchmark_datasets.py, benchmark_cli.py, showcase/report notebooks
• Exporters (pandas→Excel/Parquet + cloud clients in api_clients.py)
5) External Services
• AI Model Providers (OpenAI, Gemini, Ollama, OpenRouter)
• Symbolic Library (SymPy)
• Benchmark Data Sources (HuggingFace Datasets)
6) Local Storage
• math_cache/ (JSON caches, exports)
• model/ (state, config, history)
b. Relationships & Data Flow
• User enters a request via CLI/GUI/Notebook → passes to Core Engine facade.
• Engine queries solver_registry → dispatches to one or more solver plugins (ensemble, symbolic, KAN).
• Each solver may:
– Call external AI APIs (through api_clients.py)
– Invoke SymPy or local symbolic routines
– Read/write memory & cache
• Results aggregate in Engine → passed back to Interface → optionally exported via reporting pipeline → stored in model/ or uploaded to cloud.
• Benchmark runner invokes Engine repeatedly over datasets → collects metrics → writes to Excel/Parquet.
c. Architectural Patterns & Principles
• Plugin-based modularity (solver_registry, dynamic discovery of new solvers)
• Facade pattern (universal_math_solver orchestrates complex workflows behind simple interface)
• Pipeline/Chain of Responsibility (ensemble_iterations modules implementing different solver strategies)
• Separation of concerns: adapters (CLI/GUI/Notebook) vs. core logic vs. I/O vs. external services.
d. Technologies & Frameworks
• Python 3.8+, type-checked (mypy), linted (flake8), formatted (black), tested (pytest).
• LangChain, Transformers, PyTorch, SymPy, scikit-learn, sentence-transformers.
• CustomTkinter for GUI, vs Rich for CLI output styling.
• HuggingFace Datasets & Pandas/Parquet for benchmarks.
• Cloud SDKs: Google Cloud, Azure, Kaggle (api_clients.py).