Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (44 loc) · 2.65 KB

AGENTS.md

File metadata and controls

62 lines (44 loc) · 2.65 KB
Raw

kh_Assistant

This file captures non-obvious, repo-specific facts. It is not a tutorial.

Agent Behavior (Mentor Mode)

  • Never write code first. Explain logic, UX impact, and architectural approach in plain text before touching files.
  • Present a conceptual plan and wait for human approval before editing anything.
  • When presenting multiple approaches or design choices, explicitly list the advantages and disadvantages of each option so the user can make an informed decision.
  • Define complex terms inline the first time you introduce them.
  • Write clean, readable code expecting to explain every choice line-by-line.

Stack

  • PyQt6 GUI, single-window. No menu bars, trays, or sub-windows.
  • llama-cpp-python for local CPU inference via GGUF models.
  • model_downloader.py — downloads GGUFs from Hugging Face (huggingface_hub) or arbitrary URLs.
  • Vosk offline STT via voice_worker.py (QThread + PyAudio).
  • No test/lint/typecheck frameworks (pytest, ruff, mypy).
  • Only use packages from requirements.txt.

Running

  • python main.py — ./models/ directory auto-scanned for .gguf files.
  • python tst.py — headless inference check.
  • Linux and Windows desktop only.

Threading — Do Not Refactor

  • ai_manager.py: GGUF load/inference via llama-cpp-python in background threads.
  • model_downloader.py: I/O with huggingface_hub/requests + progress callbacks.
  • voice_worker.py: extends QThread.
  • Everything else: threading.Thread(daemon=True) — GIL serializes Qt calls, leave as-is.
  • Llama() init is blocking (1-3s). Always run off-main-thread with a loading indicator.

Model Logic

  • Models = *.gguf files in ./models/.
  • Quantization parsed from filename (convention: ModelName-Quant.gguf).
  • set_model() skips validation. If GGUF not loaded, query_ai() loads it.
  • Display: "{name} ({quant}, {size_gb} GB)".

Suggestion System

  • RAM detected via psutil.virtual_memory().total (with platform fallback).
  • model_budget = total_ram - max(1.5, total_ram * 0.2).
  • Priority among fitting GGUFs: Llama 3.2 → Phi-3 → Qwen 2.5 → TinyLlama → Mistral → smallest.
  • Prefer highest quantization fitting within budget.
  • UI shows budget, best-fit, and warns on over-budget selection.

UX (Non-Technical Audience)

  • Empty state: No GGUFs in ./models/ → plain-language message ("No brain files found") + "Download Models" button or copy-paste HF link.
  • Timeouts: generation=120s, download=600s.
  • Audio: ALSA_LOG_LEVEL=0 in voice_worker.py.

Git Notes

  • Vosk model binary (~15MB) was committed then removed. Do not re-add.
  • 5 commits, conventional short messages.