Hydro-Flow CLI: Solving Inverse Hydraulic Problems with AI & Scipy

Adisa Mubarak — Thu, 12 Feb 2026 10:03:31 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

Hydro-Flow CLI is an AI-augmented command-line tool designed to bring HEC-RAS caliber hydrology directly to the terminal.

Typically, civil engineers rely on expensive, heavy GUI software to model river floods. This creates a barrier between engineering physics and modern software practices like CI/CD and Containerization.

Hydro-Flow breaks this barrier. It is a "Headless" engineering engine that allows you to:

Auto-Design Channels: Solve the "Inverse Hydraulic Problem" using Scipy Optimization (Newton-Raphson) to find the exact channel width that minimizes excavation costs.
Stress-Test Infrastructure: Run 1,000 Monte Carlo simulations in seconds to predict flood failure probabilities under climate change scenarios.
Generate Digital Twins: Instantly plot hydraulic cross-sections using procedural Matplotlib generation.
Ship Anywhere: Run complex physics models on any machine using Docker.

Battle-tested on data from the Ona River Basin (Nigeria), this project merges rigorous Civil Engineering physics with modern DevOps.

Demo

Here is Hydro-Flow in action, demonstrating the Auto-Designer, Risk Analysis, and Docker Containerization.

⏩ VIDEO NAVIGATION (Skip to the features):

0:45 - THE AI AGENT: How Copilot CLI wrote the Scipy Optimization logic.
1:30 - DEMO 1: Auto-Designing Channels (The Inverse Solver).
2:15 - DEMO 2: Monte Carlo Risk Analysis (1,000 Simulations).
3:45 - DEMO 3: Visualization (Generating the Digital Twin).
4:30 - THE DOCKER RUN: Proof of Production-Readiness.

🔗 Project Links:

GitHub Repository: https://github.com/AdMub/hydro-flow-cli

My Experience with GitHub Copilot CLI

Building a physics engine in the terminal is difficult because it requires deep knowledge of two very different fields: Fluid Dynamics and Systems Programming.

I used the GitHub Copilot CLI not just as a code completer, but as a Domain Expert and DevOps Engineer. It transformed my workflow from "searching StackOverflow" to "conversational coding."

1. The "Math Expert": Solving Inverse Problems

I needed to implement a cost-minimization function for the river channel width, which involves finding the root of the Manning Equation derivative.

The Prompt: I asked Copilot CLI how to map engineering constraints (Max Depth < 5.0m) into a scipy.optimize.minimize_scalar function.
The Result: It generated the exact Python bounds logic and objective function needed to solve the optimization problem mathematically, saving me hours of deriving formulas.

2. The "DevOps Expert": Debugging Docker

Towards the end of the project, I hit a critical wall. When I tried to run the tool inside Docker, I kept getting ModuleNotFoundError: No module named 'hydro'.

The Interaction: I used Copilot CLI to analyze my file structure. It correctly identified that my PYTHONPATH was not set in the container and that I was missing specific __init__.py files.
The Fix: It generated a production-ready Dockerfile that explicitly set ENV PYTHONPATH=/app and handled the package resolution, allowing the tool to run anywhere.

3. The "Visual Expert": Procedural Geometry

Plotting a trapezoidal river channel with varying water levels requires complex coordinate geometry (calculating the intersection points of the water surface with the sloped banks). Copilot CLI generated the Matplotlib fill logic ("PolyCollection") to render the "Digital Twin" images dynamically based on the user's JSON profile.

Built with Python, Typer, Rich, Scipy, Matplotlib, and GitHub Copilot.

SiteMate Pro: The AI OS for African Construction

Adisa Mubarak — Sun, 08 Feb 2026 23:22:23 +0000

This is a submission for the Algolia Agent Studio Challenge: Consumer-Facing Conversational Experiences

What I Built

SiteMate Pro is an "AI Operating System" for the African construction industry. It solves a critical problem: Opacity.

In Nigeria, building material prices change daily, data is fragmented across WhatsApp chats, and fraud is rampant. Engineers often waste days calculating costs manually, and projects fail because of inaccurate estimates.

SiteMate Pro is a conversational agent that acts as a Super-Intelligent Quantity Surveyor.

Conversational Planning: You can tell it, "Build a 4-bedroom duplex on swampy soil in Lekki."
Instant Estimation: It doesn't just "guess" prices like standard LLMs. It retrieves real-time market data to generate a precise, location-specific Bill of Quantities (BOQ).
Fraud Detection: It filters supplier bids in a marketplace, flagging prices that are suspiciously high or low compared to the indexed market rate.

Demo

try the Live App: Launch SiteMate Pro

🎥 Video Walkthrough (7 Mins):

Source Code:
https://github.com/AdMub/Sitemate-Construction-Agent

How I Used Algolia Agent Studio

I leveraged Algolia Agent Studio to solve the biggest problem with Generative AI in engineering: Hallucination.

A standard LLM does not know the price of a bag of cement in Lagos today. If asked, it will hallucinate a number, which is dangerous for a construction budget.

My Architecture (RAG Pipeline):

Index: I modeled construction material data (Cement, Granite, Iron Rods) and supplier profiles as records in Algolia.
Retrieval: When a user prompts the agent (e.g., "Estimate a foundation for swampy soil"), the system first queries Algolia to fetch the current unit prices for that specific location (e.g., Lekki vs. Ibadan).
Targeted Prompting: I inject this retrieved data into the Gemini prompt context. The system instruction is strictly engineered: "You are a Senior Engineer. Use ONLY the retrieved Algolia prices to calculate the total. Do not use outside training data for costs."

This turns the AI from a creative writer into a grounded calculator, ensuring every Naira quoted is backed by real data.

Why Fast Retrieval Matters

In construction, speed is trust.

Contextual Accuracy: By retrieving data based on specific facets (Location: "Lekki", Soil: "Swampy"), the agent avoids giving generic advice that causes building collapse.
Fraud Prevention: Fast retrieval allows us to cross-check incoming supplier bids against thousands of historical data points in milliseconds. If a supplier quotes 30% above the indexed average, the user is warned instantly.
User Experience: The conversation feels natural because the latency is near-zero. The user asks a complex question, and the Bill of Quantities appears instantly, creating a "magical" experience that replaces days of spreadsheet work.

Forem: Adisa Mubarak

Hydro-Flow CLI: Solving Inverse Hydraulic Problems with AI & Scipy

What I Built

Demo

My Experience with GitHub Copilot CLI

1. The "Math Expert": Solving Inverse Problems

2. The "DevOps Expert": Debugging Docker

3. The "Visual Expert": Procedural Geometry

SiteMate Pro: The AI OS for African Construction

What I Built

Demo

How I Used Algolia Agent Studio

Why Fast Retrieval Matters