Metadata-Version: 2.4
Name: hackluminary
Version: 2.3.0
Summary: Offline-first, branch-aware hackathon presentation generator
Author: MindCore
License: MIT
Project-URL: Homepage, https://github.com/ch1kim0n1/HackLuminary
Project-URL: Repository, https://github.com/ch1kim0n1/HackLuminary
Project-URL: Bug Tracker, https://github.com/ch1kim0n1/HackLuminary/issues
Project-URL: Changelog, https://github.com/ch1kim0n1/HackLuminary/releases
Keywords: hackathon,presentation,slides,generator,offline,git,branch-aware,markdown,html,ai,llm,studio
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: colorama>=0.4; sys_platform == "win32"
Provides-Extra: ml
Requires-Dist: llama-cpp-python>=0.2.90; extra == "ml"
Requires-Dist: huggingface_hub>=0.25; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: pyinstaller>=6.10; extra == "release"
Dynamic: license-file

# 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

```bash
pipx install .
```

### Development

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

### Optional local AI dependencies

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

### Release Build Dependencies

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

## Quick Start

### Launch Studio

```bash
hackluminary studio . --base-branch main
```

### Generate deck outputs

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

### Validate quality gates only

```bash
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

```bash
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](https://docs.pypi.org/trusted-publishers/)
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
bash install/install.sh
```

Windows PowerShell:

```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

```bash
python -m pytest
```

## Browser Support

Studio and exported decks target current:
- Chrome
- Edge
- Safari
- Firefox

## License

MIT
