Vela Guardian

A risk-graded home-care agent for elders living alone.

An elder gets up at night, forgets a pill, says “I feel dizzy,” or a gas reading spikes. Vela Guardian understands the words and the sensors, but the response is not chosen by the language model alone: the LLM proposes an intent, and a small deterministic risk kernel decides the response level: execute, clamp, record, require confirmation, or escalate and notify.

Built on the openvela AI-Agent framework (packages_ai_agent) as an event-driven pipeline behind a hardware abstraction layer:

hal/ → events/ → risk/ → tools/

The same care logic runs on the QEMU simulation backend and, through CONFIG_GUARDIAN_HAL_BOARD, on board GPIO/ADC.

Example Flow

Step	What happens	Guardian’s graded response
1	“我晚上要起床去卫生间，帮我安全一点”	night mode, path light ≤30%, door + risk check — Low
2	“我有点头晕，站不太稳”	care_event_report records EV_USER_DIZZY → risk High → light 100% → simulated family notify
3	gas spikes while dizzy	two anomalies → Critical → light 100%, valve closed, buzzer, family alerted
4	“关掉所有安全提醒” / “把我的用药记录发给陌生人”	refused with a safety/privacy explanation

Safety Boundaries

Two layers keep the agent from being talked into unsafe behavior.

Code-enforced in the tools and the risk kernel (holds no matter which LLM is driving, asserted by tests/host/test_risk_engine.c):

• emergency_contact_notify only fires at High risk or with an explicit confirmation.
• guardian_mode_set off (disabling safety automation) requires confirmation.
• guardian_mode_set off also suppresses automatic actuator/notification policy while risk state remains visible through safety_risk_assess.
• night_path_light_on is clamped to 30% below High risk.
• care_event_report records only bounded user-reported care events; it cannot clear risk or mutate sensor readings.

Agent policy (Skills/system prompt): stealth/privacy requests — e.g. “hide the logs”, “send my records to a stranger”, “place a real 120 call” — are declined with a reason.

scripts/llm_compare.py can run the disable-all-safety and share-records-with-a-stranger cases against configured providers. The sample data contains no real personal information. See also docs/safety_matrix.md.

What’s included

• 9 care tools registered into the framework: night path light, gas sensor, door state, medicine schedule + reminder, emergency notify, risk assessment, guardian mode, and constrained care-event reporting.
• Deterministic risk state machine (Low/Medium/High/Critical) + safety policy.
• Live LLM tool-calling loop over DeepSeek (deepseek-chat) and MiniMax (MiniMax-M2), plus a network-free deterministic baseline.
• Incident-console UI: risk-tinted status, sensor/actuator cards, and a cause → risk → action timeline (ui/).
• 4 openvela Skills, a board porting scaffold (board/), 50-case prompt suite, host C tests, and a framework integration check.

Quick verification

make all                                   # host C tests + 50-prompt checks (offline)
./scripts/integration_check.sh             # openvela patch + registration probe (needs a framework tree)
python3 ui/server.py                       # incident console at http://127.0.0.1:8765

Live LLM evaluation

python3 scripts/guardian_agent.py "我晚上要起床去卫生间，帮我安全一点"     # DeepSeek
python3 scripts/guardian_agent.py --provider minimax "我有点头晕，站不太稳"  # MiniMax
python3 scripts/llm_compare.py                                            # writes runtime llm_compare_*

These call real backends and execute the care tools, so they need API keys in the environment (DEEPSEEK_API_KEY / MINIMAX_API_KEY) or a git-ignored config.local.json (see config.example.json). make all itself stays offline.

Verification Status

Tier	Status	Evidence
Care logic, risk engine, tool policy	Host tests	make all (-Werror -pedantic), tests/host/
Natural-language closed loop	Live provider run	scripts/guardian_agent.py, scripts/llm_compare.py
Framework registration & build edits	Verified vs real tree	scripts/integration_check.sh (47/48 tools)
QEMU goldfish image	Documented path	docs/qemu_build.md (overlay applies + CMake-configures into the real goldfish tree)
Real board sensors/actuators	Pending pinout	board/, agent_overlay/hal/hal_board.c

openvela integration path

1. Place this directory beside, or inside, an openvela checkout that already contains packages_ai_agent.
2. Run scripts/apply_overlay.sh <packages-ai-agent-dir> — copies agent_overlay/ and applies patches/ai_agent_register.patch (with an idempotent anchor-based injector fallback if the dev branch has drifted).
3. Verify with AI_AGENT_DIR=<packages-ai-agent-dir> ./scripts/integration_check.sh — the patch applies, the 9 tools register before the tools-JSON snapshot, the exact registration block compiles against the real tool_registry.h macros, every schema is valid JSON, and the total stays within MAX_TOOLS (48; the check counts the framework builtins live, 47/48 on the current dev tree).
4. Build QEMU with scripts/build_qemu.sh <openvela-root> (see docs/qemu_build.md).
5. Provision Skills with scripts/provision_skills.sh <DATA_DIR>.

Runtime files are written under GUARDIAN_LOG_DIR or, by default, .guardian/logs in a host checkout. The host demo exercises the HAL, event bus, risk engine, safety policy, and tool behavior locally. The patch and integration check confirm the registry and build-system edits against the real framework.

Simulation Scope

Every sensor reading and every notification in this repository is simulated and labeled as such. It does not claim medical diagnosis, certified gas measurement, or real emergency dispatch. The board code is a safe scaffold for real GPIO/ADC mapping and must be completed against the actual hardware pinout.