@putervision/grokjs
Advanced tools
A JavaScript implementation of a basic Language Model (LM) and utilities designed to facilitate natural language processing tasks, inspired by advanced models like xAI's Grok. (not affiliated with xAI)
A high-performance, modular JavaScript & TypeScript implementation of Language Models (LMs), N-gram text generators, and Natural Language Processing (NLP) tools — inspired by state-of-the-art language architectures like xAI's Grok. (Not affiliated with xAI).
@putervision/grokjs is designed to provide developers with zero-dependency (or minimal dependency) client-side and server-side NLP capabilities in pure JavaScript. It equips Node.js and browser applications with fast text generation, tokenization, n-gram probability distributions, semantic word embeddings, attention visualization, and RAG fact injection.
┌──────────────────────────────────────────────┐
│ LanguageModel │
└──────┬────────────────────┬──────────────────┘
│ │
┌──────────────┴───────┐ ┌────────┴──────────────┐
│ InferenceEngine │ │ AttentionMechanism │
└──────────────┬───────┘ └────────┬──────────────┘
│ │
┌─────────────────────┼────────────────────┼─────────────────────┐
│ │ │ │
┌──┴───────┐ ┌─────────┴──────────┐ ┌─────┴──────┐ ┌─────────┴─────────┐
│Tokenizer │ │ProbabilityDistro │ │ Embedding │ │EvaluationMetrics │
└──┬───────┘ └─────────┬──────────┘ └────────────┘ └───────────────────┘
│ │
┌──┴────────┐ ┌─────────┴──────────┐
│Normalizer │ │FrequencyDistro │
└───────────┘ └─────────┬──────────┘
│
┌─────┴──────┐
│ Counter │
└────────────┘
npm install @putervision/grokjs
Or run browser bundle directly:
<script src="node_modules/@putervision/grokjs/dist/grokjs.bundle.js"></script>
<script>
const { LanguageModel, InferenceEngine } = GrokJS;
const lm = new LanguageModel();
lm.train("Hello world! GrokJS enables fast browser language modeling.");
console.log(lm.generateText("Hello", 5));
</script>
| Class | Category | Description |
|---|---|---|
LanguageModel | Core Engine | Primary facade for training, text generation, serialization, and context management. |
Tokenizer | Processing | Multilingual regex tokenization with date, timestamp, and contraction handling. |
Ngram | Core Engine | Efficient N-gram model up to 5-grams using hash maps and counters. |
Counter | Math / Data | High-performance item frequency counter (Python collections.Counter port). |
Normalizer | Preprocessing | Accent stripping, NFKC unicode cleaning, lowercasing, and whitespace collapse. |
Vocabulary | Data Struct | Token-to-ID bidirectional dictionary with <unk>, <s>, </s>, <pad> handling. |
FrequencyDistribution | Distributions | Conditional and joint N-gram frequency counting per context. |
ProbabilityDistribution | Distributions | MLE, Laplace (Add-k) smoothing, Stupid Backoff, and softmax temperature sampling. |
MarkovChain | Sequence Gen | N-th order Markov chain sequence generator and state transition matrix. |
Corpus | Processing | Multi-document dataset loader, sentence extractor, TTR stats, and train/test splits. |
Embedding | Vector Space | Co-occurrence word vector space representations, cosine similarity, and vector math. |
AttentionMechanism | Visualization | Self-attention weights, sequence focus scoring, and 2D N x N heatmap matrix. |
EvaluationMetrics | Benchmark | Perplexity, BLEU (with brevity penalty), ROUGE-L, F1 Score, and Accuracy. |
InferenceEngine | Generation | Greedy, Temperature, Top-K, Top-P (nucleus), Repetition Penalty, and Beam Search. |
FactServer | RAG / Knowledge | Key-value fact store and Retrieval-Augmented Generation (RAG) prompt injection. |
FormAutocompleteEngine | Autocomplete | Self-learning DOM form autocomplete engine with continuous localStorage persistence. |
const { LanguageModel, InferenceEngine, FactServer } = require("@putervision/grokjs");
// 1. Initialize Language Model
const lm = new LanguageModel();
// 2. Train on sample corpus
lm.train(
"GrokJS is an open source JavaScript library for natural language processing. " +
"It supports n-gram language modeling, text generation, and retrieval augmented generation."
);
// 3. Predict next word
console.log("Prediction for 'grokjs is':", lm.predict("grokjs is", 3));
// 4. Generate text with nucleus (top-p) sampling and temperature
const generated = lm.generateText("grokjs is", 10, {
temperature: 0.8,
topP: 0.9,
repetitionPenalty: 1.2,
});
console.log("Generated:", generated);
// 5. Use Fact Server for RAG Prompt Injection
const factServer = new FactServer();
factServer.addFact("library", "GrokJS Version", "1.2.4");
factServer.addFact("author", "Created By", "PuterVision");
const prompt = "Tell me about GrokJS Version and author.";
const augmentedPrompt = factServer.augmentPrompt(prompt);
console.log("Augmented RAG Prompt:", augmentedPrompt);
The primary facade class wrapping Ngram, InferenceEngine, and EvaluationMetrics.
train(text: string): void: Trains model on input text.predict(prefix: string, numPredictions?: number): string[]: Returns top predicted next words.generateText(start: string, length?: number, options?: GenerationOptions): string: Generates text continuations.saveModel(path: string): void: Serializes model state (including JavaScript Maps) to JSON.loadModel(path: string): void: Restores model state from JSON.perplexity(text: string): number: Computes model perplexity.getEmbeddings(word: string, dimensions?: number): number[]: Returns normalized embedding vector.attentionWeights(input: string): { input: string, weights: number[] }: Returns attention focus scores.healthCheck(): Object: Returns model readiness status with vocabulary size and ngram level info.predictWithConfidence(prefix: string, numPredictions?: number): Array<{word, probability, ngramLevel}>: Returns predictions with probability scores.Note:
saveModel()andloadModel()use Node.jsfsmodule and are only available in Node.js environments. For browser usage, serialize manually usingJSON.stringify()andlocalStorage.
Handles multi-lingual regex tokenization, date/timestamp preservation, contractions, and special tokens.
const { Tokenizer } = require("@putervision/grokjs");
const tokenizer = new Tokenizer({
handleContractions: true,
removePunctuation: true,
});
const tokens = tokenizer.tokenize("It's 2026-07-29. The price is $10.99!");
// ['it', 'is', '2026-07-29', 'the', 'price', 'is', '10.99']
Maintains n-gram frequency trees up to maxN = 5.
const { Ngram } = require("@putervision/grokjs");
const ngram = new Ngram(3);
ngram.learn("hello world how are you");
console.log(ngram.predictNextWord("hello world"));
High-performance item counting dictionary.
const { Counter } = require("@putervision/grokjs");
const counter = new Counter(["a", "b", "a", "c", "b", "b"]);
console.log(counter.get("b")); // 3
console.log(counter.mostCommon(2)); // [['b', 3], ['a', 2]]
Clean and standardize raw text strings.
const { Normalizer } = require("@putervision/grokjs");
const norm = new Normalizer({ stripAccents: true, lowerCase: true });
console.log(norm.normalize(" Café CON Leche! ")); // 'cafe con leche!'
Build integer ID dictionaries and handle special tokens.
const { Vocabulary } = require("@putervision/grokjs");
const vocab = new Vocabulary();
vocab.buildFromTokens(["apple", "banana", "apple"], 1);
const ids = vocab.encode(["apple", "unknown_word"]); // [4, 1] (1 is <unk>)
console.log(vocab.decode(ids)); // ['apple', '<unk>']
Tracks N-gram joint and conditional token frequencies.
const { FrequencyDistribution } = require("@putervision/grokjs");
const fd = new FrequencyDistribution();
fd.record("hello", "world", 5);
console.log(fd.count("hello", "world")); // 5
Computes MLE, Laplace (Add-k) smoothing, Stupid Backoff, and softmax temperature sampling.
const { ProbabilityDistribution, FrequencyDistribution } = require("@putervision/grokjs");
const pd = new ProbabilityDistribution(fd);
console.log(pd.laplace("hello", "world", 1, 1000));
console.log(pd.sample("hello", 0.7));
N-th order Markov chain sequence generator and state transition matrix calculator.
const { MarkovChain } = require("@putervision/grokjs");
const mc = new MarkovChain(1);
mc.train([["the", "cat", "sat", "on", "mat"]]);
console.log(mc.getTransitionMatrix());
console.log(mc.generatePath("the", 4));
Text dataset loader, sentence extractor, type-token ratio (TTR) stats, and train/val/test splits.
const { Corpus } = require("@putervision/grokjs");
const corpus = new Corpus();
corpus.addDocument("Doc 1 content...");
corpus.addDocument("Doc 2 content...");
console.log(corpus.getStats()); // { documentCount, sentenceCount, tokenCount, typeTokenRatio }
const splits = corpus.split(0.8, 0.1, 0.1);
Co-occurrence based vector space representation and similarity math.
Note: Embeddings use co-occurrence with hash projection. For production-quality word vectors, consider training with larger corpora or using pre-trained embeddings (Word2Vec, GloVe).
const { Embedding } = require("@putervision/grokjs");
const emb = new Embedding(10);
emb.build(["king queen prince princess royal kingdom", "man woman boy girl human"]);
console.log(emb.cosineSimilarity("king", "queen"));
console.log(emb.mostSimilar("king", 3));
Computes self-attention weights and 2D heatmap matrix.
Note: AttentionMechanism provides heuristic-based attention visualization (position × length weighting with distance penalties). For production attention weights, integrate with a trained transformer model.
const { AttentionMechanism } = require("@putervision/grokjs");
const attn = new AttentionMechanism();
console.log(attn.computeWeights(["grok", "language", "model"]));
console.log(attn.getHeatmap(["grok", "language", "model"]));
Standardized NLP benchmark metrics: Perplexity, BLEU, ROUGE-L, F1, Accuracy.
const { EvaluationMetrics } = require("@putervision/grokjs");
console.log(EvaluationMetrics.bleu(["hello", "world"], ["hello", "world"])); // 1.0
console.log(EvaluationMetrics.rougeL(["the", "quick", "fox"], ["the", "fast", "fox"]));
Advanced text generation pipeline with Top-K, Top-P (nucleus), temperature, repetition penalty, and Beam Search.
const { InferenceEngine, LanguageModel } = require("@putervision/grokjs");
const lm = new LanguageModel();
lm.train("grokjs is an open source language model library");
const output = InferenceEngine.generate(lm, "grokjs", 5, {
temperature: 0.7,
topK: 3,
topP: 0.9,
repetitionPenalty: 1.2,
});
const beamOutput = InferenceEngine.beamSearch(lm, "grokjs", 4, 3);
RAG key-value fact store and prompt context injector.
const { FactServer } = require("@putervision/grokjs");
const fs = new FactServer();
fs.addFact("science", "speed of light", "299,792,458 m/s");
console.log(fs.queryFacts("What is the speed of light?"));
console.log(fs.augmentPrompt("What is the speed of light?"));
Attach self-learning AI autocomplete to all HTML form inputs, textareas, and contenteditable fields on any webpage. Automatically trains as users type and persists state to localStorage.
const { FormAutocompleteEngine } = require("@putervision/grokjs");
// Attach self-learning autocomplete to current webpage
FormAutocompleteEngine.inject({ autoSave: true });
Copy-paste this one-liner into your browser Developer Console (F12 -> Console) on ANY webpage (e.g. Gmail, GitHub, Notion, Twitter, Reddit) to instantly equip the page with self-learning AI autocomplete:
(function () {
if (window.__grokjs_autocomplete) return console.log("GrokJS Autocomplete active.");
function init() {
if (window.GrokJS) {
window.__grokjs_autocomplete = window.GrokJS.FormAutocompleteEngine.inject();
console.log(
"%cGrokJS Self-Learning Autocomplete Injected! Press Tab or Right Arrow to accept completions.",
"color:#38bdf8;font-size:14px;font-weight:bold;"
);
} else {
console.error("GrokJS failed to load.");
}
}
if (window.GrokJS) {
init();
} else {
const script = document.createElement("script");
script.src = "https://cdn.jsdelivr.net/npm/@putervision/grokjs@1.2.4/dist/grokjs.bundle.js";
script.onload = init;
document.head.appendChild(script);
}
})();
Full TypeScript definitions are included out of the box (index.d.ts):
import { LanguageModel, GenerationOptions, EvaluationResult } from "@putervision/grokjs";
const lm: LanguageModel = new LanguageModel();
lm.train("TypeScript support is fully integrated.");
const opts: GenerationOptions = { temperature: 0.8, topP: 0.9 };
const text: string = lm.generateText("TypeScript", 5, opts);
Models are serialized to JSON with proper handling of JavaScript Maps and Counter instances:
// Save trained model
lm.saveModel("./model.json");
// Load trained model in another process
const newLm = new LanguageModel();
newLm.loadModel("./model.json");
console.log(newLm.getVocabularySize());
An interactive, single-page web studio and documentation application is available in the docs/index.html directory.
To launch locally:
npx http-server docs -p 8080
Open http://localhost:8080 (or open docs/index.html directly in any browser) to access the interactive web tools:
| Web Tool / Studio Section | Direct Link | Key Features & Capabilities |
|---|---|---|
| Live LM Playground | docs/index.html#playground | Train N-gram models live in the browser, adjust Softmax Temperature (0.1–2.0) & Top-P Nucleus sliders, and test text generation. |
| Document Trainer & Checkpoint Studio | docs/index.html#doc-trainer | Drag & drop .txt, .md, .csv, .json files to train models, export JSON checkpoints, reload saved state, and test predictions with confidence percentages. |
| Console Autocomplete Injector | docs/index.html#autocomplete-snippet | Step-by-step console injection tutorial with a one-click copy button for embedding self-learning form autocomplete into any webpage. |
| Self-Attention Heatmap Visualizer | docs/index.html#attention | Calculate and render color-coded 2D self-attention matrices to visualize query-key token focus weights in real time. |
| FactServer & RAG Prompt Injector | docs/index.html#rag | Query key-value fact stores and observe real-time Retrieval-Augmented Generation (RAG) prompt context augmentation. |
| Architecture Modules Grid | docs/index.html#features | Production-grade class directory highlighting all 16 modular NLP engines and vector tools. |
| Node.js & TypeScript Quickstart | docs/index.html#quickstart | Copy-pasteable code examples for Node.js CommonJS, ES Modules, and TypeScript imports. |
Run all 18 test suites (194 tests):
npm test
Build browser UMD bundle (dist/grokjs.bundle.js):
npm run build
@putervision/grokjs is designed with security in mind:
eval() usagefranc-cjs for language detection (read-only)The FormAutocompleteEngine uses localStorage for persistence. If you're deploying in a shared environment, be aware that stored autocomplete data is accessible to any script running on the same origin.
For vulnerability reports, see SECURITY.md.
See CHANGELOG.md for version history.
We welcome contributions! See CONTRIBUTING.md for setup instructions and code quality guidelines.
See CODE_OF_CONDUCT.md.
MIT © PuterVision
FAQs
A JavaScript implementation of a basic Language Model (LM) and utilities designed to facilitate natural language processing tasks, inspired by advanced models like xAI's Grok. (not affiliated with xAI)
The npm package @putervision/grokjs receives a total of 13 weekly downloads. As such, @putervision/grokjs popularity was classified as not popular.
We found that @putervision/grokjs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Socket CTO Ahmad Nassri joins AppSec leaders at Black Hat to discuss active malware, package manager risks, and software supply chain defense.
Research
/Security News
Thirteen malicious Packagist themes expose visitors on unpatched iPhones to a WebKit-to-kernel exploit chain that steals device data and wallet seeds.
Research
/Security News
Ten malicious OpenAPI React Query Codegen versions were published to npm in the Mini Shai-Hulud attack, all with valid provenance.