https://github.com/alexquilis1/aigua
💧 AIgua is a friendly AI-powered assistant that analyzes water quality test results and provides clear, human-centered guidance for safe usage, risks, and treatment suggestions — built with watsonx.ai, LangChain, and RAG.
https://github.com/alexquilis1/aigua
ai-agent ibm langchain sdg6 water-quality watsonx-ai
Last synced: 8 months ago
JSON representation
💧 AIgua is a friendly AI-powered assistant that analyzes water quality test results and provides clear, human-centered guidance for safe usage, risks, and treatment suggestions — built with watsonx.ai, LangChain, and RAG.
- Host: GitHub
- URL: https://github.com/alexquilis1/aigua
- Owner: alexquilis1
- License: other
- Created: 2025-03-27T02:04:07.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-30T18:40:54.000Z (8 months ago)
- Last Synced: 2025-03-30T19:31:25.217Z (8 months ago)
- Topics: ai-agent, ibm, langchain, sdg6, water-quality, watsonx-ai
- Language: TypeScript
- Homepage: https://aigua.vercel.app
- Size: 9.37 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 💧 AIgua — Your Friendly Water Quality Companion
AIgua is an AI-powered assistant designed to help people easily understand water quality test results. Whether the water is for drinking, cleaning, or irrigation, AIgua provides clear explanations, risk assessments, and treatment suggestions — all with a human tone.
Built as part of the [AI Agent Hackathon with IBM watsonx.ai](https://developer.ibm.com/events/ai-agent-hackathon-with-ibm-watsonx-ai/), this project supports the UN’s Sustainable Development Goal **#6: Clean Water and Sanitation**.
---
## 📸 Preview
*Main interface showing test result input and AI diagnosis.*
*Community map showing shared water analyses across regions.*
---
## 🚀 Features
- ✅ Friendly, AI-generated analysis of water test results
- 💡 Personalized diagnosis based on pH, TDS, turbidity, and free chlorine
- ⚠️ Risk explanations and treatment suggestions using internal rules + RAG (retrieve-augmented generation)
- 🌍 Optional map where users can anonymously share their test data
- 🔐 Safe-by-design — no personal data required
- 📱 Built with React (frontend) + Python backend + IBM watsonx.ai
---
## 🧠 How It Works
AIgua combines:
- **Internal rules** for quick evaluation of common parameters
- **Watsonx.ai + LangChain** to generate friendly, accessible analysis
- **RAG (Retrieve-Augmented Generation)** for deeper insight using trusted sources (e.g., WHO, EPA)
- **Firestore** for storing shared anonymous results
- **React Leaflet** for map visualization
---
## 🏗 Tech Stack
| Layer | Tech |
|---------------|-----------------------------------|
| Frontend | React + TypeScript + Vite |
| Backend | Python + LangChain + FastAPI |
| AI Model | IBM watsonx.ai (Granite model) |
| Retrieval | Custom RAG pipeline with LangChain |
| Map & DB | React Leaflet + Firebase Firestore |
| Styling | Tailwind CSS |
---
## 📦 Installation
### 🔧 Prerequisites
- Node.js + npm
- Python 3.10+
- Firebase account (for map and shared data)
- IBM Cloud + watsonx.ai access
---
### 💻 Frontend Setup
```bash
cd waterbuddy-frontend
npm install
npm run dev
```
> The frontend will run at `http://localhost:5173`
---
### ⚙️ Backend Setup
```bash
cd waterbuddy-backend
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
python main.py
```
> Make sure to configure your `credentials.py` with IBM and Firebase settings.
---
## 🧪 Sample Input
```json
{
"pH": 7.2,
"TDS": 650,
"turbidity": 3.0,
"free_chlorine": 0.15,
"usage": "watering vegetables"
}
```
---
## 🌐 Live Demo
[](https://www.youtube.com/watch?v=kAa69mZ3UZk)
---
## 🤝 Contributing
We welcome contributions! To get started:
1. Fork the repo
2. Create a new branch (`git checkout -b feature-name`)
3. Commit your changes (`git commit -m 'Add feature'`)
4. Push to the branch (`git push origin feature-name`)
5. Create a Pull Request
---
## 🎯 Hackathon Info
This project was developed as part of the **AI Agent Hackathon with IBM watsonx.ai**, focusing on SDG 6: Clean Water and Sanitation.
### 👥 Team
- **Alex Quilis Vila**
[LinkedIn](https://www.linkedin.com/in/alex-quilis-vila/)
- **Junjie Wu**
[LinkedIn](https://www.linkedin.com/in/junjie-wu-jj/)
---
## 📄 License
This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
It allows for commercial use, modification, distribution, and private use, provided that proper attribution and license notice are maintained.
### ✅ You are free to:
- Use the code for personal, educational, or commercial purposes
- Modify and distribute it under the same license
### 🚫 You must not:
- Use any trademarks, service marks, or logos of the project without permission
- Use the project in ways that violate the license terms
---
For full license details, see the [LICENSE](./LICENSE) file in this repository.
## 💙 Special Thanks
- IBM & Call for Code team
- LangChain & open-source agentic frameworks
- World Health Organization (WHO) & EPA for open guidelines
---
> “Water is life. Let’s make sure it’s safe for everyone.”