dialog-forge 0.1.0__tar.gz

dialog_forge-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: dialog-forge
+Version: 0.1.0
+Summary: Generate realistic chat conversation mocks from dict/JSON input
+Author: Dialog Forge Contributors
+License: MIT
+Keywords: chat,mock,conversation,whatsapp,instagram,facebook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: export
+Requires-Dist: playwright>=1.40; extra == "export"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: playwright>=1.40; extra == "dev"
+
+# Dialog Forge
+
+Generate realistic chat conversation mocks from dict/JSON input with platform-specific styling.
+
+## Supported Platforms
+
+- **WhatsApp** — green bubbles, double-check marks, timestamps
+- **Instagram** — gradient bubbles, circular avatars, "Seen" labels
+- **Facebook Messenger** — blue bubbles, rounded UI, delivery indicators
+
+## Installation
+
+```bash
+pip install dialog-forge
+
+# With image export support (PNG/JPG via Playwright)
+pip install dialog-forge[export]
+```
+
+## Quick Start
+
+```python
+from dialog_forge import render_chat
+
+conversation = {
+    "platform": "whatsapp",
+    "title": "Family Group",
+    "participants": {
+        "me": {"name": "Alice", "avatar": None},
+        "friend": {"name": "Bob", "avatar": None},
+    },
+    "messages": [
+        {
+            "sender": "friend",
+            "text": "Hey! Are you coming tonight?",
+            "timestamp": "18:30",
+            "status": "read",
+        },
+        {
+            "sender": "me",
+            "text": "Yes! On my way 🚗",
+            "timestamp": "18:32",
+            "status": "delivered",
+        },
+    ],
+}
+
+# Get HTML string
+html = render_chat(conversation)
+
+# Get PNG bytes
+png_bytes = render_chat(conversation, format="png")
+
+# Debug mode — prints the intermediate HTML path
+html_debug = render_chat(conversation, format="png", debug=True)
+```
+
+## API
+
+### `render_chat(data, format="html", debug=False)`
+
+| Parameter | Type   | Default | Description |
+|-----------|--------|---------|-------------|
+| `data`    | `dict` | —       | Conversation data (see schema below) |
+| `format`  | `str`  | `"html"` | Output format: `"html"`, `"png"`, or `"jpg"` |
+| `debug`   | `bool` | `False` | When `True`, saves intermediate HTML to a temp file and prints its path |
+
+**Returns:** `str` (HTML) or `bytes` (image data)
+
+### Conversation Schema
+
+```json
+{
+  "platform": "whatsapp | instagram | facebook",
+  "title": "Chat Title",
+  "participants": {
+    "sender_id": {
+      "name": "Display Name",
+      "avatar": "https://url-to-avatar.png (optional)",
+      "gender": "male | female (optional)"
+    }
+  },
+  "messages": [
+    {
+      "sender": "sender_id",
+      "text": "Message content",
+      "timestamp": "HH:MM",
+      "status": "sent | delivered | read",
+      "type": "text"
+    }
+  ]
+}
+```
+
+## Adding a New Platform
+
+1. Create `src/dialog_forge/platforms/your_platform.py`
+2. Subclass `BaseRenderer` and implement `render(conversation) -> str`
+3. Register it in `src/dialog_forge/platforms/__init__.py`
+
+## License
+
+MIT

