TemporalGraph TS é uma biblioteca TypeScript projetada para modelar, analisar e visualizar redes temporais, grafos em que as conexões possuem duração no tempo, permitindo representar sistemas reais de forma dinâmica, contextual e historicamente consistente.
Enquanto grafos tradicionais representam relações estáticas, um Temporal Graph modela relações que nascem, duram e morrem ao longo do tempo. Isso permite análises impossíveis em grafos comuns, como:
- ritmo de interações
- recorrência
- intensidade temporal
- caminhos ordenados no tempo
- sobreposição de eventos
- aceleração / desaceleração
- períodos de inatividade
- padrões de burstiness
- ciclos temporais válidos
- evolução dinâmica de clusters
Essa lib fornece:
- Grafo temporal completo baseado em intervalos
- Conjunto enorme de métricas estruturais, semânticas e temporais
- Ferramentas de visualização (Plotly)
- Geração de dataset sintético
- Arquitetura modular (metrics/*)
- Compatível com GraphRAG / Temporal Graph RAG
- Uso genérico (não acoplado a WhatsApp ou CRM)
Um grafo tradicional é definido como:
G = (V, E)
Um Temporal Graph baseado em intervalos é:
Gₜ = (V, Eₜ)
Eₜ = { (u, v, [t_inicio, t_fim]) }
Onde cada aresta possui um intervalo de ativação:
activated_at: quando a relação começadeactivated_at: quando termina (ou permanece aberta)
Isso transforma o grafo em uma estrutura dinâmica que evolui no tempo.
O mundo é dinâmico: conversas, eventos, ações, sensores, microserviços, leads, tudo ocorre em uma sequência temporal.
Grafos estáticos matam a narrativa.
Grafos temporais preservam o filme, não só a foto.
Whatsapp, CRM, e-commerce, suporte, IoT, microserviços.
Bursts, quedas, travamentos, escaladas de atividade.
Fluxo temporal → causa e efeito → caminhos válidos.
LLMs conseguem raciocinar melhor sobre dados temporais estruturados.
src/
temporalGraph.ts
metrics/
nodeMetrics.ts
edgeMetrics.ts
graphMetrics.ts
temporalMetrics.ts
examples/
generateSyntheticTemporalGraph.ts
computeTemporalMetricsFromSynthetic.ts
visualizations/
temporal_metrics.json
temporal_metrics_plot.html
npm install temporal-graph-tsinterface TemporalNode<T = any> {
id: string
data: T
}interface TemporalEdge<T = any> {
id: string
from: string
to: string
created_at: number
activated_at: number
deactivated_at?: number
data?: T
}import { TemporalGraph } from "temporal-graph-ts"
interface User { id: string; name: string }
const graph = new TemporalGraph<User, any>(u => u.id)
graph.insertNode({ id: "alice", name: "Alice" })
graph.insertNode({ id: "bob", name: "Bob" })
graph.addTemporalEdge("alice", "bob", Date.now())graph.getActiveEdgesAt(time)
graph.getEdgesInInterval(t0, t1)
graph.temporalShortestPath("alice", "carol")
graph.getOutgoingEdges("alice")
graph.getAllNodes()
graph.getAllEdges()A biblioteca inclui mais de 25 métricas temporais, separadas em módulos:
import {
temporalDegree,
nodeLifespan,
nodeBurstiness
} from "temporal-graph-ts/metrics/nodeMetrics"- Grau temporal
- Tempo de vida da atividade
- Burstiness (Barabási)
import {
edgeDuration,
averageEdgeDurationBetween,
edgeRecurrence
} from "temporal-graph-ts/metrics/edgeMetrics"- Duração de intervalos
- Recorrência
- Estabilidade
import {
temporalDensity,
edgeOverlapCount,
interactionVelocity
} from "temporal-graph-ts/metrics/graphMetrics"- Densidade temporal
- Overlap global
- Velocidade de interação
import {
activeEdgeCountAt,
totalActiveTime,
averageActiveDuration,
activationsInInterval,
deactivationsInInterval,
graphAliveRatio,
temporalAcceleration,
temporalSnapshot,
temporalIntensity,
activationRhythm,
temporalOverlapRatio,
temporalChangeRate
} from "temporal-graph-ts/metrics/temporalMetrics"- Intensidade temporal
- Ritmo de ativações
- Mudança temporal
- Overlap temporal
- Snapshot temporal
- Tempo ativo acumulado
- Ativações/Desativações
Número de conexões ativas de um nó dentro de um intervalo de tempo.
Determina a relevância temporal do nó.
- WhatsApp: quantos clientes falaram com o atendente nas últimas horas.
- CRM: leads mais ativos.
- Suporte: agentes com maior carga.
- IoT: dispositivo enviando múltiplos eventos.
Tempo entre a primeira e a última interação do nó.
- Detectar leads que sumiram.
- Medir vida útil de sensores.
- Analisar tempo de engajamento em jornadas.
Mede irregularidade de comportamento.
- Leads impulsivos (resposta rápida em surtos).
- Fraudes (padrões regulares e robóticos).
- Emoção em conversas (mensagens longas + picos).
Quanto tempo uma relação ficou ativa.
- Sessões de conversa.
- Tempo conectado entre microserviços.
- Quanto um cliente permaneceu ativo.
Quantas vezes a relação reapareceu.
- Leads que voltam repetidamente.
- Suporte recorrente.
- Padrões comportamentais de retorno.
Duração média entre duas entidades ao longo do tempo.
- Medir estabilidade Cliente ↔ Vendedor.
- Confiabilidade entre serviços.
- Duração média de interação.
Quão conectado o grafo está em uma janela temporal.
- Identificar horas de pico.
- Analisar carga de operação.
- Mapear períodos de engajamento.
Quantas relações existiram simultaneamente.
- Congestionamento no atendimento.
- Requisições simultâneas.
- Momentos caóticos ou críticos.
Quantidade de interações criadas por minuto.
- Leads quentes (resposta rápida).
- SLAs de suporte.
- Ritmos em redes sociais.
Quantidade de eventos por minuto.
- Horários de maior propensão à conversão.
- Monitoramento de carga em serviços.
- Ritmo de uso em apps.
Tempo médio entre ativações.
- Entender periodicidade.
- Detectar padrões humanos.
- Mapear ciclos de operação.
Quantidade de ativações + desativações por minuto.
- Detectar anomalias.
- Mapear instabilidade.
- Rastrear eventos críticos.
Proporção de intervalos que se sobrepõem.
- Atendimento simultâneo.
- Requisições concorrentes.
- Estouro operacional.
Foto instantânea do grafo.
- Dashboards.
- Debug.
- Contexto para GraphRAG.
Soma total de tempo de todas as relações.
- Medir engajamento.
- Calcular uptime.
- Analisar carga operacional.
Número de relações iniciadas/terminadas.
- Leads iniciando vs encerrando.
- Sessões criadas/fechadas.
- Telemetria IoT.
- medição de velocidade de resposta
- análise temporal de funil
- identificação de leads quentes
- previsão de abandono
- detecção de padrões de compra
- mapeamento de fricções temporais
- evolução de jornada
- SLA temporal real
- gargalos
- fluxo entre agentes
- ativação/desativação
- correlação temporal
- picos e quedas
- rastreamento causal
- mensagens entre microserviços
- análise de latência real
- surgimento de tópicos
- ondas virais
- propagação temporal
- memória temporal
- raciocínio causal
- reconstrução contextual
Arquivo:
examples/generateSyntheticTemporalGraph.ts
Permite testar todo o motor da biblioteca.
Executar:
examples/computeTemporalMetricsFromSynthetic.ts
Gerará:
visualizations/temporal_metrics.jsonvisualizations/temporal_metrics_plot.html
O HTML mostra:
- Active Edge Count Over Time
- Temporal Intensity Over Time