Grace Guardian

Grace Guardian, an open-source project, audits animal records in DataHub, detects missing or conflicting information, and writes actionable, traceable quality reports back to DataHub.

Comment

Inspiration

Grace Guardian is an open-source data quality and governance agent for animal welfare records, released under the Apache License 2.0 and built with DataHub Open Source. It provides a working live integration with DataHub Open Source: it reads animal records directly from DataHub, audits them, and writes traceable quality reports and PASS/BLOCK results back to DataHub.

Animal rescue organizations around the world often manage lifesaving information across spreadsheets, forms, messages, documents, and media files. Small organizations and volunteer teams rarely have dedicated data-quality specialists. When records are incomplete, contradictory, or difficult to trace, medical details can be overlooked, adoption profiles become unreliable, and collaboration becomes harder.

Grace Guardian was created as a practical data-quality agent for GraceWays: an open-source project designed to help animal welfare organizations worldwide create structured, trustworthy, and reusable animal records.

Our long-term goal is to make professional data governance accessible not only to large companies, but also to small rescue organizations working with limited resources.

What it does

Grace Guardian performs a complete agentic audit workflow inside DataHub:

  1. It publishes five explicitly fictional animal records to DataHub as uniquely identifiable datasets.
  2. It reads the records back from DataHub instead of auditing only the original local files.
  3. It reconstructs the structured animal information stored in DataHub.
  4. It checks completeness, consistency, provenance, translation coverage, media availability, placement-status conflicts, and responsible ownership.
  5. It generates human-readable findings with severity levels and concrete recommendations.
  6. It writes a separate, searchable audit report and a clear PASS/BLOCK result for every animal back to DataHub.

This creates a governed feedback loop:

Animal record → DataHub → Grace Guardian audit → actionable report in DataHub

The result is more than a one-time validation script. Both the source record and its quality assessment remain traceable inside the same data environment.

No real animal, adopter, volunteer, or user data is used in the demonstration.

Open source and global impact

Grace Guardian is part of the wider GraceWays vision: an open-source digital infrastructure for animal welfare organizations worldwide.

The project is released under the Apache License 2.0 so that rescue organizations, shelters, developers, universities, and nonprofit networks can inspect it, reuse it, adapt it, and build additional modules without being locked into a proprietary platform.

GraceWays is designed for international use. Its data model can support different organizations, countries, languages, animal species, and local workflows. Multilingual adoption information is treated as structured data rather than as disconnected copies of the same record.

This approach could help organizations collaborate across borders while retaining responsibility for their own records. The same verified animal data could later support adoption websites, social-media posts, printable profiles, veterinary handovers, reports, and multilingual communication without repeatedly entering the information.

How we built it

Grace Guardian is a Python application with a command-line interface and a lightweight local user interface. It integrates with DataHub through the DataHub SDK and Graph API.

The application follows a real end-to-end workflow:

  • Structured fictional records are ingested as DataHub dataset entities.
  • Every animal has a stable record key and a deterministic, unique DataHub URN.
  • Grace Guardian retrieves the entities from DataHub.
  • The original structured record is reconstructed from governed DataHub properties.
  • Deterministic validation rules analyze each record.
  • The resulting reports are written back as separate DataHub document entities.
  • Existing entities are updated through repeatable upserts instead of creating uncontrolled duplicates.

Each DataHub record preserves technical and governance information including:

  • Stable animal and record identifiers
  • Organization identifier
  • Record status
  • Source system
  • Source revision
  • Last update timestamp
  • Responsible record steward
  • Structured multilingual content
  • Media and document information
  • Explicit fictional-data classification

Technical highlights

Grace Guardian includes several technical safeguards and architectural features:

  • True DataHub round trip: Records are written to DataHub, retrieved from DataHub, audited, and returned to DataHub as reports.
  • Stable identities: Deterministic record keys and URNs prevent accidental duplication.
  • Idempotent updates: The workflow can be run repeatedly while updating existing entities.
  • Separate governed reports: Audit results are stored as dedicated searchable DataHub documents rather than disappearing into terminal output.
  • Traceable provenance: Organization, source, revision, timestamp, and responsible-party information remain attached to the record.
  • Deterministic validation: The same input produces consistent findings and recommendations.
  • Actionable results: Findings explain what is wrong, why it matters, and what should be corrected.
  • Safety-by-design: The demonstration refuses to upload records unless they are explicitly marked as fictional.
  • International data model: Multilingual content and organization-independent identifiers prepare the system for worldwide use.
  • Modular architecture: Local and DataHub gateways separate data access from audit logic, making the validators reusable in future integrations.
  • Automated testing: Tests verify core validation, identity, ingestion, and reporting behavior.

Challenges we faced

One major challenge was implementing a reliable round trip instead of merely sending metadata to DataHub.

Writing the records was only the first step. Grace Guardian also needed to retrieve the correct entities, reconstruct their structured content, preserve stable identities, and write separate audit reports without producing duplicates.

We also had to handle the experimental DataHub SDK carefully. Dataset creation and later updates needed different behavior, and the generated URNs had to use the same valid DataHub environment throughout the complete workflow. The final implementation consistently uses the DEV environment and supports both initial creation and repeatable updates.

Another important challenge was translating technical data-quality findings into recommendations that are understandable to people working in animal welfare. The agent therefore does not merely identify a missing value. It explains what should be added or reviewed.

Accomplishments that we are proud of

Grace Guardian now completes a genuine DataHub workflow from beginning to end.

Five fictional animal records are:

  • Published to DataHub
  • Retrieved from DataHub
  • Reconstructed as structured records
  • Audited by Grace Guardian
  • Connected with five searchable quality reports written back to DataHub

We are especially proud that the project combines technical data governance, open-source development, and a social-impact purpose.

Grace Guardian demonstrates that DataHub can support not only conventional enterprise data, but also nonprofit organizations whose information quality can directly influence animal welfare, medical continuity, international cooperation, and successful adoption.

What we learned

We learned that trustworthy agentic workflows depend on stable identifiers, provenance, repeatable processing, transparent validation rules, and human-readable recommendations.

Data quality is not simply about finding errors. It is about helping people understand what needs attention, why it matters, and how the information can be improved.

We also learned that open standards and portable data structures are essential for small organizations. An open-source system can give them greater independence and allow improvements made by one organization or developer to benefit others around the world.

What's next for Grace Guardian

The next step is to connect Grace Guardian directly to the GraceWays pilot platform.

Animal welfare organizations will be able to run an audit before publishing an adoption profile, review the findings, correct missing information, and approve the final record. Verified data can then be reused for multilingual adoption pages, social-media content, printable documents, and collaboration between organizations.

Future versions will add:

  • Configurable rules for different organizations and countries
  • Stronger duplicate and identity detection
  • Scheduled and event-triggered audits
  • Human approval workflows
  • Multilingual recommendations
  • Veterinary and adoption-specific rule sets
  • Data-lineage visualization
  • Privacy controls and role-based permissions
  • Community-developed validation modules
  • Connections to additional open-source animal welfare tools

Our long-term vision is a worldwide, open-source guardian that helps animal welfare organizations transform fragmented records into trustworthy knowledge—so that people can work together more effectively and every animal can receive better-informed care.

Built With

Share this project:

Updates