dialog_forge-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Dialog Forge
+
+Generate realistic chat conversation mocks from dict/JSON input with platform-specific styling.
+
+## Supported Platforms
+
+- **WhatsApp** — green bubbles, double-check marks, timestamps
+- **Instagram** — gradient bubbles, circular avatars, "Seen" labels
+- **Facebook Messenger** — blue bubbles, rounded UI, delivery indicators
+
+## Installation
+
+```bash
+pip install dialog-forge
+
+# With image export support (PNG/JPG via Playwright)
+pip install dialog-forge[export]
+```
+
+## Quick Start
+
+```python
+from dialog_forge import render_chat
+
+conversation = {
+    "platform": "whatsapp",
+    "title": "Family Group",
+    "participants": {
+        "me": {"name": "Alice", "avatar": None},
+        "friend": {"name": "Bob", "avatar": None},
+    },
+    "messages": [
+        {
+            "sender": "friend",
+            "text": "Hey! Are you coming tonight?",
+            "timestamp": "18:30",
+            "status": "read",
+        },
+        {
+            "sender": "me",
+            "text": "Yes! On my way 🚗",
+            "timestamp": "18:32",
+            "status": "delivered",
+        },
+    ],
+}
+
+# Get HTML string
+html = render_chat(conversation)
+
+# Get PNG bytes
+png_bytes = render_chat(conversation, format="png")
+
+# Debug mode — prints the intermediate HTML path
+html_debug = render_chat(conversation, format="png", debug=True)
+```
+
+## API
+
+### `render_chat(data, format="html", debug=False)`
+
+| Parameter | Type   | Default | Description |
+|-----------|--------|---------|-------------|
+| `data`    | `dict` | —       | Conversation data (see schema below) |
+| `format`  | `str`  | `"html"` | Output format: `"html"`, `"png"`, or `"jpg"` |
+| `debug`   | `bool` | `False` | When `True`, saves intermediate HTML to a temp file and prints its path |
+
+**Returns:** `str` (HTML) or `bytes` (image data)
+
+### Conversation Schema
+
+```json
+{
+  "platform": "whatsapp | instagram | facebook",
+  "title": "Chat Title",
+  "participants": {
+    "sender_id": {
+      "name": "Display Name",
+      "avatar": "https://url-to-avatar.png (optional)",
+      "gender": "male | female (optional)"
+    }
+  },
+  "messages": [
+    {
+      "sender": "sender_id",
+      "text": "Message content",
+      "timestamp": "HH:MM",
+      "status": "sent | delivered | read",
+      "type": "text"
+    }
+  ]
+}
+```
+
+## Adding a New Platform
+
+1. Create `src/dialog_forge/platforms/your_platform.py`
+2. Subclass `BaseRenderer` and implement `render(conversation) -> str`
+3. Register it in `src/dialog_forge/platforms/__init__.py`
+
+## License
+
+MIT

