### Install iMessage Conversation Analyzer using pip

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This command installs the iMessage Conversation Analyzer (ICA) library using pip, the Python package installer. Ensure you have Python 3 and pip installed on your system.

```shell
pip3 install imessage-conversation-analyzer
```

--------------------------------

### Create Virtual Environment and Install Dependencies with uv

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This command uses the uv package manager to synchronize dependencies and create a virtual environment. It installs the project in an editable mode, allowing for direct source code modifications.

```sh
uv sync
```

--------------------------------

### Install iMessage Conversation Analyzer (ICA)

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Instructions for installing the ICA library using pip or uv. This is the first step to using the tool for analyzing iMessage conversations.

```bash
pip3 install imessage-conversation-analyzer
```

```bash
uv tool install imessage-conversation-analyzer
```

--------------------------------

### Install iMessage Conversation Analyzer using uv

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This command installs the iMessage Conversation Analyzer (ICA) using the 'uv' tool, a fast Python package installer and resolver. This method is an alternative to using pip.

```shell
uv tool install imessage-conversation-analyzer
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This shell command downloads and installs the uv package manager, a tool recommended for managing Python environments and dependencies for the project.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Run message_totals analyzer via CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Example of using the ICA command-line interface to run the 'message_totals' analyzer. It specifies two contacts and outputs message and reaction counts, as well as other metrics.

```shell
ica message_totals -c 'Thomas Riverstone' -c 'Daniel Brightingale'
```

--------------------------------

### Run ICA CLI Command

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This command demonstrates how to invoke the iMessage Conversation Analyzer (ICA) command-line interface after installation. It specifically shows how to run the 'message_totals' command for a given contact.

```sh
ica message_totals -c 'Thomas Riverstone'
```

--------------------------------

### Run message_totals analyzer with multiple person filters via CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This example shows how to filter messages by multiple people using the 'message_totals' analyzer. It includes a date range filter and specifies two contacts and two senders to include in the analysis.

```shell
ica message_totals -c 'Thomas Riverstone' -c 'Daniel Brightingale' --from-date 2024-12-01 --to-date 2025-01-01 --from-person 'Thomas' --from-person 'Jane'
```

--------------------------------

### Create Custom Analyzers with Additional Arguments (Python)

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Demonstrates how to extend the base ICA CLI parser with custom arguments. This allows for more specific filtering and analysis based on user-defined criteria, such as keywords and minimum message lengths. The example defines a `CustomCLIArguments` class inheriting from `ica.TypedCLIArguments` and adds new arguments using `parser.add_argument`.

```python
import pandas as pd
import ica

class CustomCLIArguments(ica.TypedCLIArguments):
    """Custom CLI arguments for this analyzer"""
    keyword: str
    min_length: int

def main():
    parser = ica.get_cli_parser()
    parser.add_argument("--keyword", required=True, help="Keyword to search for")
    parser.add_argument("--min-length", type=int, default=10, help="Minimum message length")

    cli_args = parser.parse_args(namespace=CustomCLIArguments())

    dfs = ica.get_dataframes(
        contacts=cli_args.contacts,
        timezone=cli_args.timezone,
        from_date=cli_args.from_date,
        to_date=cli_args.to_date,
        from_people=cli_args.from_people,
    )

    # Filter messages containing keyword with minimum length
    messages = dfs.messages[~dfs.messages["is_reaction"]]
    filtered = messages[
        (messages["text"].str.contains(cli_args.keyword, case=False, na=False)) &
        (messages["text"].str.len() >= cli_args.min_length)
    ]

    results = filtered[["datetime", "sender_display_name", "text"]]

    ica.output_results(results, format=cli_args.format, output=cli_args.output)

if __name__ == "__main__":
    main()

# Run with: python my_analyzer.py -c 'John Doe' --keyword "meeting" --min-length 20
# Or: ica ./my_analyzer.py -c 'John Doe' --keyword "meeting" --min-length 20

```

--------------------------------

### Query Messages Table with SQL

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Executes a SQL query against the messages table to count total messages sent by the user. This is a basic example of direct SQL interaction with the conversation data.

```bash
ica from_sql -c 'John Doe' "SELECT COUNT(*) as total FROM messages WHERE is_from_me = 1"
```

--------------------------------

### Retrieve and Output iMessage Transcript using Python API

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

An example of using the ICA Python API to retrieve the transcript of an iMessage conversation. It demonstrates parsing CLI arguments, fetching message dataframes, and outputting the results in a specified format to stdout or a file.

```python
# get_my_transcript.py

