Polish for public release

.env.example

@@ -1,5 +1,23 @@
+# Copy to .env at the repo root. Both services load it automatically.
+# .env is gitignored — never commit real keys.
+
+# Gemini API key for the backend. Get one at https://aistudio.google.com/apikey
+# Not needed if you run the backend with MOCK_LLM=true.
 GEMINI_API_KEY=
+
+# Run the backend without Gemini: every LLM call is answered from canned,
+# rule-based responses in backend/mock_llm.py. No network, no key, no quota.
+# Set to true to try the project without an API key.
+MOCK_LLM=false
+
+# Where the backend subscribes to the vision service's scene stream.
 VISION_WS_URL=ws://localhost:8000/ws
+
+# Seconds to wait before reconnecting when that websocket drops.
 VISION_RECONNECT_DELAY=2.0
-LLM_HTTP_HOST=127.0.0.1
-LLM_HTTP_PORT=8001
+
+# Interface the vision service binds to. Defaults to localhost because none of
+# its endpoints are authenticated and GET /frame serves live camera stills.
+# Only change this on a network you trust. See PRIVACY.md.
+VISION_HOST=127.0.0.1
+VISION_PORT=8000

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      # Only the backend is installed. vision_service pulls in InsightFace,
+      # ultralytics, and OpenCV — hundreds of MB of wheels plus model downloads —
+      # and its endpoints need a physical camera, so it is not exercised here.
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r backend/requirements.txt -r backend/requirements-dev.txt
+
+      - name: Lint
+        run: ruff check .
+
+      # No GEMINI_API_KEY is set: the suite runs against backend/mock_llm.py and
+      # must stay free of network calls.
+      - name: Test
+        run: pytest backend/tests -q

.gitignore

@@ -21,22 +21,28 @@ env/
 .env
 local_settings.py
 
-# IDE
+# IDE / agent tooling
 .vscode/
 .idea/
+.claude/
 
-# Testing/Coverage
+# Testing / linting caches
 .pytest_cache/
+.ruff_cache/
 .coverage
 htmlcov/
-.tox/   
+.tox/
 
 # OS
 .DS_Store
+**/.DS_Store
 
 # Face embeddings — biometric data, never commit
 vision_service/storage/data/embeddings.json
 
+# Offline chatbot's local store — caregiver-entered personal data + Chroma index
+**/memory_data/
+
 # Downloaded model weights — large files, re-downloaded on first run
 *.pt
 *.onnx

DISCLAIMER.md

@@ -0,0 +1,64 @@
+# Disclaimer
+
+**This is a research and demonstration project. It is not a medical device, and it must not be
+used to make care decisions.**
+
+Please read this before running the project, showing it to anyone, or reusing any part of it.
+
+## Not a medical device
+
+This software has not been evaluated, cleared, or approved by the FDA, the EMA, the MHRA, or any
+other regulatory body. It is not certified under any medical-device framework. It was built as a
+hackathon prototype to explore whether computer vision and language models could be combined into
+a memory-support interface — nothing more.
+
+## Not clinically validated
+
+No part of this system has been tested in a clinical setting, reviewed by clinicians, or measured
+against any standard of care. The prompts, the retrieval logic, and the behavioral categories were
+written by developers, not by medical professionals.
+
+In particular, the `POST /api/caregiver/analyze` endpoint returns a field named
+`clinical_rationale`. **That name describes the shape of the data, not its authority.** It is
+language-model output. It is not a clinical assessment, and no clinician reviewed it.
+
+## The model can be wrong
+
+The assistant is built on a large language model. Like all such models, it can:
+
+- state things that are confidently wrong,
+- invent details that were never in the patient profile,
+- misread a scene, or misidentify a person or object,
+- produce guidance that is inappropriate for a specific person's condition.
+
+Face recognition additionally produces false matches and false rejections. A card naming the wrong
+person is an expected failure mode of this system, not an edge case.
+
+## Do not use this for
+
+- Diagnosis, screening, triage, or staging of dementia or any other condition.
+- Treatment, medication, or dosage decisions of any kind.
+- Unsupervised care, monitoring, or companionship for a person with dementia.
+- Any situation where a wrong or missing answer could affect someone's safety.
+- Storing or processing real patient records, protected health information (PHI), or any data
+  subject to HIPAA, GDPR, or comparable regimes.
+
+## Always defer to professionals
+
+Nothing this software outputs is a substitute for a qualified healthcare professional. If you are
+caring for someone with dementia, decisions about their care belong with their doctor and care
+team.
+
+**In an emergency, contact your local emergency services. Do not consult this software.**
+
+## Sample data
+
+`patient_profile.json` describes a fictional patient ("Arthur") invented for demonstration. It is
+not a real person's record, and the repository contains no real patient data.
+
+## Liability
+
+This project is provided under the MIT License, which includes no warranty of any kind. See
+[LICENSE](LICENSE). The authors accept no liability for any use of this software.
+
+See also [PRIVACY.md](PRIVACY.md) for how the system handles biometric data.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sharif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PRIVACY.md

