hackluminary 2.3.0

Offline-first, branch-aware hackathon presentation generator

HackLuminary v2.3

Offline-first, branch-aware presentation system with a NotebookLM-style local Studio and production deck renderer.

Highlights

• Hybrid workflow: studio for drafting + generate for exports
• Source-grounded citations with snippet/line provenance
• Evidence explorer with search/filter/sort and per-slide evidence pinning
• Self-contained offline HTML deck output
• Presenter mode with notes, timer, progress timeline, jump controls
• Slide outline + reorder controls with keyboard shortcuts
• One-click Studio quality fixes (Fix This, Fix All) for common quality errors
• Bundle artifacts (notes.md, talk-track.md) for presenter prep
• Conservative offline visual pipeline (auto image selection + evidence-linked captions)
• JSON schema 2.2 with media_catalog and per-slide visuals
• Strict local runtime by default (no CDN, no cloud calls in generate/validate/studio). Remote image fetching (Wikimedia Commons) is opt-in via --remote-images or images.remote.enabled = true.

Commands

• hackluminary generate [PROJECT_DIR]
• hackluminary validate [PROJECT_DIR]
• hackluminary studio [PROJECT_DIR]
• hackluminary doctor [PROJECT_DIR]
• hackluminary init [PROJECT_DIR]
• hackluminary presets
• hackluminary sample [TARGET_DIR]
• hackluminary models list
• hackluminary models install <alias>
• hackluminary images scan [PROJECT_DIR]
• hackluminary images report [PROJECT_DIR] --json
• hackluminary images benchmark CORPUS_DIR
• hackluminary package devpost [PROJECT_DIR] --output PATH
• hackluminary telemetry enable [PROJECT_DIR] --endpoint URL
• hackluminary telemetry status [PROJECT_DIR]
• hackluminary telemetry flush [PROJECT_DIR]
• hackluminary telemetry disable [PROJECT_DIR]

Installation

Recommended

pipx install .

Development

python -m pip install -e '.[dev]'

Optional local AI dependencies

python -m pip install -e '.[ml]'

Release Build Dependencies

python -m pip install -e '.[release]'

Quick Start

Launch Studio

hackluminary studio . --base-branch main

Generate deck outputs

hackluminary generate . --preset demo-day --images auto --output deck --bundle

Validate quality gates only

hackluminary validate . --mode deterministic

generate options

• --project-dir PATH
• --output PATH
• --format html|markdown|json|both
• --preset quick|demo-day|investor|hackathon-judges|hackathon-finals
• --slides title,problem,solution,demo,impact,tech,future,delta,closing
• --max-slides N
• --docs PATH (repeatable)
• --theme default|dark|minimal|colorful|auto|custom
• --mode deterministic|ai|hybrid
• --images off|auto|strict
• --image-dirs PATH (repeatable, project-relative)
• --max-images-per-slide 0..2
• --visual-style evidence|screenshot|mixed
• --remote-images (opt in to Wikimedia image fetching; off by default for offline-first runs)
• --base-branch NAME
• --no-branch-context
• --strict-quality / --no-strict-quality
• --open
• --copy-output-dir PATH
• --logo PATH
• --bundle
• --debug

Setup And Onboarding

hackluminary doctor .
hackluminary init .
hackluminary presets
hackluminary sample

• doctor verifies local setup, project health, git context, model readiness, and Studio assets.
• init writes hackluminary.toml using an interactive wizard.
• sample creates a runnable demo project for first-time users.

Binary Distribution

On a tagged release (v*), the workflow builds and publishes:

• standalone macOS binaries (macos-x64, macos-arm64)
• standalone Windows binary (windows-x64)
• standalone Linux binary (linux-x64)
• wheel + source distribution to PyPI via Trusted Publishing (OIDC), gated by twine check
• the same wheel + sdist attached to the GitHub Release
• generated Homebrew formula + Winget manifests
• checksum verification before publish
• signing gate enforcement for macOS/Windows artifacts (override via ALLOW_UNSIGNED_RELEASE=1 secret)

PyPI publishing requires a configured Trusted Publisher for this repository and a GitHub pypi environment; until that is configured on PyPI, the publish-pypi job will fail closed rather than silently skipping.

GitHub release automation lives in:

• .github/workflows/release.yml

Direct install scripts

macOS/Linux:

bash install/install.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File install/install.ps1

Optional environment overrides for installers:

• HACKLUMINARY_REPO (default ch1kim0n1/HackLuminary)
• HACKLUMINARY_VERSION (default latest)
• HACKLUMINARY_INSTALL_DIR (custom install location)

studio options

• --project-dir PATH
• --base-branch NAME
• --theme default|dark|minimal|colorful|auto
• --port INT
• --read-only
• --debug

Configuration (hackluminary.toml)

Precedence:

1. CLI flags
2. Project config
3. User config (~/.config/hackluminary/config.toml)
4. Defaults

Sections:

• [general]: mode, format, theme, max_slides, strict_quality, logo
• [git]: base_branch, include_branch_context
• [ai]: enabled, backend, model_alias, max_tokens, top_p, temperature
• [output]: copy_output_dir, open_after_generate
• [images]: enabled, mode, image_dirs, max_images_per_slide, min_confidence, visual_style, max_image_bytes, allowed_extensions
• [images.remote]: enabled (default false — offline-first; set true or pass --remote-images to opt in), provider (wikimedia), timeout_sec, max_image_bytes, cache_dir
• [telemetry]: enabled, anonymous, endpoint (opt-in only; local event file by default)
• [studio]: enabled, default_view, autosave_interval_sec, port, read_only
• [ui]: density, motion, code_font_scale, presenter_timer_default_min
• [features]: studio_enabled, production_theme_enabled, presenter_pro_enabled
• [privacy]: telemetry=false

Custom Branding

You can override the built-in themes to match your project's brand identity.

• Custom Colors: To use custom colors, set theme = "custom" in the [general] section of your hackluminary.toml file. Then, define your color palette in the [theme.custom] section. You can override any of the following default theme keys:

  • bg
  • panel
  • panel_alt
  • text
  • muted
  • accent
  • accent2
  • warning
  • danger
  • ok
  • overlay

• Logo: To add a logo to your title slide, specify the path to your logo file in the logo field of the [general] section in hackluminary.toml. You can also use the --logo command-line option.

JSON schema 2.2

Top-level fields:

• schema_version
• metadata
• git_context
• slides
• evidence
• media_catalog
• quality_report

Slide additions:

• claims[]: { text, evidence_refs, confidence }
• notes
• visuals[]: { id, type, source_path, alt, caption, evidence_refs, confidence, width, height, sha256 }

Evidence additions:

• source_path
• source_kind
• start_line
• end_line
• snippet
• snippet_hash

Studio Session

Studio persists workspace state in:

• .hackluminary/studio/session.json

Includes slide ordering, draft overrides, note blocks, pinned evidence, presenter state, and last validation. Automatic session snapshots are written to .hackluminary/studio/snapshots/ for crash recovery.

Testing

python -m pytest

Browser Support

Studio and exported decks target current:

• Chrome
• Edge
• Safari
• Firefox

License

MIT