import pandas as pd

import ica


# Export a transcript of the entire conversation
def main() -> None:
    # Allow your program to accept all the same CLI arguments as the `ica`
    # command; you can skip calling this if have other means of specifying the
    # contact name and output format; you can also add your own arguments this
    # way (see the count_phrases analyzer for an example of this)
    cli_args = ica.get_cli_parser().parse_args(
        namespace=ica.TypedCLIArguments()
    )
    # Retrieve the dataframes corresponding to the processed contents of the
    # database; dataframes include `messages` and `attachments`
    dfs = ica.get_dataframes(
        contacts=cli_args.contacts,
        timezone=cli_args.timezone,
        from_date=cli_args.from_date,
        to_date=cli_args.to_date,
        from_people=cli_args.from_people,
    )
    # Send the results to stdout (or to file) in the given format
    ica.output_results(
        pd.DataFrame(
            {
                "timestamp": dfs.messages["datetime"],
                "is_from_me": dfs.messages["is_from_me"],
                "is_reaction": dfs.messages["is_reaction"],
                # U+FFFC is the object replacement character, which appears as
                # the textual message for every attachment
                "message": dfs.messages["text"].replace(
                    r"\ufffc", "(attachment)", regex=True
                ),
            }
        ),
        # The default format (None) corresponds to the pandas default dataframe
        # table format
        format=cli_args.format,
        # When output is None (the default), ICA will print to stdout
        output=cli_args.output,
        # Make certain column labels more human-friendly with
        # prettified_label_overrides
        prettified_label_overrides={
            'is_from_me': 'Is from Me?',
            'is_reaction': 'Is Reaction?'
        }
    )


if __name__ == "__main__":
    main()

```

--------------------------------

### Get Conversation DataFrames with Python API

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Demonstrates how to use the `ica.get_dataframes()` function to load iMessage data into pandas DataFrames. It shows basic usage and advanced filtering options like contacts, timezone, date ranges, and sender.

```python
import ica

# Basic usage
dfs = ica.get_dataframes(contacts=["John Doe"])

# With filtering options
dfs = ica.get_dataframes(
    contacts=["John Doe", "Jane Smith"],  # Required: contact names, phones, or emails
    timezone="America/New_York",           # Optional: IANA timezone name
    from_date="2024-01-01",                # Optional: start date (inclusive)
    to_date="2024-12-31",                  # Optional: end date (exclusive)
    from_people=["me", "John"]             # Optional: filter by sender
)

# Access the DataFrames
print(dfs.messages.columns)
# Index(['ROWID', 'text', 'datetime', 'sender_display_name', 'sender_handle',
#        'is_from_me', 'is_reaction'], dtype='object')

print(dfs.attachments.columns)
# Index(['ROWID', 'filename', 'mime_type', 'message_id', 'datetime',
#        'is_from_me', 'sender_handle'], dtype='object')

print(dfs.handles.columns)
# Index(['handle_id', 'name', 'first_name', 'last_name', 'identifier',
#        'contact_id', 'display_name'], dtype='object')

# Analyze messages
total_messages = len(dfs.messages)
my_messages = dfs.messages[dfs.messages["is_from_me"]].shape[0]
reactions = dfs.messages[dfs.messages["is_reaction"]].shape[0]

print(f"Total: {total_messages}, From me: {my_messages}, Reactions: {reactions}")
```

--------------------------------

### Get Base CLI Parser for Custom Analyzers (Python)

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Retrieves the base command-line argument parser provided by the ICA library. This parser includes standard arguments for selecting contacts, date ranges, and output formats, enabling the creation of custom analyzers that can accept CLI inputs. It utilizes pandas for data manipulation and the ica library for core functionalities.

```python
import pandas as pd
import ica

