@terminals-tech/graph

Language-first event graph system. Zero dependencies. <600 lines.

Extract relationships from text, find patterns, and navigate event chains - all in pure JavaScript.

Installation

npm install @terminals-tech/graph

What This Is

Events are text. Text naturally forms graphs through language patterns (causal words, temporal markers, entity references). This package makes those implicit relationships explicit and queryable.

Instead of complex machine learning, we use simple text processing to extract tremendous value from your event data.

Quick Start

import { TextGraph, PatternMatcher, GraphProcessor } from '@terminals-tech/graph'

// Your events (from any source)
const events = [
  { id: '1', type: 'user-login', description: 'User logged in' },
  { id: '2', type: 'page-view', description: 'Dashboard opened after login' },
  { id: '3', type: 'error', description: 'Failed to load data due to timeout' },
  { id: '4', type: 'retry', description: 'System retried because of error' }
]

// Extract relationships from text
const textGraph = new TextGraph()
const graph = textGraph.buildGraph(events)

// Find what caused the error
const causes = textGraph.findCauses(graph, '3')
// Returns: events that led to the error

// Detect patterns
const matcher = new PatternMatcher()
const patterns = matcher.extractPatterns(events)
// Returns: common sequences like "login → dashboard → error"

// Scale to 100K+ events
const processor = new GraphProcessor()
events.forEach(e => processor.addEvent(e, []))
const important = processor.calculatePageRank()
// Returns: most important events by connectivity

Three Phases of Power

Phase 1: Text Graph (Ships Today)

Extract causal chains, temporal sequences, and entity relationships from natural language:

const textGraph = new TextGraph()

// Automatically finds relationships like:
// "X caused Y" → causal edge
// "A then B" → temporal edge
// "C requires D" → dependency edge

const relations = textGraph.extractRelations(
  "Settings failed to load due to network timeout"
)
// Returns: [{ type: 'causal', from: 'network timeout', to: 'failed to load' }]

Phase 2: Pattern Recognition (No ML Required)

Find recurring patterns, detect anomalies, and predict likely next events:

const matcher = new PatternMatcher()

// Find patterns
const patterns = matcher.extractPatterns(events, 3) // 3-grams
// "login → browse → purchase" occurs 47 times

// Detect anomalies
const anomalies = matcher.detectAnomalies(events)
// "Direct purchase without browsing is unusual"

// Predict next
const predictions = matcher.predictNext(events)
// "85% chance user will click save"

Phase 3: Scale & Intelligence

Handle 100K+ events with graph algorithms that run entirely in the browser:

const processor = new GraphProcessor()

// PageRank for importance
const important = processor.calculatePageRank()
// "Database connection lost" has highest impact

// Find clusters
const clusters = processor.findClusters()
// Discovers 12 independent workflows

// Navigate paths
const path = processor.findPath('login', 'purchase')
// Shows: login → browse → add-to-cart → checkout → purchase

Real-World Use Cases

Debugging Production Issues

// What caused the crash?
const causes = textGraph.findCauses(graph, 'crash-event-id')

// What else was happening?
const context = processor.getSubgraph('crash-event-id', depth: 2)

// Is this pattern unusual?
const anomalies = matcher.detectAnomalies(eventsAroundCrash)

Understanding User Journeys

// How do users get from A to B?
const paths = processor.findAllPaths('signup', 'first-purchase')

// What do successful users do differently?
const successPatterns = matcher.extractPatterns(successfulUsers)
const failurePatterns = matcher.extractPatterns(failedUsers)

Monitoring System Health

// Detect unusual patterns in real-time
eventStream.subscribe(event => {
  const anomalies = matcher.detectAnomalies(recentEvents)
  if (anomalies.length > 0) {
    alert(`Unusual pattern: ${anomalies[0].reason}`)
  }
})

Integration with @terminals-tech/core

Works seamlessly with the Terminals event store:

import terminals from '@terminals-tech/core'
import { EventGraph } from '@terminals-tech/graph'

const term = terminals.init()
const graph = new EventGraph()

// Automatic graph building from event store
term.store.subscribe((event, state) => {
  graph.processEvents(term.store.getEvents())
  
  // Real-time insights
  const predictions = graph.predictNext(term.store.getEvents())
  console.log('Next likely:', predictions[0])
})

Performance

• Phase 1: 0ms extraction (pure regex)
• Phase 2: 50ms for 10K events
• Phase 3: <1s for 100K events
• Memory: ~100 bytes per event
• Dependencies: Zero

API Reference

TextGraph

• extractRelations(text) - Find relationships in text
• buildGraph(events) - Convert events to graph
• findCauses(graph, eventId) - Find what caused an event
• findEffects(graph, eventId) - Find what an event caused

PatternMatcher

• extractPatterns(events, n) - Find n-gram patterns
• detectAnomalies(events) - Find unusual sequences
• predictNext(events) - Predict likely next events
• findCycles(events) - Find repeating patterns

GraphProcessor

• addEvent(event, relations) - Add incrementally
• calculatePageRank() - Find important nodes
• findClusters() - Group related events
• findPath(from, to) - Navigate between events

Philosophy

We believe that language is already the most sophisticated graph representation we have. Every sentence encodes nodes (entities), edges (relationships), and weights (emphasis).

By working with language directly instead of abstracting it into matrices, we get:

• Interpretability: Users can read the connections
• Editability: Users can modify relationships
• Composability: New events naturally integrate
• Zero-shot generalization: Works on any text

License

MIT © Intuition Labs

Built with ❤️ for developers who want insights from events without the complexity of machine learning.