Merge pull request #21 from MIT-Emerging-Talent/gemma

Milestone 3: google-gemma

Author: CaesarGhazi

google_gemma/README.md

@@ -0,0 +1,70 @@
+# Project: “Green AI Automated RAG Testing with Gemma”
+
+## Overview
+
+We built an interactive retrieval-augmented generation (RAG) pipeline using the
+open-weight model *Gemma 2-2b* by Google and applied it to a standardized text
+and prompt set derived from the Apollo 11 lunar landing.
+
+**The goal:**
+
+* evaluate summarisation, reasoning, retrieval, paraphrasing, and creative tasks
+in a controlled, reproducible way — logging both answer quality and local
+sustainability metrics (energy/carbon emissions) via CodeCarbon.
+
+## Model
+
+**Model ID:** `google/gemma-2-2b-it` (Hugging Face)
+
+**Key attributes:**
+
+* Open-weight decoder-only model trained by Google
+* Supports text-generation and conversational usage
+* Suitable for research, summarisation, reasoning, and retrieval tasks
+* Lightweight enough for deployment on modest compute resources
+
+Model link: [https://huggingface.co/google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it)
+
+## What We Did
+
+1. Created a source document (`source.txt`) using ~1,400 words of selected
+   Wikipedia excerpts on Apollo 11.
+2. Defined a set of 21 standardised prompts spanning five categories:
+   summarisation, reasoning, RAG (fact retrieval), paraphrasing, and creative
+   generation.
+3. Built a document retrieval component using sentence-transformers to chunk
+   the document and select top-k relevant chunks per query.
+4. Developed an interactive notebook workflow that:
+
+   * Accepts a question at runtime
+   * Runs RAG → Draft → Critic → Refiner cycles using Gemma
+   * Tracks local CPU/GPU energy usage and CO₂ emissions with CodeCarbon
+   * Logs each question, answer, timestamp, and emissions to a single
+     append-only log file
+5. Logged runtime latency and emissions per query for performance and
+   sustainability insights.
+
+## How to Use
+
+1. Clone the repository:
+
+   ```bash
+   git clone <YOUR_REPO_URL>
+   cd your_repo_folder
+   ```
+
+2. Place your `source.txt` into `./data/`.
+
+3. Add your Hugging Face API key in the config cell.
+
+4. Run the notebook setup cells, then use the interactive prompt cell to ask
+   questions.
+
+## Why This Matters
+
+* **Reproducibility** — fixed source text and prompt set allow consistent
+  evaluation across models.
+* **Efficiency vs. Accuracy** — emissions are logged alongside outputs to
+  explore trade-offs between model performance and energy cost.
+* **Accessibility** — uses an open model and standard Python tools, making
+  research on small language models feasible even on laptops.

google_gemma/data/source.txt

@@ -0,0 +1,127 @@
+Apollo 11 – Lunar Descent and Moonwalk
+
+As the descent began, Armstrong and Aldrin found themselves passing landmarks on the
+surface two or three seconds early, and reported that they were “long”; they would land
+miles west of their target point. Eagle was traveling too fast. The problem could have been
+mascons—concentrations of high mass in a region or regions of the Moon’s crust that
+contains a gravitational anomaly, potentially altering Eagle’s trajectory.
+
+Five minutes into the descent burn, and 6,000 feet (1,800 m) above the surface of the
+Moon, the LM guidance computer (LGC) distracted the crew with the first of several
+unexpected 1201 and 1202 program alarms. Inside Mission Control Center, computer
+engineer Jack Garman told Guidance Officer Steve Bales it was safe to continue the
+descent, and this was relayed to the crew. The program alarms indicated “executive
+overflows”, meaning the guidance computer could not complete all its tasks in real-time and
+had to postpone some of them. Margaret Hamilton, the Director of Apollo Flight Computer
+Programming at the MIT Charles Stark Draper Laboratory later recalled: “To blame the
+computer for the Apollo 11 problems is like blaming the person who spots a fire and calls
+the fire department. Actually, the computer was programmed to do more than recognize
+error conditions. A complete set of recovery programs was incorporated into the software.
+The software’s action, in this case, was to eliminate lower priority tasks and re-establish
+the more important ones. The computer, rather than almost forcing an abort, prevented an
+abort. If the computer hadn’t recognized this problem and taken recovery action, I doubt if
+Apollo 11 would have been the successful Moon landing it was.”
+
+When Armstrong again looked outside, he saw that the computer’s landing target was in a
+boulder-strewn area just north and east of a 300-foot-diameter (91 m) crater, so he took
+semi-automatic control. Throughout the descent, Aldrin called out navigation data to
+Armstrong, who was busy piloting Eagle. Now 107 feet (33 m) above the surface,
+Armstrong knew their propellant supply was dwindling and was determined to land at the
+first possible landing site.
+
+Armstrong found a clear patch of ground and maneuvered the spacecraft towards it. They
+were now 100 feet (30 m) from the surface, with only 90 seconds of propellant remaining.
+Lunar dust kicked up by the LM’s engine began to impair his ability to determine the
+spacecraft’s motion.
+
+A light informed Aldrin that at least one of the 67-inch (170 cm) probes hanging from
+Eagle’s footpads had touched the surface and he said: “Contact light!” Three seconds later,
+Eagle landed and Armstrong shut the engine down. Aldrin immediately said “Okay, engine
+stop.”
+
+Eagle landed at 20:17:40 UTC on Sunday July 20 with 216 pounds (98 kg) of usable fuel
+remaining. Information available to the crew and mission controllers during the landing
+showed the LM had enough fuel for another 25 seconds of powered flight before an abort
+without touchdown would have become unsafe, but post-mission analysis showed that the
+real figure was probably closer to 50 seconds.
+
+Armstrong acknowledged Aldrin’s completion of the post-landing checklist with “Engine
+arm is off”, before responding to the CAPCOM, Charles Duke, with the words, “Houston,
+Tranquility Base here. The Eagle has landed.” Duke expressed the relief at Mission Control:
+“Roger, Twan—Tranquility, we copy you on the ground. You got a bunch of guys about to
+turn blue. We’re breathing again. Thanks a lot.”
+
+Preparations for Neil Armstrong and Buzz Aldrin to walk on the Moon began at 23:43 UTC.
+These took longer than expected; three and a half hours instead of two. Six hours and
+thirty-nine minutes after landing, Armstrong and Aldrin were ready to go outside, and
+Eagle was depressurized.
+
+Eagle’s hatch was opened at 02:39:33. Armstrong initially had some difficulties squeezing
+through the hatch with his portable life support system (PLSS). At 02:51 Armstrong began
+his descent to the lunar surface. Climbing down the nine-rung ladder, Armstrong pulled a
+D-ring to deploy the modular equipment stowage assembly (MESA) folded against Eagle’s
+side and activate the TV camera.
+
+Despite some technical and weather difficulties, black and white images of the first lunar
+EVA were received and broadcast to at least 600 million people on Earth.
+
+After describing the surface dust as “very fine-grained” and “almost like a powder”, at
+02:56:15, six and a half hours after landing, Armstrong stepped off Eagle’s landing pad and
+declared: “That’s one small step for [a] man, one giant leap for mankind.”
+
+Armstrong intended to say “That’s one small step for a man”, but the word “a” is not
+audible in the transmission, and thus was not initially reported by most observers of the live
+broadcast. When later asked about his quote, Armstrong said he believed he said “for a
+man”, and subsequent printed versions of the quote included the “a” in square brackets.
+
+About seven minutes after stepping onto the Moon’s surface, Armstrong collected a
+contingency soil sample using a sample bag on a stick. Twelve minutes after the sample
+was collected, he removed the TV camera from the MESA and made a panoramic sweep,
+then mounted it on a tripod. Aldrin joined Armstrong on the surface. He described the view
+with the simple phrase: “Magnificent desolation.”
+
+Armstrong said moving in the lunar gravity, one-sixth of Earth’s, was “even perhaps easier
+than the simulations … It’s absolutely no trouble to walk around.” Aldrin joined him on the
+surface and tested methods for moving around, including two-footed kangaroo hops. The
+PLSS backpack created a tendency to tip backward, but neither astronaut had serious
+problems maintaining balance. The fine soil was quite slippery.
+
+The astronauts planted the Lunar Flag Assembly containing a flag of the United States on
+the lunar surface, in clear view of the TV camera. Aldrin remembered, “Of all the jobs I had
+to do on the Moon the one I wanted to go the smoothest was the flag raising.” But the
+astronauts struggled with the telescoping rod and could only insert the pole about 2 inches
+(5 cm) into the hard lunar surface. Before Aldrin could take a photo of Armstrong with the
+flag, President Richard Nixon spoke to them through a telephone-radio transmission, which
+Nixon called “the most historic phone call ever made from the White House.”
+
+They deployed the EASEP, which included a Passive Seismic Experiment Package used to
+measure moonquakes and a retroreflector array used for the lunar laser ranging
+experiment. Then Armstrong walked 196 feet (60 m) from the LM to take photographs at
+the rim of Little West Crater while Aldrin collected two core samples. He used the
+geologist’s hammer to pound in the tubes—the only time the hammer was used on Apollo
+11—but was unable to penetrate more than 6 inches (15 cm) deep.
+
+The astronauts then collected rock samples using scoops and tongs on extension handles.
+Many of the surface activities took longer than expected, so they had to stop documenting
+sample collection halfway through the allotted 34 minutes. Aldrin shoveled 6 kilograms
+(13 lb) of soil into the box of rocks to pack them in tightly. Two types of rocks were found in
+the geological samples: basalt and breccia.
+
+While on the surface, Armstrong uncovered a plaque mounted on the LM ladder, bearing
+two drawings of Earth, an inscription, and signatures of the astronauts and President Nixon.
+The inscription read: “Here men from the planet Earth first set foot upon the Moon July
+1969, A. D. We came in peace for all mankind.”
+
+Mission Control used a coded phrase to warn Armstrong his metabolic rates were high, and
+that he should slow down. As metabolic rates remained generally lower than expected for
+both astronauts throughout the walk, Mission Control granted the astronauts a 15-minute
+extension.
+
+Aldrin entered Eagle first. With some difficulty the astronauts lifted film and two sample
+boxes containing 21.55 kilograms (47.5 lb) of lunar surface material to the LM hatch using a
+flat cable pulley device called the Lunar Equipment Conveyor (LEC). Armstrong then
+jumped onto the ladder’s third rung, and climbed into the LM. After transferring to LM life
+support, the explorers lightened the ascent stage for the return to lunar orbit by tossing out
+their PLSS backpacks, lunar overshoes, an empty Hasselblad camera, and other equipment.
+The hatch was closed again at 05:11:13. They then pressurized the LM and settled down to
+sleep.

google_gemma/emissions.csv

@@ -0,0 +1,5 @@
+timestamp,project_name,run_id,experiment_id,duration,emissions,emissions_rate,cpu_power,gpu_power,ram_power,cpu_energy,gpu_energy,ram_energy,energy_consumed,water_consumed,country_name,country_iso_code,region,cloud_provider,cloud_region,os,python_version,codecarbon_version,cpu_count,cpu_model,gpu_count,gpu_model,longitude,latitude,ram_total_size,tracking_mode,on_cloud,pue,wue
+2025-11-15T15:47:16,codecarbon,27c11b81-b7a7-47c9-ab82-9ae317559fe9,5b0fa12a-3dd7-45bb-9766-cc326314d9f1,45.95574010000564,0.0005071162574599,1.103488391997087e-05,42.5,0.0,10.0,0.0007198499136804,0.0,0.0001693503708332,0.0008892002845137,0.0,Egypt,EGY,,,,Windows-11-10.0.26100-SP0,3.13.5,3.0.8,12,12th Gen Intel(R) Core(TM) i5-1235U,,,,,7.692127227783203,machine,N,1.0,0.0
+2025-11-15T15:51:00,codecarbon,7005ea2e-d9a3-40aa-900e-f95b5e5623a2,5b0fa12a-3dd7-45bb-9766-cc326314d9f1,158.46234359999653,0.0013179222183238,8.316942614774643e-06,42.5,0.0,10.0,0.0018707337542361,0.0,0.0004401698980555,0.0023109036522917,0.0,Egypt,EGY,,,,Windows-11-10.0.26100-SP0,3.13.5,3.0.8,12,12th Gen Intel(R) Core(TM) i5-1235U,,,,,7.692127227783203,machine,N,1.0,0.0
+2025-11-15T15:52:55,codecarbon,f2cce301-9b4f-4e6a-b97d-5179efd64332,5b0fa12a-3dd7-45bb-9766-cc326314d9f1,47.64462380000623,0.0003962538208029,8.316863251272021e-06,42.5,0.0,10.0,0.0005624669925697,0.0,0.0001323421463889,0.0006948091389586,0.0,Egypt,EGY,,,,Windows-11-10.0.26100-SP0,3.13.5,3.0.8,12,12th Gen Intel(R) Core(TM) i5-1235U,,,,,7.692127227783203,machine,N,1.0,0.0
+2025-11-15T16:05:41,codecarbon,685c527f-27ef-47b7-9955-a38ea34424e8,5b0fa12a-3dd7-45bb-9766-cc326314d9f1,23.700261899997713,0.0014245466564409932,6.010678964020776e-05,42.5,0.0,10.0,0.002022092715903293,0.0,0.0004757709861110521,0.002497863702014345,0.0,Egypt,EGY,,,,Windows-11-10.0.26100-SP0,3.13.5,3.0.8,12,12th Gen Intel(R) Core(TM) i5-1235U,,,,,7.692127227783203,machine,N,1.0,0.0

google_gemma/emissions_base_27c11b81-b7a7-47c9-ab82-9ae317559fe9.csv

@@ -0,0 +1,2 @@
+task_name,timestamp,project_name,run_id,duration,emissions,emissions_rate,cpu_power,gpu_power,ram_power,cpu_energy,gpu_energy,ram_energy,energy_consumed,water_consumed,country_name,country_iso_code,region,cloud_provider,cloud_region,os,python_version,codecarbon_version,cpu_count,cpu_model,gpu_count,gpu_model,longitude,latitude,ram_total_size,tracking_mode,on_cloud
+RAG Query,2025-11-15T15:47:13,codecarbon,27c11b81-b7a7-47c9-ab82-9ae317559fe9,42.43775189999724,0.00035304605540907173,8.316975773721854e-06,42.5,0.0,10.0,0.0005011351056248814,0.0,0.00011791160861111065,0.0006190467142359921,0.0,Egypt,EGY,,,,Windows-11-10.0.26100-SP0,3.13.5,3.0.8,12,12th Gen Intel(R) Core(TM) i5-1235U,,,,,7.692127227783203,machine,N