Groundpulse-Research-Agent

Evidence before language

GroundPulse began with a simple concern: in satellite and ground-segment work, a technically polished answer is not necessarily a trustworthy answer. A research result can sound authoritative while hiding which source was used, when the source was retrieved, which values were calculated, and which information was unavailable. For engineering and operational teams, that distinction matters. A missing telemetry feed should not quietly become an assumed spacecraft-health assessment, and a deterministic calculation should not be presented as if it were a directly observed fact.

The project was inspired by the need for a research workflow that treats evidence as a first-class product. Instead of asking an AI system only to produce a narrative, GroundPulse asks it to preserve the path from a bounded question to a reviewable result: the approved source, the retrieved snapshot, the claims, the derivations, the gaps, the validation decision, and the final artifact package.

What GroundPulse does

GroundPulse is an evidence-first research agent for satellite and ground-segment questions. It converts a structured research request into a controlled workflow:

1. A question is framed with an object, scope, time window, and decision intent.

2. An approved source snapshot is selected and preserved.

3. Candidate claims are organized into a canonical claim ledger.

4. Provenance and evidence rules are validated.

5. Facts, deterministic derivations, and unavailable evidence are separated.

6. A research package is generated and stored as immutable artifacts.

7. A dashboard presents the run state, evidence ledger, execution trace, and package inventory for human review.

The system is deliberately designed not to hide uncertainty. A successful result is not simply a fluent paragraph; it is a package that allows another person to inspect what was known, what was derived, and what could not be established.

The demonstration use case

The verified demonstration focuses on the International Space Station using one approved CelesTrak GP snapshot. The research question is:

Given one approved CelesTrak GP snapshot for the ISS, what is source-backed and what is unavailable?

The released run is identified as run_p1_55cbb0817ecd. It uses the approved source celestrak_gp_25544, representing the ISS with NORAD catalog ID 25544. The run completed with status released, validation state passed, and one execution attempt.

The resulting package shows three different evidence categories. The approved snapshot directly supports orbital-element information. A derived claim calculates an approximate orbital period of 92.93 minutes from the recorded mean motion value:

$$ \text{period}_{\text{minutes}} = \frac{1440}{\text{MEAN_MOTION}} $$

Using MEAN_MOTION = 15.4951252 gives the deterministic result shown in the package. At the same time, the package explicitly records a gap: live telemetry and spacecraft-health information are unavailable from the approved GP snapshot. GroundPulse does not turn that gap into a guess or an operational recommendation.

How the project was built

The project was developed as a full-stack system with a Python research backend and a React-based Mission Control frontend. The backend uses FastAPI, Pydantic models, Uvicorn, Firestore persistence, Google Cloud Storage artifact storage, Cloud Tasks execution paths, and Google Cloud Run deployment. The agent workflow produces structured run records, validates canonical claim ledgers, generates deterministic package artifacts, and preserves immutable evidence references.

The frontend uses React, TypeScript, Vite, and a Mission Control visual language. It presents the run archive, selected mission, workflow stages, evidence state, source review, execution events, and immutable package inventory. The frontend calls the public read-only demo facade rather than accessing the private database or storage bucket directly.

The deployed architecture separates responsibilities across services:

Component	Role
groundpulse-frontend	Public React Mission Control application for judges
groundpulse-demo-api	Public read-only facade exposing the verified demonstration run and artifacts
groundpulse-research-api	Private research service for run submission, execution, persistence, and worker operations
Firestore	Private durable storage for research-run state and validation metadata
Google Cloud Storage	Private storage for immutable evidence and research-package artifacts
Cloud Tasks	Asynchronous execution boundary for research work
Restricted service accounts	Identity separation between private operations and public read-only access

The judge-facing frontend is available at:

Open GroundPulse Mission Control

The public service is intentionally read-only. Anonymous visitors can inspect the released run and open its artifacts, but they cannot submit arbitrary research jobs to the private pipeline. This protects the research service from uncontrolled public execution while providing judges with a reproducible demonstration.

What I learned

The most important lesson was that an agentic system is not defined only by the model it calls. The surrounding contracts are equally important. A useful research agent needs explicit request models, run states, idempotency behavior, provenance fields, validation rules, artifact contracts, and human-review boundaries. Without those structures, it is difficult to know whether a result is reproducible or merely plausible.

