README.md

metadata

title: EcoAgent
emoji: 🌱
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.20.0
app_file: app.py
pinned: true

🌱 EcoAgent — AI-Powered Eco Lifestyle Assistant

An sustainable assistant for India powered by IBM Granite via watsonx.ai. Chat about eco habits, explore a household impact dashboard, look up local recycling guides, and build a family sustainability profile.

Classification: Agentic AI Application with Prompt Engineering

---

Features

Tab	What it does
💬 Chat	Multi-turn conversation with IBM Granite — personalised eco tips, government schemes, impact estimates. Agent Mode enables multi-step reasoning with 5 tools.
📊 Dashboard	Session-based eco score (0–100), CO₂/water/waste savings tracker, household summary
♻️ Recycling Guide	City-specific recycling instructions for 8 material categories + eco-friendly product alternatives
🏡 Profile	Household members, Indian city, current eco habits — personalises all chat responses

---

Agent Mode

EcoAgent features an agentic AI loop that can use tools to provide accurate, data-driven answers:

Tool	Purpose
🧮 Impact Calculator	Get exact CO₂/water/waste numbers for eco actions
♻️ Recycling Guide	City-specific recycling instructions
🔍 Web Search	Search latest news, schemes, local services
🏛️ Scheme Checker	Indian government scheme details and eligibility
👥 Household Profiler	Personalized action plan based on profile

How it works:

1. Enable "Agent Mode" checkbox in Chat tab
2. Ask a question
3. Agent reasons step-by-step, calls tools as needed
4. See which tools were used below the response

Date Accuracy Fix:

• System prompt includes TODAY'S DATE so the LLM knows the current date
• Web search results include Search conducted on: <date> header
• LLM is instructed to trust search results over its training data
• Prevents hallucinated outdated dates like "August 2025"

💪 Effort Behind This Project

This project is the result of a full v2 rebuild with focused work across product design, AI integration and UX:

• Replaced the older pipeline with a new watsonx_client.py architecture using IBM Granite + watsonx.ai SDK.
• Designed and built a complete 4-tab Gradio application (Chat, Dashboard, Recycling Guide, Profile).
• Created impact tracking logic (eco score + CO₂/water/waste calculations) with session-aware state handling.
• Added India-focused sustainability guidance, recycling flows, and household personalization.
• Reworked environment setup, dependency management, and deployment readiness for Hugging Face Spaces.

In short: this is not a template drop-in — it reflects significant end-to-end implementation effort from planning to delivery.

---

Architecture

.env  (WATSONX_API_KEY, WATSONX_PROJECT_ID, WATSONX_URL)
        │
        ▼
watsonx_client.py   ← IBM Granite ModelInference, AGENT_INSTRUCTIONS, IMPACT_TABLE
        │
        ▼
tools.py            ← 5 tool definitions, executor, scheme database
        │
        ▼
agent.py            ← Agentic loop with multi-step reasoning
        │
        ▼
app.py              ← Gradio Blocks (4 tabs, ultra-light eco green theme, session state)

Model: ibm/granite-4-h-small (eu-de region, watsonx.ai)
Auth: IBM Cloud API key → watsonx.ai SDK (no Orchestrate REST API)

---

How It Works

EcoAgent uses prompt engineering + agentic AI to transform IBM Granite into a domain-specific eco advisor:

1. System Prompt: 86-line AGENT_INSTRUCTIONS defining persona, output format, focus areas, and guardrails
2. Static Knowledge: IMPACT_TABLE (20 eco actions) and PRODUCT_RECS (8 material categories) injected via prompt
3. Dynamic Context: Household profile (members, location, habits) injected per session
4. Agent Loop: Multi-step reasoning with tool calls (max 5 iterations)
5. Tool Execution: Real-time tool calls with result feedback
6. Date Injection: Current date injected into system prompt and search results for accuracy
7. Output Format: Fixed 4-part structure (Quick Tip → Why it Matters → Impact → Optional Resource)
8. Guardrails: Never invent stats, label [Lookup] vs [Estimate], no medical/financial advice

---

UI Theme

Ultra-light eco green theme with near-white background and green accents:

• Background: #fcfcfd (near white)
• Primary accent: #2e7d50 (green)
• Cards: #ffffff with subtle shadows
• Text: #1c1c1e (near black), muted: #4a4a4e
• Borders: #e4e4e7 (light gray)
• CheckboxGroup styled as selectable pills/chips

---

Environment Variables

Set these as Secrets in your Hugging Face Space (Settings → Variables and Secrets)
or in a local .env file (never commit with real values).

Variable	Required	Description
WATSONX_API_KEY	✅	IBM Cloud API key — get one here
WATSONX_PROJECT_ID	✅	watsonx.ai Studio Project ID (UUID) — see below
WATSONX_URL	✅	watsonx.ai endpoint for your region — default https://eu-de.ml.cloud.ibm.com

How to get WATSONX_PROJECT_ID

1. Go to https://eu-de.dataplatform.cloud.ibm.com
2. Create or open a project
3. Click the Manage tab → General section
4. Copy the Project ID (a UUID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
5. Add it to .env as WATSONX_PROJECT_ID=<your-uuid>

Regional watsonx.ai URLs

Region	URL
EU Frankfurt (default)	https://eu-de.ml.cloud.ibm.com
US Dallas	https://us-south.ml.cloud.ibm.com
UK London	https://eu-gb.ml.cloud.ibm.com
Japan Tokyo	https://jp-tok.ml.cloud.ibm.com
Australia Sydney	https://au-syd.ml.cloud.ibm.com

---

Local Development

Prerequisites

• Python 3.10+ (Python 3.14 via uv is configured in .venv)
• uv (recommended) or pip

Steps

# 1. Clone the repo
git clone https://huggingface.co/spaces/<your-username>/ecoagent
cd ecoagent

# 2. Install dependencies
uv pip install -r requirements.txt
# or: pip install -r requirements.txt

# 3. Configure credentials
# Copy .env.example to .env and fill in your values:
cp .env.example .env
# Edit .env — set WATSONX_API_KEY, WATSONX_PROJECT_ID, WATSONX_URL

# 4. Run
uv run python app.py
# → Open http://localhost:7860

---

Customising the Agent

Open watsonx_client.py and edit the AGENT_INSTRUCTIONS constant at the top of the file. You can change:

• Persona & tone — make it more formal, more playful, multilingual, etc.
• Focus areas — add specific sustainability topics (e.g. marine conservation)
• India-specific context — add regional schemes, local brands, city-specific advice
• Safety rules — tighten or relax what the agent will/won't say
• Answer structure — change the tip → why → impact → resource format

The IMPACT_TABLE dict below it controls the carbon/water/waste numbers shown in the Dashboard tab — add new actions or update existing values there.

---

Project Files

File	Purpose
app.py	Gradio Blocks UI — 4 tabs, callbacks, CSS theme
watsonx_client.py	IBM watsonx.ai SDK wrapper, agent config, impact data
tools.py	Agent tool definitions, executor, scheme database
agent.py	Agentic loop with multi-step reasoning
requirements.txt	Pinned Python dependencies (5 packages)
.env	Local credentials (gitignored)
.env.example	Template — safe to commit
ecoagent-plan.md	Implementation plan and architecture decisions
architecture.png	Architecture blueprint diagram
fill.txt	PPT content fill for presentation

---

Disclaimer

Answers are AI-generated by IBM Granite. Impact figures labelled [Lookup] are sourced from IPCC AR6, BEE India, and CPCB data. Figures labelled [Estimate] are model-generated approximations. Always verify government schemes and legal/financial details with official sources.