@putervision/grokjs

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).

Overview & Architecture

@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  │
                   └────────────┘

Installation

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>

Module Summary (16 Modular Classes)

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.

Quick Start

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);

Class References & Detailed API

1. LanguageModel

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() and loadModel() use Node.js fs module and are only available in Node.js environments. For browser usage, serialize manually using JSON.stringify() and localStorage.

2. Tokenizer

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']

3. Ngram

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"));

4. Counter

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]]

5. Normalizer

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!'

6. Vocabulary

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>']

7. FrequencyDistribution

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

8. ProbabilityDistribution

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));

9. MarkovChain

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));

10. Corpus

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);

11. Embedding

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));

12. AttentionMechanism

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"]));

13. EvaluationMetrics

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"]));

14. InferenceEngine

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);

15. FactServer

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?"));

16. FormAutocompleteEngine & Copy-Paste Webpage Autocomplete

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 });

🚀 Instant Copy-Paste Browser Console Snippet

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);
  }
})();

TypeScript Support

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);

Model Serialization

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());

Interactive Web Tools Studio

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 Tools Directory & Section Links

Web Tool / Studio Section	Direct Link	Key Features & Capabilities
Live LM Playground	`grokjs.com/#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	`grokjs.com/#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	`grokjs.com/#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	`grokjs.com/#attention`	Calculate and render color-coded 2D self-attention matrices to visualize query-key token focus weights in real time.
FactServer & RAG Prompt Injector	`grokjs.com/#rag`	Query key-value fact stores and observe real-time Retrieval-Augmented Generation (RAG) prompt context augmentation.
Architecture Modules Grid	`grokjs.com/#features`	Production-grade class directory highlighting all 16 modular NLP engines and vector tools.
Node.js & TypeScript Quickstart	`grokjs.com/#quickstart`	Copy-pasteable code examples for Node.js CommonJS, ES Modules, and TypeScript imports.

Testing & Building

Run all 18 test suites (194 tests):

npm test

Build browser UMD bundle (dist/grokjs.bundle.js):

npm run build

Requirements

Node.js >= 16.0.0
npm >= 8.0.0
Modern browser (ES6+ support)

Security

@putervision/grokjs is designed with security in mind:

Client-side only: All processing happens locally in your browser or Node.js process
No network calls: The library never makes HTTP requests or sends data externally
No eval(): No dynamic code execution or eval() usage
Minimal dependencies: Only franc-cjs for language detection (read-only)
No data exfiltration: Your text data never leaves your environment

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.

Changelog

See CHANGELOG.md for version history.

Contributing

We welcome contributions! See CONTRIBUTING.md for setup instructions and code quality guidelines.

Code of Conduct

See CODE_OF_CONDUCT.md.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.agents		.agents
.cursor		.cursor
.gemini		.gemini
.github		.github
.vscode		.vscode
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
.windsurfrules		.windsurfrules
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
index.d.ts		index.d.ts
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@putervision/grokjs

Table of Contents

Overview & Architecture

Installation

Module Summary (16 Modular Classes)

Quick Start

Class References & Detailed API

1. LanguageModel

2. Tokenizer

3. Ngram

4. Counter

5. Normalizer

6. Vocabulary

7. FrequencyDistribution

8. ProbabilityDistribution

9. MarkovChain

10. Corpus

11. Embedding

12. AttentionMechanism

13. EvaluationMetrics

14. InferenceEngine

15. FactServer

16. FormAutocompleteEngine & Copy-Paste Webpage Autocomplete

🚀 Instant Copy-Paste Browser Console Snippet

TypeScript Support

Model Serialization

Interactive Web Tools Studio

Web Tools Directory & Section Links

Testing & Building

Requirements

Security

Changelog

Contributing

Code of Conduct

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages