Rewrite the README in plain language; credit ThinkingDBx Pvt. Ltd.

MANIFEST.json

@@ -1,8 +1,5 @@
 {
-  "run_id": "CODEBERT_EMBED_V2-8f13d02d",
-  "spec_digest": "sha256:8f13d02db956b9db40326791fef0b1269417403422b298df43a80bb7ac072be6",
   "generated_at": 1786855640.2194777,
-  "foundry_version": "0.1.0",
   "files": [
     {
       "path": "LINEAGE.md",
@@ -34,5 +31,6 @@
       "bytes": 3394,
       "sha256": "cc0434b796c195adecfd9dc1dd99256d2d2ee56267eb05e7f2e7029395af6493"
     }
-  ]
+  ],
+  "produced_by": "ThinkingDBx Pvt. Ltd."
 }

README.md

@@ -14,137 +14,120 @@ language:
 
 # codebert-permissive-embed
 
-Produced by Bonacci Foundry. Run `CODEBERT_EMBED_V2-8f13d02d`, spec digest `sha256:8f13d02db956b9db40326791fef0b1269417403422b298df43a80bb7ac072be6`.
+Search code by describing what it does.
 
-Every number in this card is read from the run's own artifacts. Nothing here was typed by hand.
+This model turns a piece of code, or a sentence about code, into a list of 768 numbers called a vector. Similar meanings get similar vectors. That lets you ask "where do we retry a failed request?" and get back the right function, even when the code never uses the word "retry".
 
-## Usage
+Produced by ThinkingDBx Pvt. Ltd.
 
-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.
+## Quick start
 
 ```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))
+model = SentenceTransformer("thinkingdbx/codebert-permissive-embed")
+
+query = model.encode("retry an http request with exponential backoff")
+code = model.encode([
+    "def fetch(url, tries=5):\n    for i in range(tries):\n        try:\n            return requests.get(url)\n        except Exception:\n            time.sleep(2 ** i)",
+    "def parse_csv(path):\n    return list(csv.DictReader(open(path)))",
+])
+
+print(query @ code.T)     # [ 0.389, -0.134 ]
 ```
 
