Add HF metadata, usage, and scope

README.md

@@ -1,13 +1,83 @@
-# CODEBERT_EMBED_V2-8f13d02d
+---
+license: apache-2.0
+library_name: sentence-transformers
+pipeline_tag: feature-extraction
+tags:
+  - code
+  - code-search
+  - code-retrieval
+  - sentence-transformers
+  - feature-extraction
+language:
+  - code
+---
+
+# codebert-permissive-embed
 
 Produced by Bonacci Foundry. Run `CODEBERT_EMBED_V2-8f13d02d`, spec digest `sha256:8f13d02db956b9db40326791fef0b1269417403422b298df43a80bb7ac072be6`.
 
 Every number in this card is read from the run's own artifacts. Nothing here was typed by hand.
 
+## Usage
+
+Mean pooling over non-padding tokens, then L2 normalise. `sentence-transformers`
+does this for you because the pooling config ships with the model; with plain
+`transformers` you must do it yourself, or you will get a different vector than
+the one the model was trained to produce.
+
+```python
+from sentence_transformers import SentenceTransformer
+
+m = SentenceTransformer("thinkingdbx/codebert-permissive-embed")
+q = m.encode("find the function that parses a configuration file")
+d = m.encode(["def load_settings(path):\n    return yaml.safe_load(open(path))",
+              "def send_email(to, subject, body): ..."])
+print((q @ d.T))
+```
+
+```python
+import torch
+from transformers import AutoModel, AutoTokenizer
+
+tok = AutoTokenizer.from_pretrained("thinkingdbx/codebert-permissive-embed")
+model = AutoModel.from_pretrained("thinkingdbx/codebert-permissive-embed").eval()
+
+def embed(texts, max_length=256):
+    b = tok(texts, padding=True, truncation=True, max_length=max_length,
+            return_tensors="pt")
+    with torch.no_grad():
+        h = model(**b).last_hidden_state
+    mask = b["attention_mask"].unsqueeze(-1).float()
+    v = (h * mask).sum(1) / mask.sum(1).clamp(min=1e-9)
+    return torch.nn.functional.normalize(v, dim=-1)
+```
+
+## What it is for
+
+Semantic code search — retrieving the function that does what a query describes,
+including when the wording and the identifiers do not match. Also usable for
+near-duplicate detection, clustering an unfamiliar codebase, and as the retrieval
+half of a code RAG system.
+
+It produces vectors. It does not generate text.
+
+## What it is not
+
+It is a 110M-parameter model trained on 857k pairs. General-purpose embedding
+models of the same size — E5-Base, BGE-Base, GTE-Base — are trained on hundreds
+of millions of pairs across text and code, and they score higher on most of the
+benchmark below. This model is competitive on natural-language code search and
+weak on code-to-code retrieval, which it was never trained for.
+
+What it offers instead is provenance: every file it learned from carried a
+permissive licence, the ledger of what was excluded is published with it, and
+the personal data removed before training was counted.
+
+
 ## What this is
 
 - **Objective**: embedding
-- **Base model**: `/home/ubuntu/base_encoder` (apache-2.0)
+- **Base model**: the stage-1 encoder below, trained from scratch (apache-2.0)
 - **Method**: full
 - **Delivery terms**: owned_outright
 - **Training**: 1,673 steps, final loss 0.5576