diff --git a/README.md b/README.md index d44cde2..63deca7 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,11 @@ The public-sandbox runtime passes concern text through Vertex Model Garden MaaS ## Public demonstration URL -The long-lived judge-facing experience is designed for `https://staylonghome.com`. +The long-lived judge-facing experience is available at `https://staylonghome.com`. It is a temporary-data demonstration, not a production care service: it does not connect to real Gmail, Calendar, provider, payment, My Aged Care, or MyGov -accounts. During Phase A, the generated Cloud Run URL remains available while -Google-managed TLS is provisioned. Only an explicitly reviewed +accounts. The generated Cloud Run URL remains available as a rollback path. +Only an explicitly reviewed `public_edge_lockdown_enabled=true` configuration switches Cloud Run to accept traffic through the managed load balancer and branded URL. @@ -24,7 +24,7 @@ StayLong helps older people and their chosen supporters prepare, coordinate and ## Competition fit -StayLong is designed for the **Taskmaster** track of the All Things Agentic Hackathon. It will use Gemini 3.5+ through Vertex AI, Google ADK, and Google Cloud services (Cloud Run, Firestore, Cloud Tasks and Pub/Sub). +StayLong is designed for the **Taskmaster** track of the All Things Agentic Hackathon. It uses Gemini 3.6 Flash through Vertex AI, Google ADK, and Google Cloud services (Cloud Run, Firestore, Cloud Tasks and Pub/Sub). See [competition references](docs/competition-references.md) and the public [architecture](docs/architecture.md). The single source-of-truth capability mapping is in the [capability matrix](docs/capability-matrix.md). @@ -61,13 +61,15 @@ python -m uvicorn staylong.api.main:app --port 8080 The Cloud Run image is built from [`Dockerfile`](Dockerfile) and starts `staylong.api.main:app` on the platform-provided `PORT` (default `8080`). The -runtime requires the `STAYLONG_API_TOKEN` environment variable; it is never -checked into the repository or printed by the smoke test. Pull requests build -the image and run [`tools/cloudrun_smoke.py`](tools/cloudrun_smoke.py) -against a local container, while the deployment workflow runs the same health -and authenticated case-flow checks against the deployed URL. Configure -`STAYLONG_API_TOKEN` as a masked `sandbox` GitHub Environment secret before -using the deployment workflow. +**private** runtime requires the `STAYLONG_API_TOKEN` environment variable; it +is never checked into the repository or printed by the smoke test. The +**public sandbox** intentionally has no shared API token and accepts only its +scoped cookie-session routes. Pull requests build the image and run +[`tools/cloudrun_smoke.py`](tools/cloudrun_smoke.py) against a local container, +while the private deployment workflow runs health and authenticated case-flow +checks against the deployed URL. Configure `STAYLONG_API_TOKEN` as a masked +`sandbox` GitHub Environment secret only for the private-runtime deployment +path. The repeatable UI/API workflow contract lives in [`tests/api/test_ui_workflow.py`](tests/api/test_ui_workflow.py). It loads the diff --git a/docs/architecture.md b/docs/architecture.md index 64456eb..27094a4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -16,23 +16,25 @@ flowchart LR end subgraph PUBLIC["Long-lived public sandbox Cloud Run"] PW["Public React experience"] --> PS["/v1/public/* session API"] - PS --> SA["Sandbox adapters only"] + PS --> SA["Sandbox adapters only\n(no real external action)"] end W --> DNS NEG --> PW + subgraph CORE["Bounded coordination core used by both runtime surfaces"] + R["Deterministic safety route"] --> G["Vertex Model Garden MaaS\nGemma 4 privacy guard"] + G --> ADK["Google ADK intake / coordinator"] + ADK --> V["Vertex AI Gemini 3.6 Flash"] + ADK --> F[("Firestore case state")] + ADK --> Q["Cloud Tasks / Pub/Sub"] + Q --> ADK + ADK --> P["Approval policy"] + end + PS --> R subgraph PRIVATE["Private Cloud Run service"] - W --> API["Authenticated FastAPI API"] - API --> R["Deterministic safety route"] - R --> ADK["Google ADK intake / coordinator"] - API --> O["Google Calendar OAuth routes"] + API["IAM-authenticated FastAPI API"] --> R + API --> O["Optional Google Calendar OAuth routes"] end - ADK --> V["Vertex AI Gemini 3.6 Flash"] - API --> G["Vertex Model Garden MaaS\nGemma 4 privacy guard"] - ADK --> F[("Firestore case state")] - ADK --> Q["Cloud Tasks / Pub/Sub"] - Q --> ADK - ADK --> P["Approval policy"] - P --> T["Approval-gated adapters"] + P --> T["Private approval-gated adapters"] T --> C["Approved external action"] O --> GT["Google Calendar API"] GT --> C diff --git a/docs/capability-matrix.md b/docs/capability-matrix.md index 862c5c4..697565c 100644 --- a/docs/capability-matrix.md +++ b/docs/capability-matrix.md @@ -8,8 +8,8 @@ This document is the **single source of truth** mapping every user-visible capab | Capability | API Route(s) | Source Module(s) | Test Suite(s) | Infrastructure / Runtime | Safety & Policy Boundary | |---|---|---|---|---|---| -| **Deterministic Emergency Routing** | `POST /v1/workflows`
`POST /v1/public/workflows` | `staylong.policy.emergency` | `tests/policy/test_emergency.py` | Cloud Run Sydney (`australia-southeast1`) | Pure deterministic screening (000 Triple Zero advice). Never delegated to an LLM. | -| **Gemma Privacy Guard** | `POST /v1/workflows`
`POST /v1/public/workflows` | `staylong.privacy.gemma` | `tests/privacy/test_gemma.py` | Vertex AI Gemma endpoint / local fallback rule | Strict redact-only contract before Firestore persistence or tool execution. | +| **Deterministic Emergency Routing** | `POST /v1/workflows`
`POST /v1/public/workflows` | `staylong.policy.emergency` | `tests/policy/test_emergency.py` | Public sandbox and private Cloud Run (`australia-southeast1`) | Pure deterministic screening (000 Triple Zero advice). Never delegated to an LLM. | +| **Gemma Privacy Guard** | `POST /v1/workflows`
`POST /v1/public/workflows` | `staylong.privacy.gemma` | `tests/privacy/test_gemma.py` | Vertex Model Garden MaaS `gemma-4-26b-a4b-it-maas` | Strict redact-only contract before Firestore persistence or tool execution; unavailable or malformed output fails closed. | | **Non-Clinical Intake & Fact Collection** | `POST /v1/workflows`
`POST /v1/workflows/{id}/answers`
`POST /v1/public/workflows/{id}/answers` | `staylong.agents.intake`
`staylong.agents.prompts`
`staylong.agents.vertex` | `tests/agents/test_intake.py`
`tests/agents/test_vertex_factories.py` | Google ADK Python + Vertex AI Gemini 3.6-flash (`global`) | Structured Pydantic outputs only; schema enforcement rejects prompt injection or non-conforming responses. | | **Home Independence Assessment Pack** | `GET /v1/workflows/{id}`
`GET /v1/public/workflows/{id}` | `staylong.services.home_plan`
`staylong.domain.models` | `tests/evaluations/test_demo_fixture.py`
`tests/domain/test_models.py` | Cloud Run + Firestore case document | Non-clinical preparation pack; explicitly states it is not an official AT-HM or My Aged Care funding determination. | | **Human Approval & Action Gate** | `POST /v1/workflows/{id}/action-decision`
`POST /v1/public/workflows/{id}/action-decision` | `staylong.policy.approvals`
`staylong.services.taskmaster` | `tests/policy/test_approvals.py`
`tests/services/test_taskmaster.py` | Application state machine + Firestore | Strict human-in-the-loop: external action or coordination cannot execute without explicit human approval. | @@ -31,7 +31,7 @@ This document is the **single source of truth** mapping every user-visible capab ### B. Gemma Privacy Guard - **Rule**: All user-entered concern text is scanned for unnecessary PII (full names, phone numbers, Medicare numbers, street addresses) before durable persistence in Firestore. - **Configuration**: Activated via `STAYLONG_GEMMA_ENABLED=true` in Cloud Run environment. -- **Fallback**: Built-in deterministic regex and entity scrubbing ensures privacy protection even during cold starts. +- **Failure behaviour**: An unavailable, malformed or empty Gemma response blocks persistence and planning, then returns a safe retry response. Test fixtures inject a fake provider; the deployed workflow does not silently substitute a local redaction rule. ### C. Non-Clinical Fact Intake (ADK + Vertex AI) - **Model**: `gemini-3.6-flash` hosted on Vertex AI (`location: global`). @@ -45,7 +45,7 @@ This document is the **single source of truth** mapping every user-visible capab ### E. Public Sandbox Isolation & Lifecycle - **Access Control**: Session cookie `staylong_public_session` establishes cryptographically signed browser ownership. -- **Rate Limits**: Configurable max active cases per browser session (default 3). +- **Rate Limits**: Configurable max active cases per browser session (current public-sandbox default: 10). - **Cleanup**: Cloud Scheduler calls `/internal/public-sandbox/cleanup` on a recurring schedule with OIDC authentication. --- diff --git a/docs/devpost-submission-readiness.md b/docs/devpost-submission-readiness.md index c28be57..8e117ac 100644 --- a/docs/devpost-submission-readiness.md +++ b/docs/devpost-submission-readiness.md @@ -1,6 +1,6 @@ # StayLong Devpost submission readiness -This checklist is based on the [official Devpost overview](https://allthingsagentichackathon.devpost.com/) and [official rules](https://allthingsagentichackathon.devpost.com/rules), checked on 27 August 2026. Devpost currently shows a submission deadline of **31 August 2026 at 5:00 PM Pacific Time**. +This checklist is based on the [official Devpost overview](https://allthingsagentichackathon.devpost.com/) and [official rules](https://allthingsagentichackathon.devpost.com/rules), checked on 30 August 2026. Devpost currently shows a submission deadline of **31 August 2026 at 5:00 PM Pacific Time**. ## Required @@ -9,9 +9,9 @@ This checklist is based on the [official Devpost overview](https://allthingsagen - [ ] Show Gemini 3.5+, Google ADK, and Google Cloud services in the description and repository. - [ ] Link `https://github.com/sailing-together/StayLong` and verify it in an incognito window. - [ ] Keep README spin-up instructions reproducible for local testing and Terraform deployment. -- [ ] Upload an architecture diagram showing frontend, ADK/Gemini, Cloud Run, Firestore and async services. -- [ ] Provide a public English (or English-subtitled) video of about four minutes or less. -- [ ] Video covers problem, value, working demo, approved action and Google Cloud proof. +- [ ] Upload an architecture diagram showing the public sandbox, private runtime boundary, Gemma privacy guard, ADK/Gemini, Cloud Run, Firestore and asynchronous services. +- [ ] Provide a public English (or English-subtitled) YouTube or Vimeo video of **four minutes or less**. +- [ ] Video covers the problem, customer, solution, working demo, approved action and visible Google Cloud proof in one live, unedited flow. - [ ] Add the hosted public-sandbox URL after deployment is verified; never submit the private Sydney v2 URL as the product entry. ## Eligibility and disclosure @@ -38,9 +38,9 @@ This checklist is based on the [official Devpost overview](https://allthingsagen ### Additional Google AI model -- [ ] Deploy Vertex Model Garden MaaS `gemma-4-26b-a4b-it-maas` as the real PII redaction guard before persistence or tool actions. +- [x] Deploy-configure Vertex Model Garden MaaS `gemma-4-26b-a4b-it-maas` as the real PII redaction guard before persistence or tool actions. - [x] Validate its strict response contract and reject malformed/empty output. -- [ ] Add model/version, invocation path, tests and cost boundary to the final evidence and demo. +- [ ] Add the model/version, invocation path, test evidence, request-based cost boundary and a deployed synthetic-data proof to the final evidence and demo. ## Evidence bundle diff --git a/docs/release-evidence.md b/docs/release-evidence.md index da9d648..3334f1e 100644 --- a/docs/release-evidence.md +++ b/docs/release-evidence.md @@ -1,6 +1,6 @@ -# Release evidence and security checklist +# Release evidence and public-demo checklist -This document is the release evidence packet for the private StayLong Sydney sandbox service. It records reproducible repository checks and the verified Google Cloud deployment. +This document is the release evidence packet for both StayLong Cloud Run surfaces: the IAM-protected Sydney runtime and the judge-facing public sandbox. It records reproducible repository checks, verified Google Cloud deployments and the public-demo safety boundary. ## Release candidate checks @@ -35,7 +35,7 @@ The earlier `/healthz` smoke failure was caused by a Cloud Run reserved URL path - [x] WIF is used for GitHub-to-Google authentication; no JSON service-account key is stored. - [x] Terraform lifecycle is restricted to the `sandbox` environment and requires an explicit destroy confirmation. -- [x] Cloud Run starts as a non-root user and requires `STAYLONG_API_TOKEN` at runtime. +- [x] The private Cloud Run runtime starts as a non-root user and requires `STAYLONG_API_TOKEN`; the public sandbox intentionally has no shared API token. - [x] The Cloud Run service is private; both health and case-flow requests require Cloud Run IAM, while case creation and concern retrieval additionally require Bearer authentication. - [x] External actions remain approval-gated and the emergency route is deterministic. - [x] Synthetic demo data is schema-validated and contains no real personal data or credentials. diff --git a/docs/technology-and-compliance.md b/docs/technology-and-compliance.md index f6dc9fd..989b1eb 100644 --- a/docs/technology-and-compliance.md +++ b/docs/technology-and-compliance.md @@ -8,13 +8,13 @@ | Concern | Decision | | --- | --- | | Agent runtime | Google ADK for Python | -| Model | A competition-eligible Gemini 3.5+ model on Vertex AI | +| Model | Gemini 3.6 Flash on Vertex AI; Gemma 4 MaaS is a separate fail-closed privacy guard | | API and workflow service | Python 3.12, FastAPI and Pydantic | | Web experience | React, TypeScript, Vite and Tailwind; built static assets served with the FastAPI service | | Persistent case state | Firestore: household, consent, approval, case and immutable audit-event records | | Autonomous work | Cloud Tasks for delayed reminders/retries and Pub/Sub for domain-event routing | -| Approved real-world action | Google Calendar API creates an authorised coordination event; later iterations may add Gmail notifications | -| Runtime | One Cloud Run service in `australia-southeast1` (Sydney) | +| Approved real-world action | Private runtime only: Google Calendar API creates an authorised coordination event; Gmail remains an unsent-draft capability. Public sandbox actions are simulations. | +| Runtime | Two Cloud Run surfaces in `australia-southeast1`: anonymous public sandbox and IAM-protected private runtime | | Infrastructure | Terraform provisions all GCP resource lifecycle; GitHub Actions runs reviewed plans/applies through WIF | | Automation | GitHub Actions for test, lint, Terraform plan/apply and Cloud Run deployment | | Cloud authentication | GitHub OIDC Workload Identity Federation; no service-account JSON keys |