Don't guess. Solve.
The first math problem-solver for AI coding assistants. Free, open-source, and works across 7+ platforms.
Docs | Tutorial | Manifesto | Contributing
You describe what you're trying to figure out. uber-polya finds the mathematical structure hiding inside your problem, solves it with the right algorithm, checks the answer, and gives you the result: a schedule, a plan, a decision, a budget, a ranking, a proof -- whatever you need.
/uber-polya Schedule 12 nurses across 3 shifts so nobody works more than 5 days
uber-polya:
1. Understands -> "This is a constraint satisfaction problem"
2. Models -> ILP with 252 binary variables, 48 constraints
3. Solves -> Optimal schedule in 0.3 seconds
4. Verifies -> All constraints satisfied, optimality proven
5. Delivers -> A shift schedule you can use today
Describe your problem. Get a verified solution. Optionally, get a professional PDF report. That's it.
Why uber-polya?
Most real-world problems -- business or personal -- have a mathematical structure hiding inside them. Scheduling is graph coloring. Budgeting is linear programming. Pricing is optimization. Route planning is TSP. But finding that structure, picking the right algorithm, writing correct solver code, and verifying the answer takes expertise most people don't have.
uber-polya does all of that in one conversation. It implements George Polya's four-phase problem-solving cycle (How to Solve It, 1945) as an executable pipeline:
- Understand -- Socratic dialogue to extract what you really need
- Model -- Finds the mathematical structure, classifies the problem
- Solve -- Selects the right algorithm, writes verified solver code, runs it
- Interpret -- Translates the answer into actionable insight with visualizations
The pipeline is collaborative: uber-polya asks questions, you confirm understanding, and the solution is built together -- not dictated.
1. Install
git clone https://github.com/agtm1199/uber-polya.git
cd uber-polya
bash install.shThe installer asks whether to install globally (~/.claude/skills/, available in all projects) or locally (./.claude/skills/, current project only).
2. Solve a problem
Open Claude Code and type:
/uber-polya I need to schedule 4 exams into time slots so no student has two exams at the same time.
3. Get a verified result
uber-polya handles the entire pipeline automatically. One command, one conversation, one verified result.
3b. Get a PDF report (optional)
When you invoke /uber-polya, you can choose from three output formats:
| Format | What you get |
|---|---|
| Python (default) | Solver script + console output + solution.json |
| LaTeX/PDF | Professional .pdf report with equations, tables, and branded styling |
| Both | Full Python output AND compiled PDF report |
PDF generation uses fpdf2 + matplotlib.mathtext -- pure Python, no system LaTeX installation required. The .tex source is always saved for optional higher-quality compilation with pdflatex.
# Install PDF report dependencies
pip install jinja2 fpdf2 matplotlibUnder the hood, /uber-polya orchestrates three internal skills (/uber-model, /uber-solve, /uber-interpret) that you can also use individually for finer control.
/uber-polya (orchestrator)
/uber-model /uber-solve /uber-interpret
"What IS the "What is the "What does it
problem?" ANSWER?" MEAN?"
Real-world --> Formal Model --> Verified --> Actionable
problem (math) Solution Insight
Polya Phases Polya Phase Polya Phase
1-2: Understand 3: Execute 4: Look Back
& Plan
Each skill's output feeds the next. The pipeline is Socratic: uber-polya asks questions, you confirm understanding, and the solution is built collaboratively.
Every problem in these tables has a mathematical structure. uber-polya finds it and solves it.
Business Problems (18 problem types)
| Problem | You say... | uber-polya finds... | You get... |
|---|---|---|---|
| Shift scheduling | "Schedule 12 nurses across 3 shifts" | Constraint satisfaction / ILP | A shift schedule (table) |
| Project selection | "Pick the best 5 of 20 projects under budget" | Knapsack optimization | Ranked list + ROI analysis |
| Task assignment | "Assign inspectors to regions, minimize travel" | Bipartite matching | Assignment matrix |
| Route planning | "Route 4 trucks across 30 delivery stops" | Vehicle routing (TSP variant) | Optimized routes + map |
| Pricing | "Price this product to maximize revenue" | Optimization with demand model | Recommended price + sensitivity |
| A/B testing | "Is this test result statistically real?" | Hypothesis testing | Yes/no + confidence + power analysis |
| Portfolio allocation | "Allocate investments to minimize risk" | Quadratic programming | Efficient frontier + allocation |
| Build vs. buy | "Should we build or buy this component?" | Decision tree / expected value | Recommendation + break-even |
| Sales forecasting | "Forecast next quarter's revenue" | Time series (SARIMA / Holt-Winters) | Forecast + confidence intervals |
| Customer churn | "Predict which customers will leave" | Classification (Random Forest) | Risk scores + key factors |
| Training impact | "Did our training program boost sales?" | Causal inference (DiD / propensity) | Effect size + confidence interval |
| Call center staffing | "How many agents for 95% SLA?" | Queuing theory (M/M/c) | Staffing table + cost analysis |
| Subscriber retention | "When will customers cancel?" | Survival analysis (Cox PH) | Survival curves + risk factors |
| Inventory ordering | "How much to order, when to reorder?" | Inventory optimization (EOQ) | Order quantity + reorder point |
| Container loading | "Pack 50 shipments into fewest trucks" | Bin packing (ILP) | Packing plan + utilization |
| Vendor ranking | "Rank vendors balancing cost, quality, speed" | Multi-objective optimization (Pareto) | Pareto frontier + trade-offs |
| Product configuration | "Can we build this with all customer requirements?" | SAT / constraint satisfaction | Valid configuration or proof of infeasibility |
| Demand patterns | "Model customer arrival patterns for staffing" | Stochastic processes (Markov / Poisson) | Arrival model + peak hours |
Personal Problems (15 problem types)
| Problem | You say... | uber-polya finds... | You get... |
|---|---|---|---|
| Meal planning | "Plan meals for the week within budget" | Linear programming | Meal plan + grocery list |
| Rent splitting | "Split rent fairly among 3 roommates" | Fair division / allocation | Dollar amounts per person |
| Study schedule | "Schedule study sessions across 5 subjects" | Graph coloring / scheduling | Weekly study timetable |
| Apartment ranking | "Pick the best apartment from these 10" | Multi-criteria decision analysis | Ranked list + trade-offs |
| Expense splitting | "Split trip expenses among friends" | Fair allocation | Split table |
| Refinancing | "Should I refinance my mortgage?" | NPV / break-even analysis | Yes/no + savings timeline |
| Budget forecasting | "Will I stay within budget this year?" | Time series forecasting | Monthly forecast + alerts |
| Garden fencing | "Maximize garden area with 100 ft of fence" | Calculus optimization | Optimal dimensions + layout |
| Room painting | "How much paint for these oddly-shaped rooms?" | Computational geometry | Quantity + cost estimate |
| Solar payback | "When does my solar panel investment pay off?" | Root finding / break-even | Payback date + savings curve |
| Recipe scaling | "Scale this recipe for 50 people" | Linear algebra (systems of equations) | Adjusted ingredient quantities |
| Raffle odds | "What are my chances of winning this raffle?" | Discrete probability | Probability + expected value |
| Medication timing | "When do drug levels peak and trough?" | ODE modeling (pharmacokinetics) | Dosing schedule + level chart |
| Moving logistics | "Fit all furniture into fewest truck loads" | Bin packing | Loading plan + trips needed |
| House hunting | "Balance commute, price, and schools across 15 houses" | Multi-objective optimization (Pareto) | Shortlist of non-dominated options |
36 fully worked examples with solver code, verification, and sample output.
Everyday Problems (11 examples)
| Example | Problem | Algorithm |
|---|---|---|
| Shift Scheduling | Schedule 8 nurses across 3 shifts over 7 days | ILP (PuLP/CBC) |
| Budget Optimization | Select projects to maximize ROI under budget | 0/1 Knapsack ILP |
| Fair Rent | Split rent fairly among 3 roommates | Hungarian + envy-free adjustment |
| Route Planning | Shortest delivery route across 8 stops | Held-Karp DP (exact TSP) |
| Project Prioritization | Rank 8 features by weighted criteria | MCDA weighted scoring |
| Study Schedule | Conflict-free study timetable for 6 subjects | Graph coloring (NetworkX) |
| Meal Planning | Plan 7 dinners minimizing cost, meeting nutrition targets | ILP (PuLP/CBC) |
| Team Assignment | Assign 6 developers to 6 projects | Hungarian algorithm (SciPy) |
| Break-Even Analysis | Find break-even quantity for product launch | Symbolic algebra (SymPy) |
| Event Seating | Seat 12 wedding guests at 3 tables with constraints | ILP (PuLP/CBC) |
| Mortgage Comparison | Compare 3 mortgage options with refinancing analysis | NPV + amortization (numpy-financial) |
Technical Showcases (25 examples)
| Example | Domain | Algorithm |
|---|---|---|
| Milking Cows | Interval merging | Sort + sweep, O(N log N) |
| Inspector Assignment | Bipartite ILP | PuLP/CBC solver |
| Portfolio Optimization | Convex QP | cvxpy (Markowitz) |
| Tournament Hamiltonian | Graph proof | Induction + Z3 |
| A/B Testing | Statistical inference | z-test + Bayesian + bootstrap |
| Cafe Tips | Statistical inference | t-test + Mann-Whitney + bootstrap |
| Traffic Flow | Linear algebra | Gaussian elimination (numpy) |
| Water Tank | Calculus optimization | Symbolic differentiation (SymPy) |
| Land Survey | Computational geometry | Shoelace + convex hull (shapely) |
| Nash Equilibrium | Game theory | Support enumeration (nashpy) |
| Vendor Selection | Decision analysis (MCDA) | AHP + TOPSIS (numpy) |
| Pareto Optimization | Multi-objective optimization | Epsilon-constraint + Pareto filter |
| Sales Forecast | Time series analysis | SARIMA + Holt-Winters (statsmodels) |
| Anomaly Detection | Time series analysis | Z-score + PELT change point (ruptures) |
| Customer Survival | Survival analysis | Kaplan-Meier + Cox PH (lifelines) |
| Customer Churn Classification | Machine learning | Random Forest + Gradient Boosting (scikit-learn) |
| Customer Segmentation | Machine learning | K-Means + DBSCAN + GMM (scikit-learn) |
| Feature Importance | Machine learning | PCA + Feature Selection + Model Comparison |
| Call Center Queuing | Queuing theory | M/M/c + simpy DES verification |
| SIR Epidemic Model | Numerical ODEs | SIR ODE + vaccination analysis (scipy) |
| Monte Carlo Project Risk | Simulation | MC risk simulation + convergence analysis |
| Root Finding & Interpolation | Numerical methods | Bisection + Newton + Brent + cubic spline |
| Causal Inference | Causal inference | Propensity matching + DiD + doubly robust |
| Inventory Optimization | Operations research | EOQ + newsvendor + safety stock |
| Bin Packing | Operations research | First Fit Decreasing + ILP optimal |
The Knowledge Base -- 305 algorithms, 91 structures, 26 solver libraries
| Catalog | Entries |
|---|---|
| Polya's Heuristics | 17 heuristics with Socratic questions |
| Structure Catalog | 91 structures across 24 mathematical domains |
| Problem Classification | Decision tree + pattern table for rapid matching |
| Algorithm Catalogs | 305 algorithms (discrete math, continuous optimization, statistics, time series, stochastic processes, survival analysis, machine learning, simulation, queuing theory, ODEs, numerical methods, causal inference, extended OR, linear algebra, calculus, geometry, financial math, game theory, decision analysis, multi-objective optimization) |
| Solver Ecosystem | 26 Python libraries (NetworkX, PuLP, Z3, SymPy, SciPy, OR-Tools, cvxpy, statsmodels, PyMC, shapely, numpy-financial, nashpy, pymoo, prophet, arch, ruptures, lifelines, scikit-learn, xgboost, umap-learn, simpy, dowhy, and more) |
| Interpretation Patterns | Domain-specific math-to-reality translation |
| Visualization Guide | 37 chart types with matplotlib templates |
| LaTeX/PDF Templates | Jinja2 templates + polya.sty branded style in templates/latex/ |
PDF Report Generation -- Professional mathematical reports
uber-polya can generate branded PDF reports from any solved problem. The report system uses:
- Jinja2 templates in
templates/latex/with custom delimiters (\VAR{},\BLOCK{}) polya.stycustom LaTeX style with branded environments and colorsfpdf2for pure-Python PDF generation (no system LaTeX needed)matplotlib.mathtextfor rendering LaTeX math expressions as images
The data flows through three dataclasses in utils/latex_data.py:
| Dataclass | Phase | Contents |
|---|---|---|
FormalModel |
Phase A | Universe, variables, constraints, objective, mapping |
SolutionReport |
Phase B | Answer, algorithm, verification checks, solver code |
InterpretationReport |
Phase C | Question, answer, sensitivity, recommendations, figures |
To generate a PDF report from an existing example:
python utils/render_example.py examples/team-assignment/
# Output: examples/team-assignment/report/report.pdfAll 36 worked examples ship with pre-generated reports in their report/ subdirectories.
25 Domains Covered
Graph Theory, Combinatorics, Set Theory, Logic, Number Theory, Relations & Orders, Optimization, Discrete Probability, Continuous Optimization, Statistical Inference, Time Series Analysis, Stochastic Processes, Survival Analysis, Machine Learning, Simulation & ODEs, Numerical Methods, Causal Inference, Extended Operations Research, Linear Algebra, Calculus, Geometry & Trigonometry, Financial Mathematics, Game Theory, Decision Analysis, Multi-Objective Optimization.
Expansion Roadmap
| Domain | Status | What It Adds |
|---|---|---|
| Discrete Mathematics | Shipped | 86 algorithms, 32 structures, 8 solver libraries |
| Continuous Optimization | Shipped | 8 algorithms, 5 structures, cvxpy/scipy |
| Statistical Inference | Shipped | 45 algorithms, 6 structures, 6 solver libraries |
| Linear Algebra | Shipped | 12 algorithms, 4 structures, numpy.linalg/scipy.linalg |
| Calculus | Shipped | 10 algorithms, 3 structures, SymPy/scipy.integrate |
| Geometry & Trigonometry | Shipped | 10 algorithms, 4 structures, shapely/scipy.spatial |
| Financial Mathematics | Shipped | 8 algorithms, 1 structure, numpy-financial |
| Game Theory | Shipped | 12 algorithms, 3 structures, nashpy |
| Decision Analysis | Shipped | 10 algorithms, 3 structures, numpy/scipy |
| Multi-Objective Optimization | Shipped | 8 algorithms, 3 structures, pymoo |
| Time Series Analysis | Shipped | 15 algorithms, 3 structures, prophet/arch/ruptures |
| Stochastic Processes | Shipped | 5 algorithms, 3 structures, scipy |
| Survival Analysis | Shipped | 5 algorithms (3 new + 2 existing), lifelines |
| Machine Learning | Shipped | 22 algorithms, 5 structures, scikit-learn/xgboost/umap-learn |
| Simulation & ODEs | Shipped | 23 algorithms (10 ODE + 13 simulation), 8 structures, simpy/scipy.integrate |
| Numerical Methods | Shipped | 13 algorithms, 3 structures, scipy.optimize/interpolate/integrate |
| Causal Inference | Shipped | 7 algorithms, 2 structures, dowhy/scikit-learn |
| Extended Operations Research | Shipped | 8 algorithms, 3 structures, PuLP/OR-Tools |
| Partial Differential Equations | Planned | Heat, wave, diffusion equations -- FEniCS, FiPy |
| Dynamical Systems & Chaos | Planned | Stability, attractors, bifurcation analysis |
| Spatial Statistics | Planned | Geostatistics, spatial autocorrelation -- geopandas, PySAL |
| Spherical Geometry / Geodesy | Planned | Great circle distance, geodesic calculations -- geopy |
| Option Pricing | Planned | Black-Scholes, binomial lattice -- QuantLib |
| Risk Management | Planned | VaR, CVaR, stress testing |
| Agent-Based Modeling | Planned | Agent simulation, emergent behavior -- mesa |
| Fourier Analysis / Spectral Methods | Planned | FFT, spectral decomposition -- scipy.fft |
| Digital Signal Processing | Planned | Filtering, convolution, spectral analysis -- scipy.signal |
| Information Theory | Planned | Entropy, mutual information, KL divergence -- scipy.stats |
| Classical Control | Planned | PID control, stability margins -- python-control |
| Modern Control | Planned | State-space, LQR, Kalman filtering -- python-control, filterpy |
| Population Dynamics | Planned | Lotka-Volterra, predator-prey models (extends Simulation & ODEs) |
| Epidemiology | Planned | SIR, SEIR, compartmental models (extends Simulation & ODEs) |
Domains marked Shipped are fully integrated. Planned domains have clear implementation paths and are accepting contributions. New domains plug in as reference files without changing the core Polya workflow.
uber-polya ships native instruction files for 7+ AI coding assistants. Each tool gets the full Polya methodology (Model -> Solve -> Interpret) through its native config format.
Platform config details
| Tool | Config File(s) | Format |
|---|---|---|
 Claude Code |
