siftcode 0.3.1__tar.gz → 0.4.0__tar.gz

{siftcode-0.3.1 → siftcode-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: siftcode
-Version: 0.3.1
+Version: 0.4.0
 Summary: Local LLM-powered code analysis and developer guide generator
 Author-email: Tuomas Lähteenmäki <lahtis@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -76,7 +76,7 @@ generated in minutes.
 - **Configurable per project**: model, context size, temperature, file
   exclusions, and cache settings are all saved per project
 - **Two front-ends**: a modern GTK4 + libadwaita GUI and a scriptable CLI
-- **Tested**: 305 unit tests, 78 % overall coverage (88–100 % for core modules)
+- **Tested**: 353 unit tests, 79 % overall coverage (88–100 % for core modules)
 
 ---
 
@@ -120,12 +120,20 @@ GPU and the model you choose.
 |---|---|---|---|---|
 | `qwen2.5-coder:7b` | ~5 GB | ~3 min | Basic | Small projects, laptops |
 | **`qwen2.5-coder:14b`** | **~10 GB** | **~7 min** | **Good** | **Recommended default** |
-| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | Workstations, best quality |
+| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | 24 GB+ GPUs, best quality |
+
+**Quick rule of thumb by VRAM:**
+
+- **< 8 GB** → use `7b`, or accept slow CPU-only runs
+- **8–16 GB** → use `14b`; it's the sweet spot for most projects
+- **24 GB+** → use `32b`. It fits comfortably (e.g. Quadro P6000,
+  RTX 3090, RTX 4090) and produces noticeably fewer hallucinations —
+  in particular it stops inventing files like `setup.py` in modern
+  `pyproject.toml` projects.
 
 For CUDA GPUs, ensure your driver is recent enough for your Ollama
 build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
-
 **Observations from real runs:**
 
 - **14B** produces a comprehensive guide in ~7 minutes. It occasionally
@@ -136,38 +144,138 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
   concise and may skip smaller files.
 - **7B** is useful for small projects or when you need a quick pass.
 
-**Tip:** With 32 GB+ RAM and a workstation-class GPU, you can keep
-both 14B and 32B loaded at the same time:
+### Context length
+
+The default `num_ctx` is **8192** tokens, which fits the default 14B
+model on a 10 GB GPU comfortably.
+
+**When to raise it:** The guide generation prompt includes the root
+summary, all directory summaries, and all file summaries. For a
+40-file project, this can be ~23,000 tokens. With `num_ctx=8192`,
+Ollama truncates the context and the model may not see most of the
+files — the guide ends up mentioning only a handful of modules.
+
+If you have the VRAM, raise it per project:
+
+```bash
+siftcode analyze myproject --num-ctx 32768
+```
+
+### Multi-model support
+
+Different analysis stages have different needs. Per-file summaries
+are simple tasks where a small model excels; the root summary and
+the final guide require broader reasoning and benefit from a larger
+model. Siftcode lets you assign a different model to each stage.
+
+Stages: `root`, `file`, `directories`, `guide`.
+
+**With a 24 GB GPU** (Quadro P6000, RTX 3090, RTX 4090), the best
+configuration is:
+
+```bash
+siftcode analyze myproject \
+  --model-stage root=qwen2.5-coder:32b \
+  --model-stage guide=qwen2.5-coder:32b
+```
+
+This takes ~9 minutes instead of ~33 (32B on every file) or
+~7 (14B everywhere), and gives most of the quality benefit: the
+32B model handles the two stages where its broader reasoning
+matters most, while 14B handles the file summaries where speed
+matters more than depth.
+
+Persist the configuration so you don't have to type it every
+time — the stage overrides are saved to the project's TOML file:
+
+```bash
+siftcode analyze myproject --model-stage guide=qwen2.5-coder:32b
+siftcode show myproject
+```
+
+```text
+  Model:
+    Name:        qwen2.5-coder:14b
+    Stages:
+      root         (default)
+      file         (default)
+      directories  (default)
+      guide        qwen2.5-coder:32b
+    Ollama URL:  http://127.0.0.1:11434
+    num_ctx:     8192
+    spec_num_ctx: 16384
+    temperature: 0.0
+    timeout:     600s
+     
+```
+You can also edit the TOML directly:
+```toml
+[model]
+name = "qwen2.5-coder:14b"
+
+[model.stages]
+root  = "qwen2.5-coder:32b"
+guide = "qwen2.5-coder:32b"
+```
+How the cache behaves: the cache is keyed per model, so
+switching a single stage's model does not invalidate the other
+stages' cached results. If you later re-run with the same stage
+models, the previous summaries are reused — you only pay for the
+stages you actually changed.
+
+Shortcut: to use the same model for every stage, use --model:
+```bash
+siftcode analyze myproject --model qwen2.5-coder:32b
+```
+
+**Tip — keeping both models loaded:** If you have enough VRAM to
+hold both 14B and 32B simultaneously (~32 GB VRAM total), you can
+avoid model reloads between stages:
 
 ```bash
 export OLLAMA_MAX_LOADED_MODELS=2
 export OLLAMA_KV_CACHE_TYPE=q8_0
 ```
 
-This lets you use 14B for quick iterations and 32B for the final
-guide without reloading models from disk.
+---
 
-For CUDA GPUs, ensure your driver is recent enough for your Ollama
-build. CPU-only operation works but is slow (expect 5–15× longer runs).
+### Advanced per-file specifications (`--advanced`)
 
-### Recommended context length
+The `--advanced` flag generates a detailed technical specification for
+each source file instead of the usual developer guide. Specs are much
+longer than regular file summaries, so they use a separate context
+length: `spec_num_ctx` (default **16384**).
 
-The default `num_ctx` is 32768 tokens.
+**On a 24 GB GPU**, 32B Q4_K_M plus a 16k KV cache is right at the
+VRAM limit — Ollama offloads ~4% of the model to the CPU, which roughly
+doubles the run time. Lowering the spec context to 12k keeps the whole
+model on the GPU:
 
-**Why:** The guide generation prompt includes the root summary,
-all directory summaries, and all file summaries. For a 40-file
-project, this is roughly 23,000 tokens. With `num_ctx=8192`,
-Ollama truncates the context and the model never sees most of
-the files — the guide ends up mentioning only a handful of
-modules.
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+```
 
-**Verification:** A real-world 40-file Python project required
-23,575 tokens for complete context. With `num_ctx=32768`, the
-generated guide mentions 20+ modules including `analyzer.py`,
-`cache.py`, `cli.py`, and all GUI views.
+Verify with `ollama ps`: the `PROCESSOR` column should read `100% GPU`.
+If it shows any CPU percentage, lower `--spec-num-ctx` further
+(10240, 8192) until the model fits entirely on the GPU.
 
-**VRAM:** With 14B Q4_K_M + `OLLAMA_KV_CACHE_TYPE=q8_0`, VRAM
-usage is ~13 GB. Comfortably within 24 GB.
+`spec_num_ctx` is saved per project, so you only need the flag once:
+
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+siftcode show myproject
+# → spec_num_ctx: 12288
+```
+
+> **Note:** `--advanced` mode with a 32B model is very slow (one
+> document per file, each taking 10+ minutes on a 24 GB GPU). For
+> projects with more than ~10 files, use the default 14B model:
+>
+>     siftcode analyze myproject --advanced
 
 ---
 
@@ -191,8 +299,6 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-
-
 siftcode about
 # → prints version, author, and license
 ```
@@ -248,6 +354,11 @@ siftcode analyze "My Project" --output ~/siftcode-output
 # Analyze it with advanced per-file technical specifications
 siftcode analyze "My Project" --output ~/siftcode-output --advanced
 
+# Advanced + multi-model: 32B for specs, 14B for the rest
+siftcode analyze "My Project" --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+
 # Delete a project
 siftcode delete "My Project"
 ```
@@ -272,7 +383,7 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 ### Output
 
-Analysis produces two files in the output directory:
+Analysis produces these files in the output directory:
 
 - `findings_<project>_<timestamp>.json` — raw structured findings (root, directories, files, errors)
 - `guide_<project>_<timestamp>.md` — the generated developer guide
@@ -308,6 +419,22 @@ human-readable and can be edited by hand if you prefer.
 
 ---
 
+### Default exclusions
+
+The default exclusion list already covers:
+
+- Version control directories (`.git`, `.venv`, `node_modules`)
+- Build artifacts (`build`, `dist`, `.pytest_cache`)
+- Documentation directories (`docs`, `doc`)
+- Binary file suffixes (`.png`, `.jpg`, `.zip`, `.so`)
+- **Database files** (`.sqlite`, `.sqlite3`, `.db`, `.db3`, `.mdb`)
+- Editor configs (`.editorconfig`, `.env`)
+
+You can add or remove patterns per project from the GUI, or by editing
+the `analysis.exclude` list in the project's TOML file.
+
+---
+
 ## How it works
 
 1. **Root analysis** — the LLM sees the project tree and infers the

{siftcode-0.3.1 → siftcode-0.4.0}/README.md

@@ -43,7 +43,7 @@ generated in minutes.
 - **Configurable per project**: model, context size, temperature, file
   exclusions, and cache settings are all saved per project
 - **Two front-ends**: a modern GTK4 + libadwaita GUI and a scriptable CLI
-- **Tested**: 305 unit tests, 78 % overall coverage (88–100 % for core modules)
+- **Tested**: 353 unit tests, 79 % overall coverage (88–100 % for core modules)
 
 ---
 
@@ -87,12 +87,20 @@ GPU and the model you choose.
 |---|---|---|---|---|
 | `qwen2.5-coder:7b` | ~5 GB | ~3 min | Basic | Small projects, laptops |
 | **`qwen2.5-coder:14b`** | **~10 GB** | **~7 min** | **Good** | **Recommended default** |
-| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | Workstations, best quality |
+| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | 24 GB+ GPUs, best quality |
+
+**Quick rule of thumb by VRAM:**
+
+- **< 8 GB** → use `7b`, or accept slow CPU-only runs
+- **8–16 GB** → use `14b`; it's the sweet spot for most projects
+- **24 GB+** → use `32b`. It fits comfortably (e.g. Quadro P6000,
+  RTX 3090, RTX 4090) and produces noticeably fewer hallucinations —
+  in particular it stops inventing files like `setup.py` in modern
+  `pyproject.toml` projects.
 
 For CUDA GPUs, ensure your driver is recent enough for your Ollama
 build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
-
 **Observations from real runs:**
 
 - **14B** produces a comprehensive guide in ~7 minutes. It occasionally
@@ -103,38 +111,138 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
   concise and may skip smaller files.
 - **7B** is useful for small projects or when you need a quick pass.
 
-**Tip:** With 32 GB+ RAM and a workstation-class GPU, you can keep
-both 14B and 32B loaded at the same time:
+### Context length
+
+The default `num_ctx` is **8192** tokens, which fits the default 14B
+model on a 10 GB GPU comfortably.
+
+**When to raise it:** The guide generation prompt includes the root
+summary, all directory summaries, and all file summaries. For a
+40-file project, this can be ~23,000 tokens. With `num_ctx=8192`,
+Ollama truncates the context and the model may not see most of the
+files — the guide ends up mentioning only a handful of modules.
+
+If you have the VRAM, raise it per project:
+
+```bash
+siftcode analyze myproject --num-ctx 32768
+```
+
+### Multi-model support
+
+Different analysis stages have different needs. Per-file summaries
+are simple tasks where a small model excels; the root summary and
+the final guide require broader reasoning and benefit from a larger
+model. Siftcode lets you assign a different model to each stage.
+
+Stages: `root`, `file`, `directories`, `guide`.
+
+**With a 24 GB GPU** (Quadro P6000, RTX 3090, RTX 4090), the best
+configuration is:
+
+```bash
+siftcode analyze myproject \
+  --model-stage root=qwen2.5-coder:32b \
+  --model-stage guide=qwen2.5-coder:32b
+```
+
+This takes ~9 minutes instead of ~33 (32B on every file) or
+~7 (14B everywhere), and gives most of the quality benefit: the
+32B model handles the two stages where its broader reasoning
+matters most, while 14B handles the file summaries where speed
+matters more than depth.
+
+Persist the configuration so you don't have to type it every
+time — the stage overrides are saved to the project's TOML file:
+
+```bash
+siftcode analyze myproject --model-stage guide=qwen2.5-coder:32b
+siftcode show myproject
+```
+
+```text
+  Model:
+    Name:        qwen2.5-coder:14b
+    Stages:
+      root         (default)
+      file         (default)
+      directories  (default)
+      guide        qwen2.5-coder:32b
+    Ollama URL:  http://127.0.0.1:11434
+    num_ctx:     8192
+    spec_num_ctx: 16384
+    temperature: 0.0
+    timeout:     600s
+     
+```
+You can also edit the TOML directly:
+```toml
+[model]
+name = "qwen2.5-coder:14b"
+
+[model.stages]
+root  = "qwen2.5-coder:32b"
+guide = "qwen2.5-coder:32b"
+```
+How the cache behaves: the cache is keyed per model, so
+switching a single stage's model does not invalidate the other
+stages' cached results. If you later re-run with the same stage
+models, the previous summaries are reused — you only pay for the
+stages you actually changed.
+
+Shortcut: to use the same model for every stage, use --model:
+```bash
+siftcode analyze myproject --model qwen2.5-coder:32b
+```
+
+**Tip — keeping both models loaded:** If you have enough VRAM to
+hold both 14B and 32B simultaneously (~32 GB VRAM total), you can
+avoid model reloads between stages:
 
 ```bash
 export OLLAMA_MAX_LOADED_MODELS=2
 export OLLAMA_KV_CACHE_TYPE=q8_0
 ```
 
-This lets you use 14B for quick iterations and 32B for the final
-guide without reloading models from disk.
+---
 
-For CUDA GPUs, ensure your driver is recent enough for your Ollama
-build. CPU-only operation works but is slow (expect 5–15× longer runs).
+### Advanced per-file specifications (`--advanced`)
 
-### Recommended context length
+The `--advanced` flag generates a detailed technical specification for
+each source file instead of the usual developer guide. Specs are much
+longer than regular file summaries, so they use a separate context
+length: `spec_num_ctx` (default **16384**).
 
-The default `num_ctx` is 32768 tokens.
+**On a 24 GB GPU**, 32B Q4_K_M plus a 16k KV cache is right at the
+VRAM limit — Ollama offloads ~4% of the model to the CPU, which roughly
+doubles the run time. Lowering the spec context to 12k keeps the whole
+model on the GPU:
 
-**Why:** The guide generation prompt includes the root summary,
-all directory summaries, and all file summaries. For a 40-file
-project, this is roughly 23,000 tokens. With `num_ctx=8192`,
-Ollama truncates the context and the model never sees most of
-the files — the guide ends up mentioning only a handful of
-modules.
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+```
 
-**Verification:** A real-world 40-file Python project required
-23,575 tokens for complete context. With `num_ctx=32768`, the
-generated guide mentions 20+ modules including `analyzer.py`,
-`cache.py`, `cli.py`, and all GUI views.
+Verify with `ollama ps`: the `PROCESSOR` column should read `100% GPU`.
+If it shows any CPU percentage, lower `--spec-num-ctx` further
+(10240, 8192) until the model fits entirely on the GPU.
 
-**VRAM:** With 14B Q4_K_M + `OLLAMA_KV_CACHE_TYPE=q8_0`, VRAM
-usage is ~13 GB. Comfortably within 24 GB.
+`spec_num_ctx` is saved per project, so you only need the flag once:
+
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+siftcode show myproject
+# → spec_num_ctx: 12288
+```
+
+> **Note:** `--advanced` mode with a 32B model is very slow (one
+> document per file, each taking 10+ minutes on a 24 GB GPU). For
+> projects with more than ~10 files, use the default 14B model:
+>
+>     siftcode analyze myproject --advanced
 
 ---
 
@@ -158,8 +266,6 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-
-
 siftcode about
 # → prints version, author, and license
 ```
@@ -215,6 +321,11 @@ siftcode analyze "My Project" --output ~/siftcode-output
 # Analyze it with advanced per-file technical specifications
 siftcode analyze "My Project" --output ~/siftcode-output --advanced
 
+# Advanced + multi-model: 32B for specs, 14B for the rest
+siftcode analyze "My Project" --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+
 # Delete a project
 siftcode delete "My Project"
 ```
@@ -239,7 +350,7 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 ### Output
 
-Analysis produces two files in the output directory:
+Analysis produces these files in the output directory:
 
 - `findings_<project>_<timestamp>.json` — raw structured findings (root, directories, files, errors)
 - `guide_<project>_<timestamp>.md` — the generated developer guide
@@ -275,6 +386,22 @@ human-readable and can be edited by hand if you prefer.
 
 ---
 
+### Default exclusions
+
+The default exclusion list already covers:
+
+- Version control directories (`.git`, `.venv`, `node_modules`)
+- Build artifacts (`build`, `dist`, `.pytest_cache`)
+- Documentation directories (`docs`, `doc`)
+- Binary file suffixes (`.png`, `.jpg`, `.zip`, `.so`)
+- **Database files** (`.sqlite`, `.sqlite3`, `.db`, `.db3`, `.mdb`)
+- Editor configs (`.editorconfig`, `.env`)
+
+You can add or remove patterns per project from the GUI, or by editing
+the `analysis.exclude` list in the project's TOML file.
+
+---
+
 ## How it works
 
 1. **Root analysis** — the LLM sees the project tree and infers the

{siftcode-0.3.1 → siftcode-0.4.0}/src/siftcode/_version.py

@@ -38,9 +38,9 @@ __all__ = [
 ]
 
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 __version_info__ = tuple(int(p) for p in __version__.split(".") if p.isdigit())
-__release_date__ = "2026-10-21"
+__release_date__ = "2026-11-12"
 __status__ = "beta"
 
 APP_ID = "io.codeberg.lahtis.Siftcode"