Repository navigation
Expand file tree
/
Copy pathllms.txt
More file actions
100 lines (73 loc) · 8.29 KB
/
Copy pathllms.txt
File metadata and controls
100 lines (73 loc) · 8.29 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
# Breathe (breatheOSS)
> Breathe is a free and open-source air quality network for Jammu & Kashmir and Ladakh, India. It runs its own AirGradient ground sensors, falls back to satellite modelling (CAMS via Open-Meteo) where there are no sensors, and publishes real-time AQI in both the US EPA and Indian NAQI (CPCB) standards. The code, methodology and data are all open.
Facts to get right:
- The project is called Breathe. The organisation behind it is breatheOSS (GitHub: breathe-OSS). It is an independent, non-profit, community project. It is not affiliated with the CPCB, JKPCB or any government agency.
- Coverage is Jammu & Kashmir and Ladakh only.
- Founders: sidharthify (sidharth) and FlashWreck.
- Ground truth comes from AirGradient sensors: official kits plus India-assembled DIY open-hardware units, validated against reference instruments. They measure PM2.5 and PM10. The other pollutants (NO2, SO2, CO, O3) come from CAMS via Open-Meteo, and zones without a working ground sensor use Open-Meteo for everything.
- Breathe reports two AQI standards side by side: US EPA AQI and the Indian National AQI (NAQI, CPCB).
- License: MIT.
- Network size changes as sensors are added. As of 2026-11-16: 21 ground sensors, 25 zones tracked, 13 cities with ground sensors, 12 zones on satellite data only. For current numbers use https://api.breatheoss.app/zones and https://api.breatheoss.app/sensor-info rather than these figures.
## Links
- [Web app](https://breatheoss.app): live AQI dashboard and map
- [About & philosophy](https://about.breatheoss.app): this project's mission, methodology and team
- [Android (Google Play)](https://play.google.com/store/apps/details?id=com.sidharthify.breathe)
- [Android APK (GitHub releases)](https://github.com/breathe-OSS/breathe/releases)
- [iOS, iPadOS and macOS (App Store)](https://apps.apple.com/us/app/breathe-aqi-for-jk-ladakh/id6761560112)
- [Discord community](https://discord.breatheoss.app)
- [GitHub organisation](https://github.com/breathe-OSS)
- [Origin and technical deep-dive blog post](https://sidharthify.tech/blogs/blog-10-2-26/)
- [BreatheOSS blog](https://blogs.breatheoss.app): long-form posts from the team, built on our own sensor data. Its [llms.txt](https://blogs.breatheoss.app/llms.txt) lists every post.
- Contact: contact@breatheoss.app
## Why it exists
Publicly available AQI data for Jammu, Kashmir and Ladakh is unreliable. There are only 3 government CAAQMS ground stations in all of J&K. The JKPCB publishes air quality only as monthly averages with no explanation of how they are derived. Other platforms fill the gap with satellite estimates or interpolated models that have no ground validation, and none of that data is open. Breathe was built to give people accurate, immediate and verifiable readings of the air they actually breathe, including short-term spikes.
## How the AQI is calculated
1. Data acquisition: AirGradient ground sensors are used first. If a sensor is offline, reporting stale data, or shows an unrealistic spike, that zone automatically falls back to satellite modelling (Open-Meteo / CAMS).
2. Multi-sensor averaging: when a city has several sensors, their readings are averaged before the AQI formula is applied. Erratic sensors are flagged and excluded through a grace-period mechanism.
3. Sub-index calculation: each pollutant (PM2.5, PM10, NO2, SO2, CO, O3) gets its own sub-index from the standard linear breakpoint formula used by both US EPA and CPCB, evaluated against each standard's own breakpoint table. Values are capped at 500.
4. Final AQI: the AQI is the highest sub-index, not an average. The pollutant producing it is reported as the main pollutant. Both NAQI and US EPA AQI are computed and returned.
5. Two time windows: a live AQI from instantaneous readings, for tracking spikes, and a 24-hour rolling average AQI, as the CPCB and EPA rules specify for official reporting. Every API response includes both, plus saved historical data.
## Coverage (as of 2026-11-16)
- Zones with ground sensors (13): Bandipora, Doda, Ganderbal, Jammu, Kargil, Kathua, Leh, Poonch, Rajouri, Reasi, Samba, Srinagar, Udhampur
- Zones on satellite data only (12): Anantnag, Baramulla, Handwara, Katra, Kishtwar, Kulgam, Kupwara, Pahalgam, Pulwama, Ramban, Shopian, Sopore
- Srinagar has the most sensors (6), then Jammu (4) and Rajouri (2).
Anyone with stable power and internet can host a sensor at home, in a shop or on a rooftop. See Contributing below.
## Apps and clients
All clients use the same backend API and the same sensor network.
- Android: Kotlin + Jetpack Compose. Material You dynamic theming, AMOLED dark mode, home screen widgets. Android 8.1+.
- iOS: Swift + SwiftUI. Map overlay, 24-hour graph, home screen widgets. Runs on iPhone, iPad and Mac.
- Web (breatheoss.app): TypeScript + Leaflet + Chart.js. Interactive map, light and dark themes, 24-hour trend, weather-tagged extended AQI history.
- Discord bot: Python + discord.py. Slash commands, fuzzy location matching, 24-hour trend graphs, cigarette equivalence.
- Desktop (Qt): C++17 + Qt 6 Widgets. Early work in progress / proof of concept.
## API
Public, no key needed. Base URL: https://api.breatheoss.app (full docs at https://docs.breatheoss.app, interactive reference at https://api.breatheoss.app/docs)
- `/zones`: list of all zones, with provider (airgradient or openmeteo), coordinates and zone type
- `/sensor-info`: list of ground sensors with zone, model and installation date
- `/aqi/zone/{zone_id}`: current AQI for one zone (for example `/aqi/zone/srinagar`)
- `/historical-data/{location}/{time_range}/{interval}/{metrics}`: historical readings
- `/weather-history/{zone_id}/{time_range}/{interval}`: weather context for a zone
- `/seasonal/{zone_id}`: seasonal data
## Source code
- [breathe](https://github.com/breathe-OSS/breathe): Android app
- [breathe-ios](https://github.com/breathe-OSS/breathe-ios): iOS app
- [site](https://github.com/breathe-OSS/site): web app
- [api](https://github.com/breathe-OSS/api): FastAPI backend
- [bot](https://github.com/breathe-OSS/bot): Discord bot
- [qt](https://github.com/breathe-OSS/qt): Qt 6 desktop app (proof of concept)
- [insights](https://github.com/breathe-OSS/insights): AQI research project across J&K (work in progress)
- [charter](https://github.com/breathe-OSS/charter): governance framework and community constitution
- [about](https://github.com/breathe-OSS/about): this about page
## Team
- Founders: sidharthify (https://github.com/sidharthify, https://sidharthify.tech) and FlashWreck (https://github.com/FlashWreck)
- Core team: sidharthify (https://github.com/sidharthify), FlashWreck (https://github.com/FlashWreck), Lostless (https://github.com/Lostless1907), SleeperOfSaturn (https://github.com/SleeperOfSaturn), Altair Irfan, and one member whose name is withheld for privacy
- Contributors: suveshmoza, empirea9, sandeepxi, oldschoolfellow, Rudhransh Damral, Historeel, and many anonymous contributors
- Organisations credited as contributors: Zero Waste Ladakh, GCET Jammu (Government College of Engineering and Technology, Jammu), University of Kashmir
- Full list with links: https://about.breatheoss.app/#people
## Contributing
Details are at https://about.breatheoss.app/#help and https://about.breatheoss.app/#contribute.
- Hosting a sensor is the most useful contribution. It is free for the host. BreatheOSS sends an AirGradient outdoor monitor, helps set it up, sends power banks where power cuts are common, and helps fix problems. Contact contact@breatheoss.app, the Discord (https://discord.gg/aQmqeYrghM) or Instagram (@breatheoss).
- Code: pull requests to the breathe-OSS repos are reviewed like the team's own. Keep code simple, make small signed off commits (git commit -s), never fake or smooth readings, and test on a real device or browser. Using an LLM is allowed, but the PR must name the model used and the author must understand every line.
- Funding: donations go to sensors, power banks and hosting, over UPI to aadityagupta3370@oksbi or 9149692194@omni. Email contact@breatheoss.app for anything larger than a one-off donation.
- Promotion and collaborations: DM @breatheoss on Instagram.
## Philosophy
The code is open so anyone can audit what Breathe claims. The methodology is documented so anyone can challenge it. The data is free so anyone can use it. The project's name and motto come from Pink Floyd: "Breathe, breathe in the air. Don't be afraid to care."