def main():
    # Get base CLI parser with standard ICA arguments
    cli_args = ica.get_cli_parser().parse_args(
        namespace=ica.TypedCLIArguments()
    )

    # Retrieve dataframes using CLI arguments
    dfs = ica.get_dataframes(
        contacts=cli_args.contacts,
        timezone=cli_args.timezone,
        from_date=cli_args.from_date,
        to_date=cli_args.to_date,
        from_people=cli_args.from_people,
    )

    # Custom analysis: word count per message
    messages_only = dfs.messages[~dfs.messages["is_reaction"]]
    word_counts = messages_only["text"].str.split().str.len()

    results = pd.DataFrame({
        "metric": ["avg_words_per_message", "max_words", "total_words"],
        "value": [word_counts.mean(), word_counts.max(), word_counts.sum()]
    }).set_index("metric")

    ica.output_results(
        results,
        format=cli_args.format,
        output=cli_args.output
    )

if __name__ == "__main__":
    main()

```

--------------------------------

### Write Output to a File using CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Shows how to use the `-o` or `--output` flag with the ICA CLI to direct output to a specified file. The tool attempts to infer the format from the file extension, but `--format` can be used for explicit control.

```sh
ica transcript -c 'Thomas Riverstone' -o ./my_transcript.xlsx
```

--------------------------------

### Execute Python Script using ICA CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Demonstrates different ways to execute a Python script that utilizes the ICA library. This includes running it directly with `ica`, `python`, or as a module.

```sh
ica ./get_my_transcript.py -c 'Thomas Riverstone'
```

```sh
python ./get_my_transcript.py -c 'Thomas Riverstone'
```

```sh
python -m get_my_transcript -c 'Thomas Riverstone'
```

--------------------------------

### Basic CLI Usage for ICA

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Demonstrates fundamental command-line interface (CLI) commands for the ICA tool. This includes analyzing conversations with single or multiple contacts, filtering by date ranges, and specifying senders.

```bash
# Basic usage with a single contact
ica message_totals -c 'John Doe'

# Group chat analysis (multiple contacts)
ica message_totals -c 'John Doe' -c 'Jane Smith'

# Filter by date range
ica message_totals -c 'John Doe' --from-date 2024-01-01 --to-date 2024-12-31

# Filter by sender
ica message_totals -c 'John Doe' --from-person 'me'
ica message_totals -c 'John Doe' --from-person 'them'
ica message_totals -c 'John Doe' -c 'Jane Smith' --from-person 'John' --from-person 'Jane'

# Export to different formats
ica message_totals -c 'John Doe' -f csv
ica message_totals -c 'John Doe' -f json
ica message_totals -c 'John Doe' -f markdown

# Export to file (format inferred from extension)
ica transcript -c 'John Doe' -o ./my_transcript.xlsx

# Use specific timezone
ica totals_by_day -c 'John Doe' -t America/New_York
ica totals_by_day -c 'John Doe' -t UTC
```

--------------------------------

### Execute SQL Queries with Python API

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Demonstrates executing arbitrary SQL queries against conversation data using `ica.get_sql_connection()` and `ica.execute_sql_query()`. This allows for complex data manipulation and analysis using SQL, including joins and aggregations, within a Python script.

```python
import ica

dfs = ica.get_dataframes(contacts=["John Doe"])

with ica.get_sql_connection(dfs) as con:
    # Query messages sent by me
    my_messages = ica.execute_sql_query(
        "SELECT * FROM messages WHERE is_from_me = true LIMIT 10",
        con
    )
    print(my_messages)

    # Aggregate query
    daily_counts = ica.execute_sql_query(
        """
        SELECT
            DATE_TRUNC('day', datetime) as date,
            COUNT(*) as message_count,
            SUM(CASE WHEN is_from_me THEN 1 ELSE 0 END) as sent_count
        FROM messages
        GROUP BY DATE_TRUNC('day', datetime)
        ORDER BY date DESC
        LIMIT 30
        """,
        con
    )
    ica.output_results(daily_counts, format="csv")

    # Join messages and attachments
    attachment_messages = ica.execute_sql_query(
        """
        SELECT m.datetime, m.text, a.filename, a.mime_type
        FROM messages m
        JOIN attachments a ON m.ROWID = a.message_id
        ORDER BY m.datetime DESC
        LIMIT 20
        """,
        con
    )
    print(attachment_messages)
