Mortdecai
eecebe7ef5
Five-lane parallel research pass. Each subdir under tooling/ has its own README indexing downloaded files with verified upstream sources. - google-official/: deepmind-gemma JAX examples, gemma_pytorch scripts, gemma.cpp API server docs, google-gemma/cookbook notebooks, ai.google.dev HTML snapshots, Gemma 3 tech report - huggingface/: 8 gemma-4-* model cards, chat-template .jinja files, tokenizer_config.json, transformers gemma4/ source, launch blog posts, official HF Spaces app.py - inference-frameworks/: vLLM/llama.cpp/MLX/Keras-hub/TGI/Gemini API/Vertex AI comparison, run_commands.sh with 8 working launches, 9 code snippets - gemma-family/: 12 per-variant briefs (ShieldGemma 2, CodeGemma, PaliGemma 2, Recurrent/Data/Med/TxGemma, Embedding/Translate/Function/Dolphin/SignGemma) - fine-tuning/: Unsloth Gemma 4 notebooks, Axolotl YAMLs (incl 26B-A4B MoE), TRL scripts, Google cookbook fine-tune notebooks, recipe-recommendation.md Findings that update earlier CORPUS_* docs are flagged in tooling/README.md (not applied) — notably the new <|turn>/<turn|> prompt format, gemma_pytorch abandonment, gemma.cpp Gemini-API server, transformers AutoModelForMultimodalLM, FA2 head_dim=512 break, 26B-A4B MoE quantization rules, no Gemma 4 tech report PDF yet, no Gemma-4-generation specialized siblings yet. Pre-commit secrets hook bypassed per user authorization — flagged "secrets" are base64 notebook cell outputs and example Ed25519 keys in the HDP agentic-security demo, not real credentials. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# Gemma 4 + HDP: Securing Agentic Function Calls
|
||
|
||
This example demonstrates how to integrate the **Human Delegation Provenance (HDP)** protocol with **Gemma 4's native function-calling** to cryptographically verify that every tool invocation was authorized by a human principal before execution.
|
||
|
||
## The problem
|
||
|
||
Gemma 4 is purpose-built for agentic workflows. Its native function-calling lets it autonomously call tools and APIs across multi-step plans — on anything from a cloud workstation to a Raspberry Pi running a robot offline.
|
||
|
||
This creates a gap: when Gemma 4 generates a function call, there is no verifiable record that a human principal authorized that specific action. An injected prompt, a compromised system prompt, or a lateral pivot from another agent can trigger function calls that are indistinguishable from legitimate requests at the tool interface.
|
||
|
||
HDP closes this gap.
|
||
|
||
## What HDP does
|
||
|
||
HDP (IETF draft: `draft-helixar-hdp-agentic-delegation-00`) provides:
|
||
|
||
- **Ed25519-signed Delegation Tokens (HDTs)** issued by a human principal
|
||
- **Scope constraints** — which tools the agent is permitted to call
|
||
- **Irreversibility classification** (Class 0–3) — from read-only to physical actuation
|
||
- **Pre-execution verification** — the middleware gate runs *before* any tool executes
|
||
- **Audit log** — a tamper-evident record of every authorization decision
|
||
|
||
For Gemma 4 on **edge devices directing physical actuators** (Jetson Nano, Raspberry Pi + robot arm), the HDP-P companion specification adds embodiment constraints, policy attestation, and fleet delegation controls.
|
||
|
||
## Files
|
||
|
||
| File | Description |
|
||
|---|---|
|
||
| `Gemma_4_HDP_Agentic_Security.ipynb` | Full walkthrough notebook — load Gemma 4, issue tokens, gate function calls |
|
||
| `hdp_middleware.py` | Drop-in middleware — `HDPMiddleware.gate()` wraps any Gemma 4 tool executor |
|
||
|
||
## Quick start
|
||
|
||
```python
|
||
from hdp_middleware import HDPDelegationToken, HDPMiddleware, IrreversibilityClass
|
||
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
|
||
|
||
# Human principal issues a delegation token
|
||
private_key = Ed25519PrivateKey.generate()
|
||
token = HDPDelegationToken.issue(
|
||
principal_id="alice@example.com",
|
||
agent_id="gemma4-agent-01",
|
||
scope=["get_weather", "send_email"],
|
||
max_class=IrreversibilityClass.CLASS_2,
|
||
ttl_seconds=3600,
|
||
private_key=private_key,
|
||
)
|
||
|
||
# Middleware verifies every Gemma 4 function call before execution
|
||
middleware = HDPMiddleware(public_key=private_key.public_key())
|
||
|
||
result = middleware.gate(
|
||
function_call={"name": "send_email", "parameters": {"to": "bob@example.com", ...}},
|
||
token=token,
|
||
)
|
||
|
||
if result.allowed:
|
||
execute_tool(function_call)
|
||
```
|
||
|
||
## Irreversibility classes
|
||
|
||
| Class | Definition | Authorization |
|
||
|---|---|---|
|
||
| 0 | Fully reversible — reads, queries | HDT sufficient |
|
||
| 1 | Reversible with effort — writes, moves | HDT sufficient |
|
||
| 2 | Irreversible — send, delete, publish | HDT + principal confirmation |
|
||
| 3 | Irreversible + potentially harmful — physical actuation | Dual-principal required (HDP-P) |
|
||
|
||
## References
|
||
|
||
- **IETF draft:** https://datatracker.ietf.org/doc/draft-helixar-hdp-agentic-delegation/
|
||
- **Zenodo DOI:** https://doi.org/10.5281/zenodo.19332023
|
||
- **HDP-P (physical AI):** https://doi.org/10.5281/ZENODO.19332440
|
||
- **Helixar:** https://helixar.ai
|