time2 2.5.0__py3-none-any.whl

time2-2.5.0.data/data/share/time2/docs/DEVELOPER_GUIDE.md

@@ -0,0 +1,738 @@
+# Developer Guide For time-2.0.5
+
+This guide explains how the code is organized, how data moves through the app,
+and where to begin when building the next version.
+
+It is intentionally written for a future developer who may not remember the
+conversation that created this app.
+
+## Design Goals
+
+time-2.0.5 is built around these priorities:
+
+- Local-first data ownership.
+- Simple Python code that can be run from JupyterLab.
+- Dataclasses and JSON instead of a database for this version.
+- Clear history instead of disappearing tasks.
+- Attention-friendly workflows: visible progress, reschedule reasons, mind states,
+  spontaneous work, reserved backlog tasks, audio capture, transcripts, and
+  AI-ready summaries.
+- Optional heavy dependencies: Whisper and llama-cpp are loaded only when used.
+- Optional LLM provider choice: local llama.cpp or an OpenAI-compatible API.
+
+## Runtime Shape
+
+```mermaid
+flowchart TD
+    User["User in browser/Jupyter iframe"] --> Streamlit["Streamlit app"]
+    Streamlit --> App["time2_app/app.py"]
+    App --> Views["time2_app/views.py"]
+    Views --> Models["time2_app/models.py"]
+    Views --> Storage["time2_app/storage.py"]
+    Views --> Budget["time2_app/budget.py"]
+    Views --> AI["time2_app/ai.py"]
+    Views --> Whisper["time2_app/transcription.py"]
+    Views --> Tailscale["time2_app/tailscale_utils.py"]
+    Storage --> JSON["Local JSON files"]
+    Budget --> BudgetJSON["Monthly budget JSON files"]
+    AI --> Cache["AI cache JSON files"]
+    Whisper --> Audio["Local audio files"]
+```
+
+## Source File Explanation
+
+### `time2_streamlit_app.py`
+
+Tiny entrypoint used by Streamlit and JupyterLab.
+
+It imports `run_app()` from `time2_app.app` and calls it. Keep this file small
+so the launch command remains stable:
+
+```bash
+python -m streamlit run time2_streamlit_app.py
+```
+
+### `time2_app/streamlit_entry.py`
+
+Installed-package Streamlit entrypoint.
+
+The `time2` CLI points Streamlit at this file after the package is installed
+from a wheel. Keep it tiny; it should only import and call `run_app()`.
+
+### `time2_app/cli.py`
+
+Command-line interface exposed as:
+
+```bash
+time2
+```
+
+Responsibilities:
+
+- `time2 run`: start the Streamlit app from an installed package.
+- `time2 doctor`: check required and optional Python imports.
+- `time2 install-optionals`: ask before installing Whisper/LLM extras.
+- `time2 tailscale`: install/check/login/serve helpers for Tailscale.
+
+The CLI should never install optional packages or system software without an
+explicit yes/no confirmation.
+
+### `pyproject.toml` and `MANIFEST.in`
+
+Package metadata and source distribution rules.
+
+Important packaging details:
+
+- `project.scripts` defines the `time2` command.
+- Optional extras are `whisper`, `llm`, and `all`.
+- Streamlit component HTML is included as wheel data under `share/time2/`.
+- `MANIFEST.in` keeps docs, examples, launchers, and component HTML in source
+  distributions.
+
+### `time2_jupyter_launcher.py`
+
+Portable launcher for JupyterLab.
+
+Responsibilities:
+
+- Find the app folder.
+- Start Streamlit in a subprocess.
+- Use port `8503`.
+- Open the app in a browser.
+- Display it in a Jupyter iframe.
+
+This file should not contain a developer-specific absolute path.
+
+### `time2_jupyter_launcher.ipynb`
+
+Notebook wrapper around the launcher. It exists because `%run` can hit
+permission/path issues in some JupyterLab setups. The notebook is the friendlier
+launch surface.
+
+### `time2_tailscale_jupyter_launcher.py`
+
+JupyterLab-only private-access launcher.
+
+Responsibilities:
+
+- Start or restart the local Streamlit process.
+- Find the Tailscale CLI in common macOS/Jupyter locations.
+- Run `tailscale serve --bg http://127.0.0.1:8503`.
+- Print the private tailnet HTTPS URL/status.
+- Display the local app in a Jupyter iframe.
+
+This file assumes Tailscale is already installed and signed in on the home
+laptop.
+
+### `time2_tailscale_jupyter_launcher.ipynb`
+
+Notebook wrapper for the Tailscale launcher.
+
+It has cells for:
+
+- Starting the app and Tailscale Serve.
+- Showing Tailscale Serve status again.
+- Resetting Tailscale Serve and stopping the Streamlit subprocess.
+
+### `time2_ai_cache_worker.py`
+
+Optional background script.
+
+Responsibilities:
+
+- Load the same settings/data as the app.
+- Refresh deterministic AI cache files.
+- Optionally refresh LLM cache files.
+- Run once or loop at an interval.
+
+This is separate from Streamlit because Streamlit reruns are not a true
+scheduler.
+
+## Package Modules
+
+### `time2_app/config.py`
+
+Independent constants and defaults.
+
+Contains:
+
+- `APP_TITLE`
+- `DATA_FILE`
+- `SETTINGS_FILE`
+- `DEFAULT_SETTINGS`
+- `OPTION_FIELDS`
+
+Add new setting defaults here first. Then normalize them in `utils.py`.
+
+### `time2_app/utils.py`
+
+General helper layer.
+
+Contains:
+
+- ID generation.
+- Current timestamps.
+- Date/time parsing and formatting.
+- Deadline/urgency math.
+- Energy labels.
+- Settings load/save.
+- Settings normalization.
+- Theme CSS.
+- Project and daily routine normalization.
+- Option helpers for Streamlit selectboxes.
+
+Keep this module free of Streamlit tab workflows. Small UI-independent helpers
+belong here.
+
+### `time2_app/models.py`
+
+Core app meaning.
+
+Defines:
+
+- `Time2Comment`
+- `Time2MindLog`
+- `Time2AudioLog`
+- `Time2Session`
+- `Time2Reschedule`
+- `Time2Item`
+- `Time2Board`
+
+Important model behavior:
+
+- `Time2Item.start_session()`
+- `Time2Item.stop_session()`
+- `Time2Item.mark_done()`
+- `Time2Item.undo_done()`
+- `Time2Item.cancel()`
+- `Time2Item.reschedule()`
+- `Time2Item.sync_matrix_scores()`
+- `Time2Board.stats()`
+- `Time2Board.load()`
+- `Time2Board.save()`
+
+When adding fields, update:
+
+1. Dataclass field.
+2. `from_dict()` for backward compatibility.
+3. Any table/rendering code in `views.py`.
+4. Example data/settings if needed.
+
+Reserved tasks use `Time2Item.reserved`. They are intentional unscheduled
+backlog items. `sync_matrix_scores()` clears reserved mode once a planned date
+or deadline exists, so the task returns to the normal color scheme.
+
+### `time2_app/storage.py`
+
+Disk and folder behavior.
+
+Contains:
+
+- Path resolution.
+- Data folder handling.
+- First-run folder creation.
+- Main board JSON read/write support.
+- Per-task file saving.
+- Per-mind-log file saving.
+- Audio file saving.
+- Backup writing.
+
+Important functions:
+
+- `data_storage_folder(settings)`
+- `data_file_path(settings)`
+- `task_storage_folder(settings)`
+- `mind_storage_folder(settings)`
+- `audio_storage_folder(settings)`
+- `backup_storage_folder(settings)`
+- `ensure_data_folder_structure(settings)`
+- `store_audio_upload(...)`
+- `write_backup(...)`
+
+Relative paths resolve from the app working directory. Absolute paths are used
+directly.
+
+### `time2_app/budget.py`
+
+Budget data layer.
+
+Defines:
+
+- `BudgetEntry`
+- `DEFAULT_BUDGET_CATEGORIES`
+- `BUDGET_KINDS`
+- `BUDGET_CLASSES`
+
+Responsibilities:
+
+- Normalize budget categories.
+- Decide budget month from a custom month-end day.
+- Read/write monthly budget files.
+- Add budget entries.
+- Build budget reports.
+
+Budget files live under:
+
+```text
+time2_budget/budget_YYYY_MM.json
+```
+
+Budget entries can contain:
+
+- Item.
+- Amount.
+- Category.
+- Kind: income, expense, savings.
+- Date.
+- Bank/account.
+- Note.
+- Audio log metadata.
+- Transcript status/text.
+
+### `time2_app/ai.py`
+
+AI and deterministic analytics layer.
+
+Responsibilities:
+
+- Build daily/range reports.
+- Calculate period scores.
+- Calculate data availability.
+- Build attention flags.
+- Build next-action candidates.
+- Create compact prompts for local or API LLM calls.
+- Load and call `llama-cpp-python` only when requested.
+- Call OpenAI-compatible `/chat/completions` APIs through the standard library.
+- Write/read AI cache files.
+
+This module should not edit tasks. It should read data and produce analysis.
+
+### `time2_app/transcription.py`
+
+Optional Whisper integration.
+
+Responsibilities:
+
+- Keep supported language mapping.
+- Load Whisper lazily.
+- Transcribe a stored audio file.
+
+The lazy import matters. The app should still run when `openai-whisper` is not
+installed.
+
+Supported UI languages:
+
+- Auto detect
+- English
+- German
+- Spanish
+- Bengali
+- Hindi
+
+`Auto detect` should remain the default. When it is selected,
+`transcribe_audio_file()` should call Whisper without a forced `language`
+keyword and then store Whisper's detected language code/name.
+
+### `time2_app/tailscale_utils.py`
+
+Optional Tailscale integration shared by the CLI and Settings screen.
+
+Responsibilities:
+
+- Detect the local `tailscale` command.
+- Report download links and package-manager install commands.
+- Ask callers to decide before install/sign-in/share actions.
+- Start `tailscale up` for sign-in.
+- Start `tailscale serve` for private tailnet access.
+- Parse private `https://...ts.net` URLs from Serve status output.
+
+This module should not import Streamlit. It should stay usable from both the
+CLI and the app UI.
+
+### `time2_app/components.py`
+
+Registers custom Streamlit components.
+
+Components:
+
+- `time2_matrix_component`
+- `time2_e2_component`
+- `time2_task_list_component`
+
+In a source checkout, browser-side component files live beside the Python
+package:
+
+```text
+time2_matrix_component/index.html
+time2_e2_component/index.html
+time2_task_list_component/index.html
+```
+
+In an installed wheel, `pyproject.toml` installs those files under
+`share/time2/`, and `components.py` checks both locations.
+
+### `time2_app/views.py`
+
+Most Streamlit UI code lives here.
+
+Responsibilities:
+
+- First-run setup screen.
+- AI Insights tab UI.
+- Planning tab.
+- Deadlines tab.
+- Matrix tab.
+- E2 Plot tab.
+- Mind Log tab.
+- Budget tab.
+- Settings tab.
+- Task list rendering.
+- Universal task editor.
+- Audio upload/record/transcribe controls.
+- Transcript display.
+- Folder/file pickers.
+
+Important functions:
+
+- `save_board(board, settings=None, force_backup=False)`
+- `render_first_run_setup(settings)`
+- `render_planning_tab(board, settings)`
+- `render_deadlines_tab(board, settings)`
+- `render_eisenhower_tab(board, settings)`
+- `render_e2_plot_tab(board, settings)`
+- `render_mind_log_tab(board, settings)`
+- `render_budget_tab(settings)`
+- `render_settings_tab(settings, board)`
+- `show_item_controls(board, item, settings, key_prefix="item", show_signal=False)`
+- `save_audio_upload_log(...)`
+- `transcribe_existing_audio_log(...)`
+
+The universal task editor is especially important. Anything added to
+`show_item_controls()` appears wherever a task is editable:
+
+- Planning
+- Pending
+- Victory Board
+- Cancelled
+- Deadlines
+- Matrix
+- E2 Plot
+
+### `time2_app/app.py`
+
+Top-level app composition.
+
+Responsibilities:
+
+- Set page config.
+- Load settings.
+- Apply theme.
+- Show first-run setup if settings do not exist.
+- Load board.
+- Show top metrics.
+- Create the 16 tabs.
+- Call view functions.
+- Handle the Data tab import/restore workflow.
+
+Add new tabs here, but implement the tab body in `views.py`.
+
+The time-2.0.5 tabs added after AI Insights are:
+
+- `AI Chat`: saved local/API conversations over selected data context.
+- `Reports`: PDF/HTML/TXT/JSON exports for tasks, ranges, dashboard, mind logs,
+  budgets, chats, and raw snapshots.
+
+## Data Flow
+
+### Task Creation
+
+1. User creates task in `Add`.
+2. `app.py` collects form values.
+3. `Time2Item` is created.
+4. Optional task audio is saved through `save_audio_upload_log()`.
+5. `Time2Board.add()` adds the task.
+6. `save_board()` writes:
+   - Main board JSON.
+   - Per-task files.
+   - Per-mind-log files.
+   - Backup if due.
+
+### Task Editing
+
+1. User clicks a task card.
+2. Custom task-list component sends selected ID.
+3. `show_item_controls()` renders the universal editor.
+4. User edits sessions, reschedules, deadlines, comments, details, audio, or status.
+5. `save_board()` persists changes.
+
+### Audio And Transcript
+
+1. User uploads or records audio.
+2. `store_audio_upload()` writes the file to `time2_audio/`.
+3. A `Time2AudioLog` is created.
+4. If `Transcribe` is on, `transcribe_audio_file()` runs Whisper.
+5. Transcript status/text are stored on the audio log.
+6. For mind logs and budget entries, transcript text is copied into the entry
+   for easier direct display.
+
+### Budget Entry
+
+1. User opens `Budget`.
+2. Date determines budget year/month using `budget_period_for_date()`.
+3. User adds income, expense, or savings.
+4. Optional audio/transcript is saved.
+5. `BudgetEntry` is written into the monthly JSON file.
+6. `budget_report()` recalculates totals and category rows.
+
+### AI Insights
+
+1. User selects today, single day, or range.
+2. `build_period_report()` gathers task, session, mind-log, project, audio, and
+   reschedule evidence.
+3. `score_period()` uses Settings-backed score weights and thresholds.
+4. `build_ai_insight_modules()` adds the deterministic attention support detectors.
+5. Deterministic scores/flags/modules are shown.
+6. Optional local or API LLM receives the compact report.
+7. AI cache can save common deterministic reports. LLM cache is local-model only
+   in time-2.0.5.
+
+## Storage Files
+
+### Main board JSON
+
+```text
+time2_data.json
+```
+
+Contains:
+
+- `items`
+- `mind_logs`
+- `audio_logs`
+
+### Task files
+
+```text
+time2_tasks/
+  index.json
+  item_xxxxxxxx.json
+```
+
+Used when per-task file storage is enabled.
+
+### Mind log files
+
+```text
+time2_mind_logs/
+  index.json
+  mind_xxxxxxxx.json
+```
+
+Used when per-mind-log file storage is enabled.
+
+### Audio files
+
+```text
+time2_audio/
+  audio_xxxxxxxx_original_name.wav
+```
+
+The main JSON stores metadata and transcript text.
+
+### Budget files
+
+```text
+time2_budget/
+  budget_2026_07.json
+```
+
+Each month file stores budget entries for that budget period.
+
+### Backups
+
+```text
+time2_backups/
+  time2_backup_YYYYMMDD_HHMMSS.json
+```
+
+Backup payload:
+
+- `created_at`
+- `board`
+- `settings`
+
+### AI cache
+
+```text
+time2_ai_cache/
+```
+
+Stores deterministic and optional LLM report payloads.
+
+## Settings Flow
+
+When adding settings:
+
+1. Add default in `DEFAULT_SETTINGS` in `config.py`.
+2. Normalize in `load_settings()` in `utils.py`.
+3. Add controls in `render_settings_tab()` or a helper in `views.py`.
+4. Update `examples/time2_settings.example.json`.
+5. Update docs.
+
+## Compatibility Rules
+
+The app should continue to open old JSON files.
+
+When adding fields:
+
+- Always use `.get()` with defaults in `from_dict()`.
+- Do not assume old data has new keys.
+- Do not delete unknown runtime data.
+- Prefer adding fields rather than reshaping existing fields.
+
+## Testing Checklist
+
+Run this after code changes:
+
+```bash
+python -m py_compile time2_streamlit_app.py time2_jupyter_launcher.py time2_tailscale_jupyter_launcher.py time2_ai_cache_worker.py time2_app/*.py tests/time2_regression_checks.py
+python tests/time2_regression_checks.py
+```
+
+Run a Streamlit AppTest smoke test:
+
+```bash
+python -c "from streamlit.testing.v1 import AppTest; at=AppTest.from_file('time2_streamlit_app.py', default_timeout=30); at.run(timeout=30); print([tab.label for tab in at.tabs]); print('exceptions', len(at.exception)); [print(e.value) for e in at.exception]"
+```
+
+Expected full tab list:
+
+```text
+Add
+Planning
+Deadlines
+Matrix
+E2 Plot
+Mind Log
+Pending
+Victory Board
+Cancelled
+Dashboard
+Budget
+AI Insights
+AI Chat
+Reports
+Settings
+Data
+```
+
+Recommended extra checks:
+
+- Fresh unzip with no `time2_settings.json` shows First-time setup.
+- Seeded settings opens all tabs.
+- `time2 doctor` runs after editable install.
+- `time2 run --open-browser` starts the app from the installed package entry.
+- Reserved task can be added without planned date/deadline and turns non-reserved
+  when a planned date or deadline is saved.
+- Task with attached audio opens in E2 without nested expander error.
+- Task transcript is visible.
+- Task comment audio transcript is visible under the same task.
+- Mind transcript is visible.
+- Budget transcript is visible.
+- AI Chat works with local provider settings and API provider settings.
+- Settings private-access section detects Tailscale or shows the install link.
+- Zip contains no `__pycache__` or `.pyc`.
+- Zip contains no private local paths.
+
+## Packaging Checklist
+
+For pip package publishing, see `docs/PACKAGING.md`.
+
+Build package artifacts:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Then install the wheel in a clean environment and verify:
+
+```bash
+python -m pip install dist/time2_local-2.0.5-py3-none-any.whl
+time2 doctor
+time2 run --open-browser
+```
+
+Do not include runtime/private data in any release zip, wheel, source
+distribution, or repository upload.
+
+## Next Version Starting Points
+
+### Local accounts
+
+Files to touch:
+
+- `models.py`: add user model or owner fields.
+- `storage.py`: save/load user auth data.
+- `views.py`: login/settings UI.
+- `app.py`: gate the app after settings load.
+
+Use password hashing such as Argon2id or bcrypt.
+
+### SQLite migration
+
+Files to add/touch:
+
+- New `database.py`.
+- `models.py` for conversion helpers.
+- `storage.py` for import/export compatibility.
+- `views.py` Data tab for migration controls.
+
+Keep JSON export/import.
+
+### Transcript search
+
+Files to touch:
+
+- `models.py`: ensure transcript fields are indexed in summaries.
+- `views.py`: add search UI in Dashboard or new Search tab.
+- `ai.py`: include transcript snippets in evidence payloads.
+
+### Budget editing
+
+Files to touch:
+
+- `budget.py`: update/delete entry helpers.
+- `views.py`: add edit controls inside Budget tab.
+- Docs/manual.
+
+### Calendar integration
+
+Files to add/touch:
+
+- New `calendar_export.py`.
+- `views.py`: export/import controls.
+- `models.py`: stable event/task mapping.
+
+## Known Design Tradeoffs
+
+- JSON storage is easy to inspect but not ideal for simultaneous multi-user
+  editing.
+- Whisper runs synchronously in the app, so long audio can block the UI.
+- Local LLM generation can be slow on laptops.
+- Streamlit is excellent for fast local tools but not a full multi-user web app
+  framework without extra care.
+- The app has no login yet. Tailscale is the current private access layer.
+
+## Commenting Policy
+
+The source code uses:
+
+- Module-level dependency notes.
+- Clear function names.
+- Focused comments before non-obvious blocks.
+
+It intentionally does not comment every single line. Line-by-line comments make
+the code harder to maintain. This guide is the detailed explanation layer for
+future development.