Installation

System Requirements

Minimum Requirements:

Python 3.10, 3.11, 3.12, or 3.13
4GB RAM (8GB recommended for comprehensive simulations)
500MB disk space for code + dependencies
Internet connection for API calls

Timepoint Pro is a standalone simulation engine. It has no runtime dependencies on other Timepoint Suite services. All LLM calls go directly to OpenRouter. All data stays in local SQLite + flat files.

Installation Methods

pip (Recommended)
Poetry
Dev Container

Using pip

The fastest way to get started:

Clone the repository

git clone https://github.com/timepoint-ai/timepoint-pro.git
cd timepoint-pro

Create a virtual environment (recommended)

python3.10 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

This installs:

Core: Pydantic, Hydra, OmegaConf
LLM & AI: Instructor, httpx (for OpenRouter), LangGraph
Graph: NetworkX
Database: SQLModel
Scientific: NumPy 1.x, SciPy, scikit-learn
Serialization: msgspec
Web: FastAPI, uvicorn
Dev: pytest, ruff, black, mypy

Verify installation

python -c "import pydantic; import instructor; print('✓ Installation successful')"

Using Poetry

For dependency management and reproducible environments:

Install Poetry

curl -sSL https://install.python-poetry.org | python3 -

Or via pip:

pip install poetry

Clone the repository

git clone https://github.com/timepoint-ai/timepoint-pro.git
cd timepoint-pro

Install with Poetry

poetry install

This creates a virtual environment and installs all dependencies from pyproject.toml.

Activate the environment

poetry shell

Verify installation

poetry run python -c "import pydantic; import instructor; print('✓ Installation successful')"

Poetry locks dependencies to exact versions via poetry.lock, ensuring reproducible builds across environments.

Using Dev Container (VS Code / Codespaces)

For an isolated, pre-configured development environment:

Open in VS Code

Clone the repository and open in VS Code:

git clone https://github.com/timepoint-ai/timepoint-pro.git
code timepoint-pro

Reopen in Container

VS Code will detect .devcontainer/devcontainer.json and prompt:“Reopen in Container” - Click this.The container handles setup automatically:

Python 3.10+
All dependencies from requirements.txt
Environment variables
SQLite databases

Configure API key in container

Create .env file in the container:

echo "OPENROUTER_API_KEY=your_key_here" > .env

GitHub Codespaces: The same .devcontainer configuration works automatically in Codespaces.

Environment Configuration

API Keys

Timepoint Pro requires an OpenRouter API key. Optional: Oxen.ai key for dataset uploads.

Get an OpenRouter API key

Visit openrouter.ai/keys
Sign up (free tier available)
Create a new API key
Copy the key (format: sk-or-v1-...)

Create .env file

In the project root, create a .env file:

.env

# Required: OpenRouter API for LLM calls
OPENROUTER_API_KEY=sk-or-v1-your_key_here

# Optional: Oxen.ai for dataset versioning and uploads
OXEN_API_KEY=your_oxen_key_here

# Optional: Timepoint API (for cloud execution)
TIMEPOINT_API_KEY=your_timepoint_key_here
TIMEPOINT_API_URL=http://localhost:8080

Critical: Ensure your API key is on a single line with no line breaks. Multi-line keys cause “Illegal header value” errors.

Load environment variables

Before running any simulation:

# Export all variables from .env
export $(cat .env | xargs)

# Or source the file directly
source .env

# Or set directly (must be ONE line, no breaks)
export OPENROUTER_API_KEY="your_key_here"

You must load environment variables in every new terminal session before running simulations.

Verify environment

./run.sh doctor

This validates:

Python 3.10+ installation
.env file exists and API keys are set
Database paths are accessible
Key dependencies installed

Directory Structure

After installation, your project structure looks like:

timepoint-pro/
├── .env                          # Your API keys (NEVER commit)
├── requirements.txt              # pip dependencies
├── pyproject.toml                # Poetry config + dependencies
├── run.sh                        # Main CLI entry point
├── run_all_mechanism_tests.py    # Python runner
├── metadata/
│   ├── runs.db                   # SQLite database for run metadata
│   └── tensors.db                # Entity tensor storage
├── output/
│   └── simulations/              # Generated simulation artifacts
├── templates/                    # JSON scenario templates (if present)
├── generation/
│   └── templates/
│       └── loader.py             # TemplateLoader class
├── workflows/                    # Dialog, portal, branching strategies
└── tests/                        # Pytest test suites