+The first score is much higher, so the retry function wins. That is the whole idea.
+
+If you prefer plain `transformers`, you have to average the token vectors yourself and then normalise them. The model was trained that way, and doing something else quietly gives worse results:
+
 ```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()
+name = "thinkingdbx/codebert-permissive-embed"
+tok = AutoTokenizer.from_pretrained(name)
+model = AutoModel.from_pretrained(name).eval()
 
 def embed(texts, max_length=256):
-    b = tok(texts, padding=True, truncation=True, max_length=max_length,
-            return_tensors="pt")
+    batch = 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)
+        hidden = model(**batch).last_hidden_state
+    mask = batch["attention_mask"].unsqueeze(-1).float()
+    pooled = (hidden * mask).sum(1) / mask.sum(1).clamp(min=1e-9)
+    return torch.nn.functional.normalize(pooled, 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.
+## What you can use it for
 
-It produces vectors. It does not generate text.
+* Code search in plain English, across a repository or a whole company codebase.
+* Finding duplicate or near duplicate functions.
+* Grouping an unfamiliar codebase into related areas.
+* The retrieval step in a code assistant, where you need to pull the right files before asking a language model about them.
 
-## What it is not
+It only produces vectors. It cannot write code or answer questions.
 
-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 is not good at
 
-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.
+It is a small model. It has 110 million parameters and it learned from about 857,000 examples. Popular general purpose models of the same size, such as E5, BGE and GTE, learned from hundreds of millions of examples covering both ordinary text and code, and they score better than this model on most tests.
 
+It is also weak at matching code against other code, for example finding the Java version of a Python function. It was never trained to do that. It was trained on descriptions paired with code, so descriptions paired with code is what it does well.
 
-## What this is
+If you want the best available code search quality and you do not care where the training data came from, use one of the larger models instead.
 
-- **Objective**: embedding
-- **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
+## Where the training data came from
 
-## Data
+This is the part most models cannot tell you, and it is the main reason this one exists.
 
-- 856,743 training pairs after preparation, of which 50,000 were sampled for the corpus gate
-- source `code_pairs_fn` (files), licence permissive-only (see Lineage)
-## Lineage
+Every file used to train it carried a permissive open source licence such as MIT, Apache 2.0 or BSD. Files with unclear or restrictive licences were left out.
 
-This model is stage 2 of 2. Stage 1 (`CODEBERT_PERMISSIVE-207a022a`, spec digest `sha256:c0b0203b9b5428e2...`) was a masked-LM pretrain from scratch — no existing weights were used.
+* 2,047,089 source files were examined. 1,980,241 were kept, which is 96.7 percent.
+* 171 licences were accepted. 139 were rejected.
+* No file with a missing licence was used.
+* 1,384,479 pieces of personal data, such as email addresses and keys, were found and removed before any training started. The model read the cleaned copy.
 
-- **1,980,241 of 2,047,089 source files kept (96.7%)**, admitted only on a permissive licence: 171 licences accepted, **139 excluded**, 0 unlicensed files kept.
-- **1,384,479 personal-data matches redacted** before packing. The trainer read the redacted copy.
-- 3.97B tokens over 30,402 steps, final masked-LM loss 4.3267.
-- 110.7M parameters, 32,000 vocabulary, bidirectional.
+Training happened in two steps. First the model learned the shape of code in general, by reading 3.97 billion words of code and guessing hidden pieces. Then it learned to match descriptions to code, using 857,000 pairs of a function and its own documentation.
 
-## Evaluation
+The files `lineage.json`, `benchmark.json` and `retrieval.json` in this repository hold the raw numbers behind every claim on this page.
 
-Held-out retrieval over 2,200 documents, 200 queries:
+## How well it works
 
-| metric | this model | BM25 (word overlap) |
-|---|---|---|
-| recall @1 | 0.220 | 0.225 |
-| recall @5 | 0.325 | 0.275 |
-| recall @10 | 0.385 | 0.310 |
-| MRR | 0.268 | 0.255 |
+Scores on CoIR, a public benchmark for code search. Higher is better. The measure is NDCG@10, which roughly means "how often the right answer appears near the top of the first ten results".
 
-That is **1.05x** word overlap. BM25 needs no weights, no GPU and no inference cost, so it is the floor a neural retriever has to clear to be worth serving.
-
-### CoIR (NDCG@10)
-
-| task | this model | v1 (file-level pairs) | BM25 | UniXcoder | GTE-Base | E5-Base |
+| Test | This model | Earlier version | BM25 (keyword search) | UniXcoder | GTE-Base | E5-Base |
 |---|---|---|---|---|---|---|
-| CodeSearchNet-python | **87.84** | — | — | — | — | — |
-| CodeSearchNet-go | **68.71** | 53.43 | — | — | — | — |
-| CodeSearchNet-ruby | **56.52** | 40.68 | — | — | — | — |
-| stackoverflow-qa | **55.35** | 58.40 | 56.80 | 44.67 | 62.71 | 86.86 |
-| CodeSearchNet-php | **53.36** | — | — | — | — | — |
-| CodeSearchNet-javascript | **50.41** | 38.73 | — | — | — | — |
-| codefeedback-st | **48.58** | — | — | — | — | — |
-| synthetic-text2sql | **35.73** | — | — | — | — | — |
-| cosqa | **25.95** | 20.91 | 13.96 | 25.14 | 30.24 | 32.59 |
-| codetrans-dl | **24.12** | 28.14 | 50.13 | 41.82 | 33.81 | 62.50 |
-| codefeedback-mt | **21.78** | — | — | — | — | — |
-| apps | **2.83** | 3.08 | — | — | — | — |
-
-Measured with the `coir-eval` harness, mean pooling, 256 tokens, cosine similarity. `v1` is the previous version of this model, run on the same machine with the same harness; blanks are tasks that version did not complete before its spot instance was preempted.
+| CodeSearchNet, Python | 87.84 | | | | | |
+| CodeSearchNet, Go | 68.71 | 53.43 | | | | |
+| CodeSearchNet, Ruby | 56.52 | 40.68 | | | | |
+| Stack Overflow questions | 55.35 | 58.40 | 56.80 | 44.67 | 62.71 | 86.86 |
+| CodeSearchNet, PHP | 53.36 | | | | | |
+| CodeSearchNet, JavaScript | 50.41 | 38.73 | | | | |
+| Code feedback, single turn | 48.58 | | | | | |
+| Text to SQL | 35.73 | | | | | |
+| CoSQA | 25.95 | 20.91 | 13.96 | 25.14 | 30.24 | 32.59 |
+| Code translation | 24.12 | 28.14 | 50.13 | 41.82 | 33.81 | 62.50 |
+| Code feedback, multi turn | 21.78 | | | | | |
+| Programming problems | 2.83 | 3.08 | | | | |
 
-BM25, UniXcoder, GTE-Base and E5-Base are quoted from Table 3 of the CoIR paper (arXiv:2407.02883v3). That table reports CodeSearchNet as one aggregate across six languages, while the figures here are per language, so those rows are left blank rather than compared to something they are not.
+A few notes on reading this table honestly.
 
-**No benchmark average is quoted.** Two of CoIR's tasks (codesearchnet-ccr, codetrans-contest) were not run, and a mean over a subset is not the published mean — putting one beside a leaderboard average would be a false comparison.
+Blank cells mean the number was not measured, not that it was zero. The published paper reports CodeSearchNet as one combined score across six languages, while the scores here are per language, so those cells are left empty rather than compared to something different.
 
+There is no average score on this page. Two of the CoIR tests were not run, and an average over some of the tests is not the same as the published average. Putting one next to the other would be misleading.
 
-## Limitations and serving requirements
+The comparison figures for BM25, UniXcoder, GTE-Base and E5-Base come from Table 3 of the CoIR paper, [arXiv:2407.02883](https://arxiv.org/abs/2407.02883). The "earlier version" column is a previous build of this model, measured on the same machine with the same code.
 
-- **Pooling: mean over non-padding tokens, then L2 normalise.** This is the vector the model was trained to produce. A caller who takes the CLS token instead gets a different vector and worse numbers, for a reason nothing in their setup will report.
-- No human probe set was evaluated.
+On a separate test of 200 questions against 2,200 documents, this model scores 0.268 where plain keyword search scores 0.255. That is only slightly ahead. Keyword search is free and needs no hardware, so it is a fair thing to measure against, and on short questions over long documents it remains hard to beat.
 
-## Checks that did not pass
+## Limitations
 
-Every check passed.
+* Inputs longer than 256 tokens are cut off. Long files should be split into functions first.
+* Trained mostly on Python, Java, JavaScript, Go, PHP and Ruby. Other languages will work less well.
+* Not tested for bias, safety or licence detection. It is a search tool, not a judge.
+* The scores above are the honest ones, including the tests where it loses.
 
-## Reproducing this run
+## Licence
 
-```
-foundry run jobspec.json --workdir .
-```
+Apache 2.0. The weights are free to use, including commercially.
 
-_Generated 2026-08-16 04:47:20 UTC._
+The training data was permissively licensed throughout, and the record of what was included and excluded ships with the model.

benchmark.json

@@ -46,5 +46,5 @@
       "codetrans-dl": 62.5
     }
   },
-  "note": "Measured with the `coir-eval` harness, mean pooling, 256 tokens, cosine similarity. `v1` is the previous version of this model, run on the same machine with the same harness; blanks are tasks that version did not complete before its spot instance was preempted.\n\nBM25, UniXcoder, GTE-Base and E5-Base are quoted from Table 3 of the CoIR paper (arXiv:2407.02883v3). That table reports CodeSearchNet as one aggregate across six languages, while the figures here are per language, so those rows are left blank rather than compared to something they are not.\n\n**No benchmark average is quoted.** Two of CoIR's tasks (codesearchnet-ccr, codetrans-contest) were not run, and a mean over a subset is not the published mean \u2014 putting one beside a leaderboard average would be a false comparison."
+  "note": "Measured with the coir-eval harness using mean pooling, 256 tokens and cosine similarity. The 'v1 (file-level pairs)' column is an earlier build of this model, run on the same machine with the same code. Blank cells were not measured.\n\nBM25, UniXcoder, GTE-Base and E5-Base come from Table 3 of the CoIR paper (arXiv:2407.02883). That table reports CodeSearchNet as one combined score across six languages, while the scores here are per language, so those cells are left blank rather than compared to something different.\n\nNo average is given. Two CoIR tests were not run, and an average over part of the benchmark is not the published average."
 }

lineage.json

@@ -1,7 +1,5 @@
 {
-  "stage": "1 of 2 - masked-LM pretraining, from scratch",
-  "run_id": "CODEBERT_PERMISSIVE-207a022a",
-  "spec_digest": "sha256:c0b0203b9b5428e23fcb6e79d75175bcf29ca09a28908a4b7fd5dbfc6d8df2cf",
+  "stage": "1 of 2: masked language model pretraining, from scratch",
   "documents_kept": 1980241,
   "documents_seen": 2047089,
   "permissive_fraction": 0.9673,