I also learned that evidence quality requires preserving negative results. It is tempting to optimize a product demo around successful answers, but unavailable information is often the most important part of a responsible result. GroundPulse therefore treats an evidence gap as a valid, inspectable output rather than as a failure to be hidden.

Another lesson was the importance of separating deployment boundaries early. The private research API can safely handle authenticated submissions and worker operations, while the public facade can expose only carefully selected released data. This separation allowed the project to provide a public judge experience without exposing identity tokens, service-account credentials, private bucket access, or write endpoints.

Finally, I learned that cloud deployment is part of the product rather than an afterthought. Local tests can confirm application behavior, but they do not prove that a service starts correctly, listens on the expected Cloud Run port, has the correct runtime dependency, uses the intended identity, or serves the correct public route. The deployment process became an extension of the verification process.

Challenges faced

One major challenge was maintaining compatibility while the project evolved from a local prototype into a cloud-backed system. Earlier records and newer structured run records did not always share the same schema. The dashboard initially failed when it encountered legacy Firestore documents that could not be validated by the current Pydantic model. The solution was to make the repository layer tolerate invalid legacy records for dashboard listing while preserving strict validation for current canonical runs.

A second challenge involved preserving the authoritative run_id through the entire pipeline. The run identifier is used in Firestore, task execution, artifact paths, manifests, and dashboard links. A mismatch could make a successful artifact appear disconnected from the run that produced it. The artifact-generation path was corrected so that the authoritative run ID is passed through consistently, and a dedicated contract test verifies this behavior.

Cloud Run startup configuration created another important debugging challenge. The service initially failed because the runtime could not find the Uvicorn executable through an overridden command. Subsequent attempts also exposed how command and argument overrides can bypass the environment prepared by the Python buildpack. The final deployment used the buildpack-supported entrypoint configuration and verified that the public service reached a ready revision and served traffic successfully.

The public artifact path exposed a further boundary issue. The artifact listing initially returned links using the private dashboard route, even though the public artifact bytes were available through the demo facade. This produced links that were valid in the private application but unusable for judges. The artifact URL generation was corrected to use the public /demo/runs/.../artifacts/... route, and the final artifact download was verified with an unauthenticated HTTP 200 response.

The frontend deployment also required care. The repository contains backend deployment configuration, and a root Dockerfile caused the first frontend Cloud Run deployment to start an API response instead of serving the React application. The frontend was redeployed through the Node buildpack path, producing a public Mission Control URL that serves the visual application correctly.

Verification and current result

The project now has a verified public demonstration path. A judge can open the React dashboard, select the released ISS run, inspect its released and passed states, review the approved CelesTrak source, distinguish supported and derived claims from explicit gaps, and open immutable artifacts through the public API boundary.

The public frontend is backed by these services:

• Frontend: https://groundpulse-frontend-1081077557421.europe-west3.run.app/dashboard

• Demo API: https://groundpulse-demo-api-1081077557421.europe-west3.run.app

• Verified run: run_p1_55cbb0817ecd

• Approved source: celestrak_gp_25544

• Artifact package: 20260827T110302Z

The repository’s main branch contains the complete cloud-backed implementation, frontend integration, deployment documentation, verification materials, and updated project status. The public GCS bucket is not exposed; artifact access is mediated by the restricted read-only facade.

What remains intentionally out of scope

GroundPulse does not claim to provide live spacecraft telemetry, spacecraft-health assessment, mission-control authority, or operational recommendations. The approved CelesTrak GP snapshot contains orbital elements, not a live health or telemetry feed. The public demonstration also does not accept anonymous research submissions. These boundaries are deliberate: the goal is to demonstrate a trustworthy evidence workflow, not to imply capabilities that the available evidence and deployment controls do not support.

Closing perspective

GroundPulse is an attempt to make an AI research system more accountable by turning evidence handling into a visible workflow. The project combines structured agent behavior, Google Cloud infrastructure, immutable artifacts, and a human-readable interface so that a reviewer can follow the result from question to evidence to conclusion.

The central design principle is simple:

A useful research agent should not only answer a question. It should show why the answer is supportable, what was calculated, and what remains unknown.

What's next for Groundpulse-Research-Agent

Built With

• ai-agents
• celestrak
• cloud-run
• cloud-tasks
• evidence-validation
• fastapi
• firestore
• gemini
• google-adk
• google-cloud
• immutable-artifacts
• provenance
• pydantic
• python
• react
• rest-api
• satellite-data
• tailwind-css
• typescript
• uvicorn
• vite