Skip to content

getting-started.md

Latest commit

 

History

History
160 lines (123 loc) · 9.54 KB

getting-started.md

File metadata and controls

160 lines (123 loc) · 9.54 KB
Raw

Getting Started with uber-polya

A zero-to-hero tutorial. By the end, you will have modeled, solved, and interpreted a mathematical problem entirely through Claude Code slash commands.

Prerequisites

  • Claude Code -- Anthropic's CLI for Claude (installation guide)
  • Python 3.10+ -- for running the solver code that uber-polya generates

Optional Python packages (installed automatically when 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

Install uber-polya

git clone https://github.com/agtm1199/uber-polya.git
cd uber-polya
bash install.sh

The installer asks where to put the four skills:

  1. Global (~/.claude/skills/) -- available in every project
  2. Local (./.claude/skills/) -- current project only

That is it. No virtual environment, no build step. The skills are plain markdown files that Claude Code reads on demand.

Your First Problem

Open Claude Code in any project directory and type:

/uber-polya I need to schedule 4 exams (A, B, C, D) into the fewest time
slots so that no student has two exams at the same time. Students are
enrolled in these pairs of courses: {A,B}, {A,C}, {B,D}, {C,D}.

That's it -- one command. /uber-polya handles the entire pipeline automatically. Here's what happens:

Phase 1 -- Understand & Model

Claude walks through Polya's "Understanding" and "Planning" phases. It asks clarifying questions, then produces a formal model. Representative output:

Problem Type: Problem to Find (optimization) Unknown: Minimum number of time slots (colors) such that no two conflicting exams share a slot Structure: Graph coloring on a conflict graph G = (V, E)

  • Vertices V = {A, B, C, D} (exams)
  • Edges E = {(A,B), (A,C), (B,D), (C,D)} (student enrolled in both) Objective: Minimize k such that a proper k-coloring of G exists

Phase 2 -- Solve & Verify

Claude automatically classifies the problem, selects an algorithm, writes a solver script, runs it, and verifies the result. Representative output:

Named Problem: Graph Coloring (k-coloring) Complexity: NP-hard in general; O(V + E) for bipartite detection Instance Size: |V| = 4, |E| = 4 Algorithm: Bipartite 2-coloring via BFS

Answer: chromatic number = 2

  • Slot 1: {A, D}
  • Slot 2: {B, C}

Verification: All 4 edges checked -- no two adjacent vertices share a color. PASS.

Phase 3 -- Interpret & Recommend

Claude translates the math back into your world. Representative output:

Bottom line: You need exactly 2 time slots. No student has a conflict.

Schedule:

  • Slot 1 (e.g., Monday 9 AM): Exams A and D
  • Slot 2 (e.g., Monday 2 PM): Exams B and C

Sensitivity: If a student enrolls in both A and D, the chromatic number rises to 3 (the conflict graph gains an odd cycle). Monitor enrollment changes.

Modeling insight: Whenever you need to assign items to the fewest groups such that conflicting items are separated, model it as graph coloring on a conflict graph.

Note: Claude's exact wording, formatting, and level of detail will vary between runs. The outputs above are representative, not verbatim.

What Just Happened?

You typed one command and /uber-polya orchestrated the entire Polya problem-solving cycle:

Polya Phase What uber-polya does
1-2: Understand & Plan Translates your real-world problem into a formal mathematical model
3: Execute Classifies the problem, selects the right algorithm, solves it, verifies the answer
4: Look Back Translates the solution back into actionable insight with sensitivity analysis

Under the hood, /uber-polya chains three internal skills (/uber-model, /uber-solve, /uber-interpret). You can also use these individually for finer control -- for example, /uber-solve accepts any well-specified math problem, and /uber-interpret can explain any solution you hand it.

Next Steps

Try the worked examples. The examples/ directory contains 36 fully solved problems with runnable code, organized in two categories:

Everyday Problems (11 examples):

Technical Showcases (25 examples):

Try your own problem. Good candidates for /uber-polya:

  • Scheduling (exams, meetings, shifts) -- graph coloring or ILP
  • Assignment (people to tasks, resources to jobs) -- bipartite matching or ILP
  • Routing (deliveries, network paths) -- shortest path, flow, TSP
  • Counting (arrangements, combinations, probabilities) -- combinatorics, inclusion-exclusion
  • Feasibility ("Is it possible to...?") -- SAT, constraint satisfaction
  • Optimization (minimize cost, maximize profit) -- continuous optimization, convex QP
  • Comparing groups ("Is A better than B?") -- hypothesis testing, A/B tests
  • Prediction (forecast outcomes from data) -- regression, Bayesian inference
  • Time series (forecasting, anomaly detection) -- SARIMA, change point detection
  • Survival analysis (churn, equipment failure) -- Kaplan-Meier, Cox PH
  • Machine learning (classification, clustering, feature selection) -- Random Forest, K-Means, PCA
  • Simulation (queuing, epidemics, Monte Carlo risk) -- DES, SIR ODE, MC sampling
  • Causal inference (treatment effects, policy evaluation) -- propensity matching, DiD
  • Operations research (inventory, bin packing, lot sizing) -- EOQ, newsvendor, first-fit decreasing

Start with /uber-polya <describe your problem in plain English> and let Claude handle the rest.