@inerate/acri-core 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @inerate/acri-core (TypeScript)
+
+A minimal TypeScript port of acri's core resolver: `Tool`/`Corpus`/`index()` and
+BM25 `resolve()` — the v0.1 scope `docs/decisions.md` (the Python repo's own
+design doc) calls "a complete product on its own." Nothing else is ported: no
+port/daemon/server/cli/config/gate/press/sandbox/ledger/router/adapters/
+escape-hatch.
+
+Install: `npm install @inerate/acri-core` —
+[npmjs.com/package/@inerate/acri-core](https://www.npmjs.com/package/@inerate/acri-core).
+Versions independently at `0.1.x`, not tracking the Python package.
+
+Mirrors the Python implementation's behavior directly, not just its shape:
+same BM25 constants (`K1=1.5`, `B=0.75`), same tokenizer (lowercase, strip
+`'`/`'`, `[a-z0-9]+`, the same stopword list), same query-only synonym
+expansion (never applied to indexed tool text — see `src/synonyms.ts`'s
+comment for why that matters), same `resolve()` semantics: zero-score tools
+are dropped rather than padded in, the top score normalizes to 1.0, `k` is
+respected. `test/compass.test.ts` mirrors `tests/test_compass.py`'s five
+cases exactly, same fixture and queries, and passes.
+
+## Shipped ahead of its own gate
+
+`docs/decisions.md`:
+
+> **TypeScript** | A real gap, and the JavaScript agent ecosystem is large.
+> Port after the Python package has users, never in parallel with it.
+
+`pyacri` is live on PyPI (has been since v0.4.0) with real download activity
+(547 in the last 30 days — [pypistats.org/packages/pyacri](https://pypistats.org/packages/pyacri),
+checked live, not download count alone confused for "real users"). Shipping
+this in parallel with it, rather than after evidence someone specifically
+wants the TypeScript side, is exactly the scenario that line warns against:
+it doubles the maintenance surface for every future acri feature on a guess,
+not a measured need.
+Built anyway at the maintainer's explicit request — the same override pattern
+used elsewhere in this project (`gate`, `press`, `sandbox`, and the `daemon`
+all shipped ahead of their own gates too; see the root
+[`README.md`](../README.md)'s Roadmap table). Stated here plainly, not
+softened, so this isn't mistaken for a maintained, gate-cleared parallel
+implementation — it's a v0.1-equivalent skeleton, nothing more.
+
+## Run
+
+```
+npm install
+npm test
+```

package/dist/src/compass.d.ts

@@ -0,0 +1,7 @@
+import type { Corpus, Tool } from "./corpus.js";
+export interface Resolved {
+    tool: Tool;
+    score: number;
+}
+export declare function bm25(queryTokens: string[], corpus: Corpus, docIdx: number): number;
+export declare function resolve(query: string, corpus: Corpus, k?: number): Resolved[];

package/dist/src/compass.js

@@ -0,0 +1,43 @@
+// compass — the resolver. Given a query, returns the k tools that matter.
+// Ported from acri/compass.py. No language understanding: BM25 scores query
+// terms against tool text, weighting terms that are rare in the corpus.
+import { tokenize } from "./text.js";
+import { expand } from "./synonyms.js";
+const K1 = 1.5;
+const B = 0.75;
+function idf(df, nDocs) {
+    return Math.log(1 + (nDocs - df + 0.5) / (df + 0.5));
+}
+export function bm25(queryTokens, corpus, docIdx) {
+    const docLen = corpus.docTokens[docIdx].length;
+    const freqs = corpus.docFreqs[docIdx];
+    const nDocs = corpus.tools.length;
+    let score = 0;
+    for (const tok of queryTokens) {
+        const f = freqs.get(tok);
+        if (!f)
+            continue;
+        const termIdf = idf(corpus.df.get(tok) ?? 0, nDocs);
+        const denom = f + K1 * (1 - B + (B * docLen) / corpus.avgdl);
+        score += (termIdf * (f * (K1 + 1))) / denom;
+    }
+    return score;
+}
+// Tools that score zero (no shared term with the query) are dropped rather
+// than padded in -- an empty result means "nothing in this corpus matches".
+export function resolve(query, corpus, k = 5) {
+    if (corpus.tools.length === 0)
+        return [];
+    const queryTokens = expand(tokenize(query));
+    const raw = corpus.tools.map((_, i) => bm25(queryTokens, corpus, i));
+    const top = Math.max(...raw);
+    if (top <= 0)
+        return [];
+    const scored = [];
+    for (let i = 0; i < corpus.tools.length; i++) {
+        if (raw[i] > 0)
+            scored.push({ tool: corpus.tools[i], score: raw[i] / top });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, k);
+}

package/dist/src/corpus.d.ts

@@ -0,0 +1,13 @@
+export interface Tool {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+export interface Corpus {
+    tools: Tool[];
+    docTokens: string[][];
+    docFreqs: Map<string, number>[];
+    df: Map<string, number>;
+    avgdl: number;
+}
+export declare function index(tools: Tool[]): Corpus;

package/dist/src/corpus.js

@@ -0,0 +1,23 @@
+// corpus — the capability index. Ingests tools into one searchable body, once.
+// Ported from acri/corpus.py. `handler` (Python's optional dispatcher field)
+// is not ported -- nothing in this resolver-only port calls it, same as the
+// Python side ("resolution never calls it").
+import { tokenize } from "./text.js";
+export function index(tools) {
+    if (tools.length === 0) {
+        throw new Error("index() needs at least one tool");
+    }
+    const docTokens = tools.map((t) => tokenize(`${t.name} ${t.description}`));
+    const docFreqs = [];
+    const df = new Map();
+    for (const tokens of docTokens) {
+        const freqs = new Map();
+        for (const tok of tokens)
+            freqs.set(tok, (freqs.get(tok) ?? 0) + 1);
+        docFreqs.push(freqs);
+        for (const tok of freqs.keys())
+            df.set(tok, (df.get(tok) ?? 0) + 1);
+    }
+    const avgdl = docTokens.reduce((sum, t) => sum + t.length, 0) / docTokens.length;
+    return { tools: [...tools], docTokens, docFreqs, df, avgdl };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./corpus.js";
+export * from "./compass.js";
+export * from "./text.js";
+export * from "./synonyms.js";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from "./corpus.js";
+export * from "./compass.js";
+export * from "./text.js";
+export * from "./synonyms.js";

package/dist/src/synonyms.d.ts

@@ -0,0 +1,2 @@
+export declare const ALIASES: Readonly<Record<string, readonly string[]>>;
+export declare function expand(tokens: string[]): string[];

package/dist/src/synonyms.js

@@ -0,0 +1,25 @@
+// synonyms — query-side alias expansion for compass. Not corpus-facing.
+// Ported from acri/_synonyms.py. Applied to the query only, never the corpus:
+// expanding doc text here would let a tool's description quietly start
+// matching queries for a synonym it never claimed, and would shift df/idf
+// for every other tool too. Every entry traces to a real recall@5 miss in
+// the Python repo's assay/diagnose.py, not a guess.
+export const ALIASES = {
+    pr: ["pull", "request"],
+    meeting: ["event"],
+    rain: ["weather"],
+    raining: ["weather"],
+    storm: ["weather"],
+    warning: ["alerts"],
+    warnings: ["alerts"],
+    text: ["sms", "message"],
+    sharpen: ["upscale", "resolution"],
+    money: ["refund", "charge"],
+};
+export function expand(tokens) {
+    const expanded = [...tokens];
+    for (const tok of tokens) {
+        expanded.push(...(ALIASES[tok] ?? []));
+    }
+    return expanded;
+}

package/dist/src/text.d.ts

@@ -0,0 +1 @@
+export declare function tokenize(text: string): string[];

package/dist/src/text.js

@@ -0,0 +1,25 @@
+// text — tokenization shared by corpus (indexing) and compass (scoring).
+// Ported from acri/_text.py -- both sides must tokenize identically or BM25
+// scores a query against tokens the corpus was never split the same way.
+const TOKEN_RE = /[a-z0-9]+/g;
+// Same list as acri/_text.py's _STOPWORDS (the NLTK stoplist's
+// non-contraction core) -- ported verbatim, not re-derived.
+const STOPWORDS = new Set([
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "am", "of", "in", "on", "at", "to", "for", "with", "and", "or",
+    "but", "this", "that", "these", "those", "what", "which", "who", "whom", "me",
+    "my", "you", "your", "it", "its", "we", "they", "do", "does", "did",
+    "into", "from", "by", "about", "up", "down", "out", "off", "over", "under",
+    "again", "further", "then", "once", "here", "there", "when", "where", "why", "how",
+    "all", "any", "both", "each", "few", "more", "most", "other", "some", "such",
+    "no", "nor", "not", "only", "own", "same", "so", "than", "too", "very",
+    "s", "t", "can", "will", "just", "now", "if", "because", "as", "until",
+    "while", "against", "between", "during", "before", "after", "above", "below",
+]);
+export function tokenize(text) {
+    // Strip apostrophes before splitting: "user's" -> "users" as one token,
+    // not "user" + a stray "s" that then matches every other possessive.
+    const normalized = text.toLowerCase().replace(/'/g, "").replace(/’/g, "");
+    const matches = normalized.match(TOKEN_RE) ?? [];
+    return matches.filter((t) => !STOPWORDS.has(t));
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@inerate/acri-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Minimal TypeScript port of acri capability resolver (corpus + compass)",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/test/compass.test.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://forge.inerate.com/acri",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/INERATE/acri.git"
+  },
+  "bugs": {
+    "url": "https://github.com/INERATE/acri/issues"
+  }
+}