JuliaLabs · emmanuellujan · Dec 5, 2025 · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -24,13 +24,13 @@ jobs:
       matrix:
         version:
           - '1.12'
-          - 'pre'
+          #- 'pre'
         os:
           - ubuntu-latest
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
@@ -39,7 +39,7 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           files: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -52,7 +52,7 @@ jobs:
       contents: write
       statuses: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'

diff --git a/.gitignore b/.gitignore
@@ -1 +1,3 @@
 .DS_Store
+Manifest.toml
+docs/build/
diff --git a/Project.toml b/Project.toml
@@ -22,9 +22,18 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
+BenchmarkTools = "1"
+CSV = "0.10"
+BSON = "0.3"
 CUDA = "5.9.2"
+CairoMakie = "0.15"
+DecisionTree = "0.12"
+DataFrames = "1"
 LinearAlgebra = "1.12.0"
+MKL = "0.9"
 MatrixDepot = "1.0.13"
 OpenAI = "0.12.0"
+OrderedCollections = "1"
+ScikitLearn = "0.7"
 Test = "1.11.0"
 julia = "1.11"
diff --git a/README.md b/README.md
@@ -1,56 +1,14 @@
-
 <img src="smartsolve.png" alt="SmartSolve.jl">
 
-
 SmartSolve.jl is a Julia-based toolbox for AI-guided algorithmic discovery, designed to accelerate computations by generating enhanced algorithmic and architectural selection strategies. Envisioned as a general-purpose tool for scientific computing, current efforts focus on challenges in computational linear algebra. The toolbox addresses the growing complexity of selecting efficient solvers, data formats, precision strategies, and hardware resources for structurally diverse matrices—where conventional approaches offer substantial opportunities for improvement. SmartSolve.jl constructs a performance database through systematic benchmarking and applies automated Pareto analysis to identify optimal trade-offs between accuracy and speed. This database underpins a data-driven model that synthesizes dispatch strategies tailored to high-performance linear algebra software.
 