```

--------------------------------

### Output to Specific Format using CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Demonstrates how to use the `-f` or `--format` flag with the ICA CLI to specify the output format. Supported formats include CSV, Excel (xlsx), Markdown (md), and JSON.

```sh
ica message_totals -c 'Thomas Riverstone' -f csv
```

```sh
ica ./my_custom_analyzer.py -c 'Thomas Riverstone' -f csv
```

--------------------------------

### Specify Timezone using CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Illustrates how to use the `--timezone` or `-t` option with the ICA CLI to specify a custom timezone for date and time processing. An IANA timezone name must be provided.

```sh
ica totals_by_day -c 'Daniel Brightingale' -t UTC
```

```sh
ica totals_by_day -c 'Daniel Brightingale' -t America/New_York
```

--------------------------------

### Query Attachments by MIME Type using SQL

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Retrieves and counts attachments based on their MIME types using a SQL query. This is useful for understanding the types of media shared in conversations.

```bash
ica from_sql -c 'John Doe' "SELECT mime_type, COUNT(*) as count FROM attachments GROUP BY mime_type ORDER BY count DESC"
```

--------------------------------

### Run message_totals analyzer with date and person filters via CLI

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This command demonstrates filtering the 'message_totals' analyzer by a specific date range and sender. It uses ISO 8601 format for dates and filters messages from a particular person.

```shell
ica message_totals -c 'Thomas Riverstone' --from-date 2024-12-01 --to-date 2025-01-01 --from-person 'Thomas'
```

--------------------------------

### Handle Library-Specific Exceptions (Python)

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Illustrates how to gracefully handle various exceptions that may arise when using the ICA Python API. This includes specific error types like `ContactNotFoundError`, `ConversationNotFoundError`, `DateRangeInvalidError`, `FormatNotSupportedError`, `ContactWithSameNameError`, and a general `BaseAnalyzerException` for broader error catching. Proper exception handling ensures robustness and provides informative feedback to the user.

```python
import ica

try:
    dfs = ica.get_dataframes(contacts=["Nonexistent Person"])
except ica.ContactNotFoundError as e:
    print(f"Contact error: {e}")
except ica.ConversationNotFoundError as e:
    print(f"No conversation found: {e}")
except ica.DateRangeInvalidError as e:
    print(f"Invalid date range: {e}")
except ica.FormatNotSupportedError as e:
    print(f"Unsupported format: {e}")
except ica.ContactWithSameNameError as e:
    print(f"Ambiguous contact: {e}")
except ica.BaseAnalyzerException as e:
    print(f"General ICA error: {e}")

```

--------------------------------

### Execute SQL Query on iMessage DataFrames

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

This Python code snippet demonstrates how to retrieve iMessage conversation dataframes, establish an in-memory SQLite connection, and execute a SQL query to filter messages sent by the user. It utilizes the `ica` library for data retrieval and SQL execution, outputting the results.

```python
import ica

def main() -> None:
    # Retrieve conversation data
    dfs = ica.get_dataframes(contacts=["Jane Doe"])

    # Run SQL queries against the data
    with ica.get_sql_connection(dfs) as con:
        results = ica.execute_sql_query(
            "SELECT * FROM messages WHERE is_from_me = 1",
            con
        )
        ica.output_results(results)

if __name__ == "__main__":
    main()
```

--------------------------------

### Query Messages with Date Filtering using SQL

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Performs a SQL query to group messages by sender and count them, demonstrating date filtering capabilities. This helps in analyzing message frequency per contact.

```bash
ica from_sql -c 'John Doe' "SELECT sender_display_name, COUNT(*) as count FROM messages GROUP BY sender_display_name"
```

--------------------------------

### Output Analysis Results with Python API

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Illustrates how to use the `ica.output_results()` function to export pandas DataFrames to various formats like stdout, CSV, XLSX, and Markdown. It also shows how to customize column names for better readability.

```python
import pandas as pd
import ica

dfs = ica.get_dataframes(contacts=["John Doe"])

# Create analysis results
results = pd.DataFrame({
    "metric": ["total_messages", "from_me", "from_them"],
    "value": [
        len(dfs.messages),
        dfs.messages["is_from_me"].sum(),
        (~dfs.messages["is_from_me"]).sum()
    ]
}).set_index("metric")

# Output to stdout (default format)
ica.output_results(results)

# Output to CSV format
ica.output_results(results, format="csv")

# Output to file
ica.output_results(results, format="xlsx", output="./results.xlsx")

