feat: publish the experimental contact model

NOTICE

@@ -0,0 +1,9 @@
+Tessera
+
+The code in this repository is licensed under MIT OR Apache-2.0.
+
+The trained model weights are licensed under CC BY 4.0. They are derived from the following sources, whose notices are reproduced as their licenses require.
+
+OpenStreetMap: Contains information from OpenStreetMap, © OpenStreetMap contributors, available under the Open Database License (https://opendatacommons.org/licenses/odbl/1-0/). The address training data derived from it is itself available under the Open Database License: it is produced deterministically from the libpostal training files published at https://archive.org/download/libpostal-parser-training-data-20170304/ by the trainer's prepare command, using the manifests and label map under data/manifests/.
+
+Open Addresses UK: Contains data from Open Addresses UK, published by Open Addresses Ltd under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). It includes data originally licensed under the UK Open Government Licence or the Ordnance Survey OpenData Licence: contains public sector information licensed under the Open Government Licence v3.0, and OS data © Crown copyright and database right.

README.md

@@ -0,0 +1,166 @@
+---
+language:
+- en
+license: cc-by-4.0
+pipeline_tag: token-classification
+library_name: tessera
+tags:
+- tessera
+- contact-extraction
+- named-entity-recognition
+- wasm
+- experimental
+---
+
+# tessera
+
+A tiny model for extracting contact details from text, locally.
+
+<p align="center">
+
+[![CI](https://github.com/theiskaa/tessera/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/theiskaa/tessera/actions/workflows/ci.yml)
+[![Model](https://img.shields.io/badge/model-int8%20%C2%B7%203.49%20MB-blue)](#model)
+[![Code license](https://img.shields.io/badge/code-MIT%20OR%20Apache--2.0-blue)](#license)
+[![Weights license](https://img.shields.io/badge/weights-CC%20BY%204.0-blue)](NOTICE)
+
+</p>
+
+Tessera finds people, organizations, postal addresses, emails, and phone numbers. It returns their exact positions in the original text, splits addresses into components, and groups related details into contacts. The same Rust implementation runs natively and through WebAssembly in browsers, Node, and Bun.
+
+Email and phone extraction uses validating rules. Names, organizations, and addresses use an int8 neural network; a separate network parses address components. Inference stays in your process or browser worker. No text is sent to an inference service.
+
+**This release is experimental.** The learned detector currently focuses on English United States material. Organization detection and unfamiliar prose need review; fresh unseen release accuracy has not been established. See [results and limitations](#results-and-limitations).
+
+[Usage](#usage) · [Model](#model) · [Results](#results-and-limitations) · [License](#license)
+
+## Usage
+
+| Operation                              | Use it to                                                | Returns                                      |
+| -------------------------------------- | -------------------------------------------------------- | -------------------------------------------- |
+| `detect`                               | Find individual entities in a document                   | Kind, source offsets, confidence, and origin |
+| `parse_address` / `parseAddress`       | Split text already known to be one address               | Labeled address components                   |
+| `extract_contacts` / `extractContacts` | Associate extracted details with people or organizations | Contacts and unassigned entities             |
+
+Rust and CLI offsets use UTF-8 bytes. JavaScript offsets use UTF-16 code units, so `text.slice(start, end)` returns the entity. Every `end` is exclusive. Keep the original string when using offsets.
+
+### Rust
+
+For an application beside a Tessera checkout, add the runtime as a local dependency:
+
+```toml
+[dependencies]
+tessera = { path = "../tessera/tessera" }
+```
+
+Load the bundle and its checksum once, then reuse the extractor:
+
+```rust
+use tessera::{Config, Kind, Query, Tessera};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let bytes = std::fs::read("models/tessera-v1.safetensors")?;
+    let checksum = std::fs::read_to_string("models/tessera-v1.sha256")?;
+    let extractor = Tessera::load(&bytes, Config {
+        kinds: Kind::all(),
+        expected_checksum: Some(checksum.trim()),
+    })?;
+    let query = Query { country_hint: &["US"], ..Query::default() };
+    let text = "Jordan Avery, Project Coordinator\nAcme Corporation\n500 Main St, Springfield, IL 62701\n+1 202-555-0199\njordan@acme.example";
+    let contacts = extractor.extract_contacts(text, &query)?;
+    println!("{} contacts, {} unassigned entities",
+        contacts.contacts.len(), contacts.unassigned.len());
+    let address = extractor.parse_address("400 Broad St, Seattle, WA 98109", &query)?;
+    println!("{} address components", address.components.len());
+    Ok(())
+}
+```
+
+`unassigned` is part of a successful extraction: the grouper leaves details there when it cannot confidently choose a contact. Experimental detection may omit or mislabel entities.
+
+### JavaScript
+
+Serve the bundle and checksum with your application:
+
+```js
+import { createTessera } from "tessera";
+
+const response = await fetch("/models/tessera-v1.sha256");
+if (!response.ok) throw new Error("Could not load model checksum");
+const integrity = (await response.text()).trim();
+const extractor = await createTessera({
+  modelUrl: "/models/tessera-v1.safetensors",
+  integrity,
+  worker: true,
+});
+
+try {
+  const text = "Contact hello@example.org or +1 202-555-0123.";
+  const entities = await extractor.detect(text, { countryHint: ["US"] });
+  for (const entity of entities) {
+    console.log(entity.kind, text.slice(entity.start, entity.end));
+  }
+  const contacts = await extractor.extractContacts(text, {
+    countryHint: ["US"],
+  });
+  console.log(contacts.contacts, contacts.unassigned);
+} finally {
+  extractor.dispose();
+}
+```
+
+For Node or Bun, read the bundle from disk and pass `modelBytes` instead of `modelUrl`. `worker: true` runs inference off the browser's main thread when workers are available; it is ignored outside that environment. Rules alone need no model fetch: `createTessera({ kinds: ["email", "phone"] })`.
+
+The complete JavaScript API is in [index.d.ts](https://github.com/theiskaa/tessera/blob/main/tessera/js/index.d.ts).
+
+### Options
+
+- `country_hint` / `countryHint` helps interpret national phone numbers; it does not change the detector's training coverage.
+- `include_uncertain` / `includeUncertain` returns additional uncertain results. Internal detector thresholds still apply.
+- `parse_address` accepts one address of at most 256 non-whitespace tokens and 8 KiB.
+- Rust's optional `markdown` feature scans prose and contact link destinations while retaining source offsets. The default JavaScript package omits it and rejects `format: "markdown"`.
+- Rust failures use `tessera::Error`; JavaScript failures expose a `TesseraError` code. An empty successful result means nothing was returned.
+
+## Model
+
+The distributed [Safetensors bundle](tessera-v1.safetensors) contains both the entity detector and address parser. It uses Tessera's own runtime: it is not a Transformers `AutoModel` checkpoint, and no hosted inference endpoint is included.
+
+| Property                             | Value                                                 |
+| ------------------------------------ | ----------------------------------------------------- |
+| Model version / bundle format        | `0.3.0` / `2`                                         |
+| Runtime version                      | `0.1.0`                                               |
+| Bundle size                          | 3,489,616 bytes (3.49 MB; about 3.09 MB with gzip)    |
+| Weight encoding                      | Per-channel symmetric int8; float32 scales and biases |
+| Detector architecture                | `detector-context96-rms-v2`                           |
+| Hidden channels / convolution kernel | 96 / 3                                                |
+| Detector dilations                   | `[1, 2, 4, 8, 16, 1, 64]`                             |
+| Normalization                        | Channel RMS after each residual block, epsilon `1e-5` |
+| Context radius / window / overlap    | 96 / 2,048 / 448 retained tokens                      |
+
+The detector combines hashed character n-grams of lengths 2, 3, and 4 with script, shape, and contextual features. It predicts BIO labels for PERSON, ORG, and ADDRESS. Email and phone spans found by rules are protected from competing model labels. The parser labels components of supplied or detected addresses, and the grouper associates related entities.
+
+The Safetensors header contains 39 metadata fields, including graph and decoder identifiers, dimensions, labels, feature settings, licensing, experimental status, and source checkpoint hashes. [bundle.json](bundle.json) exposes the same metadata in readable form. Load [tessera-v1.sha256](tessera-v1.sha256) with the bundle to verify its integrity.
+
+Format 2 binds the context graph and decoder explicitly. The runtime also reads legacy format 1 bundles using their original graph. The asset filename is independent of its embedded model version.
+
+## Results and limitations
+
+The detector completed 4,000 optimizer updates. It failed the automatic quality-promotion requirements, including the full 95% training-seen gate, and was accepted for an experimental release. The bounded run finished, but the full configured training schedule did not; metadata retains `detector_training_complete=false`.
+
+These are **native checkpoint exact entity F1** scores, measured before int8 packaging. Both the kind and boundaries must match:
+
+| Evaluation set                    | Documents | PERSON |    ORG | ADDRESS |
+| --------------------------------- | --------: | -----: | -----: | ------: |
+| Real training-seen documents      |     1,799 | 96.47% | 75.39% |  97.33% |
+| Reused real development documents |       196 | 76.86% | 53.76% |  89.22% |
+
+Training-seen results measure fitting. The development set was reused during model selection. **Neither establishes fresh unseen release accuracy.** These scores do not measure email/phone rules, address parsing, or contact grouping. Aggregate PERSON results also conceal weaker biography coverage; organization names, aliases, and boundaries remain a substantial source of error.
+
+Separately, the **packaged address parser** scored 99.05% component F1 and 95.23% completely correct parses on its 3,000-row US test shard through `parse_address`. This tests parsing supplied addresses, not detecting them in prose.
+
+Eight of thirteen small public detector fixture cases remain documented failures, including missed people in prose and tables. Their expected labels are retained. These examples expose limitations; they are not an independent accuracy benchmark.
+
+Confidence and `review_recommended` are signals for inspection, not guarantees. Check names, organizations, and contact assignments before using them in important records. Other countries, languages, and unfamiliar document layouts have no demonstrated general accuracy from this evaluation.
+
+## License
+
+Code is available under [MIT](https://github.com/theiskaa/tessera/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/theiskaa/tessera/blob/main/LICENSE-APACHE). Trained weights are licensed under CC BY 4.0; retain [NOTICE](NOTICE) when redistributing them. It preserves the underlying source attributions, including OpenStreetMap and Open Addresses UK. Training combines synthetic contacts and annotated real US documents; the parser has its own training history. Raw corpora and local run evidence are not part of the model upload.

bundle.json

@@ -0,0 +1,47 @@
+{
+  "runtime": "tessera",
+  "file": "tessera-v1.safetensors",
+  "bytes": 3489616,
+  "sha256": "abfa972301f82d23240cc15bc9f70c7c574bb047e33473254a737abacfe995ff",
+  "metadata": {
+    "created": "2026-10-02",
+    "decoder_contract": "tessera-bio-context96-address-continuation-v1",
+    "description": "Experimental contact extraction for United States documents",
+    "detector_architecture": "{\"name\":\"detector-context96-rms-v2\",\"dilations\":[1,2,4,8,16,1,64],\"kernel\":3,\"channels\":96,\"operator\":\"post-residual-channel-rms-v2\",\"epsilon\":0.00001,\"learned_parameters\":0,\"margin_tokens\":96,\"overlap_tokens\":448,\"window_tokens\":2048,\"max_entity_tokens\":256,\"decoder_contract\":\"tessera-bio-context96-address-continuation-v1\"}",
+    "detector_best_sha256": "f4248d1cd0b9f208f4143cacd284c6009352385d0199799e9eac42ff3e35a2aa",
+    "detector_input_snapshot_sha256": "ece44fc87959a391b3f99f3c113655f26cf8e45d2c7bc44f474b10bfc1b6517c",
+    "detector_labels": "[\"O\",\"B-PERSON\",\"I-PERSON\",\"B-ORG\",\"I-ORG\",\"B-ADDRESS\",\"I-ADDRESS\"]",
+    "detector_network": "{\"hidden\":96,\"kernel\":3,\"dilations\":[1,2,4,8,16,1,64]}",
+    "detector_parameter_sha256": "b9ca96cf3b9cd92d96151e6226eb134a04312d691a4dd603fbe8076625cc0b87",
+    "detector_quantized_sha256": "2d211666c7e04fceb61073fdbbd73d5457019feed7ed5f437c3a0f3b94eddaa2",
+    "detector_training_complete": "false",
+    "detector_training_updates": "4000",
+    "evaluation_scope": "training-seen and reused development; no fresh unseen evaluation",
+    "experimental_regions": "[\"US\"]",
+    "feature_config": "{\"ngram_sizes\":[2,3,4],\"hash_buckets\":32768,\"hash_seed\":0,\"max_ngrams_per_token\":64,\"flag_bits\":23,\"script_rows\":13,\"shape_rows\":64}",
+    "format": "2",
+    "fresh_unseen_evaluation_pending": "true",
+    "general_accuracy_claim": "false",
+    "license": "CC-BY-4.0",
+    "model_name": "Tessera",
+    "model_scope": "US",
+    "model_version": "0.3.0",
+    "nets": "parser,detector",
+    "parser_best_sha256": "9c5d0ec78099d58d7ffc9d1b20ca3c4a7e31cbc5cf598afb63a9d11bf48a73ba",
+    "parser_input_snapshot_sha256": "46d8b63046534c904b233f5090d3d4cc0b0d1ddd403d4621858bb453c991ba48",
+    "parser_labels": "[\"O\",\"B-house_number\",\"I-house_number\",\"B-road\",\"I-road\",\"B-unit\",\"I-unit\",\"B-level\",\"I-level\",\"B-suburb\",\"I-suburb\",\"B-city\",\"I-city\",\"B-district\",\"I-district\",\"B-region\",\"I-region\",\"B-postcode\",\"I-postcode\",\"B-country\",\"I-country\",\"B-po_box\",\"I-po_box\"]",
+    "parser_network": "{\"hidden\":96,\"kernel\":3,\"dilations\":[1,2,4,8]}",
+    "parser_quantized_sha256": "ffb631258693b17cfb12a23b8bb0372512dbdaa04b1bdfbde1703e0e6da30576",
+    "phone_metadata_version": "libphonenumber v9.0.33 generated tables",
+    "quantization": "per-channel symmetric int8",
+    "release_approval_sha256": "a1fe01d61bf3be31ec20d5aef05af01c9d0b9be7d0f7002adcb6cd2fbcf13bf0",
+    "report_url": "",
+    "repository": "https://github.com/theiskaa/tessera",
+    "runtime_version": "0.1.0",
+    "status": "experimental",
+    "supported_regions": "[]",
+    "tokenizer_contract": "tessera-tokenize-legacy-v1",
+    "training_seen_95_percent_gate_passed": "false",
+    "training_snapshot": "parser-inputs:46d8b63046534c904b233f5090d3d4cc0b0d1ddd403d4621858bb453c991ba48,detector-inputs:ece44fc87959a391b3f99f3c113655f26cf8e45d2c7bc44f474b10bfc1b6517c"
+  }
+}

tessera-v1.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abfa972301f82d23240cc15bc9f70c7c574bb047e33473254a737abacfe995ff
+size 3489616

tessera-v1.sha256

@@ -0,0 +1 @@
+sha256-abfa972301f82d23240cc15bc9f70c7c574bb047e33473254a737abacfe995ff