AGENTS.md

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

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