Molecule.dev

← All @molecule/* packages · App templates

@molecule/api-text-provenance-overlap

Provider bond · text-provenance · API (Node) · v1.0.0 · Apache-2.0

Attributes paragraphs to agent turns by overlapping word sequences, tolerant of light human edits and never crediting the user's own words to the AI

npm install @molecule/api-text-provenance-overlap

npm · Source on GitHub · Implements @molecule/api-text-provenance

How it works

@molecule/api-text-provenance-overlap is a provider bond on the API (Node) side: it implements the text-provenance core interface (@molecule/api-text-provenance) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { attributeText, setProvider } from '@molecule/api-text-provenance'
import { provider } from '@molecule/api-text-provenance-overlap'

setProvider(provider)
const { paragraphs, aiShare, prompts } = attributeText({ paragraphs: blocks, sessions })

Works with: @molecule/api-agent-transcript, @molecule/api-text-provenance

Reference

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Text provenance by word overlap, for @molecule/api-text-provenance.

Indexes every three-word sequence the assistant produced in the sessions (its replies and the files it wrote) and every sequence the user typed, then marks a paragraph ai when at least minAiShare (default 0.5) of its words are covered by assistant sequences and by no user sequence. The turn that contributed the most sequences is the paragraph's source; its prompt is the user message just before it, and its model is the turn's.

Quick Start

import { attributeText, setProvider } from '@molecule/api-text-provenance'
import { provider } from '@molecule/api-text-provenance-overlap'

setProvider(provider)
const { paragraphs, aiShare, prompts } = attributeText({ paragraphs: blocks, sessions })

Type

provider

Installation

npm install @molecule/api-text-provenance-overlap @molecule/api-agent-transcript @molecule/api-text-provenance

API

Functions

shingles(ws, size)

The size-word sequences of a word list, as strings.

function shingles(ws: readonly string[], size?: number): string[]
  • ws — The words.
  • size — Sequence length.

Returns: One key per starting position.

words(text)

A text's words, as attribution compares them.

function words(text: string): string[]
  • text — Any text: markdown, rendered prose, a file's content.

Returns: Its words, lowercase, in order.

Constants

provider

Attributes paragraphs by overlapping word sequences.

const provider: TextProvenanceProvider

SHINGLE

How many consecutive words make one comparison unit.

const SHINGLE: 3

Core Interface

Implements @molecule/api-text-provenance interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-text-provenance'
import { provider } from '@molecule/api-text-provenance-overlap'

export function setupTextProvenanceOverlap(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-agent-transcript ^1.0.0
  • @molecule/api-text-provenance ^1.0.0

Runtime Dependencies

  • @molecule/api-agent-transcript

  • @molecule/api-text-provenance

  • Compares words only (letters and digits, lowercase), so markdown in the session (**bold**, ## heading, links) matches the rendered prose, and a Claude Code /export's re-wrapped text matches too.

  • Tolerates light edits: changing a word breaks at most three sequences, so a paragraph with a few words changed stays ai. A rewrite falls below minAiShare and becomes human.

  • Words the user typed are never counted as the AI's, even where the agent repeated them — a paragraph pasted into a prompt stays human.

  • A paragraph shorter than three words is ai only when the whole phrase appears in an assistant text and in no user text.

  • When several turns wrote the same words (a draft, then a revision), the turn with the most matching sequences wins, and the later one on a tie.