concept-maker/README.md

# Concept Maker GUI

A desktop tool to turn raw ideas, notes, and files into a clear, actionable project concept. Drag in files, jot notes, build a compact knowledge base, and generate an editable Markdown concept using a local Ollama model.

## Features
- Drag and drop files/folders into a table (falls back to add buttons).
- Freeform notes area for thoughts and fragments.
- Builds a JSONL knowledge base from your files (uses `corpus_builder.py` when present; includes a simple fallback).
- Generates a polished Concept (Markdown) via a local Ollama model.
- Edit the result in‑app, then save it into a local Git repo and optionally push to a remote.
- Remembers sessions; re‑open and continue later.
- Uses `icon.png` for the window/taskbar/dock icon.

## Requirements
- Python 3.9+
- Ollama running locally (default `http://localhost:11434`)
  - Suggested default model: `mistral3.2-small:24b` (configurable in the UI)
- OS packages as needed for Tk:
  - macOS: included with the official Python.org installer
  - Ubuntu/Debian: `sudo apt-get install python3-tk`
  - Windows: included with the official Python.org installer

Optional Python packages improve file ingestion:
- `tkinterdnd2` (native drag & drop)
- `pymupdf` (PDF text extraction)
- `beautifulsoup4` (better HTML text extraction)

Note: `requirements.txt` also lists some optional extras and system tools. If installation fails on entries that are not Python packages (e.g., system binaries), install them via your OS package manager or comment those lines out.

## Quick Start
- With the convenience script:
  - `bash run.sh`
- Manual steps:
  - `python3 -m venv .venv`
  - `source .venv/bin/activate` (Windows: `.\\.venv\\Scripts\\activate`)
  - `python -m pip install --upgrade pip`
  - `pip install -r requirements.txt`
  - `python concept-maker_gui.py`

Ensure Ollama is running before generating concepts:
- Install: https://ollama.com
- Pull a model: `ollama pull mistral3.2-small:24b`
- Start service (if not auto-started): `ollama serve`

## Usage
- Add files/folders via drag & drop or the Add buttons.
- Write or paste notes in the Notes panel.
- Choose the Ollama model (or keep your default).
- Click to generate the Concept; edit as needed.
- Save: the app can save to a local repo and push to a remote.

## Configuration
Environment variables (optional):
- `OLLAMA_HOST`: override Ollama URL (default `http://localhost:11434`).
- `IDEA_HOLE_MODEL`: default model name shown in the UI.
- `IDEA_HOLE_REMOTE`: default Git remote URL.

## Data & Storage
- Working data lives under `./.idea-hole/`:
  - `files/`: symlinks/copies of added files
  - `corpus.jsonl`: unified knowledge base
  - `sessions.jsonl`: saved sessions metadata

## Platform Notes
- macOS dock icon: if you install PyObjC (`pip install pyobjc`), the app also sets the dock icon from `icon.png`.
- Drag & drop requires `tkinterdnd2`; otherwise, the app uses the add buttons.
- PDF extraction works best with `pymupdf` installed.

## Troubleshooting
- Tk import errors on Linux: install `python3-tk` via your package manager.
- Ollama connection errors: ensure `ollama serve` is running and the model is pulled.
- Pip fails on non-Python entries in `requirements.txt`: install those tools via your OS, or comment out the offending lines and rerun the install.

## Development
- Code entry point: `concept-maker_gui.py`
- Launcher script: `run.sh`
- Optional corpus builder: `corpus_builder.py` (if present) is invoked for richer ingestion; otherwise, a simple built‑in fallback is used.