Project Info

Probability Maxxing

This project did not submit a demo video on Devpost.

Inspiration

We were frustrated by how confidently wrong most prediction tools are. Whether it's AI models hallucinating details or business forecasts pretending to know the future, everyone claims certainty when they have incomplete data. We asked ourselves: "What if we built a tool that's honest about uncertainty?" The inspiration came from a simple scenario: You're deciding whether to grab lunch at Shake Shack. You know the average wait is 25 minutes, but that tells you nothing about the actual distribution. Will it be 10 minutes? 60 minutes? Traditional tools either oversimplify (just show the mean) or overfit (draw confident curves from 3 data points). We discovered the Maximum Entropy Principle from information theory - a mathematical framework for making the most unbiased predictions possible given limited constraints. It's been used in physics and AI research for decades, but never made accessible to everyday decision-makers. We set out to change that.

What it does

Probability Maxxing is a suite of intelligent prediction engines that transform incomplete data into honest probability distributions. Unlike traditional forecasting tools that pretend to know more than they do, our system explicitly models uncertainty. Five Core Solvers: Quick Predictor - Feed it raw observations (like wait times: "12, 15, 8, 45, 22") and it computes the full probability distribution, showing you not just the average, but the entire likelihood curve. Quick Predictor - Feed it raw observations (like wait times: "12, 15, 8, 45, 22") and it computes the full probability distribution, showing you not just the average, but the entire likelihood curve. Scenario Tree Engine - Handles complex real-world situations where multiple scenarios exist. Example: Shake Shack wait times depend on time-of-day (40% off-peak, 60% peak) AND location (Midtown vs. Madison Square Park). The tree structure lets you model hierarchical assumptions and automatically combines them into a single, marginalized distribution. Scenario Tree Engine - Handles complex real-world situations where multiple scenarios exist. Example: Shake Shack wait times depend on time-of-day (40% off-peak, 60% peak) AND location (Midtown vs. Madison Square Park). The tree structure lets you model hierarchical assumptions and automatically combines them into a single, marginalized distribution. Additive Risk Calculator - For situations where independent sources combine (like flu spread from classrooms + cafeteria + sports). Uses mathematical convolution to properly model how independent uncertainties add up. Additive Risk Calculator - For situations where independent sources combine (like flu spread from classrooms + cafeteria + sports). Uses mathematical convolution to properly model how independent uncertainties add up. Spatiotemporal Mapper - Predicts events in both time AND space. Example: "When and where will birds land in Central Park?" Generates beautiful contour maps showing probability density across 2D domains. Spatiotemporal Mapper - Predicts events in both time AND space. Example: "When and where will birds land in Central Park?" Generates beautiful contour maps showing probability density across 2D domains. Convergence Visualizer - Shows animated videos of the optimization process, demonstrating how the algorithm evolves from total uncertainty (flat line) to the final distribution. This builds trust by making the "learning" transparent. Convergence Visualizer - Shows animated videos of the optimization process, demonstrating how the algorithm evolves from total uncertainty (flat line) to the final distribution. This builds trust by making the "learning" transparent. Key Innovation: We use the Jaynes Maximum Entropy Principle - mathematically proven to be the least biased way to make predictions. Our solver minimizes entropy (information) while satisfying all known constraints, ensuring we never inject assumptions that aren't in the data.

How we built it

Mathematical Foundation: Implemented optimization using scipy.optimize.minimize with SLSQP (Sequential Least Squares Programming) Designed constraint systems for means, variances, and log-moments to capture different distribution shapes Developed recursive tree traversal algorithm for weighted probability aggregation Implemented FFT-based convolution for efficient additive risk modeling Core Architecture: Python backend with NumPy for numerical computation Modular solver design: each file (max_ent_exp.py, max_ent_tree.py, etc.) is a standalone solver Matplotlib for static visualizations and FFMpegWriter for optimization animations Object-oriented AssumptionNode class for tree-based scenario modeling Technical Challenges Solved: Numerical stability: np.clip(p, 1e-12, None) prevents log(0) errors during optimization Constraint formulation: Carefully designed equality constraints that are numerically well-conditioned Multi-dimensional optimization: Spatiotemporal solver handles 100+ variables (10×10 grids) Convergence tracking: Callback functions record optimization history for educational animations Validation: Built max_ent_test.py with pytest suite verifying: Probability distributions sum to 1 Constraint satisfaction (mean, variance) Special cases (uniform distribution with zero constraints, Gaussian with mean+variance) Probability distributions sum to 1 Constraint satisfaction (mean, variance) Special cases (uniform distribution with zero constraints, Gaussian with mean+variance)

