time2 2.5.0__py3-none-any.whl

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

@@ -0,0 +1,188 @@
+# AI Insights
+
+time-2.0.5 adds an optional `AI Insights` tab.
+
+The AI layer is intentionally separate from the main task model:
+
+- It reads task and mind-log data.
+- It computes deterministic scores first.
+- It can send a compact selected-date/range summary to a local
+  `llama-cpp-python` model or an OpenAI-compatible API endpoint.
+- It does not edit tasks automatically.
+- The app still runs if `llama-cpp-python` is not installed.
+
+## Optional Install
+
+Install the base app first:
+
+```bash
+pip install -r requirements.txt
+```
+
+Install local LLM support only on the laptop that will run the model:
+
+```bash
+pip install -r requirements-llm.txt
+```
+
+Put the model at the default path or change the path in the `AI Insights` tab:
+
+```text
+./Models/Qwen2.5-7B-Instruct-Q4_K_M.gguf
+```
+
+If you prefer an API provider, no extra Python package is needed. Configure:
+
+```text
+Settings -> LLM defaults -> OpenAI-compatible API
+```
+
+Use a base URL such as `http://127.0.0.1:8000/v1`, a model name, optional API
+key, and timeout. API mode sends the selected task, mind-state, audio,
+transcript, and budget context to that endpoint, so use a trusted local or
+private server for personal data.
+
+## Current AI Functions
+
+- Daily or date-range summary.
+- Period support score.
+- Data availability score.
+- Score breakdown plot.
+- Attention flags.
+- Tiny next-action candidates.
+- Momentum score from worked minutes.
+- Completion score from done/left/cancelled work.
+- Mindfulness/data check-in score from mind logs.
+- Stability score from reschedules.
+- Data availability plot.
+- attention support detectors for time blindness, forgotten tasks, energy budget,
+  reschedule reasons, morning launch, evening shutdown, data honesty, routine
+  adherence, deadline heat, victory evidence, context switching, and recovery.
+- Local or API LLM review using your selected provider.
+- Downloadable AI insight markdown.
+- Cached deterministic reports for today, last 7 days, and last 30 days.
+- Optional cached LLM reports.
+- Project counts in the AI report payload.
+- Audio-log evidence in the AI report payload.
+
+## Score And Detector Settings
+
+Open:
+
+```text
+Settings -> AI score and detector settings
+```
+
+You can tune:
+
+- Support-score weights for data capture, momentum, completion, mind logs, and
+  stability.
+- Momentum target minutes per day.
+- Reschedule penalty.
+- Low-data threshold.
+- Edit contact minutes, which adds a small closed session when a task is edited
+  outside an already-running session.
+- Forgotten-task deadline window.
+- High energy-cost and recovery-energy thresholds.
+- Context-switching thresholds.
+- Morning available minutes.
+- Routine matching window.
+
+These settings affect the `AI Insights` tab, cached reports, exported period
+reports, and the `daily_scores` context sent to AI Chat.
+
+## Provider And Model Settings
+
+In `Settings -> LLM defaults` or `AI Insights -> LLM settings`, choose the
+provider. For local mode, use `Choose file` to select the `.gguf` model file.
+The model path is a file path, not just a folder path.
+
+## AI Cache
+
+The cache stores ready-made reports in the configured AI cache folder. By
+default, the cache folder is inside the main data folder:
+
+```text
+time2_ai_cache
+```
+
+The app refreshes cached reports when the `AI Insights` tab is opened and the
+refresh interval has passed. This keeps the common windows ready:
+
+- Today.
+- Last 7 days.
+- Last 30 days.
+
+Deterministic reports are fast and safe to keep enabled. LLM cache is optional
+because the local model can take a while to run. In time-2.0.5, scheduled LLM
+cache uses local llama.cpp only; manual AI Insights and AI Chat can use either
+local or API mode.
+
+## Optional Background Worker
+
+For true regular refreshes while the laptop is on, run:
+
+```bash
+python time2_ai_cache_worker.py
+```
+
+Run once and exit:
+
+```bash
+python time2_ai_cache_worker.py --once --no-llm
+```
+
+Run one forced LLM cache refresh:
+
+```bash
+python time2_ai_cache_worker.py --once --force --include-llm
+```
+
+The worker reads the same settings as the app and writes into the same AI cache
+folder.
+
+## Implemented Detector Modules
+
+- Time-blindness detector: flags days where plans existed but no session,
+  comment, or mind log was recorded.
+- Forgotten-task radar: surfaces active tasks with no session/comment evidence
+  and an approaching deadline.
+- Energy budget: compares high energy-cost touched tasks with active recovery
+  candidates.
+- Reschedule reason clustering: groups planned/deadline movement reasons.
+- Morning launch plan: suggests a 3-item plan from urgency, importance, energy,
+  and available time.
+- Evening shutdown review: summarizes the latest day in the range and picks a
+  safe next bookmark.
+- Data honesty score: shows whether each day has enough evidence to interpret.
+- Routine adherence: compares enabled daily routines against session/mind-log
+  evidence.
+- Deadline heat forecast: highlights active deadlines whose urgency is high
+  relative to worked minutes.
+- Victory evidence: turns completed tasks and sessions into confidence lines.
+- Context-switching meter: estimates fragmentation from short sessions and area
+  switching.
+- Recovery recommendation: suggests lower-friction follow-up work after heavy
+  energy-cost periods.
+
+## Local Model Notes
+
+The app uses the same basic pattern as your starter code:
+
+```python
+from llama_cpp import Llama
+
+llm = Llama(
+    model_path="./Models/Qwen2.5-7B-Instruct-Q4_K_M.gguf",
+    n_ctx=32768,
+    verbose=False,
+    logits_all=False,
+)
+
+response = llm.create_chat_completion(
+    messages=[{"role": "user", "content": "Hello World"}]
+)
+```
+
+The app wraps this in `time2_app/ai.py` and caches the loaded model so it does
+not reload on every Streamlit rerun.

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