@@ -0,0 +1,87 @@
+# Privacy and biometric data
+
+This project processes **face biometrics** and a **live camera feed**. That carries real legal and
+ethical weight, so this document states plainly what is captured, where it goes, and how to delete
+it.
+
+Read this alongside [DISCLAIMER.md](DISCLAIMER.md).
+
+## What the system captures
+
+| Data | Where it comes from | Where it is stored |
+|---|---|---|
+| **Face embeddings** — a 512-float vector per registered face | `POST /register` and `POST /register/capture` in `vision_service` | `vision_service/storage/data/embeddings.json`, on your machine |
+| **Name, relationship, note** for each registered person | The registration form | Same file |
+| **Live camera frames** | Your webcam, while `vision_service` runs | In memory only. Served on request via `GET /frame`; never written to disk |
+| **Patient profile** — name, condition, family, preferences | `patient_profile.json`, edited by hand | That file, on your machine |
+| **Scene descriptions and caretaker questions** | The running pipeline | Sent to the Gemini API (see below); held in memory, never written to disk |
+
+Face embeddings are **biometric identifiers**. Under the GDPR they are special-category data
+(Art. 9), and jurisdictions such as Illinois (BIPA) and Texas (CUBI) impose specific consent and
+retention duties on anyone who collects them. Treat the embeddings file accordingly.
+
+## What leaves your machine
+
+**`vision_service` is fully offline.** Face recognition and object detection run locally. No image,
+frame, or embedding is ever transmitted anywhere. Model weights are downloaded once on first run.
+
+**`backend` calls the Google Gemini API.** What is sent: the text description of the current scene
+(names, relationships, object labels), retrieved lines from `patient_profile.json`, and caretaker
+questions. **No images are ever sent** — only text. Your prompts are subject to
+[Google's Gemini API terms](https://ai.google.dev/gemini-api/terms). If you do not want any data
+leaving your machine, run with `MOCK_LLM=true`, which makes no network calls at all.
+
+**`offline-chatbot/` is fully offline.** It uses a local Ollama model and a local Chroma store.
+
+## Consent
+
+**Register only people who have knowingly agreed to it.** Enrolling someone's face without their
+informed consent is unlawful in many jurisdictions, regardless of intent.
+
+Where the person cannot meaningfully consent — which includes many people living with advanced
+dementia — consent must come from whoever holds legal authority for their care decisions, in line
+with local law.
+
+## Deleting biometric data
+
+Remove one person:
+
+```bash
+curl -X DELETE http://localhost:8000/people/NAME
+```
+
+Remove everyone, permanently:
+
+```bash
+rm vision_service/storage/data/embeddings.json
+```
+
+The file is recreated empty on the next registration. There is no backup and no recovery — that is
+deliberate.
+
+## Retention
+
+The system applies **no automatic retention limit**. Embeddings persist until you delete them. If
+you deploy this anywhere real, set and enforce a retention policy; the code will not do it for you.
+
+## Committing data by accident
+
+`.gitignore` excludes `vision_service/storage/data/embeddings.json`, `**/memory_data/`, and `.env`.
+Verify before pushing:
+
+```bash
+git ls-files | grep -E 'embeddings\.json|memory_data|\.env$'   # must print nothing
+```
+
+## Known limitations
+
+This is a prototype, and its security posture reflects that:
+
+- **No authentication on any endpoint.** Anyone who can reach the port can register a face, delete
+  a person, or pull a live camera still from `GET /frame`.
+- **CORS is fully open** (`allow_origins=["*"]`) on both services.
+- **No encryption at rest.** `embeddings.json` is plain, readable JSON.
+- **No audit log.** Nothing records who registered or deleted whom.
+
+Both services therefore default to binding `127.0.0.1`. Do not expose either to a network, and do
+not deploy this as-is.