Challenges we ran into

Numerical Instability - Early versions crashed when probabilities approached zero during optimization. Solution: Implemented safe clipping and epsilon buffers (1e-12) throughout. Numerical Instability - Early versions crashed when probabilities approached zero during optimization. Solution: Implemented safe clipping and epsilon buffers (1e-12) throughout. Constraint Design - Finding the right balance between too few constraints (results too vague) and too many (solver can't converge). We settled on mean + log-mean as a sweet spot for most use cases. Constraint Design - Finding the right balance between too few constraints (results too vague) and too many (solver can't converge). We settled on mean + log-mean as a sweet spot for most use cases. Tree Recursion Complexity - Initially struggled with properly weighting nested probability branches. The breakthrough came when we realized we needed to multiply parent probabilities down the tree path, not just at leaf level. Tree Recursion Complexity - Initially struggled with properly weighting nested probability branches. The breakthrough came when we realized we needed to multiply parent probabilities down the tree path, not just at leaf level. Convolution Array Sizing - When convolving distributions for additive risks, the output array grows. Took several iterations to figure out proper slicing and renormalization to keep results aligned with the original x-axis. Convolution Array Sizing - When convolving distributions for additive risks, the output array grows. Took several iterations to figure out proper slicing and renormalization to keep results aligned with the original x-axis. Spatiotemporal Scaling - The 2D solver initially took 5+ minutes to converge. Optimized by reducing grid resolution intelligently and tuning SLSQP parameters (increased maxiter to 150). Spatiotemporal Scaling - The 2D solver initially took 5+ minutes to converge. Optimized by reducing grid resolution intelligently and tuning SLSQP parameters (increased maxiter to 150). Educational Balance - Making the math accessible without dumbing it down. We chose to show the optimization process through animations rather than hiding it - this actually increases user trust. Educational Balance - Making the math accessible without dumbing it down. We chose to show the optimization process through animations rather than hiding it - this actually increases user trust.

Accomplishments we're proud of

🏆 Mathematical Rigor Meets Usability - We implemented a genuine research-grade optimization algorithm (used in physics and AI labs) but packaged it with practical examples anyone can understand (Shake Shack wait times, flu spread). 🏆 Five Distinct Solvers - Most projects have one demo. We built an entire framework with specialized solvers for different problem types, all sharing the same MaxEnt foundation. 🏆 Transparency Through Visualization - The animated convergence videos (distribution_evolution_shack.mp4) make the black box transparent. Users see exactly how the algorithm "learns" from their data. 🏆 Recursive Tree Architecture - The scenario tree solver is genuinely novel - we couldn't find another tool that handles hierarchical probability structures with MaxEnt at each node. 🏆 Production-Ready Code - Type hints, docstrings, test suite, modular design. This isn't a hackathon throw-away; it's extensible research infrastructure. 🏆 Real-World Validated - We tested with actual scenarios: NYC restaurant queues, epidemic modeling, wildlife behavior patterns. The results match intuition while revealing hidden insights (like the bimodal distribution from peak/off-peak mixing).

What we learned

