🌱 Carbon Shift

A personal AI companion for reducing your carbon footprint, one everyday decision at a time.

Carbon Shift helps people understand the climate impact of their daily choices and turn sustainable intentions into practical action. From commute decisions and food choices to energy use and shopping habits, the app makes carbon tracking feel approachable, motivating, and easy to act on.

The goal is not perfection — Carbon Shift helps people build sustainable habits that are realistic, personal, and measurable.

---

✨ Key Features

• 📊 Carbon Footprint Estimation: Calculate emissions for transportation, diet, energy, clothing, and goods.
• 📝 Flexible Activity Tracking: Log only the categories you care about without rigid constraints.
• 🌿 Gentle Nudges: Encouraging, non-judgmental guidance instead of guilt-based pressure.
• 🔄 Optional Eco-Swaps: Receive lower-carbon alternatives strictly when you ask for recommendations.
• 📸 Snapshot Logging: Upload receipts, transit tickets, or photos to auto-estimate impact.
• 📈 Visual Footprint Summaries: Daily, weekly, and monthly recaps with progress breakdowns.
• 🏆 Milestone Badges: AI-generated celebratory badges to mark eco achievements.
• 🤝 Inclusive Experience: Respects all lifestyles, dietary choices, and commuting preferences.

---

⚙️ How It Works

Carbon Shift combines a conversational AI agent with practical sustainability tools:

• Gemini AI Agent: Interprets natural language requests and decides when to calculate emissions, compare alternatives, or summarize habits.
• Structured Tools: Precision calculation tools for carbon emissions, activity logging, and summary generation.
• Firestore DB: Persists user activity records and preferences seamlessly.
• Cloud Storage: Stores snapshot uploads and generated milestone badges.
• Frontend Proxy: Connects the web UI to the deployed agent over A2A (Agent-to-Agent) protocol.
• Memory Bank: Remembers user preferences (e.g., vehicle type, home energy) across sessions.

---

📐 Technical Architecture

flowchart LR
    User["User"] --> UI["Web UI"]
    UI --> Proxy["FastAPI Frontend Proxy"]
    Proxy --> Agent["A2A Agent Runtime"]
    Agent --> Gemini["Gemini AI Agent"]
    Gemini --> Tools["Carbon Shift Tools"]
    Tools --> Firestore["Firestore<br/>Activity Logs"]
    Tools --> Storage["Cloud Storage<br/>Snapshots & Badges"]
    Tools --> Solar["Open-Meteo API"]
    Tools --> Maps["OpenStreetMap Nominatim"]
    Gemini --> Memory["Memory Bank"]
    Memory --> Gemini
    Agent --> UI

Loading

---

📁 Repository Structure

app/
  agent.py                Core agent definition and tool orchestration
  tools.py                Emissions, logging, recap, solar, and travel tools
  a2ui_utils.py           Structured UI response helpers
  fast_api_app.py         FastAPI backend application
  app_utils/              Supporting utilities

frontend/
  main.py                 Browser-facing A2A proxy
  static/                 Web interface assets & index.html

tests/
  eval/                   Agent evaluation datasets and workflows

pyproject.toml             Python dependencies and project configuration
Dockerfile                 Container configuration
agents-cli-manifest.yaml   Agent deployment configuration

The agent is built with Google ADK and Gemini. Its tools calculate emissions, store activity records in Firestore, upload snapshots and badges to Cloud Storage, and fetch solar/location data from public APIs. The frontend uses FastAPI to proxy browser requests to the deployed agent via A2A.

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• uv package manager
• Google Cloud SDK (gcloud)
• Google Agents CLI (agents-cli)
• Google Cloud Credentials with Vertex AI & Firestore access

Installation

git clone https://github.com/SrishttiS/carbon-shift.git
cd carbon-shift

cp .env.example .env

uvx google-agents-cli setup
agents-cli install

Authenticate with Google Cloud:

gcloud auth application-default login
gcloud config set project <your-project-id>

Run the Agent Playground

agents-cli playground

Run the Web Frontend

The frontend connects to a deployed A2A agent:

export AGENT_ENGINE_RESOURCE_NAME="projects/<project-id>/locations/<location>/reasoningEngines/<agent-id>"
export AGENT_DIRECTORY="app"

cd frontend
python main.py

Open your browser at: http://localhost:8080

---

🧪 Testing and Evaluation

Run unit and integration tests:

uv run pytest tests/unit tests/integration

Evaluate agent performance:

agents-cli eval generate
agents-cli eval grade

---

☁️ Deployment

Deploy the agent to Google Agent Runtime:

gcloud config set project <your-project-id>
agents-cli deploy

For infrastructure and CI/CD enhancements:

agents-cli scaffold enhance
agents-cli infra cicd

---

🎯 Mission

Carbon Shift makes sustainability easier to practice by giving people the flexibility to track what matters to them, discover meaningful patterns, and make informed decisions at their own pace.