gagelink

Hydrologiedaten für KI-Agenten. Flusspegel, Abfluss, Hochwasservorhersagen, Wasserqualität, Einzugsgebiete und Satelliten-Wasseroberflächenhöhen von USGS, NOAA und SWOT. Jeder Wert trägt seine Einheit, das Bezugssystem, von dem aus er gemessen wird, seine Zeitzone und ob der Datensatz vorläufig oder genehmigt ist.

mcp-name: io.github.Adeniyikayodee/gagelink

Vor-Alpha. Die API wird sich ändern.

Als MCP-Server ausführen

{
  "mcpServers": {
    "gagelink": {
      "command": "uvx",
      "args": ["--from", "gagelink", "gagelink-mcp"]
    }
  }
}

Für den Start ist kein Konto erforderlich. Ein kostenloser Schlüssel von api.waterdata.usgs.gov/signup erhöht das Kontingent von 50 Anfragen pro Stunde auf 1.000; setzen Sie ihn als GAGELINK_API_KEY.

Oder als Bibliothek:

pip install gagelink

Related MCP server: Environment Agency Flood Monitoring MCP Server

Fragen, die es beantwortet

• Wie hoch ist der Fluss an einem Pegel, und wie verhält sich das zur Hochwasserstufe?

• Wie viel Freibord besteht zwischen dem Wasser und einer vermessenen Deichkrone?

• Wie hoch ist der Abfluss jetzt, und welcher Anteil des Rekordhöchstwertes ist das?

• Was wird für die nächsten Tage vorhergesagt, und überschreitet es eine Hochwasserkategorie?

• Was liegt flussaufwärts oder flussabwärts von diesem Punkt entlang des Flusses?

• Wie groß ist das Einzugsgebiet, das zu diesem Punkt entwässert?

• Was hat diese Station über einen Zeitraum aufgezeichnet, und wurde dieser Datensatz seitdem überarbeitet?

• Wie hoch ist die Wasseroberfläche eines Flusses ohne Pegel?

• Ist eine Messung vorläufig oder genehmigt, und wie alt ist sie?

Was es ablehnt, und warum das der Punkt ist

Eine Pegelhöhe wird vom eigenen Bezugssystem der Station gemessen, nicht vom Meeresspiegel. Wenn man eine vermessene Höhe davon subtrahiert, erhält man eine Zahl, die wie ein Freibord aussieht und um dutzende Fuß falsch ist – in der Richtung, die einen Deich als sicher ausweist. Beide Werte sind Längen in Fuß, also trennt sie dimensional nichts, und keine Einheitenbibliothek fängt das ab.

Dieses Paket lehnt diese Subtraktion ab, statt sie zu beantworten, und describe_location gibt den Offset zurück, der sie wohldefiniert macht. Dasselbe gilt für Satellitenhöhen, die auf einem Geoid liegen, und für modellierte Abflüsse, hinter denen möglicherweise keine Messung steht.

Warum

Wasserdienste veröffentlichen bereits alles, was nötig ist, um ihre Daten korrekt zu verwenden. Ein Abfluss gibt seine Einheit an, ein Pegelstand gibt das Bezugssystem an, von dem aus gemessen wird, eine Messung gibt an, ob sie vorläufig oder genehmigt ist, und ein Zeitstempel gibt seinen Offset an. Clients parsen typischerweise die Zahl und verwerfen den Rest, und die Fehler folgen daraus.

Das Versagen ist messbar. In einem Benchmark von 4.288 Läufen über elf Modelle stellte quantity-guard fest, dass jedes Modell, das das Rechenwerkzeug erreichte, einen in Kubikfuß pro Sekunde veröffentlichten Abfluss in einen Parameter einspeiste, der in Kubikmetern pro Sekunde deklariert war, ohne umzurechnen – bei fast jedem Lauf, was eine Antwort ergab, die 35,3-mal zu groß war, ohne dass etwas in der Ausgabe darauf hindeutete. Sieben von elf Modellen differenzierten einen Pegelstand auf einem lokalen Pegel-Bezugssystem gegen eine Höhe auf NAVD88 und meldeten das Ergebnis als Freibord.