Technical: Information theory is deeply practical - entropy isn't just abstract math, it's the quantification of honesty in predictions Constrained optimization is an art - you need enough constraints to guide the solution but not so many that you overconstrain Convolution is the right operation for additive risks (not just weighted sums) - this clicked when we realized independent random variables add through their PDFs Philosophical: Epistemic humility is valuable - Users actually prefer tools that admit uncertainty over tools that confidently hallucinate The "least biased" prediction is often surprising - MaxEnt naturally produces distributions that humans wouldn't intuit Transparency builds trust - showing the optimization process makes people more likely to use the results Software Engineering: Animation as documentation - our MP4s explain the algorithm better than pages of text could Modular solver design allows easy extension - adding new constraint types is straightforward Test-driven development for numerical code is essential (caught several edge cases early) Domain Knowledge: Queue theory's heavy-tailed distributions emerge naturally from mean + log-mean constraints Spatiotemporal problems need careful normalization (learned from the bird landing contour plot) Tree-based aggregation captures conditional probability without needing full Bayesian networks

What's next

Immediate Roadmap: Interactive Web Application - Convert the Python backend into a full-stack web app with: React/Next.js frontend with Plotly.js for interactive charts FastAPI backend wrapping the solvers Drag-and-drop tree builder for scenario modeling Real-time computation (< 2 seconds for typical problems) Export as PNG, JSON, or executable Python code Interactive Web Application - Convert the Python backend into a full-stack web app with: React/Next.js frontend with Plotly.js for interactive charts FastAPI backend wrapping the solvers Drag-and-drop tree builder for scenario modeling Real-time computation (< 2 seconds for typical problems) Export as PNG, JSON, or executable Python code API Access - RESTful API for programmatic use: POST /api/maxent/predict Body: {"observations": [12, 15, 8, 45], "x_range": [0, 100]} Response: {"distribution": [...], "peak": 18.3, "entropy": 2.47} API Access - RESTful API for programmatic use: Pre-built Templates - One-click solvers for common use cases: Restaurant wait times Project delay estimation Epidemic spread modeling Financial risk assessment Traffic/commute prediction Pre-built Templates - One-click solvers for common use cases: Restaurant wait times Project delay estimation Epidemic spread modeling Financial risk assessment Traffic/commute prediction Advanced Features: Bayesian Updating - As new observations come in, dynamically update the distribution in real-time (recursive MaxEnt) Bayesian Updating - As new observations come in, dynamically update the distribution in real-time (recursive MaxEnt) Constraint Recommendation - ML system that suggests which constraint types (mean, variance, log-mean, etc.) best fit your data characteristics Constraint Recommendation - ML system that suggests which constraint types (mean, variance, log-mean, etc.) best fit your data characteristics Multi-Objective Optimization - Handle competing constraints with Pareto frontiers (e.g., "maximize both accuracy and robustness") Multi-Objective Optimization - Handle competing constraints with Pareto frontiers (e.g., "maximize both accuracy and robustness") Causality Integration - Combine MaxEnt with causal graphs (do-calculus) to handle interventional predictions, not just observational Causality Integration - Combine MaxEnt with causal graphs (do-calculus) to handle interventional predictions, not just observational Research Extensions: MaxEnt for Neural Networks - Use entropy regularization for safer AI uncertainty quantification (connecting back to the RL safety component of the codebase) MaxEnt for Neural Networks - Use entropy regularization for safer AI uncertainty quantification (connecting back to the RL safety component of the codebase) Time-Series MaxEnt - Extend to temporal sequences with auto-regressive constraints Time-Series MaxEnt - Extend to temporal sequences with auto-regressive constraints Quantum MaxEnt - Apply to quantum state tomography and quantum machine learning (von Neumann entropy) Quantum MaxEnt - Apply to quantum state tomography and quantum machine learning (von Neumann entropy) Commercialization: SaaS Model - Freemium with API rate limits, Pro tier for businesses Enterprise Integration - Jupyter notebook plugin, Excel add-in, Slack bot Education Platform - Partner with universities for teaching information theory and Bayesian inference Ultimate Vision: Make MaxEnt the default prediction method for any system dealing with uncertainty. Just like how Git became the default for version control or React for UI, we want "just use MaxEnt" to be the standard advice for honest forecasting.

Analysis

Compare with all teams

View

Metric

Kourosh-Salahi
1

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

PythonIn code
Google GeminiClaimed

1 of 2 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

60 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.