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.
