Skip to main content

iMessage Data Foundry

Generate realistic iMessage and Address Book sqlite databases for mock testing and demo applications.

Overview

iMessage Data Foundry creates synthetic chat.db SQLite databases that exactly mirror the macOS iMessage schema. You have the option to use Ai to generate the personas and conversations. You can either use local models through mlx (note, really only for apple silicon though given the dependency on mlx-lm.), or OpenAI / Anthropic endpoints.

Good use cases for this synthetic data are:

  • Testing iMessage analysis tools and exporters
  • Development of applications that interface with iMessage data
  • Demos and documentation requiring realistic message data

Demo

iMessage Data Foundry Demo

Features

  • Full Schema Replication — Exact match of macOS iMessage chat.db structure
  • Multi-Version Support — Sonoma (14.x), Sequoia (15.x), and Tahoe (26.x)
  • AI-Powered Personas — Generate realistic personas with distinct personalities
  • Natural Conversations — LLM-generated messages that feel authentic
  • Persona Library — Save and reuse personas across database generations
  • Group Chats — Support for both 1:1 and group conversations
  • Realistic Timestamps — Natural message timing with conversation batching
  • Attachment Stubs — Placeholder attachments with proper database records

Installation

pip install imessage-data-foundry

With uvx (no install required)

uvx imessage-data-foundry

With pipx

pipx install imessage-data-foundry

From source

git clone https://github.com/johnlarkin1/imessage-data-foundry.git
cd imessage-data-foundry
pip install -e .

Quick Start

# Launch the TUI
uvx imessage-data-foundry

# Or run directly
uv run python -m imessage_data_foundry

CLI Options

imessage-data-foundry --help
imessage-data-foundry --version
imessage-data-foundry --output ~/Desktop/chat.db
imessage-data-foundry # interactive mode (this is the default)

Configuration

LLM Provider

Select your preferred LLM provider from the Settings menu in the app. Available providers depend on which API keys you have configured.

API Keys

Set API keys as environment variables before running the app:

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."

Local Models

For local inference on Apple Silicon, install mlx-lm:

pip install mlx-lm

Settings are stored in ~/.config/imessage-data-foundry/foundry.db.

Usage

Creating Personas

Personas can be created manually or generated by AI:

┌─ Create Persona ─────────────────────────────────┐
│                                                  │
│  Name: Sarah Chen                                │
│  Phone: +1 (555) 123-4567                        │
│  Relationship: Close friend from college         │
│                                                  │
│  Personality:                                    │
│  Outgoing, tech-savvy software engineer who      │
│  loves hiking and craft coffee. Quick to         │
│  respond with enthusiasm and emoji.              │
│                                                  │
│  [Generate with AI]  [Save]  [Cancel]            │
│                                                  │
└──────────────────────────────────────────────────┘

Generating Conversations

  1. Select personas to include
  2. Choose chat type (1:1 or group)
  3. Set message count target
  4. Optionally provide a conversation seed
  5. Generate!

Output

The generated chat.db file can be used with any tool that reads iMessage databases:

# Example: Use with imessage-exporter
imessage-exporter -p ./output/chat.db -f html -o ./export/

API Keys

You'll need an API key from one of the supported providers:

Provider Get API Key
OpenAI https://platform.openai.com/api-keys
Anthropic https://console.anthropic.com/settings/keys

Project Structure

imessage-data-foundry/
├── imessage_data_foundry/
│   ├── cli/               # CLI application and flows
│   ├── db/                # Database schema and building
│   ├── personas/          # Persona management
│   ├── conversations/     # Conversation generation
│   ├── llm/               # LLM provider integrations
│   ├── settings/          # Settings storage
│   └── utils/             # Utility functions
├── tests/                 # Test suite
└── docs/                  # Documentation

Schema Compatibility

Generated databases are tested for compatibility with:

Limitations

  • Text-only focus — Reactions, read receipts, and message effects are not simulated
  • Placeholder attachments — Attachments are stubs, not real media files
  • macOS-centric — Schema targets macOS; iOS backup databases may differ slightly

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run type checking
uv run mypy src/

# Format code
uv run ruff format src/

License

MIT License — See LICENSE for details.

Acknowledgments

Metadata

Release files for imessage-data-foundry 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imessage-data-foundry 1.0.0
File Size Uploaded Provenance Actions
imessage_data_foundry-1.0.0.tar.gz 164.2 kB With provenance Details for imessage_data_foundry-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for imessage-data-foundry 1.0.0
File Interpreter ABI Platform Actions
imessage_data_foundry-1.0.0-py3-none-any.whl Python 3 none any Details for imessage_data_foundry-1.0.0-py3-none-any.whl

Total release size: 236.3 kB

Release files / imessage_data_foundry-1.0.0.tar.gz

Download URL imessage_data_foundry-1.0.0.tar.gz
Size 164.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1a47a569a35b5c592a8103affba7afdef8cf14462c2a4bddb9cd2f3d8240efbe
BLAKE2b-256 checksum
How to use checksums
112341daf3ba2904d871f0bda8d2a9fe9b12c454eb7738adfbcd381d02531cbe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.

Transparency log

Release files / imessage_data_foundry-1.0.0-py3-none-any.whl

Download URL imessage_data_foundry-1.0.0-py3-none-any.whl
Size 72.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7916d75905c877cfa2b0676f067fa28e7ba4a8cf794621eabc21588ec78ff619
BLAKE2b-256 checksum
How to use checksums
4376695296e09f1e89853721971ddecdd446957a61573391dba28cdf53b278e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.

Transparency log

Security for imessage-data-foundry 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for imessage_data_foundry-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page