Spaces:
Paused
Paused
| # AGENTS.md | |
| This file provides guidance to agents when working with code in this repository. | |
| ## Project | |
| EcoAgent v2 — A Gradio Blocks web app for eco lifestyle advice, powered by **IBM Granite** (`ibm/granite-4-h-small`) via the `ibm-watsonx-ai` SDK. India-focused with 4 tabs: Chat, Dashboard, Recycling Guide, Household Profile. | |
| **Classification:** Agentic AI Application with Prompt Engineering | |
| **IBM Orchestrate REST API is NOT used** — direct SDK calls to watsonx.ai only. | |
| ## Stack | |
| - **Runtime:** Python 3.14 via `uv` (venv at `.venv/`) | |
| - **Package manager:** `uv` — always use `uv pip install` / `uv run python`, NOT bare `pip` or `python` | |
| - **UI Framework:** Gradio 6.20 (ultra-light eco green theme) | |
| - **AI Model:** IBM Granite 4 H Small (`ibm/granite-4-h-small`) via watsonx.ai eu-de | |
| - **SDK:** `ibm-watsonx-ai` >= 1.1.15 (APIClient + ModelInference pattern) | |
| - **Agent Tools:** 5 tools (Impact Calculator, Recycling Guide, Web Search, Scheme Checker, Household Profiler) | |
| - **System Python is 3.11 (Miniconda)** — unrelated to this project's venv | |
| - **Target deploy:** Hugging Face Spaces (Gradio SDK) | |
| ## Key Commands | |
| ```bash | |
| uv pip install -r requirements.txt # install deps | |
| uv run python app.py # run locally → http://localhost:7860 | |
| ``` | |
| ## Critical Gotchas | |
| - **`.env` is gitignored** — cannot be written by file tools. Use `Set-Content` PowerShell command instead. | |
| - **`WATSONX_PROJECT_ID` is mandatory** — the SDK raises an error without it. Get it from: `https://eu-de.dataplatform.cloud.ibm.com` → project → Manage → General → Project ID. | |
| - **Region is eu-de (Frankfurt)** — `WATSONX_URL=https://eu-de.ml.cloud.ibm.com`. Do not use `us-south`. | |
| - **Model lazy-init** — `_get_model()` in `watsonx_client.py` initialises `ModelInference` on the first call, not at import. Import-time errors = missing env vars. First-call errors = bad project ID or model access. | |
| - **`load_dotenv(".env")` explicit path** — both `app.py` and `watsonx_client.py` call this. The default `load_dotenv()` looks for `.env` by name; the explicit path ensures it works regardless of CWD. | |
| - **Chat history format (Gradio 6.x)** — History uses structured content blocks: `{"role": "user", "content": [{"type": "text", "text": "..."}]}`. The `chat_submit()` function extracts text for the API call and returns structured blocks for display. | |
| - **`dashboard_html` is defined inside the Tab 2 block** — it's referenced by `save_profile()` in Tab 4. Both must be inside the same `gr.Blocks` context. | |
| - **Theme/CSS in Gradio 6.x** — `theme` and `css` parameters go in `demo.launch()`, NOT in `gr.Blocks()` constructor. | |
| - **SSL_CERT_FILE** — The app auto-detects and sets the correct certifi path on startup. | |
| - **Agent Mode** — When enabled, uses agentic loop with tool calls. Max 5 iterations to prevent infinite loops. | |
| - **Web Search Date Fix** — IBM Granite ignores search results and hallucinates outdated dates. Fixed by injecting `TODAY'S DATE` into the system prompt and adding `Search conducted on: <date>` to search results. Never rely on LLM training data for time-sensitive information. | |
| ## Architecture | |
| ``` | |
| .env | |
| └─ WATSONX_API_KEY, WATSONX_PROJECT_ID, WATSONX_URL | |
| │ | |
| ▼ | |
| watsonx_client.py | |
| ├─ AGENT_INSTRUCTIONS ← 86-line system prompt (persona, tone, rules, format) | |
| ├─ IMPACT_TABLE ← 20 actions with CO2/water/waste lookup values | |
| ├─ PRODUCT_RECS ← static eco-product recs per material category | |
| ├─ INDIAN_CITIES ← 15 major Indian cities for recycling guide | |
| ├─ _get_model() ← lazy-init APIClient + ModelInference ( Granite 4 H Small ) | |
| ├─ get_eco_answer() ← multi-turn chat, builds [system]+messages list | |
| ├─ get_recycling_guide() ← single-turn recycling lookup call | |
| └─ compute_session_impact() ← aggregates logged actions → metric dict | |
| │ | |
| ▼ | |
| tools.py (Agent Tools) | |
| ├─ TOOLS ← 5 tool definitions (JSON Schema format) | |
| ├─ SCHEMES_DB ← 8 Indian government eco schemes | |
| ├─ execute_tool() ← routes tool calls to appropriate functions | |
| ├─ _execute_calculate_impact() ← reuse compute_session_impact() | |
| ├─ _execute_recycling_guide() ← reuse get_recycling_guide() | |
| ├─ _execute_web_search() ← DuckDuckGo search (free, no API key) + date header | |
| ├─ _execute_check_scheme() ← static lookup + web search fallback | |
| └─ _execute_analyze_household() ← LLM-powered personalized analysis | |
| │ | |
| ▼ | |
| agent.py (Agentic Loop) | |
| ├─ agent_loop() ← reason → act → observe → repeat (max 5 iterations) | |
| ├─ AGENT_SYSTEM_PROMPT ← tool usage rules + TODAY'S DATE injection + search trust rules | |
| ├─ _extract_tool_call() ← parses JSON tool calls from LLM response | |
| └─ format_tool_calls() ← formats tool usage for UI display | |
| │ | |
| ▼ | |
| app.py (Gradio Blocks — ultra-light theme) | |
| ├─ Tab 1: Chat ← chatbot + Agent Mode toggle + tool display + action chips | |
| ├─ Tab 2: Dashboard ← HTML metric cards from compute_session_impact() | |
| ├─ Tab 3: Recycling ← material+city dropdowns → get_recycling_guide() | |
| └─ Tab 4: Profile ← household form → profile_state (gr.State) | |
| ``` | |
| ## Agent Mode | |
| ### How It Works | |
| 1. User enables "Agent Mode" checkbox in Chat tab | |
| 2. User sends a message | |
| 3. Agent loop begins (max 5 iterations): | |
| - LLM receives message + tool definitions | |
| - LLM decides to call a tool (or gives final answer) | |
| - If tool call: execute tool, feed result back to LLM, repeat | |
| - If final answer: return response to user | |
| 4. Tool calls are displayed below the chatbot | |
| ### Available Tools | |
| | Tool | Purpose | When to Use | | |
| |------|---------|-------------| | |
| | `calculate_impact` | Get CO2/water/waste numbers | User asks about impact, wants numbers | | |
| | `get_recycling_guide` | City-specific recycling instructions | User asks how to recycle, where to dispose | | |
| | `web_search` | Search latest news, schemes, services | User asks about recent events, new policies | | |
| | `check_scheme` | Indian government scheme details | User asks about subsidies, government programs | | |
| | `analyze_household` | Personalized action plan | User wants comprehensive recommendations | | |
| ### Agent Loop Safety | |
| - **MAX_ITERATIONS = 5** — prevents infinite loops | |
| - **MAX_TOOL_CALLS_BEFORE_SYNTHESIS = 2** — forces LLM to answer after 2 tool calls | |
| - **TODAY'S DATE injection** — system prompt includes current date so LLM doesn't hallucinate outdated info | |
| - **Search result date header** — web search results include `Search conducted on: <date>` to reinforce recency | |
| - **Graceful degradation** — if tool fails, continues with error message | |
| - **Tool call logging** — all tool invocations are tracked and displayed | |
| ## Environment Variables | |
| | Variable | Source | Purpose | | |
| |---|---|---| | |
| | `WATSONX_API_KEY` | `.env.example` | IBM Cloud API key | | |
| | `WATSONX_PROJECT_ID` | watsonx.ai Studio | SDK project scope — required | | |
| | `WATSONX_URL` | `https://eu-de.ml.cloud.ibm.com` | eu-de watsonx.ai endpoint | | |
| ## Agentic AI Pattern | |
| This project uses **agentic AI** to transform IBM Granite into a domain-specific eco advisor with tool use: | |
| - **System Prompt:** 86-line `AGENT_INSTRUCTIONS` + tool usage instructions | |
| - **Tool Definitions:** 5 tools with JSON Schema parameters | |
| - **Agent Loop:** Multi-step reasoning with tool execution | |
| - **Static Knowledge:** `IMPACT_TABLE` (20 eco actions) and `PRODUCT_RECS` (8 material categories) | |
| - **Dynamic Context:** Household profile (members, location, habits) injected per session | |
| - **Tool Execution:** Real-time tool calls with result feedback | |
| - **Output Format:** Fixed 4-part structure (Quick Tip → Why it Matters → Impact → Optional Resource) | |
| - **Guardrails:** Never invent stats, label [Lookup] vs [Estimate], no medical/financial advice | |
| ## Prompt Engineering Pattern | |
| This project uses **prompt engineering** to transform IBM Granite into a domain-specific eco advisor: | |
| - **System Prompt:** 86-line `AGENT_INSTRUCTIONS` defining persona, output format, focus areas, and guardrails | |
| - **Static Knowledge:** `IMPACT_TABLE` (20 eco actions) and `PRODUCT_RECS` (8 material categories) injected via prompt | |
| - **Dynamic Context:** Household profile (members, location, habits) injected per session | |
| - **Output Format:** Fixed 4-part structure (Quick Tip → Why it Matters → Impact → Optional Resource) | |
| - **Guardrails:** Never invent stats, label [Lookup] vs [Estimate], no medical/financial advice | |
| ## UI Theme | |
| Ultra-light eco green theme: | |
| - 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 | |
| - Chatbot with welcome placeholder and white-flash prevention CSS | |
| ## 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 | | |
| | `AGENTS.md` | This file — agent guidance | | |
| | `README.md` | HF Spaces front-matter, setup instructions | | |
| | `ecoagent-plan.md` | Implementation plan and architecture decisions | | |
| | `architecture.png` | Architecture blueprint diagram | | |
| | `fill.txt` | PPT content fill for presentation | | |
| ## Deleted Files (v1 → v2) | |
| - `rag_pipeline.py` → replaced by `watsonx_client.py` | |
| - `ibm-credentials.env` → replaced by `.env` | |
| - `embed.txt` → was a debugging artifact; deleted | |