Verify Installation

Run environment check

./run.sh doctor

Expected output:

[OK] Python 3.10+ detected
[OK] .env file found
[OK] OPENROUTER_API_KEY set
[OK] Database paths accessible
[OK] Key dependencies installed

List available templates

./run.sh list

You should see 21 templates organized by category:

Showcase (13 templates): Production-ready scenarios
Persona (5 templates): Domain evaluator testing
Convergence (3 templates): Consistency evaluation

Run a quick test simulation (optional)

./run.sh run --free convergence_simple

This runs a lightweight template with free models ($0 cost) to verify the full pipeline.

Model Configuration

Default Models

Timepoint Pro uses OpenRouter to access multiple model providers:

Task	Default Model	Context	Cost
Graph generation	Llama 4 Scout	128K	$0.40/M tokens
Dialog synthesis	Llama 4 Scout	128K	$0.40/M tokens
PORTAL judging	Llama 3.1 405B	128K	$3.00/M tokens
Summaries	Llama 4 Scout	128K	$0.40/M tokens

Updated February 2026: Costs are ~10x lower than previous estimates due to efficient Llama 4 Scout pricing.

Free Models

For testing without cost:

# Best quality free model (Qwen 235B, Llama 70B, etc.)
./run.sh run --free board_meeting

# Fastest free model (Gemini Flash, smaller Llama)
./run.sh run --free-fast board_meeting

# List currently available free models
python run_all_mechanism_tests.py --list-free-models

Free models have more restrictive rate limits and availability may rotate.

Model Override

Override the default model for all LLM calls:

# Use DeepSeek Chat (MIT license, training-safe)
./run.sh run --model deepseek/deepseek-chat board_meeting

# Use Gemini 3 Flash (1M context, fast inference)
./run.sh run --gemini-flash board_meeting

# Use Groq for ultra-fast inference (~300 tok/s)
./run.sh run --groq board_meeting

Model Licensing for Training Data:If you plan to use simulation outputs as training data for fine-tuning, you must use models with licenses that permit it:

License	Models	Training Data Status
MIT	DeepSeek Chat, DeepSeek R1	✓ Fully unrestricted
Apache 2.0	Mistral 7B, Mixtral 8x7B/8x22B	✓ Fully unrestricted
Llama	Llama 3.1 8B/70B/405B, Llama 4 Scout	✗ Restricted - prohibits training non-Llama models
Qwen	Qwen 2.5 7B/72B, QwQ 32B	✓ Permissive for most uses

Default behavior: The model selector (M18) automatically filters to training-safe models (MIT/Apache-2.0) when for_training_data=True.

Database Setup

Timepoint Pro uses SQLite for persistence. No manual database setup required.

Automatic Initialization

Databases are created automatically on first run:

metadata/runs.db - Stores run metadata, convergence sets, usage tracking
metadata/tensors.db - Stores entity tensors and embeddings
output/simulations/sim_TIMESTAMP.db - Per-run simulation database

Manual Initialization (Optional)

If you need to manually initialize:

# Create metadata directories
mkdir -p metadata output/simulations

# Run database migrations (if applicable)
python -c "from storage import GraphStore; GraphStore('sqlite:///metadata/runs.db')"

Optional: Oxen.ai Integration

For dataset versioning and collaborative data management:

Get an Oxen.ai API key

Visit oxen.ai
Create an account
Generate an API key

Add to .env

.env

OXEN_API_KEY=your_oxen_key_here

Auto-upload training data

When OXEN_API_KEY is set, training data is automatically uploaded to Oxen.ai after simulation runs complete.

./run.sh run board_meeting
# Training data auto-uploaded to Oxen.ai with full versioning

Oxen.ai provides Git-like versioning for datasets. When enabled, all simulation outputs (JSONL, SQLite, TDF) are automatically tracked and versioned.

Testing Your Installation

Unit Tests

Run the test suite to verify everything works:

# All unit tests (fast, no LLM calls)
./run.sh test unit

# SynthasAIzer tests (142 ADPRS waveform tests)
./run.sh test synth