dialog_forge-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dialog-forge"
+version = "0.1.0"
+description = "Generate realistic chat conversation mocks from dict/JSON input"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Dialog Forge Contributors"},
+]
+keywords = ["chat", "mock", "conversation", "whatsapp", "instagram", "facebook"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+export = ["playwright>=1.40"]
+dev = ["pytest>=7.0", "playwright>=1.40"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dialog_forge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dialog_forge-0.1.0/src/dialog_forge/__init__.py

@@ -0,0 +1,12 @@
+"""
+Dialog Forge — Generate realistic chat conversation mocks.
+
+Public API:
+    render_chat(data, format="html", debug=False) -> str | bytes
+"""
+
+from dialog_forge.api import render_chat
+from dialog_forge.models import Conversation, Message, Sender
+
+__all__ = ["render_chat", "Conversation", "Message", "Sender"]
+__version__ = "0.1.0"

dialog_forge-0.1.0/src/dialog_forge/api.py

@@ -0,0 +1,78 @@
+"""
+Public API for dialog_forge.
+
+Provides the main entry point: render_chat()
+"""
+
+from __future__ import annotations
+
+import tempfile
+import os
+
+from dialog_forge.models import Conversation
+from dialog_forge.renderer import RendererRegistry
+
+# Ensure built-in platforms are registered on first import
+import dialog_forge.platforms  # noqa: F401
+
+
+def render_chat(
+    data: dict,
+    format: str = "html",
+    debug: bool = False,
+) -> str | bytes:
+    """
+    Render a chat conversation mock from a dict/JSON input.
+
+    Args:
+        data: Dictionary describing the conversation (see README for schema).
+        format: Output format — "html", "png", or "jpg".
+        debug: When True and format is an image, saves the intermediate HTML
+               to a temp file and prints its path for visual tuning.
+
+    Returns:
+        str: The HTML document (when format="html").
+        bytes: Image data (when format="png" or "jpg").
+
+    Raises:
+        ValueError: If the platform is not recognized or format is invalid.
+        ImportError: If image export is requested but Playwright is not installed.
+    """
+    fmt = format.lower()
+    if fmt not in ("html", "png", "jpg", "jpeg"):
+        raise ValueError(
+            f"Unsupported format '{format}'. Use 'html', 'png', or 'jpg'."
+        )
+
+    # Parse input into a Conversation model
+    conversation = Conversation.from_dict(data)
+
+    # Select the renderer for the given platform
+    renderer = RendererRegistry.get(conversation.platform)
+
+    # Render to HTML
+    html = renderer.render(conversation)
+
+    # HTML output mode
+    if fmt == "html":
+        if debug:
+            path = _save_debug_html(html)
+            print(f"[dialog_forge debug] HTML saved to: {path}")
+        return html
+
+    # Image output mode
+    if debug:
+        path = _save_debug_html(html)
+        print(f"[dialog_forge debug] Intermediate HTML saved to: {path}")
+
+    from dialog_forge.exporters import export_to_image
+
+    return export_to_image(html, fmt=fmt)
+
+
+def _save_debug_html(html: str) -> str:
+    """Save HTML to a temporary file and return its path."""
+    fd, path = tempfile.mkstemp(suffix=".html", prefix="dialog_forge_debug_")
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(html)
+    return path

dialog_forge-0.1.0/src/dialog_forge/exporters.py

@@ -0,0 +1,109 @@
+"""
+Image export functionality for dialog_forge.
+
+Uses Playwright (headless Chromium) to render HTML to PNG or JPG.
+Playwright is an optional dependency — install with:
+    pip install dialog-forge[export]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+
+def _check_playwright_available() -> None:
+    """Raise a helpful error if Playwright is not installed."""
+    try:
+        import playwright  # noqa: F401
+    except ImportError:
+        raise ImportError(
+            "Image export requires Playwright. "
+            "Install it with: pip install dialog-forge[export]\n"
+            "Then run: python -m playwright install chromium"
+        )
+
+
+async def _render_html_to_image(
+    html: str,
+    fmt: str = "png",
+    width: int = 420,
+) -> bytes:
+    """
+    Render an HTML string to image bytes using Playwright.
+
+    Args:
+        html: Complete HTML document string.
+        fmt: Image format — "png" or "jpg"/"jpeg".
+        width: Viewport width in pixels (height auto-adjusts to content).
+
+    Returns:
+        Image bytes in the requested format.
+    """
+    from playwright.async_api import async_playwright
+
+    fmt_lower = fmt.lower()
+    if fmt_lower in ("jpg", "jpeg"):
+        screenshot_type = "jpeg"
+    else:
+        screenshot_type = "png"
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        page = await browser.new_page(viewport={"width": width, "height": 800})
+
+        await page.set_content(html, wait_until="networkidle")
+
+        # Auto-size the viewport height to fit the content
+        content_height = await page.evaluate(
+            "() => document.documentElement.scrollHeight"
+        )
+        await page.set_viewport_size({"width": width, "height": content_height})
+
+        screenshot_bytes = await page.screenshot(
+            type=screenshot_type,
+            full_page=True,
+            quality=95 if screenshot_type == "jpeg" else None,
+        )
+
+        await browser.close()
+
+    return screenshot_bytes
+
+
+def export_to_image(
+    html: str,
+    fmt: str = "png",
+    width: int = 420,
+) -> bytes:
+    """
+    Synchronous wrapper to export HTML to an image.
+
+    Args:
+        html: Complete HTML document string.
+        fmt: Image format — "png" or "jpg"/"jpeg".
+        width: Viewport width in pixels.
+
+    Returns:
+        Image file bytes.
+    """
+    _check_playwright_available()
+
+    # Handle event loop — if one is already running, use it; otherwise create one
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        # We're inside an async context; run in a new thread to avoid deadlock
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as pool:
+            future = pool.submit(
+                asyncio.run,
+                _render_html_to_image(html, fmt, width),
+            )
+            return future.result()
+    else:
+        return asyncio.run(_render_html_to_image(html, fmt, width))

dialog_forge-0.1.0/src/dialog_forge/models.py

@@ -0,0 +1,115 @@
+"""
+Data models for dialog_forge.
+
+Defines the core dataclasses used to represent a chat conversation:
+- Sender: a participant in the conversation
+- Message: a single chat message
+- Conversation: the full conversation container
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Sender:
+    """Represents a chat participant."""
+
+    name: str
+    avatar: Optional[str] = None  # URL or base64 data URI
+    gender: Optional[str] = None  # "male", "female", or None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Sender:
+        """Create a Sender from a raw dictionary."""
+        return cls(
+            name=data["name"],
+            avatar=data.get("avatar"),
+            gender=data.get("gender"),
+        )
+
+
+@dataclass
+class Message:
+    """Represents a single chat message."""
+
+    sender: str  # Key referencing a participant in the conversation
+    text: str
+    timestamp: str = ""  # Display string like "18:30"
+    status: str = "sent"  # "sent", "delivered", "read"
+    type: str = "text"  # "text" (extensible for future types)
+
+    # Resolved at render time — not expected from user input
+    _sender_obj: Optional[Sender] = field(default=None, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Message:
+        """Create a Message from a raw dictionary."""
+        return cls(
+            sender=data["sender"],
+            text=data["text"],
+            timestamp=data.get("timestamp", ""),
+            status=data.get("status", "sent"),
+            type=data.get("type", "text"),
+        )
+
+
+@dataclass
+class Conversation:
+    """
+    Represents a full chat conversation.
+
+    Attributes:
+        platform: Target platform for styling ("whatsapp", "instagram", "facebook").
+        title: Display title of the chat (e.g. contact name or group name).
+        participants: Mapping of participant IDs to Sender objects.
+        messages: Ordered list of Message objects.
+        me: The participant ID representing the local/owner user. Defaults to "me".
+    """
+
+    platform: str
+    title: str
+    participants: dict[str, Sender]
+    messages: list[Message]
+    me: str = "me"  # Which participant ID is "us" (outgoing messages)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Conversation:
+        """
+        Parse a raw dictionary (or deserialized JSON) into a Conversation.
+
+        Expected schema:
+            {
+                "platform": "whatsapp",
+                "title": "Chat Title",
+                "me": "alice",          # optional, defaults to "me"
+                "participants": {
+                    "alice": {"name": "Alice", "avatar": null},
+                    "bob":   {"name": "Bob",   "avatar": null},
+                },
+                "messages": [
+                    {"sender": "bob", "text": "Hello!", "timestamp": "18:30", "status": "read"},
+                    ...
+                ]
+            }
+        """
+        participants = {
+            pid: Sender.from_dict(pdata)
+            for pid, pdata in data.get("participants", {}).items()
+        }
+
+        messages = [Message.from_dict(m) for m in data.get("messages", [])]
+
+        # Resolve sender objects on each message for convenience
+        for msg in messages:
+            msg._sender_obj = participants.get(msg.sender)
+
+        return cls(
+            platform=data["platform"],
+            title=data.get("title", "Chat"),
+            participants=participants,
+            messages=messages,
+            me=data.get("me", "me"),
+        )

dialog_forge-0.1.0/src/dialog_forge/platforms/__init__.py

@@ -0,0 +1,16 @@
+"""
+Platform renderer registration.
+
+Importing this module registers all built-in platform renderers
+with the global RendererRegistry.
+"""
+
+from dialog_forge.renderer import RendererRegistry
+from dialog_forge.platforms.whatsapp import WhatsAppRenderer
+from dialog_forge.platforms.instagram import InstagramRenderer
+from dialog_forge.platforms.facebook import FacebookRenderer
+
+# Register all built-in renderers
+RendererRegistry.register("whatsapp", WhatsAppRenderer)
+RendererRegistry.register("instagram", InstagramRenderer)
+RendererRegistry.register("facebook", FacebookRenderer)