gagelink ruft die Daten mit den Metadaten ab und verwendet quantity-guard, um sie durchzusetzen, wenn die Werkzeuge des Agenten aufgerufen werden.

Aktuelle Oberfläche

from gagelink import Service

service = Service(api_key="...")           # free key, see below
page, retrieval = service.items(
    "latest-continuous",
    monitoring_location_id="USGS-07374000",
    parameter_code="00060",
)

retrieval.record()      # what a replay needs: url, params, time, status, sha256
retrieval.quota         # Quota(limit=1000, remaining=999)

items gibt die geparste Seite und den Datensatz des Abrufs zusammen zurück, nicht nur die Seite, weil eine Zahl, die eine Antwort erreicht, ohne die Anfrage, die sie erzeugt hat, nicht reproduzierbar ist, und die Kopplung am einzigen Einstiegspunkt billiger ist, als sich zu merken, sie aufzuzeichnen.

Nutzlasten werden zu Größen, die ihre eigenen Bezugssysteme tragen:

from gagelink import location_from, readings_from

page, _ = service.items("monitoring-locations", id="USGS-06730500")
station = location_from(page["features"][0])
station.register()                       # its datum, and the offset where one is published

observations, _ = service.items("latest-continuous", monitoring_location_id=station.id)
readings = {r.parameter_code: r for r in readings_from(observations, station)}

readings["00060"].value       # Q(1.35 ft³/s (provisional))
readings["00065"].value       # Q(9.11 ft (GAGE:06730500, provisional))
readings["00065"].value.to_datum("NGVD29")   # Q(4869.11 ft (NGVD29, provisional))
readings["00065"].value.to_datum("NAVD88")   # DatumConversionUnavailable

Diese letzte Zeile ist der Punkt. Boulder Creek veröffentlicht seine Höhe auf NGVD29, also löst sich ein Pegelstand dort auf NGVD29 auf und lehnt NAVD88 ab, da der Offset zwischen beiden je nach Ort variiert und hier nicht veröffentlicht wird. Das moderne Bezugssystem anzunehmen, weil es das moderne ist, ist ein Freibordfehler einen Schritt früher als der, nach dem jeder sucht.

Was nicht veröffentlicht wird, und was dagegen getan wird

altitude und drainage_area kommen als nackte Zahlen zurück, und das Sammelschema gibt für keine von beiden eine Einheit an, also werden die USGS-Konventionen von Fuß und Quadratmeilen in normalise.py angewendet, wo sie sichtbar sind, statt weiter unten stillschweigend angenommen zu werden.

Eine Einheit ohne Zuordnung wird abgelehnt statt geraten. Eine Einheit, die pint parsen kann, für die dieses Paket aber keinen Eintrag hat, wird mit einer Warnung durchgelassen, weil parsebar nicht dasselbe ist wie verstanden: ppt liest pint als Teile pro Billion und bedeutet bei USGS Teile pro Tausend, was ein Faktor von 10^9 zwischen zwei dimensional identischen Messwerten ist.

Ein fehlender Wert ist hier null statt der -999999, die WaterServices veröffentlicht hat, und er bleibt fehlend. Der Qualifizierer sagt warum, ["EQUIP"] für einen Geräteausfall.

Die Genehmigung kommt als Provisional oder Approved statt als P oder A, und Zustandscodes stufen unterhalb ihres Prüfstatus ein, also wird ein genehmigter Datensatz einer eisbeeinflussten Messung als unverifiziert statt als genehmigt eingestuft.