# All mechanism tests (M1-M19)
./run.sh test mechanisms

# Specific mechanism (e.g., M7 causal chains)
./run.sh test m7

# With coverage report
./run.sh test unit --coverage

Integration Tests

# Waveform pipeline integration
pytest tests/integration/test_adprs_phase2_integration.py \
  tests/integration/test_waveform_sufficiency.py -v

Development Setup

Code Quality Tools

Timepoint Pro uses:

ruff - Fast Python linter (replaces flake8, isort)
black - Code formatter
mypy - Type checking
pytest - Testing framework

# Format with black
black . --line-length 100

# Lint with ruff
ruff check .

# Auto-fix linting issues
ruff check --fix .

Security

Static analysis is integrated:

# Run Bandit security scan
bandit -r . -ll

# Run Semgrep security scan
semgrep --config=auto .

All HIGH security findings have been resolved as of February 2026. Embedding index uses numpy .npz + JSON sidecar (safe serialization). All DB queries are parameterized. No hardcoded secrets.

Troubleshooting

Python version mismatch

Problem: requires-python >=3.10,<3.14Solution: Use Python 3.10, 3.11, 3.12, or 3.13. Check version:

python --version

Install Python 3.10+ via:

macOS: brew install [email protected]
Ubuntu: sudo apt install python3.10
Windows: Download from python.org

grpcio build failures on macOS

Problem: grpcio fails to build from source on macOS M1/M2Solution: Use pre-built wheels by pinning to version ≥1.68.1:

pip install grpcio>=1.68.1

Or install with conda:

conda install grpcio

NumPy version conflicts

Problem: ImportError: numpy.core.multiarray failed to importSolution: Requirements pin NumPy to 1.x for matplotlib/numba compatibility:

pip install "numpy>=1.26,<2.0"

Missing dependencies after Poetry install

Problem: ModuleNotFoundError after poetry installSolution: Install with dev dependencies:

poetry install --with dev

Or install specific missing packages:

poetry add msgspec

SQLite database locked

Problem: OperationalError: database is lockedSolution: Another process is using the database. Kill it:

# Find Python processes
ps aux | grep python

# Kill the process
kill -9 <PID>

Or use a different database:

./run.sh run board_meeting --db metadata/runs_alt.db

Next Steps

First Simulation

Run your first template and understand the output

Templates

Explore 21 production templates

Temporal Modes

Forward, Portal, Branching, Cyclical, Directorial

API Reference

Programmatic simulation submission

Getting Started

Core Concepts

Temporal Modes

Mechanisms

Guides

Examples

System Requirements

Installation Methods

Using pip

Using Poetry

Using Dev Container (VS Code / Codespaces)

Environment Configuration

API Keys

Directory Structure

Verify Installation

Model Configuration

Default Models

Free Models

Model Override

Database Setup

Automatic Initialization

Manual Initialization (Optional)

Optional: Oxen.ai Integration

Testing Your Installation

Unit Tests

Integration Tests

Development Setup

Code Quality Tools

Security

Troubleshooting

Next Steps

First Simulation

Templates

Temporal Modes

API Reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Temporal Modes

Mechanisms

Guides

Examples

​System Requirements

​Installation Methods

​Using pip

​Using Poetry

​Using Dev Container (VS Code / Codespaces)

​Environment Configuration

​API Keys

​Directory Structure

​Verify Installation

​Model Configuration

​Default Models

​Free Models

​Model Override

​Database Setup

​Automatic Initialization

​Manual Initialization (Optional)

​Optional: Oxen.ai Integration

​Testing Your Installation

​Unit Tests

​Integration Tests

​Development Setup

​Code Quality Tools

​Security

​Troubleshooting

​Next Steps

First Simulation

Templates

Temporal Modes

API Reference

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Using pip

Using Poetry

Using Dev Container (VS Code / Codespaces)

Environment Configuration

API Keys

Directory Structure

Verify Installation

Model Configuration

Default Models

Free Models

Model Override

Database Setup

Automatic Initialization

Manual Initialization (Optional)

Optional: Oxen.ai Integration

Testing Your Installation

Unit Tests

Integration Tests

Development Setup

Code Quality Tools

Security

Troubleshooting

Next Steps