Introduction

SNAG-powered temporal simulation engine for synthetic time travel through social networks with causal provenance

Timepoint Pro

Synthetic time travel through social simulation.

The first practical SNAG engine: Social Network Augmented Generation.

Like RAG retrieves documents to ground generation, SNAG synthesizes and maintains a structured social graph—complete with causal provenance, knowledge flow, emotional states, and temporal consistency—to ground LLM generation in complex group dynamics.

This transforms LLMs from fragile, drifting storytellers into reliable multi-agent reasoners. Naive single-prompt simulations collapse beyond ~10 entities or ~20 interactions due to inconsistency and token explosion. SNAG’s structured propagation, variable-depth fidelity, and composable mechanisms let you scale to dozens of entities across hundreds of timepoints—while keeping costs low and causality auditable.

Quick Start

Get up and running in 5 minutes

Core Concepts

Understand SNAG and temporal modes

API Reference

Explore the CLI and Python API

Examples

See real simulation scenarios

Why SNAG Matters

	RAG	SNAG (Timepoint Pro)
Grounds LLMs in	Retrieved documents	Synthesized social graphs
Maintains	Document relevance	Causal provenance + temporal consistency
Scales to	Millions of documents	Dozens of entities, hundreds of timepoints
Output	Grounded answers	Auditable causal simulations + training data

The value is exponential with scale: the larger and more intricate the social system (board + investors + competitors, colony crew + Earth command, historical delegations), the more emergent behaviors surface that intuition or simple models miss.

Cost-effective at scale: $0.15–$1.00 per simulation run. All 21 templates verified February 2026.

Key Features

Five Temporal Modes

FORWARD, PORTAL, BRANCHING, CYCLICAL, DIRECTORIAL—each with unique causal semantics

Heterogeneous Fidelity

95% cost reduction: entities scale from TENSOR_ONLY (~200 tokens) to TRAINED (~50k tokens)

Knowledge Provenance

Track who learned what, from whom, when—with exposure events and causal audit trails

Dialog Synthesis

Per-character generation with voice discipline, archetype profiles, and naturalness scoring

19 Mechanisms

Composable building blocks for fidelity, temporal reasoning, knowledge tracking, and more

Training Data Export

TDF, JSONL, SQLite, Fountain formats—ready for fine-tuning and ML pipelines

Architecture Overview

Temporal Modes

FORWARD — Strict causality

Standard forward timeline with knowledge provenance. Entities only know what they’ve witnessed or been told.

PORTAL — Backward reasoning

Start from a target outcome (mission failure, election won) and work backward to discover critical paths and pivot points.

BRANCHING — Counterfactuals

Explore “what-if” scenarios with divergent timelines. Run multiple survival strategies, pitch outcomes, or decision paths.

CYCLICAL — Prophecy loops

Future constrains past. Perfect for mythic sagas, generational stories, and bootstrap paradoxes.

DIRECTORIAL — Dramatic tension

Five-act structure with camera system. Events driven by narrative arc rather than pure causality.

Flagship Examples

Template	Mode	Key Feature	Entities	Timepoints	Cost
mars_mission_portal	PORTAL	Backward reasoning from 2031 failure	4	6	~$0.18
castaway_colony_branching	BRANCHING	Counterfactual survival strategies	8	16	~$0.35
vc_pitch_branching	BRANCHING	Investor reactions across pitches	5	16	~$0.30

Use Cases

Strategic Foresight

PORTAL maps critical paths backward from any outcome

Decision Testing

Run scenarios multiple ways, measure causal convergence

Training Data

Full causal ancestry, provenance, counterfactuals baked in

Social Forecasting

Variable-depth fidelity: low-res for long horizons, high-res at pivots

Quick Installation

pip

pip install -r requirements.txt
export OPENROUTER_API_KEY=your_key

Run your first simulation

./run.sh list                            # View all templates
./run.sh run mars_mission_portal         # PORTAL: backward from failed mission
./run.sh run castaway_colony_branching   # Full mechanisms + counterfactuals

Python 3.10+ required. OpenRouter API key needed for LLM access.

Timepoint Suite Integration

Timepoint Pro is part of the open-source Timepoint Suite for temporal AI:

• Flash — Reality Writer: renders grounded historical moments
• Pro — SNAG simulation engine (this project)
• Clockchain — Temporal Causal Graph: Rendered Past + Rendered Future
• SNAG Bench — Quality certifier: measures Causal Resolution
• Proteus — Settlement layer: prediction markets for Rendered Futures
• TDF — Data format: JSON-LD interchange across all services

Learn more about the Timepoint Suite

Explore how Pro integrates with Flash, Clockchain, and other services

Next Steps

Quickstart Guide

Run your first simulation in 5 minutes

Understanding SNAG

Learn the core architecture and philosophy

Temporal Modes Deep Dive

Master FORWARD, PORTAL, BRANCHING, and more

19 Mechanisms

Explore the composable building blocks

---

Open Source — Apache 2.0 License · GitHub · @seanmcdonaldxyz