# Output with prettified column names
ica.output_results(
    results,
    format="markdown",
    prettified_label_overrides={
        "total_messages": "Total Messages",
        "from_me": "Sent by Me",
        "from_them": "Received"
    }
)
```

--------------------------------

### Specify Timezone using Python API

Source: https://github.com/caleb531/imessage-conversation-analyzer/blob/main/README.md

Shows how to set a specific timezone when retrieving dataframes using the `ica.get_dataframes()` function in the Python API, by passing the `timezone` parameter.

```python
dfs = ica.get_dataframes(contact=my_contact, timezone='UTC')
```

--------------------------------

### ICA: From SQL Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Allows users to execute custom SQL queries directly against the iMessage conversation data. The data is loaded into an in-memory SQLite database, enabling advanced, ad-hoc data retrieval and analysis.

```bash
# Example: Select all messages from 'John Doe' sent after a specific date
ica from_sql -c 'John Doe' "SELECT * FROM messages WHERE date > '2023-01-01'"

# Example: Count messages per day
ica from_sql -c 'John Doe' "SELECT date, COUNT(*) FROM messages GROUP BY date ORDER BY date"
```

--------------------------------

### ICA: Totals by Day Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Provides a daily breakdown of message activity, including total messages sent and messages sent by each participant. This analyzer is useful for identifying communication patterns over time and can be exported to CSV.

```bash
ica totals_by_day -c 'John Doe' -f csv -o ./daily_stats.csv

# Output:
# Date        # Sent  # Sent By Me  # Sent By John
# 2024-01-01      45            20              25
# 2024-01-02      67            34              33
# 2024-01-03      23            10              13
```

--------------------------------

### ICA: Message Totals Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Analyzes and summarizes message and reaction counts for a conversation. It provides metrics such as total messages, messages sent by each participant, total reactions, and days with interaction.

```bash
ica message_totals -c 'Thomas Riverstone' -c 'Daniel Brightingale'

# Output:
# Metric               Total
# Messages             20036
# Messages From Me      7000
# Messages From Daniel  6501
# Messages From Thomas  6535
# Reactions             4880
# Reactions From Me     1700
# Reactions From Daniel 1675
# Reactions From Thomas 1505
# Days Messaged          115
# Days Missed              0
# Days With No Reply       0
```

--------------------------------

### ICA: Count Phrases Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Counts the occurrences of specific phrases or patterns within messages. It supports case-insensitive matching, case-sensitive matching, and regular expression matching for flexible text analysis.

```bash
# Count specific phrases (case-insensitive by default)
ica count_phrases -c 'John Doe' "hello" "goodbye" "thanks"

# Case-sensitive counting
ica count_phrases -c 'John Doe' -s "Hello" "HELLO"

# Regular expression mode
ica count_phrases -c 'John Doe' -r "https?://.*" "\\b\\d{3}-\\d{4}\\b"

# Output:
# Phrase   Count  Count From Me  Count From John
# hello      234             89              145
# goodbye     56             23               33
# thanks     189             90               99
```

--------------------------------

### ICA: Attachment Totals Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Counts the occurrences of different attachment types within an iMessage conversation. Supported types include GIFs, YouTube videos, Spotify links, Apple Music links, audio messages, and recorded videos.

```bash
ica attachment_totals -c 'John Doe'

# Output:
# Type             Total
# GIFs               150
# YouTube Videos      45
# Apple Music         23
# Spotify             67
# Audio Messages      12
# Audio Files          8
# Recorded Videos     34
```

--------------------------------

### ICA: Transcript Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Generates a complete, unedited transcript of all messages within a conversation. It includes timestamps, sender information, and indicates whether a message is a reaction. The output can be exported to formats like Excel.

```bash
ica transcript -c 'John Doe' -o ./transcript.xlsx

# Output columns: Timestamp, Sender, Is Reaction, Message
```

--------------------------------

### ICA: Most Frequent Emojis Analyzer

Source: https://context7.com/caleb531/imessage-conversation-analyzer/llms.txt

Identifies and counts the most frequently used emojis in a conversation, with options to specify the number of results and break down counts by sender. This helps understand emotional expression patterns.

```bash
# Default: top 10 emojis
ica most_frequent_emojis -c 'John Doe'

# Custom result count
ica most_frequent_emojis -c 'John Doe' --result-count 20

# Output:
# Emoji  Count  Count From Me  Count From John
# 😂       234             89              145
# ❤️       156             78               78
# 😊       123             45               78
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.