Die Zeitzone der Station wird aus der Abkürzung zusammen mit dem Sommerzeit-Flag aufgelöst, da MST ohne Sommerzeit Arizona ist und MST mit Sommerzeit Colorado, und sie unterscheiden sich acht Monate im Jahr um eine Stunde.

Werkzeuge

Eine Sitzung hält den Zustand für eine Frage und den Datensatz dessen, was sie beantwortet hat. Werkzeuge geben ein Ergebnis zurück, statt eine Ausnahme zu werfen, weil ein Fehler mit einer Reparatur ein Modell im Gespräch hält, wo es sich selbst korrigieren kann, und eine geworfene Ausnahme die Runde beendet.

from gagelink import Session, Toolkit

with Session(question="How high is the Potomac at Little Falls?") as work:
    kit = Toolkit(work)
    kit.describe_location("USGS-01646500")
    kit.get_latest("USGS-01646500", parameters=["00060", "00065"], max_age_hours=6)

    work.audit("The gage height is 3.02 ft and the discharge is 2960 ft3/s.")
    work.manifest()

Jeder Wert verlässt das System mit seinem Bezugssystem, und jeder wird in einem Hauptbuch erfasst, sodass eine Antwort gegen das tatsächlich Abgerufene geprüft werden kann:

[ok]         3.02 ft        from get_latest.00065
[ok]         2960 ft3/s     from get_latest.00060
[UNSOURCED]  116000 ft3/s   no tool output produced this value

Die dritte Zeile ist die Prüfung, die ihren Platz verdient. Die Zahl ist ein plausibler Abfluss für diesen Fluss, sie ist falsch, und nichts an dem Satz, der sie enthält, deutet darauf hin.

Eine Reihe wird als Handle mit einer Zusammenfassung und einer Stichprobe von zwanzig Punkten zurückgegeben statt als ihre Punkte, da ein Jahr mit 15-Minuten-Aufzeichnung 35.000 Werte umfasst. Das Handle wird aus der Abfrage abgeleitet, die es erzeugt hat, sodass eine Wiederholung derselben Sitzung dasselbe Handle erzeugt. Ergebnisse sind budgetiert, und alles, was verworfen wird, um innerhalb des Budgets zu bleiben, wird im Ergebnis angegeben, da eine stille Kürzung wie Abdeckung aussieht.

Als MCP-Server

export GAGELINK_API_KEY=...        # free, see below
gagelink-mcp

{"mcpServers": {"gagelink": {"command": "gagelink-mcp"}}}

Elf Werkzeuge, nicht mehr. Ein Modell verschlechtert sich, wenn seine Werkzeugliste wächst, also ist die Oberfläche nach Verben organisiert, und die Wahl, welcher Dienst antwortet, trifft der Server, statt dem Aufrufer überlassen zu werden.

Die Werkzeugbeschreibungen sind Teil des Produkts, nicht dessen Dokumentation. In der quantity-guard-Evaluierung stellte sich heraus, dass die Deklaration physikalischer Metadaten im Schema ohne Durchsetzung immer noch ein Drittel der Läufe rettete, die in der Basislinie scheiterten, also wirkt das, was eine Beschreibung über Bezugssysteme, Einheiten und vorläufige Datensätze sagt, bevor irgendeine Validierung läuft.

Ein Werkzeugfehler kommt als Inhalt zurück, der als Fehler markiert ist, statt als Protokollfehler, was die Reparatur vor dem Modell hält, statt die Runde zu beenden. Die Sitzung wird bei initialize zurückgesetzt, sodass die Größen einer Unterhaltung nicht im Manifest einer anderen auftauchen können.

Freibord, wo die Gefahren zusammentreffen

python demo/freeboard.py führt das Ganze offline aus aufgezeichneten Antworten aus:

stage      3.02 ft (GAGE:01646500)
crest      41 ft (NAVD88)

The two are both lengths, so nothing dimensional separates them:
  refused: cannot difference an elevation on NAVD88 against one on GAGE:01646500

