siftcode 0.3.0__py3-none-any.whl

siftcode-0.3.0.dist-info/METADATA

@@ -0,0 +1,413 @@
+Metadata-Version: 2.4
+Name: siftcode
+Version: 0.3.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
+Project-URL: Homepage, https://codeberg.org/lahtis/siftcode
+Project-URL: Repository, https://codeberg.org/lahtis/siftcode
+Project-URL: Issues, https://codeberg.org/lahtis/siftcode/issues
+Project-URL: Changelog, https://codeberg.org/lahtis/siftcode/src/branch/main/CHANGELOG.md
+Keywords: llm,ollama,documentation,code-analysis,gtk
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: PyGObject>=3.46
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.7; extra == "dev"
+Dynamic: license-file
+
+# Siftcode
+
+> Local LLM-powered code analysis and developer guide generator.
+
+**Siftcode** analyzes software projects using a locally-running language
+model (via [Ollama](https://ollama.com)) and produces:
+
+- **Per-file summaries** — what each file does, its functions, and how it fits
+- **Per-directory summaries** — how files work together
+- **A comprehensive Markdown developer guide** — architecture, setup, API reference, and examples
+
+Everything runs on your own hardware. **No code leaves your machine.**
+
+---
+
+## Why Siftcode?
+
+Reading an unfamiliar codebase is slow. Documentation is often outdated
+or missing entirely. Existing AI tools send your code to a cloud service,
+which is a non-starter for proprietary or sensitive projects.
+
+Siftcode combines three things that no other tool offers together:
+
+1. **100 % local** — your code never leaves your machine
+2. **Project-wide context** — each file is analyzed with the project's
+   structure and sibling files already in view
+3. **A cache** — re-analysis skips files that haven't changed, making
+   iterative work fast
+
+The result is a well-organized developer guide you can actually use,
+generated in minutes.
+
+---
+
+## Features
+
+- **Local-first**: runs entirely on your hardware via [Ollama](https://ollama.com)
+- **Cache-aware**: unchanged files are never re-analyzed — second runs
+  are up to 10× faster
+- **Project-wide context**: file analyses see the root summary and
+  sibling files, producing coherent guides
+- **Progress feedback**: a live progress bar and log during analysis
+- **Cancellable**: stop an analysis mid-run without losing your work
+- **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**: 200+ unit tests, ~95 % coverage in the core
+
+---
+
+## Screenshots
+
+### Project list
+
+![Project list](https://codeberg.org/lahtis/siftcode/raw/branch/main/docs/screenshots/projects.png)
+
+### Settings
+
+![Settings](https://codeberg.org/lahtis/siftcode/raw/branch/main/docs/screenshots/settings.png)
+
+### Analysis in progress
+
+![Analysis](https://codeberg.org/lahtis/siftcode/raw/branch/main/docs/screenshots/analyzing.png)
+
+### Generated developer guide
+
+![Guide](https://codeberg.org/lahtis/siftcode/raw/branch/main/docs/screenshots/guide.png)
+---
+
+## Requirements
+
+- **Linux** (X11 or Wayland)
+- **Python 3.11** or newer
+- **GTK 4.10+** and **libadwaita 1.4+**
+- **[Ollama](https://ollama.com)** running locally
+- A code-capable LLM installed via Ollama, for example:
+
+  ```bash
+  ollama pull qwen2.5-coder:14b
+  ```
+
+### Hardware
+
+Siftcode runs on modest hardware, but quality and speed depend on your
+GPU and the model you choose.
+
+| Model | VRAM (Q4) | ~42-file run | Quality | Best for |
+|---|---|---|---|---|
+| `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 |
+
+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
+  mentions files that don't exist (e.g. `setup.py` in a modern
+  `pyproject.toml` project). These are easy to spot and correct.
+- **32B** is ~4.5× slower but produces a more accurate guide — notably
+  it no longer invents `setup.py`. However, its output is more
+  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:
+
+```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).
+
+### Recommended context length
+
+The default `num_ctx` has been increased from 8192 to 32768
+tokens.
+
+**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.
+
+**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.
+
+**VRAM:** With 14B Q4_K_M + `OLLAMA_KV_CACHE_TYPE=q8_0`, VRAM
+usage is ~13 GB. Comfortably within 24 GB.
+
+---
+
+## Installation
+
+### From source (recommended for now)
+
+```bash
+git clone https://codeberg.org/lahtis/siftcode.git
+cd siftcode
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Verify installation
+
+```bash
+siftcode --version
+# → siftcode 0.3.0
+
+siftcode about
+# → prints version, author, and license
+```
+
+### System dependencies (Ubuntu / Debian)
+
+```bash
+sudo apt install \
+    python3-dev python3-gi python3-gi-cairo \
+    gir1.2-gtk-4.0 libadwaita-1-0 gir1.2-adw-1 \
+    libgirepository1.0-dev libcairo2-dev pkg-config
+```
+
+### System dependencies (Fedora)
+
+```bash
+sudo dnf install \
+    python3-devel python3-gobject gtk4 libadwaita \
+    gobject-introspection-devel cairo-devel pkg-config
+```
+
+---
+
+## Usage
+
+### GUI
+
+```bash
+siftcode-gui
+```
+
+1. Click the **+** button to add a project directory.
+2. Double-click the project to open its settings.
+3. Adjust the model, context size, and exclusions if needed.
+4. Click **Analyze** to start.
+5. When finished, click **Open guide** to view the generated Markdown.
+
+### CLI
+
+```bash
+# Register a project under a friendly name
+siftcode add /path/to/project --name "My Project"
+
+# List saved projects
+siftcode list
+
+# Show a project's configuration
+siftcode show "My Project"
+
+# Analyze it (standard run)
+siftcode analyze "My Project" --output ~/siftcode-output
+
+# Analyze it with advanced per-file technical specifications
+siftcode analyze "My Project" --output ~/siftcode-output --advanced
+
+# Delete a project
+siftcode delete "My Project"
+```
+
+The CLI also works without registering:
+
+```bash
+siftcode analyze /path/to/project --output ./docs
+```
+
+```bash
+siftcode analyze /path/to/project --output ./docs --advanced
+```
+### Cache management
+
+```bash
+siftcode cache stats                # show entry counts and sizes
+siftcode cache clear                # remove everything
+siftcode cache clear --model qwen2.5-coder:14b
+siftcode cache gc --days 30         # prune entries unused for 30 days
+```
+
+### Output
+
+Analysis produces two files in the output directory:
+
+- `findings.json` — raw structured findings (root, directories, files, errors)
+- `guide.md` — the generated developer guide
+- `docs/specs/` — advanced per-file technical specifications (when `--advanced` is used)
+
+---
+
+## Configuration
+
+Siftcode stores project configurations in the standard XDG config
+directory:
+
+```
+~/.config/siftcode/projects/<slug>.toml
+```
+
+Each project's TOML file records:
+
+- Project name, path, and notes
+- Model name, Ollama URL, context size, temperature, timeout
+- File exclusion patterns
+- Cache settings
+- Last run timestamp
+
+Cache data lives in:
+
+```
+~/.cache/siftcode/
+```
+
+The GUI exposes all of these settings; the TOML file is
+human-readable and can be edited by hand if you prefer.
+
+---
+
+## How it works
+
+1. **Root analysis** — the LLM sees the project tree and infers the
+   main language(s), purpose, and architecture.
+2. **File analysis** — each file is analyzed with the root summary and
+   the summaries of sibling files already in view.
+3. **Directory summaries** — the LLM summarizes each directory based
+   on the file summaries it contains.
+4. **Guide generation** — all of the above is composed into a
+   structured Markdown developer guide.
+5. **Advanced specs (optional)** — when `--advanced` is used, individual
+   per-file technical specifications are generated and stored in `docs/specs/`.
+
+Each step is cached by SHA-256 hash of the input. When you re-run on an
+unchanged project, only the guide is regenerated.
+
+---
+
+## Development
+
+```bash
+# Clone and install with dev dependencies
+git clone https://codeberg.org/lahtis/siftcode.git
+cd siftcode
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run the test suite
+pytest --cov=siftcode --cov-report=term-missing
+
+# Lint
+ruff check src/ tests/
+
+# Type-check
+mypy src/
+```
+
+### Project layout
+
+```
+siftcode/
+├── src/siftcode/
+│   ├── _version.py       # single source of truth for metadata
+│   ├── cli.py            # command-line interface
+│   ├── core/             # framework-agnostic logic
+│   │   ├── analyzer.py   # analysis engine
+│   │   ├── cache.py      # hash-based cache
+│   │   ├── config.py     # project configuration
+│   │   ├── llm.py        # Ollama client
+│   │   ├── prompts.py    # prompt templates
+│   │   └── manual.py     # Advanced Technical Analysis & Specification Generator
+│   └── gui/              # GTK4 front-end
+│       ├── app.py
+│       ├── window.py
+│       ├── project_list.py
+│       ├── settings_view.py
+│       ├── analyzer_view.py
+│       └── widgets/
+├── tests/                # unit tests
+└── pyproject.toml
+```
+
+The `core/` package has **no GTK dependencies** and is usable from any
+Python program.
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
+guidelines on:
+
+- Reporting bugs
+- Suggesting features
+- Submitting pull requests
+- Coding style and testing
+
+For translations, open an issue on Codeberg — the string table is not
+yet extracted, but that will come.
+
+---
+
+## License
+
+Siftcode is free software: you can redistribute it and/or modify it
+under the terms of the **GNU General Public License** as published by
+the Free Software Foundation, either version 3 of the License, or (at
+your option) any later version.
+
+See [LICENSE](LICENSE) for the full text.
+
+Copyright © 2026 Tuomas Lähteenmäki
+
+---
+
+## Acknowledgements
+
+Siftcode stands on the shoulders of excellent open-source projects:
+
+- [GTK 4](https://gtk.org) and [libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/) — the GUI toolkit
+- [Ollama](https://ollama.com) — local LLM runtime
+- [Qwen2.5-Coder](https://huggingface.co/Qwen/Qwen2.5-Coder-32B) — the recommended model
+- [platformdirs](https://github.com/platformdirs/platformdirs) — XDG directory handling
+- [tomli-w](https://github.com/hukkin/tomli-w) — TOML writing
+
+Thank you to the maintainers of these projects.

siftcode-0.3.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+siftcode/__init__.py,sha256=inZRLbKr2Hvh1sVCuzI3V0tIiVuOmnW_8UD-PScMaLk,75
+siftcode/__main__.py,sha256=Y4sl9JXs-nTkFB-8hpLVaHANuLaJMPEAzVzAoSFeJKc,173
+siftcode/_version.py,sha256=zM_ctEoYRqbPN5xDrCPEPjy7lPj3dA_wDprTCXzC9_k,1918
+siftcode/cli.py,sha256=MgcqdyWQB_EHIqnLj0iyo2JYFVLXwFh8tQP6lI36aQs,17170
+siftcode/core/__init__.py,sha256=qKN43TBs4HvA-QrY6zBrlvMcOnzRfVQmKeROCUAOX6o,52
+siftcode/core/analyzer.py,sha256=s60t2MmS3qqqPlgBC1O_n_x83-2HlpbQdlPlHyHF_CM,20712
+siftcode/core/cache.py,sha256=7VBY8ZTECgDkYOGgnwyGMNLwCUwwOMPY8XDtNcoqdyU,9780
+siftcode/core/config.py,sha256=X8lIS_pAy9nvLYHh4twpHjstcThYa4zcuANi1CtgR6I,8313
+siftcode/core/llm.py,sha256=IY3OMdllEhpVWh36RdAEBkGM2g_BjmFngwHuG0f04Gw,9632
+siftcode/core/manual.py,sha256=jIwYmHU3OJRswBAx6xarI0BIU3AQ3f7HCNFSPi027cU,7889
+siftcode/core/prompts.py,sha256=wy1KEoA9gD9nvslKzLTDU989dz6H4dF3WA-DuVMFuHM,7068
+siftcode/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+siftcode/data/siftcode-logo.png,sha256=uCkXCVWO1KHxDI6P8BOmPRYc7qWuKKz6sVzFaDKJKt4,398215
+siftcode/gui/__init__.py,sha256=Us6Q4ey0PeHjnoXzH-CWfQ16goi1ep4XKpdgQbFpiKM,271
+siftcode/gui/analyzer_view.py,sha256=a993QWXVPjq8hLMRxH7PvKeOPzxEgITYqgHCw_J69Dw,21198
+siftcode/gui/app.py,sha256=Rm5hU5r1QrJK5ry_7yUK8u1nqZ3yF2fuTKBYsmqcODU,7290
+siftcode/gui/guide_window.py,sha256=6SGMj5jjUDYAQwjb8c7oGEN-pL9onooj_S4CnMmnkEc,2689
+siftcode/gui/project_list.py,sha256=rswzN_xZdzij-C0cIy0GS9AYNrfqS9lXyqMRDGbsMAo,5222
+siftcode/gui/settings_view.py,sha256=Zqkyi7lOu_SAVtJvJo_Vqdvpc9_JLSS9yz7K1KAJ2Tg,15828
+siftcode/gui/window.py,sha256=hVVGMyjDSNabfHGc7Qj2d_PFRZfmVTNI9PUXNgO41r8,15202
+siftcode/gui/widgets/__init__.py,sha256=H_ttgUQfiRQRl_3y65K5sthEYSK_cycnRJ0jpcZA7ks,41
+siftcode/gui/widgets/exclusion_list.py,sha256=i0wb0mXOuFOXbo2D-tbE7oQxT9ilpE8fpa7cC-s7Dlk,5799
+siftcode/gui/widgets/log_view.py,sha256=h72YVJL8Z6_jCM0KW_s5e68OIGKe9oycIxo5L9aMN8Y,3646
+siftcode/gui/widgets/markdown_view.py,sha256=g1EWCb9ylbdEMKso31sHNL26qcbJmwo_Y6jj1X3n_14,6965
+siftcode/gui/widgets/project_row.py,sha256=agZ1huT-UvsrJQjotm8D0ax93j-PIZniSvvR5cjO1Hc,4724
+siftcode-0.3.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+siftcode-0.3.0.dist-info/METADATA,sha256=ObytxF_kc1sORerCthd7skJ-MampGWoZdi4tpNPB-8s,12306
+siftcode-0.3.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+siftcode-0.3.0.dist-info/entry_points.txt,sha256=d1JirDrfmZ92Bdh2SmmvfiZiidfj-OlQwBClRFopFsI,104
+siftcode-0.3.0.dist-info/top_level.txt,sha256=vu-_jUd_mpqNGL621YYXUQJLY7MVDFBr_lJ9qZmVJxQ,9
+siftcode-0.3.0.dist-info/RECORD,,

siftcode-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

siftcode-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+siftcode = siftcode.__main__:main
+
+[gui_scripts]
+siftcode-gui = siftcode.gui.app:main