source/README.md

# BarunAction-35M

[![Model](https://img.shields.io/badge/%F0%9F%A4%97_Model-BarunAction--35M-ffcc4d)](https://huggingface.co/harrrshall/BarunAction-35M)
[![Live demo](https://img.shields.io/badge/%F0%9F%A4%97_Spaces-Live_Demo-blue)](https://huggingface.co/spaces/harrrshall/BarunAction-35M)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)](pyproject.toml)

**A 35-million-parameter local compiler for typed personal actions.**

BarunAction-35M turns a natural-language request, explicit tool schemas, context, and a reference
time into strict Action IR JSON. It is small enough for local research, hash-verifies its own
checkpoint, validates every proposal deterministically, and never invokes a real tool.

[Try the live interactive demo](https://huggingface.co/spaces/harrrshall/BarunAction-35M) ·
[Download the model](https://huggingface.co/harrrshall/BarunAction-35M) ·
[Read the model card](docs/barunaction-model-card.md) ·
[Reproduce the benchmark](docs/benchmark.md)

## Release highlights

| | BarunAction-35M candidate-v2 |
| --- | --- |
| Parameters | **35,072,768** |
| Model size | 140.3 MB float; 57.5 MB Darwin ARM64 int8 payload |
| Output | Strict, typed Action IR JSON |
| Mobile Actions development exact match | **602/756 (79.63%)** |
| Matched Qwen2.5-0.5B-Instruct comparison | Retains **90.80%** of exact-match rate at **14.09× fewer parameters** |
| Runtime boundary | Proposals only; external execution is always disabled |
| License | Apache-2.0 code and released weights |

The comparison model is exactly 494,032,768 parameters and scored 663/756 (87.70%). BarunAction
trails it by 61 rows, or 8.07 percentage points. These are strict results on a grouped 756-row
Mobile Actions **development** split derived from public training rows—not the official evaluation
split or a broad safety benchmark.

## See it work

The [Hugging Face Space](https://huggingface.co/spaces/harrrshall/BarunAction-35M) offers curated
calendar, contacts, settings, email, maps, and flashlight examples. It shows:

1. the exact prompt contract supplied to the compact model;
2. the generated Action IR;
3. deterministic parse and schema validation;
4. a readable explanation of the proposed action; and
5. an explicit safety summary showing that no real side effect was executed.

The Space and local demo never connect to a calendar, contact book, mail service, map provider, or
device API.

## Quick start

```console
git clone https://github.com/harrrshall/barunaction-35m.git
cd barunaction-35m
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Weight-free contract and sandbox demonstration
barunaction demo

# Download candidate-v2 from Hugging Face and verify every required SHA-256
barunaction download --output ./models/BarunAction-35M

# Verify again at any time
barunaction verify --checkpoint ./models/BarunAction-35M

# Run deterministic CPU inference
barunaction infer \
  --checkpoint ./models/BarunAction-35M \
  --tools examples/barunaction_tools.example.json \
  --context examples/barunaction_empty_context.example.json \
  --now 2026-08-03T20:00:00+05:30 \
  --request "Turn on the flashlight" \
  --device cpu
```

Every successful result still carries `policy.execution_permitted: false`. A proposal becomes a
real action only if an application supplies its own authentication, authorization, confirmation,
rate limiting, and tool execution layer outside this package.

## Python API

```python
import json

from barunaction import BarunActionCompiler, download_candidate_checkpoint

downloaded = download_candidate_checkpoint("./models/BarunAction-35M")
compiler = BarunActionCompiler(downloaded.path, device="cpu")

with open("examples/barunaction_tools.example.json", encoding="utf-8") as source:
    tools = json.load(source)

result = compiler.infer(
    request="Turn on the flashlight",
    tool_schemas=tools,
    context={},
    now="2026-08-03T20:00:00+05:30",
)
print(json.dumps(result.to_dict(), indent=2))
```

Inputs are rejected unless the request is non-empty, tool declarations are strict and
non-duplicated, context is a JSON object, and `now` is timezone-aware. Outputs are parsed as one
complete JSON object without extraction, repair, coercion, or implicit defaults.

## What the released model learned

Candidate-v2 was post-trained for one epoch with full-parameter, response-only supervised
fine-tuning from the exact `harrrshall/BarunLM-35M` base checkpoint. It saw 7,937 derived examples
once and completed 126 optimizer steps. It used no synthetic teacher data, distillation,
preference optimization, DPO, or reinforcement learning.

The released training population covers seven Mobile Actions tools:

- `create_calendar_event`
- `create_contact`
- `open_wifi_settings`
- `send_email`
- `show_map`
- `turn_off_flashlight`
- `turn_on_flashlight`

See [Training](docs/training.md) for the exact recipe and [Data card](docs/barunaction-data-card.md)
for revisions, derivation, licenses, hashes, and redistribution boundaries.

## Benchmark result and terminology

The primary metric is **strict Action IR AST exact match**. A prediction must be one valid JSON
object, satisfy the supplied tool schema, match the decision and call mode, preserve ordered calls
for `SINGLE`/`SERIAL`, and match typed arguments exactly. `PARALLEL` calls are compared as an
order-independent multiset. Missing outputs, parse failures, schema failures, truncations, and
generation failures remain incorrect.

| Model | Parameters | Parse valid | Schema valid | Strict AST exact |
| --- | ---: | ---: | ---: | ---: |
| **BarunAction-35M candidate-v2** | **35,072,768** | 756/756 | 755/756 | **602/756 (79.63%)** |
| Qwen2.5-0.5B-Instruct | 494,032,768 | 755/756 | 754/756 | 663/756 (87.70%) |

The comparison used identical 7,937 training IDs, 756 development IDs, semantic labels, one pass,
effective batch 63, 126 optimizer steps, seed 17, final-checkpoint selection, and unconstrained
deterministic greedy decoding. Model-native tokenizers/templates and learning rates differed, and
BarunAction had an earlier development sweep. This is therefore a one-seed matched
**semantic-adaptation** comparison, not a universal model ordering.

The source is `google/mobile-actions` revision
`e920309bc2acbc2e99a5e3201cf37df2b9fd9151` (CC BY 4.0). The reported 756 rows are grouped public
development data and contain only `CALL` cases. The separate 961-row official evaluation split
was never read or materialized.

Full definitions, evaluator logic, exact model revisions, data hashes, decoding settings, and
curated sample-level outcome evidence are in [Benchmark](docs/benchmark.md) and
[Evaluation](docs/evaluation.md). The executable scorer is
[`src/barunlm/evaluation/mobile_actions.py`](src/barunlm/evaluation/mobile_actions.py).

## Reproduce

The public repository separates four layers so results are inspectable without internal lab
state:

```text
src/                 model, training, inference, schema, scorer, quantization
configs/             released candidate and matched-baseline contracts
benchmarks/          curated manifests, aggregates, paired outcomes, verification
docs/                model, data, training, evaluation, retrieval, deployment cards
space/               public Gradio demonstration
```

Common verification commands:

```console
# Product runtime and scorer tests
pytest -q

# Style and formatting
ruff check .
ruff format --check .

# Rebuild the grouped public train/dev manifests from the pinned source.
# Official evaluation rows remain opaque and are never parsed or materialized.
python -m barunlm.datasets.mobile_actions \
  --download-pinned \
  --tokenizer-json ./models/BarunAction-35M/tokenizer.json \
  --tokenizer-revision candidate-v2 \
  --output-dir ./build/mobile-actions

# Re-score the published BarunAction predictions without generating new outputs
barunaction score-mobile \
  --manifest ./build/mobile-actions/dev.jsonl \
  --predictions benchmarks/evidence/barunaction-predictions.jsonl \
  --output ./reproduced-score
```

No raw training dataset or sealed evaluation label is redistributed. The repository supplies
pinned source revisions, derivation code, membership and content hashes, licenses, evaluator code,
aggregate results, and curated sample-level comparison outcomes. See
[Release evidence](docs/barunaction-release-evidence.md).

## Model files

The canonical Hugging Face mirror contains:

| File | SHA-256 |
| --- | --- |
| `model.safetensors` | `fdb95ccf58a095e0d321be998924318b35ee59a334f6dd97d8726d2cf80021d3` |
| `tokenizer.json` | `70ded9605fccd09c2340ca7e225361eab0ae8b4dbbb0d6e26343ab5183979db6` |
| `barun_config.json` | `9b3a1d71baa95a198744d250f9629231738d942570b8685c44307fd83dd33565` |
| `checkpoint_manifest.json` | `c743ab7c4d33ae75c6b0aa4547458a961b92766da8fcf85fd148fda2ebb5530a` |

The source artifacts remain immutable public W&B `v0` releases. Hugging Face is a byte-identical,
freshly verified mirror. See [Retrieval](docs/barunaction-retrieval.md) for both locations.

## Scope and safety

BarunAction-35M is a compact proposal compiler, not an autonomous assistant. Its public
development set contains no safety denominator and does not establish performance on ambiguity,
unsafe requests, out-of-scope requests, unseen schemas, or broad function calling. Product
integrations must validate identity and permissions outside the model and must never treat valid
JSON as authorization.

The included simulator is intentionally in-memory only. It has no network client and no real tool
handlers. This makes the demo useful for understanding the contract without risking a message,
calendar edit, or device change.

## Citation

```bibtex
@software{harrrshall2026barunaction35m,
  author  = {Harrrshall},
  title   = {BarunAction-35M: A Compact Typed Personal-Action Compiler},
  year    = {2026},
  version = {candidate-v2},
  url     = {https://github.com/harrrshall/barunaction-35m}
}
```

## License

Source code and released model weights are licensed under Apache License 2.0. Mobile Actions is
licensed CC BY 4.0 and retains its upstream attribution and terms. See [NOTICE](NOTICE) and the
[data card](docs/barunaction-data-card.md).