@@ -0,0 +1,222 @@
+# Code Walkthrough
+
+This file gives a compact walkthrough of the source layers. For a fuller
+developer handoff, use `docs/DEVELOPER_GUIDE.md`.
+
+## Entry Point
+
+`time2_streamlit_app.py` imports `run_app()` from `time2_app.app` and calls it.
+Keep this file small so JupyterLab always has one stable file to run.
+
+When installed as a package, the `time2` command runs
+`time2_app/streamlit_entry.py`. That module also imports and calls `run_app()`,
+but it lives inside the package so Streamlit can find it after wheel
+installation.
+
+`time2_app/cli.py` provides:
+
+- `time2 run`
+- `time2 doctor`
+- `time2 install-optionals`
+- `time2 tailscale`
+
+## App Composition
+
+`time2_app/app.py` does the page-level work:
+
+- Sets Streamlit page config.
+- Loads settings.
+- Applies theme CSS.
+- Loads the board.
+- Shows top metrics.
+- Creates the tabs.
+- Calls the view functions.
+- Handles Data tab import/restore.
+- Handles Add-tab flexible planned-time windows.
+- Places AI Chat and Reports/PDF as separate tabs.
+
+## Data Model
+
+`time2_app/models.py` is the center of the app's meaning.
+
+- `Time2Item` is one task or event.
+- `Time2Session` is one focused work session.
+- `Time2Reschedule` records movement of planned time or deadline.
+- `Time2Comment` records notes, blockers, reflections, and reasons.
+- `Time2MindLog` records a mind state without requiring a task.
+- `Time2AudioLog` records uploaded or browser-recorded meeting/audio file
+  metadata and optional Whisper transcript metadata.
+- `Time2Board` owns all items, mind logs, and audio log metadata.
+
+The model is where methods like `mark_done()`, `cancel()`, `start_session()`,
+`stop_session()`, `reschedule()`, and `stats()` belong.
+
+## Storage
+
+`time2_app/storage.py` owns disk behavior.
+
+It writes:
+
+- Main board JSON.
+- One-file-per-task JSON files.
+- One-file-per-mind-log JSON files.
+- Uploaded and browser-recorded meeting/audio files.
+- Backup JSON files.
+- AI chat JSON files.
+- Exported PDF/HTML/TXT/JSON report files.
+- The `time2_budget/` folder is created here, while month-file logic lives in
+  `budget.py`.
+
+It also resolves user-selected folders from Settings. Relative folders are
+resolved from the app working directory; absolute folders are used as entered.
+The main board path comes from `data_file_path(settings)`, which points to
+`time2_data.json` inside the selected main data folder.
+
+## Views
+
+`time2_app/views.py` owns Streamlit screens and interactions.
+
+It contains reusable render functions for:
+
+- Task lists and editable task cards.
+- Task-level audio upload, microphone recording, transcript display, and
+  transcribe-now controls.
+- Planning filters.
+- Eisenhower matrix.
+- E2 plot.
+- Mind logs.
+- Budget tab and budget settings.
+- Browser audio recording controls.
+- Audio transcription settings.
+- Pending/done/cancelled boards.
+- Dashboard search and sorting.
+- AI Chat data selection, saved-chat UI, and local LLM parameter controls.
+- Reports/PDF export controls.
+- Private-access/Tailscale status controls.
+- Settings forms.
+
+## AI
+
+`time2_app/ai.py` owns optional AI analytics.
+
+It computes deterministic reports before any model call:
+
+- Daily rows.
+- Data availability.
+- Period scores.
+- Status, area, mind-state, session, and reschedule counts.
+
+When the user clicks `Generate AI insight`, the view sends that compact report
+to `run_llm_report()`. Local mode loads `llama-cpp-python` lazily; API mode calls
+an OpenAI-compatible `/chat/completions` endpoint with the configured base URL,
+model, optional key, and timeout.
+
+`refresh_ai_cache()` writes cached reports for today, last 7 days, and last 30
+days. The Streamlit tab can refresh this cache when opened. For true regular
+refreshes, `time2_ai_cache_worker.py` can run as a separate process.
+
+## AI Chat
+
+`time2_app/chat.py` owns saved chat files and selected prompt context.
+
+It can include:
+
+- Tasks.
+- Sessions.
+- Comments.
+- Mind logs.
+- Audio transcripts.
+- Budget entries.
+- Daily score summaries.
+
+The module builds a compact JSON context and sends it to the selected local/API
+chat runner. The chat is read-only in time-2.0.5.
+
+## Reports
+
+`time2_app/reports.py` owns report text, HTML, JSON, and dependency-free PDF
+generation. It supports task reports, period reports, dashboard/all-task
+reports, mind-state reports, budget reports, AI chat reports, and full raw
+snapshots.
+
+## Budget
+
+`time2_app/budget.py` owns budget data that should not be mixed into task
+history.
+
+It provides:
+
+- `BudgetEntry`
+- Category normalization
+- Custom month-end period calculation
+- Monthly JSON load/save helpers
+- Budget reports with income, expense, savings, surplus, class summaries, and
+  overspending flags
+
+Budget files are written under the selected data folder:
+
+```text
+time2_budget/budget_YYYY_MM.json
+```
+
+## Transcription
+
+`time2_app/transcription.py` owns optional Whisper support.
+
+The module imports `whisper` lazily inside `load_whisper_model()`, so the app
+can start even when `openai-whisper` is not installed. Views call
+`save_audio_upload_log()` for both uploaded files and microphone recordings,
+optionally run Whisper, and store a transcript status.
+
+`Auto detect` is the default transcription mode. In that mode,
+`transcribe_audio_file()` does not pass a forced language to Whisper; it stores
+the detected language code/name from Whisper's result when available.
+
+## Components
+
+`time2_app/components.py` registers custom browser components. Their HTML/JS
+lives in separate folders so the Python side can stay clean.
+
+The component folders are:
+
+- `time2_matrix_component/`
+- `time2_e2_component/`
+- `time2_task_list_component/`
+
+In installed wheels these folders are packaged under `share/time2/`.
+`components.py` checks both the source checkout location and the installed data
+location.
+
+## Private Access
+
+`time2_app/tailscale_utils.py` owns optional Tailscale command detection and
+execution. The CLI and Settings screen both use it.
+
+It can:
+
+- find the `tailscale` command;
+- show install links/commands;
+- start `tailscale up` for sign-in;
+- start `tailscale serve`;
+- parse private Serve URLs from status output.
+
+It does not silently install or expose anything. The caller must be responding
+to a user command or button press.
+
+## Settings and Theme
+
+`time2_app/config.py` defines default settings.
+
+`time2_app/utils.py` loads settings, validates custom option lists, parses
+dates/times, normalizes projects, creates IDs, and builds the CSS theme.
+
+## Import and Restore
+
+The Data tab calls `import_uploaded_json()` from `time2_app/app.py`.
+
+That function accepts:
+
+- A raw board JSON containing `items`.
+- A backup JSON containing `board` and optionally `settings`.
+
+After import, the app saves the board and writes a backup.