-## How to start
-
-In the following example SmartSolve is used to automatically generate SmartLU, an optimized version of the LU decomposition.
-
-```bash
-cd SmartSolve/examples/smartlu
-julia --project=.
-```
-
-```julia
-pkg> dev ../..
-pkg> instantiate
-julia> include("generate_smartlu.jl")
-```
-
-## Publications
-
-- Emmanuel Lujan and Alan Edelman. "When Structure is Silent: Opportunities for Algorithmic Dispatch in Linear Algebra," 2025 IEEE High Performance Extreme Computing Conference (HPEC). Submitted.
-- Rushil Shah, Emmanuel Lujan, and Rabab Alomairy, and Alan Edelman. "Data-Driven Dynamic Algorithm Dispatch with Large Language Models," 2025 IEEE High Performance Extreme Computing Conference (HPEC). Submitted.
-- Emmanuel Lujan, Rushil Shah, Rabab Alomairy, and Alan Edelman. "SmartSolve.jl: AI for Algorithmic Discovery," 0.1.0-alpha. Zenodo [(link)](https://doi.org/10.5281/zenodo.15784217).
-- Rabab Alomairy, Felipe Tome, Julian Samaroo, Alan Edelman. _"Dynamic Task Scheduling with Data Dependency Awareness Using Julia"_, 2024 IEEE High Performance Extreme Computing Conference (HPEC) [(link)](https://ieeexplore.ieee.org/document/10938467).
-
-## Talks
-
-- Rushil Shah, Emmanuel Lujan, and Rabab Alomairy. _"Automated Algorithm Selection Discovery via LLMs,"_ JuliaCon 2025, Lightning Talk. [(Link)](https://pretalx.com/juliacon-2025/talk/review/FXWAYZEZ9XEPYPHL3JJNAS7NBACU3GXE). 
-- Alan Edelman et al. _"Julia, Portable Numerical Linear Algebra and Beyond."_ Presentation at Householder Symposium, 2025. [(Link)](https://householder-symposium.github.io/presenters.html). Accessed June 20, 2025.
-- Alan Edelman, _"Improving the HPC Experience: Did Julia Get It Right, or Will AI Hide the Problem (or Both)?"_ Keynote at the Workshop on Asynchronous Many-Task Systems and Applications (WAMTA), 2025. [(Link)](https://wamta25.github.io/keynote). Accessed June 20, 2025.
-
-## How to Cite
-
-```bibtex
-@software{SmartSolve2025,
-  author       = {Lujan, Emmanuel and Shah, Rushil N. and Alomairy, Rabab and Edelman, Alan},
-  title        = {SmartSolve.jl: AI for Algorithmic Discovery},
-  month        = jul,
-  year         = 2025,
-  publisher    = {Zenodo},
-  version      = {0.1.0-alpha},
-  doi          = {10.5281/zenodo.15784217},
-  url          = {https://doi.org/10.5281/zenodo.15784217},
-}
-```
-
-## Acknowledgements
-
-We thank [DARPA](https://www.darpa.mil/research/programs/mathematics-for-the-discovery-of-algorithms-and-architectures) for supporting this work at MIT.
-
-
-
-
+<a href="https://julia.mit.edu/SmartSolve.jl/dev/">
+<img alt="Development documentation" src="https://img.shields.io/badge/documentation-in%20development-orange?style=flat-square">
+</a>
+<a href="https://mit-license.org">
+<img alt="MIT license" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square">
+</a>
+<a href="https://github.com/JuliaLabs/SmartSolve.jl/issues/new">
+<img alt="Ask us anything" src="https://img.shields.io/badge/Ask%20us-anything-1abc9c.svg?style=flat-square">
+</a>
+</a>
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 SmartSolve = "4fbb3a3c-2fa1-4c19-8d57-bae8bc1e16ac"
diff --git a/docs/citation.bib b/docs/citation.bib
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,23 +1,78 @@
 using SmartSolve
 using Documenter
+using DocumenterCitations
+using Literate
 
-DocMeta.setdocmeta!(SmartSolve, :DocTestSetup, :(using SmartSolve); recursive=true)
-
-makedocs(;
-    modules=[SmartSolve],
-    authors="JuliaLabs",
-    sitename="SmartSolve.jl",
-    format=Documenter.HTML(;
-        canonical="https://JuliaLabs.github.io/SmartSolve.jl",
-        edit_link="main",
-        assets=String[],
-    ),
-    pages=[
-        "Home" => "index.md",
-    ],
+DocMeta.setdocmeta!(
+    SmartSolve,
+    :DocTestSetup,
+    :(using SmartSolve);
+    recursive = true,
+)
+
+ENV["BASE_PATH"] = joinpath(@__DIR__, "../") 
+
+# Citations ####################################################################
+bib = CitationBibliography(joinpath(@__DIR__, "citation.bib"))
+
+
+# Generate examples ############################################################
+const examples_path = joinpath(@__DIR__, "..", "examples")
+const output_path   = joinpath(@__DIR__, "src/generated")
+function create_examples(examples, examples_path, output_path)
+    for (_, example_path) in examples
+        s = split(example_path, "/")
+        sub_path, file_name = string(s[1:end-1]...), s[end]
+        example_filepath = joinpath(examples_path, example_path)
+        Literate.markdown(example_filepath,
+                          joinpath(output_path, sub_path),
+                          documenter = true)
+    end
+    examples = [title => joinpath("generated", replace(example_path, ".jl" => ".md"))
+                for (title, example_path) in examples]
+    return examples
+end
+
+# Basic examples
+examples = [
+#    "Simple example" => "simple-example/simple-example.jl",
+]
+basic_examples = create_examples(examples, examples_path, output_path)
+
+# Make and deploy docs #########################################################
+
+makedocs(
+      root    =  joinpath(dirname(pathof(SmartSolve)), "..", "docs"),
+      source  = "src",
+      build   = "build",
+      clean   = true,
+      doctest = true,
+      modules = [SmartSolve],
+      repo    = "https://github.com/JuliaLabs/SmartSolve.jl/blob/{commit}{path}#{line}",
+      highlightsig = true,
+      sitename = "SmartSolve.jl",
+      expandfirst = [],
+      draft = false,
+      pages = ["Home" => "index.md",
+               "Install" => "install.md",
+               #"Examples" => basic_examples,
+               "Simple examples" => ["Generate linear solver" => 
+                                     "gen_lin_solver.md",
+                                     "Benchmark & generate linear solver" => 
+                                     "benchmark_and_gen_lin_solver.md"],
+               "Awards, Publications & Talks" => "publications.md",
+               "API" => "api.md"],
+      format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://github.com/JuliaLabs/SmartSolve.jl",
+        assets = String[],
+      ),
+      plugins=[bib]
 )
 
 deploydocs(;
-    repo="github.com/JuliaLabs/SmartSolve.jl",
-    devbranch="main",
+    repo = "https://github.com/JuliaLabs/SmartSolve.jl",
+    devbranch = "main",
+    push_preview = true,
 )
+
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -0,0 +1,9 @@
+# API Reference
+
+This page provides a list of all documented types and functions and in SmartSolve.jl.
+
+
+```@autodocs
+Modules = [SmartSolve]
+Order   = [:type, :function, :constant]
+```
diff --git a/docs/src/assets/smartsolve-2.png b/docs/src/assets/smartsolve-2.png
diff --git a/docs/src/assets/smartsolve.png b/docs/src/assets/smartsolve.png
diff --git a/docs/src/benchmark_and_gen_lin_solver.md b/docs/src/benchmark_and_gen_lin_solver.md
@@ -0,0 +1,39 @@
+# Benchmark and generate linear solver
+
+Automatically generate an optimized LU decomposition by selecting a specialized solver tailored to the input matrix structure.
+
+Define candidate algorithms
+```julia
+dgetrf(A::Matrix) = lu(A)
+dgetrf(A::SparseMatrixCSC) = lu(Matrix(A))
+dgetrf(A::SparseMatrixCSC{Bool, Int64}) = lu(Matrix(A))
+dgetrf(A::Symmetric) = lu(A.data)
+bandedlu(A::Matrix) = BandedMatrices.lu(BandedMatrix(sparse(A)))
+bandedlu(A::SparseMatrixCSC{Float64, Int64}) = BandedMatrices.lu(BandedMatrix(A))
+bandedlu(A::SparseMatrixCSC{Int64, Int64}) = BandedMatrices.lu(BandedMatrix(Float64.(A)))
+bandedlu(A::SparseMatrixCSC{Bool, Int64}) = BandedMatrices.lu(BandedMatrix(Float64.(A)))
+bandedlu(A::Symmetric) = BandedMatrices.lu(Float64.(BandedMatrix(sparse(A.data))))
+algs = [dgetrf, bandedlu]
+```
+
+Define your custom matrices to be included in training
+```julia
+n = 2^12;
+A = ...
+B = ...
+mats = [A, B]
+```
+
+Generate a smart version of the algorithm
+```julia
+alg_name  = "lu"
+alg_path = "smartlu/"
+smartsolve(alg_path, alg_name, algs; n_experiments = 1,
+           mats = mats, ns = [2^8.2^10,2^12], features = [:isbandedpattern])
+```
+
+Include and run the newly generated algorithm
+```julia
+include("$alg_path/smart$alg_name.jl")
+smartlu(A)\b
+```
diff --git a/docs/src/gen_lin_solver.md b/docs/src/gen_lin_solver.md
@@ -0,0 +1,15 @@
+# Generate LU with iterative refinement
+```julia
+using SmartSolve
+
+prompt = """
+Generate a high performance Julia implementation of LU
+with iterative refinement using the following reference:
+https://nhigham.com/2023/03/13/what-is-iterative-refinement
+"""
+
+secret_key = ENV["OPENAI_API_KEY"]
+
+code, hist, conv = generate(prompt, secret_key)
+
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -2,13 +2,28 @@
 CurrentModule = SmartSolve
 ```
 
-# SmartSolve
+![SmartSolve logo](assets/smartsolve.png)
 
-Documentation for [SmartSolve](https://github.com/JuliaLabs/SmartSolve.jl).
+SmartSolve.jl is a Julia-based toolbox for AI-guided algorithmic discovery, designed to accelerate computations by generating enhanced algorithmic and architectural selection strategies. Envisioned as a general-purpose tool for scientific computing, current efforts focus on challenges in computational linear algebra. The toolbox addresses the growing complexity of selecting efficient solvers, data formats, precision strategies, and hardware resources for structurally diverse matrices—where conventional approaches offer substantial opportunities for improvement. SmartSolve.jl constructs a performance database through systematic benchmarking and applies automated Pareto analysis to identify optimal trade-offs between accuracy and speed. This database underpins a data-driven model that synthesizes dispatch strategies tailored to high-performance linear algebra software.
 
-```@index
-```
+  
+## How to Cite
 
-```@autodocs
-Modules = [SmartSolve]
+```bibtex
+@software{SmartSolve2025,
+  author       = {Lujan, Emmanuel and Shah, Rushil N. and Alomairy, Rabab and Edelman, Alan},
+  title        = {SmartSolve.jl: AI for Algorithmic Discovery},
+  month        = jul,
+  year         = 2025,
+  publisher    = {Zenodo},
+  version      = {0.1.0-alpha},
+  doi          = {10.5281/zenodo.15784217},
+  url          = {https://doi.org/10.5281/zenodo.15784217},
+}
 ```
+
+## Acknowledgements
+
+We thank [DARPA](https://www.darpa.mil/research/programs/mathematics-for-the-discovery-of-algorithms-and-architectures) for supporting this work at MIT.
+
+
diff --git a/docs/src/install.md b/docs/src/install.md
@@ -0,0 +1,5 @@
+# Install 
+```julia
+~$ julia
+pkg> add https://github.com/JuliaLabs/SmartSolve.jl
+```
diff --git a/docs/src/publications.md b/docs/src/publications.md
@@ -0,0 +1,13 @@
+## Awards
+- Outstanding Short Paper Award. Rushil Shah, Emmanuel Lujan, and Rabab Alomairy, and Alan Edelman. "Data-Driven Dynamic Algorithm Dispatch with Large Language Models," 2025 IEEE High Performance Extreme Computing Conference (HPEC).
+
+## Publications
+- Emmanuel Lujan and Alan Edelman. "When Structure is Silent: Opportunities for Algorithmic Dispatch in Linear Algebra," 2025 IEEE High Performance Extreme Computing Conference (HPEC).
+- Outstanding Short Paper Award. Rushil Shah, Emmanuel Lujan, and Rabab Alomairy, and Alan Edelman. "Data-Driven Dynamic Algorithm Dispatch with Large Language Models," 2025 IEEE High Performance Extreme Computing Conference (HPEC).
+- Emmanuel Lujan, Rushil Shah, Rabab Alomairy, and Alan Edelman. "SmartSolve.jl: AI for Algorithmic Discovery," 0.1.0-alpha. Zenodo [(link)](https://doi.org/10.5281/zenodo.15784217).
+- Rabab Alomairy, Felipe Tome, Julian Samaroo, Alan Edelman. _"Dynamic Task Scheduling with Data Dependency Awareness Using Julia"_, 2024 IEEE High Performance Extreme Computing Conference (HPEC) [(link)](https://ieeexplore.ieee.org/document/10938467).
+
+## Talks
+- Rushil Shah, Emmanuel Lujan, and Rabab Alomairy. _"Automated Algorithm Selection Discovery via LLMs,"_ JuliaCon 2025, Lightning Talk. [(Link)](https://pretalx.com/juliacon-2025/talk/review/FXWAYZEZ9XEPYPHL3JJNAS7NBACU3GXE). 
+- Alan Edelman et al. _"Julia, Portable Numerical Linear Algebra and Beyond."_ Presentation at Householder Symposium, 2025. [(Link)](https://householder-symposium.github.io/presenters.html). Accessed June 20, 2025.
+- Alan Edelman, _"Improving the HPC Experience: Did Julia Get It Right, or Will AI Hide the Problem (or Both)?"_ Keynote at the Workshop on Asynchronous Many-Task Systems and Applications (WAMTA), 2025. [(Link)](https://wamta25.github.io/keynote). Accessed June 20, 2025.
diff --git a/examples/agentic/example.jl → examples/agentic/deprecated/example.jl b/examples/agentic/example.jl → examples/agentic/deprecated/example.jl
diff --git a/examples/agentic/test_sorted.jl → examples/agentic/deprecated/test_sorted.jl b/examples/agentic/test_sorted.jl → examples/agentic/deprecated/test_sorted.jl
diff --git a/examples/agentic/generate-cpu-linear-solver/Project.toml b/examples/agentic/generate-cpu-linear-solver/Project.toml
@@ -0,0 +1,9 @@
+[deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+SmartSolve = "4fbb3a3c-2fa1-4c19-8d57-bae8bc1e16ac"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
+[sources]
+SmartSolve = {path = "../../.."}