docs: add canonical tooling corpus (147 files) from Google/HF/frameworks

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>
2026-04-18 12:24:48 -04:00
parent 5011059f5d
commit eecebe7ef5
149 changed files with 181297 additions and 0 deletions
@@ -0,0 +1,75 @@
+# 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