The gage's zero is at 37.04 ft NAVD88, so the stage is 40.06 ft (NAVD88).
  freeboard = 0.94 ft

Ignoring the datum gives 37.98 ft of margin where 0.94 ft is correct,
overstating it by a factor of 40.

Ein Pegelstand und eine vermessene Höhe sind beide Längen in Fuß, und die Subtraktion des einen vom anderen ergibt eine Zahl, die wie ein Freibord aussieht. Der Fehler ist still, er läuft in die Richtung, einen Deich als sicher zu melden, und keine Einheitenbibliothek verhindert ihn, weil nichts an den Einheiten falsch ist.

Vorhersagen

Hochwasserschwellen stammen vom NOAA National Water Prediction Service, da ein Pegelstand nichts bedeutet, bis er gegen den Stand gesetzt wird, bei dem der Fluss über die Ufer tritt. Drei Dinge in dieser Nutzlast müssen behandelt werden, und keines ist ausgeschildert:

Der Abfluss erscheint als cfs in den Hochwasserkategorien und als kcfs im Statusblock derselben Antwort, also ist ein Aufrufer, der beide liest und sie gleich behandelt, um einen Faktor von tausend daneben.

Schwellen, die nie gesetzt wurden, werden als -9999 veröffentlicht statt weggelassen. Das ist dimensional gültig, nur im Vorzeichen plausibel und besteht jede nachgelagerte Prüfung, also wird es als das Sentinel gelesen, das es ist.

Pegelstände liegen auf dem eigenen Bezugssystem des Pegels, nicht auf einem nationalen. Der dort veröffentlichte beobachtete Pegelstand stimmt exakt mit USGS-Parameter 00065 an derselben Station und zur selben Zeit überein, was der Beleg für diese Lesart ist, und es ist der Grund, warum eine Hochwasserstufe gegen eine Pegelhöhe differenziert wird, aber nicht gegen eine vermessene Höhe.

Das Flussnetzwerk

Die Navigation verläuft entlang des Flusses statt innerhalb eines Radius, was die Unterscheidung ist, die die Antwort nützlich macht: Ein Pegel zwei Meilen entfernt im nächsten Einzugsgebiet ist hier flussaufwärts von nichts. Richtungen sind Wörter statt der zweibuchstabigen Codes des Index, also umfasst upstream Nebenflüsse und upstream_main folgt allein dem Hauptstrang.

Ein Einzugsgebiet kommt als Polygon von ein paar tausend Koordinatenpaaren. Das ist die Antwort auf eine Kartierungsfrage und die falsche Antwort auf jede Frage, die ein Agent stellt, also wird das Polygon behalten und seine Fläche, Ausdehnung und Scheitelpunktzahl werden gemeldet. Die Fläche wird aus dem Polygon durch die Linienintegralform der sphärischen Fläche berechnet, die keine Projektion benötigt und daher keine Zone hat, die zu wählen oder falsch zu wählen wäre. Sie stimmt mit dem Einzugsgebiet, das USGS für die eine Station veröffentlicht, an der beide Zahlen existieren, auf 0,06 % überein, und das Ergebnis sagt, dass es berechnet statt veröffentlicht ist, also wird es nicht gegen eine vermessene Zahl zitiert, als wären beide dasselbe.

Wiedergabe

Hydrologie reproduziert in der getesteten Literatur zu 1,6 %. Die übliche Erklärung ist, dass Daten und Code nicht veröffentlicht wurden, und sie verbirgt das interessantere Versagen: Eine veröffentlichte Pipeline gegen einen Live-Dienst reproduziert ebenfalls nicht, weil der Dienst den Datensatz darunter überarbeitet hat. Vorläufiger Abfluss wird zu genehmigtem Abfluss, und die Zahl bewegt sich.

Eine Sitzung speichert ein Bündel aus ihrem Manifest und den Antwortkörpern, die sie gesehen hat. Die Wiedergabe läuft in drei Modi, und die Unterscheidung zwischen ihnen ist der Punkt.

