AI Phonebook

Version: 0.2.0

A modern, local phonebook application with optional encryption, advanced search capabilities, and intelligent contact management. This README has been updated to reflect the current project state and implemented multi-value contact support, migration, testing and production-readiness details.

Highlights (Current)

• Multi-value contacts: multiple phone numbers and email addresses per contact
• Birthday tracking and favorite flag per contact
• Backward-compatible migration from legacy single-value schema
• Import/Export: CSV (semicolon-separated multi-values) and vCard (VCF) 3.0
• Fast prefix search (in-memory Trie) and optional fuzzy search (requires rapidfuzz)
• PyQt6 GUI + full-featured CLI
• Interaction tracking and ranking with caching and decay-based scoring
• Comprehensive automated test suite (unit, integration, migration, performance)

Features

Core Functionality

• Local SQLite/SQLCipher database with automatic migrations
• Multiple phones/emails per contact with backward compatibility for legacy data
• Birthday tracking with ISO date validation
• Favorite contacts with scoring boost for suggestions
• Contact merging with intelligent duplicate detection and conflict resolution
• Full-text prefix search and optional fuzzy matching

Interfaces

• Rich PyQt6 GUI (when PyQt6 is available)
  • Multi-value contact forms (add/remove phones/emails)
  • Duplicate detection dialog and merge preview
  • Light/dark theme support and keyboard shortcuts
• CLI (argparse) with comprehensive subcommands
  • Multi-value --phone and --email flags supported
  • add, edit, show, list, search, fuzzy-search, import-csv, export-csv, merge, find-duplicates, init-db

Data Management

• CSV format with semicolon-separated multiple values; legacy single-value CSV is supported
• VCF (vCard) 3.0 export including multiple TEL/EMAIL entries and BDAY
• Dry-run capability for safe imports
• Optional SQLCipher encryption when sqlcipher3-wheels is installed

Advanced

• Duplicate detection using multi-factor scoring (name similarity + overlap of phones/emails)
• Smart merging that unions multi-values and preserves survivor's authoritative fields
• Ranking system combining frequency and recency with exponential decay and favorites boost
• TTL-based caching for Top-N suggestions

Requirements

• Python 3.13+
• Core dependencies (installed as part of package):
  • pydantic - data validation and modeling
  • cryptography - encryption support
• Optional dependencies:
  • sqlcipher3-wheels - database encryption
  • PyQt6 - GUI
  • rapidfuzz - fuzzy search
  • jellyfish - additional similarity algorithms

Installation

Using uv (recommended)

git clone https://github.com/HyperspaceDan/AI_phonebook
cd AI_phonebook
uv pip install -e .

Using pip

git clone https://github.com/HyperspaceDan/AI_phonebook
cd AI_phonebook
pip install -e .

Usage

GUI Mode (default when available)

uv run python -m ai_phonebook.app
# or explicitly
uv run python -m ai_phonebook.app gui

CLI Examples

# Initialize database
uv run python -m ai_phonebook.app init-db

# Add contact (multi-value)
uv run python -m ai_phonebook.app add --name "Bob Smith" \
  --phone "+1234567890" --phone "+1987654321" \
  --email "bob@work.com" --email "bob@personal.com" \
  --birthday "1985-03-15" --favorite

# Edit contact (add/remove phones/emails)
uv run python -m ai_phonebook.app edit --id 1 \
  --add-phone "+5555555555" --remove-email "old@ex.com" --favorite true

# Search
uv run python -m ai_phonebook.app search --prefix "ali"

# Fuzzy search (requires optional dependency)
uv run python -m ai_phonebook.app fuzzy-search --query "Alise" --threshold 0.8

# Import/export
uv run python -m ai_phonebook.app import-csv --path contacts.csv --dry-run
uv run python -m ai_phonebook.app import-csv --path contacts.csv
uv run python -m ai_phonebook.app export-csv --path export.csv

CSV format

Supports multiple phones/emails separated with semicolons:

name,phones,emails,birthday,favorite
"John Doe","+1234567890;+1987654321","john@work.com;john@personal.com","1985-03-15",1

• name required
• phones required (at least one) in E.164-like format; semicolon-separated
• emails optional; semicolon-separated
• birthday optional (YYYY-MM-DD)
• favorite optional (1/0, true/false)

Legacy CSVs using phone/email single-value columns are still accepted and migrated on import.

Migration & Backward Compatibility

• On first run the application will automatically migrate legacy single-value phone/email fields into the new contact_phones/contact_emails tables.
• The main contacts table gained birthday and favorite columns; old data is preserved and mapped.
• UNIQUE constraint on main phone column has been removed in favor of per-contact phone rows.

Testing

• Test runner: pytest.
• Extensive test suite covering unit tests, integration tests, migration compatibility, import/export, CLI, ranking, dedupe and performance.

Run tests:

uv run pytest
uv run pytest --cov=ai_phonebook

Targeted test groups:

uv run pytest tests/test_cli_*.py
uv run pytest tests/test_multi_*.py
uv run pytest tests/test_import_export_*.py

Development

Code quality tools:

uv run black src/ tests/
uv run ruff check src/ tests/
uv run mypy src/

Contributing

1. Fork the repository
2. Create a branch (git checkout -b feature/my-feature)
3. Implement changes and tests
4. Run quality checks and tests
5. Submit a pull request

License

MIT License - see LICENSE.txt for details.

---

For more details about the multi-value implementation, migration steps and testing strategy see IMPLEMENTATION_COMPLETE.md and the tests/ directory.