Metadata-Version: 2.4
Name: vaultwright
Version: 0.1.0
Summary: Command line tools for working with an Obsidian vault, including local-LLM note refining.
Keywords: obsidian,markdown,notes,ollama,cli
Author: Rebanta Gupta
Author-email: Rebanta Gupta <guptarebanta816@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: ollama>=0.6.2
Requires-Dist: pydantic>=2.0
Requires-Dist: python-frontmatter>=1.3.0
Requires-Python: >=3.11
Project-URL: Repository, https://github.com/Rebanta-Gupta/vaultwright
Project-URL: Issues, https://github.com/Rebanta-Gupta/vaultwright/issues
Description-Content-Type: text/markdown

# vaultwright

Command line tools for working with an [Obsidian](https://obsidian.md) vault, including
`kiln` — a note refiner that runs entirely on a local [Ollama](https://ollama.com) model.
Nothing leaves your machine, and your original notes are never modified.

**Alpha.** It works and it's careful, but the commands may change.

## Requirements

- Python 3.11 or newer
- [Ollama](https://ollama.com) with a model pulled, for `vw kiln` only:
  `ollama pull qwen3:8b`. The other commands need no model.

## Install

```bash
pip install vaultwright      # or: uv tool install vaultwright
```

From a clone, for development:

```bash
uv sync
```

## Usage

```bash
vw vaults                        # list the vaults it can see
vw scan Job_Box                  # by name, if your config points at a vaults folder
vw scan path/to/vault            # or by path
vw scan path/to/vault -s Lectures  # just one folder
vw scan path/to/vault -d 2         # limit tree depth
vw check path/to/vault           # verify notes survive protect/restore
vw kiln Lectures/w1.md           # refine one note (dry run)
vw kiln Lectures/w1.md --write   # save it (refused if the model changed a figure)
vw kiln Lectures/w1.md -m gemma3:4b   # override the model for one run

vw config                        # show settings in use
vw config set default_vault Job_Box
vw config set kiln.model gemma3:4b
```

`vaultwright` and `vw` are the same command.

## Configuration

Optional. Settings are read from the first of these that exists:

1. `--config <path>`
2. `vaultwright.toml` in the current folder
3. `~/.config/vaultwright/config.toml`

```toml
# Either one vault, or the folder that holds them all.
vault = "C:/Users/you/Obsidian/Vaults"
default_vault = "MyVault"     # which one to use when none is named

[scan]
ignore = ["Cold Emails", "Templates"]

[kiln]
model = "qwen3:8b"
output = "refined"
layout = "sibling"    # refined/ beside the note; "mirror" puts it at the vault root
temperature = 0.3
summary = true        # add a ## Summary section
tags = true           # merge topic tags into the note's frontmatter
flashcards = true     # add a ## Flashcards section
```

`vw config set <key> <value>` edits one line and leaves your comments alone.
Settable: `vault`, `default_vault`, `kiln.model`, `kiln.output`, `kiln.layout`,
`kiln.temperature`, `kiln.summary`, `kiln.tags`, `kiln.flashcards`.

With `vault` set, the path argument becomes optional: `vw scan -s Lectures`. If it points
at a folder of vaults, name one (`vw scan Job_Box`) or set `default_vault`.
`vw config` prints the settings in use and where they came from.

## How kiln protects your notes

Before the model sees a note, everything Markdown and Obsidian treat as machinery is swapped
for an opaque placeholder: code fences, inline code, display and inline maths, `[[wikilinks]]`,
`![[embeds]]`, link targets, `%%` and `<!-- -->` comments, and horizontal rules. The model only
ever edits prose. Afterwards:

- a dropped or invented placeholder **rejects the note** — nothing is written
- **figures are compared** between original and refined. If a number changed, `--write` is
  refused unless you pass `--allow-number-changes`
- your **indentation characters are restored**, so a three-line fix stays a three-line diff
- anything the model adds is put in a `> [!ai]` callout **by the tool**, not by the model
- notes under 30 words get typo fixes only — no summary, no flashcards
- your original file is never touched

`vw check` runs the protect/restore round trip over a whole vault and writes nothing, so you
can confirm the guarantee holds on your own notes before refining anything.

## Planned

- Batch mode — refine a folder, with a cache so reruns only touch changed notes
- Retrieval, so gap-filling draws on your other notes instead of the model's own knowledge

## A note on model output

`kiln` output is generated by a language model. It is checked — protected content must come
back intact, figures must not change, and anything the model adds is marked in a
`> [!ai]` callout — but **read the diff before you keep it.** Refined notes go to a separate
folder precisely so you can compare.

## License

MIT