with Session(question="what was the discharge in mid May 2021?") as work:
    Toolkit(work).get_series("USGS-02344872", "00060", "2021-05-16", "2021-05-20")
    work.save("bundle.json")

gagelink-replay bundle.json --mode strict
gagelink-replay bundle.json --mode revision_aware

Dasselbe Bündel, derselbe erneute Abruf und zwei verschiedene Urteile:

strict replay: changed
  changed      daily
      [changed] USGS-02344872 00060 at 2021-05-16: 702.1 -> 826.0 ft^3/s

revision_aware replay: reproduced
  changed      daily
      [revised] USGS-02344872 00060 at 2021-05-16: 702.1 -> 826.0 ft^3/s,
                Revisions: Discharge for the period May 16, 2021 to Oct. 27, 2021,
                was revised on Aug. 16, 2024, based on changes to the estimated discharge.

Ein Ergebnis, das sich änderte, weil die Behörde 400 vorläufige Werte revidiert hat, ist eine andere Tatsache über die Wissenschaft als eines, das sich änderte, weil sich der Code änderte, und die beiden sind ansonsten nicht zu unterscheiden. Der Revisionsdatensatz stammt aus der eigenen time-series-revisions-Sammlung des Dienstes, verknüpft über die Zeitreihenkennung, die die Messung bereits trägt, sodass die Zuordnung eine Nachschlageoperation und keine Vermutung ist. Eine Differenz ohne veröffentlichte Revision dahinter bleibt als unerklärt gemeldet, was die Prüfung davor bewahrt, nichtssagend zu sein.

Körper werden vor jedem Vergleich gegen ihre Hashes verifiziert. Ein Bündel, dessen Archiv nicht übereinstimmt, wird abgelehnt und nicht abgespielt, da jedes Urteil darauf beruht, dass das Archiv das ist, was die Sitzung tatsächlich gesehen hat.

waterbench

bench/ ist ein Benchmark, der misst, was das Toolkit einem Modell wert ist, über neun Aufgaben an einer Station, die neun Gefahren abdecken, jede davon in einer Live-Dienst-Payload beobachtet, während das Paket gebaut wurde.

Drei Bedingungen werden auf identischen Daten verglichen, die sich nur in der Schnittstelle zwischen dem Modell und den Bytes unterscheiden:

Die mittlere Bedingung ist das, was die Messung wertvoll macht. Ohne sie würde ein Unterschied zwischen der ersten und der letzten nur zeigen, dass strukturierter Abruf rohes JSON schlägt, was niemand bezweifelt. Der Unterschied zwischen den letzten beiden ist das, was die Metadaten für sich genommen wert sind.

python -m bench --dry-run                                   # no provider, no spend
python -m bench --model anthropic/claude-opus-5 --replicates 4

Jede erwartete Antwort wird aus denselben aufgezeichneten Antworten abgeleitet, die die Tools bedienen, und tests/test_bench.py löst jede Aufgabe aus diesen Antworten und prüft das Ergebnis gegen die deklarierte Antwort. Eine Aufgabe, deren Antwort auf diese Weise nicht erreicht werden kann, ist eine kaputte Aufgabe, und genau dort zeigt es sich. Jede Aufgabe protokolliert auch eine basis, die angibt, woher ihre Zahl stammt, sodass ein Leser sie überprüfen kann, ohne das Wort dieses Projekts zu nehmen.

Die Freibord-Aufgabe ist gegen die eigene Arithmetik der Behörde prüfbar: USGS veröffentlicht die Wasseroberflächenhöhe als Parameter 63160, bei 40,07 ft NAVD88, was die Pegelhöhe von 3,03 ft plus dem Bezugshöhenversatz der Station von 37,04 ft ist.

