Document static showcase and Colab runtime

README.md

@@ -21,7 +21,8 @@ tags:
 
 ### A 35M-parameter, proposal-only compiler for typed personal actions
 
-[Try the sandboxed demo](https://huggingface.co/spaces/harrrshall/BarunAction-35M) ·
+[Browse the interactive showcase](https://huggingface.co/spaces/harrrshall/BarunAction-35M) ·
+[Run in Colab](https://colab.research.google.com/github/harrrshall/barunaction-35m/blob/main/examples/BarunAction_35M_Demo.ipynb) ·
 [Source release](https://github.com/harrrshall/barunaction-35m/tree/v1.0.0) ·
 [Artifact manifest](./MODEL_ARTIFACTS.json)
 
@@ -30,6 +31,10 @@ JSON context, and a timezone-aware reference time into strict **Action IR v1** J
 **35,072,768 parameters** and is post-trained from
 [`harrrshall/BarunLM-35M`](https://huggingface.co/harrrshall/BarunLM-35M).
 
+The hosted showcase contains six precomputed outputs generated and schema-verified locally with
+this checkpoint; it is not hosted inference. Use the Colab notebook or local runtime to try an
+arbitrary request.
+
 > [!IMPORTANT]
 > BarunAction produces proposals; it does not execute tools. The reference runtime verifies the
 > checkpoint and output schema, returns `execution_permitted: false`, and has no calendar,

demo/BarunAction_35M_Demo.ipynb

@@ -0,0 +1,115 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# BarunAction-35M: run a typed action locally\n",
+        "\n",
+        "This notebook installs the immutable `v1.0.0` runtime, anonymously downloads and hash-verifies the `candidate-v2` checkpoint, and compiles one request on the Colab CPU. The model only proposes typed Action IR: this notebook has no device integration and cannot execute the flashlight action."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!pip -q install \"barunaction-35m @ git+https://github.com/harrrshall/barunaction-35m.git@v1.0.0\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Download the public checkpoint\n",
+        "\n",
+        "The downloader requests only the four release files from Hugging Face, uses anonymous access, and rejects any digest mismatch. The float checkpoint is approximately 141 MB."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import tempfile\n",
+        "from pathlib import Path\n",
+        "\n",
+        "from barunaction import BarunActionCompiler, download_candidate_checkpoint\n",
+        "\n",
+        "model_dir = Path(tempfile.mkdtemp(prefix=\"barunaction-demo-\")) / \"BarunAction-35M\"\n",
+        "downloaded = download_candidate_checkpoint(model_dir)\n",
+        "compiler = BarunActionCompiler(downloaded.path, device=\"cpu\")\n",
+        "print(f\"Verified checkpoint: {downloaded.path}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Compile a request to Action IR\n",
+        "\n",
+        "The caller supplies the tool schema explicitly. `side_effecting: true` tells the deterministic policy layer to require external authorization and confirmation; it does **not** give the model permission to execute anything."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import json\n",
+        "\n",
+        "tools = [\n",
+        "    {\n",
+        "        \"name\": \"turn_on_flashlight\",\n",
+        "        \"description\": \"Turn on the device flashlight.\",\n",
+        "        \"arguments\": {},\n",
+        "        \"required\": [],\n",
+        "        \"additional_arguments\": False,\n",
+        "        \"side_effecting\": True,\n",
+        "    }\n",
+        "]\n",
+        "\n",
+        "result = compiler.infer(\n",
+        "    request=\"Turn on the flashlight\",\n",
+        "    tool_schemas=tools,\n",
+        "    context={},\n",
+        "    now=\"2026-08-05T11:30:00+05:30\",\n",
+        ")\n",
+        "print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))\n",
+        "\n",
+        "assert result.ok\n",
+        "assert result.policy is not None\n",
+        "assert result.policy.execution_permitted is False"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Safety boundary\n",
+        "\n",
+        "A valid Action IR object is a proposal, not authorization. A real product must separately authenticate the user, check permissions, request confirmation when appropriate, apply rate limits, and implement the external tool. BarunAction deliberately implements none of those side-effect paths."
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "BarunAction-35M Demo",
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}