CLAUDE.md + skills/*/SKILL.md |
Skills with YAML frontmatter |
 Codex |
AGENTS.md |
Plain markdown (cross-tool standard) |
 GitHub Copilot |
.github/copilot-instructions.md + AGENTS.md |
Markdown |
 Cursor |
.cursor/rules/uber-polya.mdc, solver-conventions.mdc |
Markdown with glob targeting |
 Windsurf |
.windsurf/rules/uber-polya.md, solver-conventions.md |
Markdown |
 Amazon Kiro |
.kiro/steering/uber-polya.md, solver-conventions.md |
Markdown with YAML frontmatter |
  + others |
AGENTS.md |
Cross-tool standard (60K+ repos) |
The reference files (skills/*/references/) are pure markdown -- readable by any tool. The 36 worked examples use standard Python with no tool-specific dependencies.
- Claude Code (Anthropic's CLI) -- the runtime for skills
- Python 3.10+ -- for running generated solver code
Optional Python packages (installed as needed)
pip install networkx pulp z3-solver sympy scipy matplotlib numpy cvxpy statsmodels shapely numpy-financial nashpy pymoo prophet arch ruptures lifelines scikit-learn xgboost umap-learn simpy dowhy jinja2 fpdf2- Socratic, not didactic. Asks questions that could have occurred to you. Never lectures.
- Verify everything. Every solution includes independent verification.
- Right tool for the job. Algorithm selection based on problem class and instance size.
- Audience adaptation. Results adapted for technical, decision-maker, or general audiences.
- Knowledge transfer. Every problem teaches a reusable modeling pattern.
- Modular expansion. New domains plug in without changing the core workflow.
- The Manifesto -- Why most of your problems are math problems
- Architecture -- How Polya's method maps to the skills
- Getting Started -- Your first problem
- Creating Skills -- Build on this framework
- Contributing -- Add algorithms, domains, or examples
Contributions welcome! Whether it's a new domain, algorithm, worked example, or bug fix -- see CONTRIBUTING.md for guidelines.
Please note that this project follows the Contributor Covenant Code of Conduct.
If you use uber-polya in your work, please cite it:
@software{uber_polya,
title = {uber-polya: Universal Problem-Solving Engine},
url = {https://github.com/agtm1199/uber-polya},
license = {Apache-2.0},
year = {2025}
}Or in text:
uber-polya: Universal Problem-Solving Engine. https://github.com/agtm1199/uber-polya. Apache-2.0 License.
Apache 2.0 -- free to use, modify, and distribute.
George Polya, How to Solve It (1945). The heuristic framework, Socratic questioning methodology, and four-phase problem-solving cycle that underpin this project are adapted from his work.