Die Bewertung wird geschrieben, bevor ein Durchlauf stattfindet, und steht unter Versionskontrolle, sodass eine Regel nicht angepasst werden kann, nachdem ein Ergebnis gesehen wurde, das sie benachteiligt.

Erste Ergebnisse

gpt-oss-120b, neun Aufgaben, drei Bedingungen, acht Wiederholungen, 216 Läufe, 0,09 $.

Korrektheit zählt jeden Lauf, einschließlich der acht, die ohne Antwort endeten. Sieben davon gehören zu http_only bei den beiden Aufgaben, deren roher Datensatz 42.000 und 50.000 Prompt-Token umfasst, wo das Modell degeneriert und eine Zahl wiederholt, statt zu antworten. Diese Fehler werden durch die Bedingung verursacht, sodass ihr Ausschluss rohem JSON für die Läufe gutschreiben würde, die seine eigene Payload-Größe zerstört hat.

Die Suite liegt bei sechs von neun Aufgaben an der Obergrenze, was eine Erkenntnis über die Suite ist. Wo sie trennt:

Bei den beiden Aufgaben mit langen Datensätzen betrug der Median-Prompt 49.864 und 42.006 Token durch rohes JSON gegenüber 5.462 und 2.384 durch das Toolkit. Bei der Aufgabe mit undurchsichtiger Einheit schickte das Entfernen der Referenzrahmen sieben von acht Läufen in die aufgezeichnete Falle, die mit dem USGS-Abfluss von 3010 ft³/s antworteten statt mit den 2,95 kcfs des Vorhersagedienstes.

Das Toolkit schlägt rohes JSON bei der Genauigkeit im Allgemeinen nicht. Die Lücke wird fast vollständig durch die beiden Aufgaben getrieben, bei denen die rohe Payload nicht passt. Acht von 27 Zellen verteilt über ihre Wiederholungen, sodass Unterschiede unter etwa zwei Läufen von acht durch dieses Design nicht getrennt werden, und ein Modell ist ein Modell.

API-Schlüssel und Ratenlimits

Der Dienst erlaubt 50 Anfragen pro IP und Stunde ohne Authentifizierung und 1.000 pro Stunde mit einem Schlüssel, der kostenlos unter api.waterdata.usgs.gov/signup erhältlich ist. Eine einzelne Agentenfrage, die Bedingungen an fünf Standorten vergleicht, kostet etwa 15 bis 25 Anfragen, daher ist Caching tragend und keine Optimierung, und Antworten werden standardmäßig für die Lebensdauer des Prozesses zwischengespeichert.

Das verbleibende Kontingent wird aus X-RateLimit-Remaining auf jeder Antwort gelesen und auf dem Abruf mitgeführt, sodass einem Agenten mitgeteilt werden kann, was ihm noch bleibt, anstatt das Limit durch Scheitern zu entdecken.

Der Schlüssel reist im X-Api-Key-Header und erscheint nie in einer aufgezeichneten URL, da ein Manifest zur Veröffentlichung gedacht ist.

Der Dienst, den dies anspricht

USGS stellt die WaterServices-API-Familie ein, mit der Einstellung geplant für das erste Quartal 2027 und möglicher Verschlechterung ab der zweiten Hälfte 2026. gagelink zielt nur auf den Ersatz unter api.waterdata.usgs.gov/ogcapi/v0. Eine Konsequenz, die es wert ist, genannt zu werden, ist die time-series-revisions-Sammlung, die Änderungen und Löschungen an genehmigten Aufzeichnungen veröffentlicht und die es einer Wiedergabe ermöglichen wird, eine Antwort, die sich änderte, weil die Behörde eine Messung revidiert hat, von einer zu trennen, die sich änderte, weil sich der Code änderte.

Entwicklung

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Netzwerkzugriff erfolgt über ein austauschbares fetch, sodass die Suite gegen aufgezeichnete Antworten läuft und kein Test das Netzwerk benötigt.

Lizenz

MIT