EqualizeED

Project summary

EqualizeED is a governed, event-driven network for redistributing educational resources across schools, colleges, libraries, nonprofits, and training centres. One institution may have idle laptops, books, laboratory kits, projectors, calculators, assistive devices, rooms, or workshop equipment while another nearby institution is purchasing the same resource or leaving learners on a waiting list. EqualizeED treats those resources as a shared institutional fleet and coordinates the work required to move them safely.

The project goes beyond a chatbot. Inventory and need events create durable cases that may remain active for days or weeks. A Google ADK fleet separates responsibilities among Need Scout, Inventory Scout, Condition Inspector, Governance Agent, Allocation Planner, Repair Coordinator, Logistics Coordinator, and Impact Auditor. Gemini 3.5 Flash interprets unstructured request and inspection notes, identifies missing information, and returns typed facts. It is explicitly prohibited from deciding who deserves a resource.

Eligibility and allocation are handled by a transparent deterministic engine. It checks resource type, compatibility tags, condition, distance, verified quantity, institutional separation, and repair-cost policy. Eligible matches receive a stable integer score with recorded reasons and a rule version. Every result is only a proposal until an authorized staff member provides human attestation.

Features and functionality

Editable testing workspace: Users can add, edit, and delete inventory and need records instead of relying on fixed demo cards. Records can be imported or exported as JSON and persist in browser-local storage for safe judge testing.
Asynchronous case intake: Authenticated Pub/Sub events invoke a private Cloud Run orchestrator through OIDC, with retry and dead-letter handling.
Governed multi-agent workflow: Eight Google ADK specialists have narrowly defined responsibilities. Repair, logistics, and audit agents are kept outside the pre-approval execution path.
Gemini evidence interpretation: The deployed Need Scout uses Google ADK and Gemini 3.5 Flash on Vertex AI to normalize synthetic institutional notes and identify missing evidence without ranking recipients.
Deterministic allocation: Versioned Python rules enforce hard eligibility constraints, verified-demand caps, stable ordering, and explainable scoring.
Human approval gates: Dispatch cannot occur before an authorized participant approves a proposal. Non-participating institutions are rejected.
Durable and idempotent state: Firestore stores cases, event histories, processed Pub/Sub message IDs, and command idempotency records. Replayed commands return the original result instead of repeating side effects.
Security controls: The backend is private, runs under a dedicated least-privilege service identity, uses a separate Pub/Sub invocation identity, and places Model Armor before Gemini. Prompt-injection tests are blocked with HTTP 422.
Auditable impact: Receipt, activation, and audit transitions record learners supported, avoided replacement spending, repair cost, and estimated e-waste avoided with provenance.
Observability: OpenTelemetry spans, Cloud Logging audit events, and Cloud Trace identifiers provide evidence of execution across the workflow.

Technologies used

AI and agents: Gemini 3.5 Flash, Vertex AI global endpoint, Google ADK 2.8.0, Google Gen AI SDK, Model Armor
Backend: Python 3.12, FastAPI, Pydantic, deterministic allocation module
Google Cloud: Cloud Run, Pub/Sub, Firestore, Cloud Storage, Artifact Registry, Cloud Build, IAM service accounts, Cloud Logging, Cloud Trace
Frontend: Node.js, semantic HTML, CSS, and browser JavaScript with no client-side framework dependency
Infrastructure and delivery: Terraform, Docker, authenticated OIDC push, retry/dead-letter configuration, container image versioning
Testing: Python unittest, FastAPI TestClient, Node.js test runner, live authenticated Cloud Run workflow tests

The verified deployment runs in the isolated Google Cloud project equalizeed-aah-2026-a83126. The public editable workspace is available at https://equalizeed-dashboard-520579651136.us-central1.run.app, while the governed backend remains private.

Data sources

The hackathon demonstration uses only fictional institutions, synthetic resource records, synthetic request and inspection notes, and user-entered test data. It does not use real learner identities, protected characteristics, institutional credentials, or third-party datasets. Browser test records remain on the user's device unless exported.

In a production deployment, data would come from authorized institutional inventory systems, aggregate need forms, qualified inspection reports, approved transport providers, and signed handover or activation records. Each integration would require an institutional agreement, a defined retention policy, tenant-scoped authorization, and verification that the institution is permitted to share the data. Individual learner data is not required for allocation; aggregate verified learner counts are sufficient.

Findings and learnings

The most important finding was that responsible autonomy requires separating interpretation from authority. Gemini is useful for normalizing messy evidence, detecting missing information, explaining policy, and coordinating bounded work, but eligibility and ranking must remain deterministic, versioned, and independently testable.

We also learned that a multi-agent system becomes more credible when each agent has less authority. Keeping logistics and impact agents outside the pre-approval fleet prevents a persuasive model response from crossing a legal or operational boundary. Typed APIs, explicit state transitions, participant checks, and human attestation proved more important than adding conversational features.

Long-running institutional workflows also require durable state and idempotency. Pub/Sub is intentionally at-least-once, so message IDs and command keys must prevent duplicate bookings or inventory changes. Firestore is the authoritative ledger; conversational memory can assist an agent but cannot change case truth.

Finally, production readiness must be demonstrated rather than implied. The project therefore includes an editable no-login judge interface, a private authenticated backend, live Model Armor and Gemini evidence, observable cloud traces, negative authorization tests, reproducible infrastructure, and an honest distinction between deployed controls and future managed Gemini Enterprise extensions.