colloquium 0.1.0__py3-none-any.whl

colloquium/__init__.py

@@ -0,0 +1,8 @@
+"""Colloquium — agent-native slide creation tool for research talks."""
+
+__version__ = "0.1.0"
+
+from colloquium.slide import Slide
+from colloquium.deck import Deck
+
+__all__ = ["Slide", "Deck", "__version__"]

colloquium/build.py

@@ -0,0 +1,174 @@
+"""HTML builder — converts a Deck into a self-contained HTML file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from string import Template
+
+from markdown_it import MarkdownIt
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+
+from colloquium.deck import Deck
+from colloquium.slide import Slide
+
+
+def _get_theme_path(theme: str = "default") -> Path:
+    """Get the path to a theme directory."""
+    themes_dir = Path(__file__).parent / "themes" / theme
+    if not themes_dir.exists():
+        themes_dir = Path(__file__).parent / "themes" / "default"
+    return themes_dir
+
+
+def _read_theme_css(theme: str = "default") -> str:
+    """Read the theme CSS file."""
+    return (_get_theme_path(theme) / "theme.css").read_text(encoding="utf-8")
+
+
+def _read_presentation_js(theme: str = "default") -> str:
+    """Read the presentation JS file."""
+    return (_get_theme_path(theme) / "presentation.js").read_text(encoding="utf-8")
+
+
+def _create_md_renderer() -> MarkdownIt:
+    """Create a markdown-it renderer with math support."""
+    md = MarkdownIt("commonmark", {"html": True, "typographer": True})
+    dollarmath_plugin(md, double_inline=True)
+    return md
+
+
+def _render_markdown(text: str, md: MarkdownIt) -> str:
+    """Render markdown text to HTML."""
+    if not text:
+        return ""
+    return md.render(text)
+
+
+def _build_slide_html(slide: Slide, index: int, md: MarkdownIt) -> str:
+    """Build the HTML for a single slide."""
+    # CSS classes
+    classes = ["slide", f"slide--{slide.layout}"]
+    if index == 0:
+        classes.append("active")
+    classes.extend(slide.classes)
+
+    class_str = " ".join(classes)
+
+    # Style attribute
+    style_attr = f' style="{slide.style}"' if slide.style else ""
+
+    # Slide content
+    parts = []
+    if slide.title:
+        tag = "h1" if slide.is_title_slide else "h2"
+        parts.append(f"<{tag}>{slide.title}</{tag}>")
+
+    if slide.content:
+        rendered = _render_markdown(slide.content, md)
+        parts.append(f'<div class="slide-content">{rendered}</div>')
+
+    inner = "\n".join(parts)
+
+    return f'<section class="{class_str}"{style_attr} data-index="{index}">\n{inner}\n</section>'
+
+
+# HTML template — uses $-style substitution
+_HTML_TEMPLATE = Template("""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>$title</title>
+
+<!-- KaTeX for LaTeX math -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/contrib/auto-render.min.js"></script>
+
+<!-- highlight.js for code syntax highlighting -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/github.min.css">
+<script defer src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/highlight.min.js"></script>
+
+<style>
+$theme_css
+$custom_css
+</style>
+</head>
+<body>
+<div class="colloquium-deck">
+$slides_html
+</div>
+
+<div class="colloquium-nav">
+    <span class="colloquium-counter">1 / $total_slides</span>
+</div>
+
+<div class="colloquium-progress">
+    <div class="colloquium-progress-bar" style="width: 0%"></div>
+</div>
+
+<script>
+$presentation_js
+</script>
+
+<script>
+// Initialize KaTeX auto-render after load
+document.addEventListener("DOMContentLoaded", function() {
+    if (typeof renderMathInElement !== "undefined") {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$$$", right: "$$$$", display: true},
+                {left: "$$", right: "$$", display: false},
+                {left: "\\\\(", right: "\\\\)", display: false},
+                {left: "\\\\[", right: "\\\\]", display: true}
+            ],
+            throwOnError: false
+        });
+    }
+    // Initialize highlight.js
+    if (typeof hljs !== "undefined") {
+        hljs.highlightAll();
+    }
+});
+</script>
+</body>
+</html>
+""")
+
+
+def build_deck(deck: Deck) -> str:
+    """Build a Deck into a self-contained HTML string."""
+    md = _create_md_renderer()
+    theme_css = _read_theme_css(deck.theme)
+    presentation_js = _read_presentation_js(deck.theme)
+
+    slides_html_parts = []
+    for i, slide in enumerate(deck.slides):
+        slides_html_parts.append(_build_slide_html(slide, i, md))
+
+    slides_html = "\n\n".join(slides_html_parts)
+
+    return _HTML_TEMPLATE.substitute(
+        title=deck.title,
+        theme_css=theme_css,
+        custom_css=deck.custom_css,
+        slides_html=slides_html,
+        total_slides=len(deck.slides),
+        presentation_js=presentation_js,
+    )
+
+
+def build_file(input_path: str, output_path: str | None = None) -> str:
+    """Build a markdown file into an HTML file. Returns the output path."""
+    from colloquium.parse import parse_file
+
+    deck = parse_file(input_path)
+    html = build_deck(deck)
+
+    if output_path is None:
+        output_path = str(Path(input_path).with_suffix(".html"))
+
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    Path(output_path).write_text(html, encoding="utf-8")
+    return output_path

colloquium/cli.py

@@ -0,0 +1,116 @@
+"""CLI entry point for colloquium."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _build(args):
+    """Build a markdown file into an HTML presentation."""
+    from colloquium.build import build_file
+
+    input_path = args.file
+    if not Path(input_path).exists():
+        print(f"Error: {input_path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    if args.output:
+        output_dir = args.output
+        stem = Path(input_path).stem
+        output_path = str(Path(output_dir) / f"{stem}.html")
+    else:
+        output_path = None  # build_file will default to same dir as input
+
+    result = build_file(input_path, output_path)
+    print(f"Built: {result}")
+
+
+def _serve(args):
+    """Serve a presentation with live reload."""
+    from colloquium.serve import serve
+
+    input_path = args.file
+    if not Path(input_path).exists():
+        print(f"Error: {input_path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    serve(input_path, port=args.port)
+
+
+def _export(args):
+    """Export a presentation to PDF."""
+    from colloquium.export import export_pdf
+
+    input_path = args.file
+    if not Path(input_path).exists():
+        print(f"Error: {input_path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    output_path = args.output
+    result = export_pdf(input_path, output_path)
+
+    if result:
+        print(f"Exported: {result}")
+    else:
+        # Build HTML and give instructions
+        from colloquium.build import build_file
+
+        html_path = build_file(input_path)
+        print("No compatible browser found for headless PDF export.")
+        print(f"HTML built at: {html_path}")
+        print(f"Open it in a browser and use Cmd+P / Ctrl+P to print to PDF.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="colloquium",
+        description="Agent-native slide creation tool for research talks",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_get_version()}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # build
+    build_parser = subparsers.add_parser("build", help="Build markdown to HTML")
+    build_parser.add_argument("file", help="Input markdown file")
+    build_parser.add_argument("-o", "--output", help="Output directory")
+    build_parser.set_defaults(func=_build)
+
+    # serve
+    serve_parser = subparsers.add_parser("serve", help="Dev server with live reload")
+    serve_parser.add_argument("file", help="Input markdown file")
+    serve_parser.add_argument("-p", "--port", type=int, default=8080, help="Port (default: 8080)")
+    serve_parser.set_defaults(func=_serve)
+
+    # export
+    export_parser = subparsers.add_parser("export", help="Export to PDF")
+    export_parser.add_argument("file", help="Input markdown file")
+    export_parser.add_argument("--pdf", action="store_true", default=True, help="Export as PDF (default)")
+    export_parser.add_argument("-o", "--output", help="Output PDF path")
+    export_parser.set_defaults(func=_export)
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)
+
+
+def _get_version() -> str:
+    try:
+        from colloquium import __version__
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+if __name__ == "__main__":
+    main()

colloquium/deck.py

@@ -0,0 +1,138 @@
+"""Deck class — the agent-facing API for building presentations."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from colloquium.slide import Slide
+
+
+class Deck:
+    """A presentation deck composed of slides."""
+
+    def __init__(
+        self,
+        title: str = "Untitled",
+        author: str = "",
+        date: str = "",
+        theme: str = "default",
+        aspect_ratio: str = "16:9",
+        custom_css: str = "",
+    ):
+        self.title = title
+        self.author = author
+        self.date = date
+        self.theme = theme
+        self.aspect_ratio = aspect_ratio
+        self.custom_css = custom_css
+        self.slides: list[Slide] = []
+
+    def add_slide(
+        self,
+        title: str = "",
+        content: str = "",
+        layout: str = "content",
+        speaker_notes: str = "",
+        classes: list[str] | None = None,
+        style: str = "",
+        **metadata,
+    ) -> Slide:
+        """Add a slide to the deck and return it."""
+        slide = Slide(
+            title=title,
+            content=content,
+            layout=layout,
+            speaker_notes=speaker_notes,
+            classes=classes or [],
+            style=style,
+            metadata=metadata,
+        )
+        self.slides.append(slide)
+        return slide
+
+    def add_title_slide(
+        self,
+        title: str = "",
+        subtitle: str = "",
+        author: str = "",
+        date: str = "",
+    ) -> Slide:
+        """Add a title slide to the deck."""
+        parts = []
+        if subtitle:
+            parts.append(subtitle)
+        # Use deck-level author/date as fallback
+        slide_author = author or self.author
+        slide_date = date or self.date
+        if slide_author:
+            parts.append(slide_author)
+        if slide_date:
+            parts.append(slide_date)
+        return self.add_slide(
+            title=title or self.title,
+            content="\n\n".join(parts),
+            layout="title",
+        )
+
+    def insert_figure(
+        self,
+        src: str,
+        alt: str = "",
+        caption: str = "",
+        slide_title: str = "",
+    ) -> Slide:
+        """Add a slide with a figure."""
+        parts = [f"![{alt}]({src})"]
+        if caption:
+            parts.append(f"*{caption}*")
+        return self.add_slide(
+            title=slide_title,
+            content="\n\n".join(parts),
+            layout="content",
+        )
+
+    def set_theme(self, theme: str) -> None:
+        """Set the deck theme."""
+        self.theme = theme
+
+    def build(self, output_dir: str = ".") -> str:
+        """Build the deck to HTML and return the output path."""
+        from colloquium.build import build_deck
+
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+
+        # Generate a filename from the deck title
+        safe_title = self.title.lower().replace(" ", "-")
+        safe_title = "".join(c for c in safe_title if c.isalnum() or c == "-")
+        filename = f"{safe_title or 'presentation'}.html"
+        filepath = output_path / filename
+
+        html = build_deck(self)
+        filepath.write_text(html, encoding="utf-8")
+        return str(filepath)
+
+    def to_markdown(self) -> str:
+        """Serialize the deck back to markdown format."""
+        lines = ["---"]
+        lines.append(f"title: {self.title}")
+        if self.author:
+            lines.append(f"author: {self.author}")
+        if self.date:
+            lines.append(f"date: {self.date}")
+        if self.theme != "default":
+            lines.append(f"theme: {self.theme}")
+        if self.aspect_ratio != "16:9":
+            lines.append(f"aspect_ratio: {self.aspect_ratio}")
+        if self.custom_css:
+            lines.append(f"custom_css: {self.custom_css}")
+        lines.append("---")
+
+        for slide in self.slides:
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+            lines.append(slide.to_markdown())
+
+        return "\n".join(lines)

colloquium/export.py

@@ -0,0 +1,116 @@
+"""PDF export via system browser and print CSS."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def _find_browser() -> str | None:
+    """Find a headless-capable browser on the system."""
+    # macOS application paths
+    mac_paths = [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ]
+
+    # Check macOS application paths first
+    for path in mac_paths:
+        if os.path.isfile(path):
+            return path
+
+    # Check PATH for common browser commands
+    for cmd in ["google-chrome", "chromium", "chromium-browser", "microsoft-edge", "brave"]:
+        found = shutil.which(cmd)
+        if found:
+            return found
+
+    return None
+
+
+def _is_chromium_based(browser_path: str) -> bool:
+    """Check if the browser is Chromium-based (supports --print-to-pdf)."""
+    name = browser_path.lower()
+    return any(x in name for x in ["chrome", "chromium", "edge", "brave"])
+
+
+def export_pdf(input_path: str, output_path: str | None = None) -> str | None:
+    """Export a presentation to PDF using a system browser.
+
+    Returns the output path on success, or None if no browser was found.
+    """
+    from colloquium.build import build_file
+
+    input_path = str(Path(input_path).resolve())
+
+    # Build HTML first
+    html_path = build_file(input_path)
+
+    if output_path is None:
+        output_path = str(Path(input_path).with_suffix(".pdf"))
+
+    html_url = f"file://{Path(html_path).resolve()}"
+
+    browser = _find_browser()
+    if browser is None:
+        return None
+
+    if not _is_chromium_based(browser):
+        return None
+
+    # Use Chromium's headless print-to-pdf
+    cmd = [
+        browser,
+        "--headless",
+        "--disable-gpu",
+        f"--print-to-pdf={output_path}",
+        "--no-pdf-header-footer",
+        html_url,
+    ]
+
+    try:
+        subprocess.run(cmd, capture_output=True, timeout=30, check=True)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+
+    if Path(output_path).exists():
+        # Optional ghostscript compression
+        _compress_pdf(output_path)
+        return output_path
+
+    return None
+
+
+def _compress_pdf(pdf_path: str) -> None:
+    """Compress PDF with ghostscript if available."""
+    gs = shutil.which("gs")
+    if not gs:
+        return
+
+    compressed = pdf_path + ".compressed"
+    cmd = [
+        gs,
+        "-sDEVICE=pdfwrite",
+        "-dCompatibilityLevel=1.4",
+        "-dPDFSETTINGS=/prepress",
+        "-dNOPAUSE",
+        "-dQUIET",
+        "-dBATCH",
+        f"-sOutputFile={compressed}",
+        pdf_path,
+    ]
+
+    try:
+        subprocess.run(cmd, capture_output=True, timeout=30, check=True)
+        # Only replace if compressed is smaller
+        if Path(compressed).stat().st_size < Path(pdf_path).stat().st_size:
+            os.replace(compressed, pdf_path)
+        else:
+            os.unlink(compressed)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        if os.path.exists(compressed):
+            os.unlink(compressed)

colloquium/parse.py

@@ -0,0 +1,131 @@
+"""Markdown parser — converts markdown files into Deck objects."""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from colloquium.deck import Deck
+from colloquium.slide import Slide
+
+
+# Directive patterns: <!-- key: value -->
+_DIRECTIVE_RE = re.compile(
+    r"<!--\s*(layout|class|style|notes)\s*:\s*(.*?)\s*-->",
+    re.DOTALL,
+)
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Extract YAML frontmatter from markdown text.
+
+    Returns (metadata_dict, remaining_text).
+    """
+    text = text.strip()
+    if not text.startswith("---"):
+        return {}, text
+
+    # Find closing ---
+    end = text.find("---", 3)
+    if end == -1:
+        return {}, text
+
+    yaml_str = text[3:end].strip()
+    remaining = text[end + 3 :].strip()
+
+    try:
+        metadata = yaml.safe_load(yaml_str) or {}
+    except yaml.YAMLError:
+        metadata = {}
+
+    if not isinstance(metadata, dict):
+        return {}, text
+
+    return metadata, remaining
+
+
+def parse_slide(text: str) -> Slide:
+    """Parse a single slide's markdown text into a Slide object."""
+    layout = "content"
+    classes = []
+    style = ""
+    notes = ""
+    title = ""
+    content_lines = []
+
+    # Extract directives and notes
+    remaining = text
+    for match in _DIRECTIVE_RE.finditer(text):
+        key = match.group(1)
+        value = match.group(2).strip()
+        if key == "layout":
+            layout = value
+        elif key == "class":
+            classes.extend(value.split())
+        elif key == "style":
+            style = value
+        elif key == "notes":
+            notes = value
+        remaining = remaining.replace(match.group(0), "")
+
+    # Parse remaining content for title
+    lines = remaining.strip().splitlines()
+    content_parts = []
+
+    for line in lines:
+        stripped = line.strip()
+        if not title and stripped.startswith("# "):
+            title = stripped[2:].strip()
+            if layout == "content":
+                layout = "title"
+        elif not title and stripped.startswith("## "):
+            title = stripped[3:].strip()
+        else:
+            content_parts.append(line)
+
+    content = "\n".join(content_parts).strip()
+
+    return Slide(
+        title=title,
+        content=content,
+        layout=layout,
+        speaker_notes=notes,
+        classes=classes,
+        style=style,
+    )
+
+
+def parse_markdown(text: str) -> Deck:
+    """Parse a full markdown file into a Deck."""
+    metadata, body = parse_frontmatter(text)
+
+    deck = Deck(
+        title=metadata.get("title", "Untitled"),
+        author=metadata.get("author", ""),
+        date=str(metadata.get("date", "")),
+        theme=metadata.get("theme", "default"),
+        aspect_ratio=str(metadata.get("aspect_ratio", "16:9")),
+        custom_css=metadata.get("custom_css", ""),
+    )
+
+    # Split on --- slide separators (horizontal rules)
+    # A --- on its own line (possibly with whitespace) separates slides
+    slide_texts = re.split(r"\n---\s*\n", body)
+
+    for slide_text in slide_texts:
+        slide_text = slide_text.strip()
+        if not slide_text:
+            continue
+        slide = parse_slide(slide_text)
+        deck.slides.append(slide)
+
+    return deck
+
+
+def parse_file(path: str) -> Deck:
+    """Parse a markdown file into a Deck."""
+    from pathlib import Path
+
+    text = Path(path).read_text(encoding="utf-8")
+    return parse_markdown(text)