evoc-ts

evoc-ts is a TypeScript reimplementation of the original Python EVōC project from Tutte Institute, adapted for JavaScript applications that need hierarchical embedding exploration and reusable filtering primitives.

This package exposes:

• a headless explorer core for clustering generic records with embeddings
• React UI components for treemap and layer-band navigation
• helpers that turn hierarchy selections into filtered record ids and records

Credits

• Original Python repo: TutteInstitute/evoc
• EVōC docs: evoc.readthedocs.io
• Inspiration video: Embedding explorer video

Install

pnpm add evoc-ts

Headless usage

import { applySelection, buildExplorer } from "evoc-ts/core";

const model = buildExplorer([
  {
    id: "r1",
    label: "Slow response",
    embedding: [0.12, 0.5, 0.1],
    payload: { type: "slow_response" },
  },
]);

const result = applySelection(model, [{ layerIndex: 0, clusterId: 0 }]);

React usage

import "evoc-ts/styles.css";
import { EmbeddingExplorer } from "evoc-ts/react";

<EmbeddingExplorer
  model={model}
  selection={selection}
  onSelectionChange={setSelection}
/>;

Publishing

pnpm install
pnpm build
pnpm typecheck
pnpm lint
pnpm test
npm publish --access public

Performance

Run the TypeScript benchmark runner with:

pnpm performance

Useful flags:

pnpm performance -- --output performance-results.json
pnpm performance -- --report performance-report.md
pnpm performance -- --baseline previous-results.json
pnpm performance -- --threshold 1.5

The output JSON is designed to be easy to diff against later TypeScript runs or the Python benchmark outputs from the original EVōC project.