# jgitsol/universal_solver architecture

> Architecture diagram of the GitHub repository jgitsol/universal_solver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jgitsol/universal_solver
- Repository: https://github.com/jgitsol/universal_solver

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interface Layer
    subgraph "Interface Layer"
        style InterfaceLayer fill:none,stroke:none
        CLI["CLI Adapter"]:::frontend
        GUI["GUI Adapter"]:::frontend
        Notebook["Notebook Adapter"]:::frontend
    end

    %% Benchmarking Pipeline
    subgraph "Benchmarking Pipeline"
        style BenchmarkPipeline fill:none,stroke:none
        DatasetLoader["Benchmark Datasets Loader"]:::internal
        ShowcaseNB["Benchmark Showcase Notebook"]:::frontend
        ReportNB["Reporting Showcase Notebook"]:::frontend
    end

    %% Engine Layer
    subgraph "Engine Layer"
        style EngineLayer fill:none,stroke:none
        Facade["Universal Solver Facade"]:::internal
        Registry["Solver Registry & Orchestrator"]:::internal
        Ensemble["Ensemble Iterations"]:::internal
        Symbolic["Symbolic Engine"]:::internal
        ProofAssist["Proof Assistant Interface"]:::internal
        MemoryMgr["Memory & Cache Manager"]:::internal
        APIClients["API Clients"]:::internal
        KANModule["KAN Symbolic Regression Project"]:::internal
    end

    %% Data Layer
    subgraph "Data Layer"
        style DataLayer fill:none,stroke:none
        MathCachePersist["Math Cache Store"]:::storage
        ModelStore["Model Storage"]:::storage
    end

    %% External Services
    subgraph "External Services"
        style ExternalLayer fill:none,stroke:none
        OpenAI["OpenAI / Gemini / Ollama / OpenRouter"]:::external
        SymPyExt["SymPy"]:::external
        HFDatasets["HuggingFace Datasets"]:::external
        CloudClients["Cloud SDKs (GCP/Azure/Kaggle)"]:::external
    end

    %% Connections: Interface to Engine
    CLI -->|"invoke"| Facade
    GUI -->|"invoke"| Facade
    Notebook -->|"invoke"| Facade

    %% Benchmarking to Engine & Data
    DatasetLoader -->|"loads data"| Facade
    Facade -->|"runs benchmarks"| DatasetLoader
    Facade -->|"outputs metrics"| ReportNB
    ShowcaseNB -->|"demonstrate reports"| Facade

    %% Engine internal flows
    Facade -->|"dispatch"| Registry
    Registry -->|"calls"| Ensemble
    Registry -->|"calls"| Symbolic
    Registry -->|"calls"| ProofAssist
    Registry -->|"calls"| KANModule
    Facade -->|"manages memory"| MemoryMgr
    Facade -->|"uses external APIs"| APIClients

    %% External interactions
    APIClients -->|"REST/gRPC"| OpenAI
    Symbolic -->|"function call"| SymPyExt
    DatasetLoader -->|"fetch"| HFDatasets
    APIClients -->|"upload"| CloudClients

    %% Data storage
    MemoryMgr -->|"read/write JSON"| MathCachePersist
    Facade -->|"persist outputs"| ModelStore
    ReportNB -->|"export"| MathCachePersist

    %% Click Events
    click CLI "https://github.com/jgitsol/universal_solver/blob/base_proposal/benchmark_cli.py"
    click GUI "https://github.com/jgitsol/universal_solver/blob/base_proposal/universal_solver_gui.py"
    click Notebook "https://github.com/jgitsol/universal_solver/tree/base_proposal/collab_training_ntbks/"
    click DatasetLoader "https://github.com/jgitsol/universal_solver/blob/base_proposal/benchmark_datasets.py"
    click ShowcaseNB "https://github.com/jgitsol/universal_solver/blob/base_proposal/benchmark_showcase_colab.ipynb"
    click ReportNB "https://github.com/jgitsol/universal_solver/blob/base_proposal/showcase_benchmark_report.ipynb"
    click Facade "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/universal_math_solver.py"
    click Registry "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/solver_registry.py"
    click Ensemble "https://github.com/jgitsol/universal_solver/tree/base_proposal/adv_resolver_math/ensemble_iterations/"
    click Symbolic "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/symbolic_engine.py"
    click ProofAssist "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/proof_assistant_interface.py"
    click MemoryMgr "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/memory.py"
    click APIClients "https://github.com/jgitsol/universal_solver/blob/base_proposal/adv_resolver_math/api_clients.py"
    click KANModule "https://github.com/jgitsol/universal_solver/blob/base_proposal/KAN/SimpleSymbolicRegressionProject.py"
    click MathCachePersist "https://github.com/jgitsol/universal_solver/tree/base_proposal/math_cache/"
    click ModelStore "https://github.com/jgitsol/universal_solver/tree/base_proposal/model/"

    %% Styles
    classDef frontend fill:#e0f7da,stroke:#2e7d32,color:#2e7d32
    classDef internal fill:#e3f2fd,stroke:#1565c0,color:#1565c0
    classDef storage fill:#fff9c4,stroke:#f9a825,color:#f57f17
    classDef external fill:#ffe0b2,stroke:#ef6c00,color:#e65100
```
