note-tagger/README.md

# Note Tagging & SEO Automation

Automatically tag your Obsidian notes, add slugs, and add SEO metadata using a local LLM.

The script requires these frontmatter fields:
- title (used as the basis for the SEO title)
- tags
- seo-title
- seo-description
- seo-keywords
- slug

**Note:** The script sends only the first 20,000 characters of the note to the LLM. This should be more than sufficient for most notes, however if you have extremely long notes then you can increase this by editing the `CONTENT_CHAR_LIMIT` constant in `tag-notes.py`.

## Setup

1. **Install dependencies:**
   ```bash
   pip install pyyaml ruamel.yaml requests
   ```
2. **Make sure LM Studio is running** on  with the preferred model loaded
3. **Place these files in a directory:**
   - `tag-notes.py` (the main script)
   - `tag-taxonomy.yaml` (your tag taxonomy)
4. **Adjust Variables in 'tag-notes.py'**
   - Edit the 'NOTES_FOLDER' variable to change the folder it searches
   - Edit the 'MODEL_NAME' variable to change the LLM model
   - Edit the 'LM_STUDIO_URL' variable to change URL of the LLM API
5. **Adjust preset tags**
   - Edit the `tag-taxonomy.yaml` file to change what tags you want it to use.

## Usage

Simply run the script:
```bash
./tag-notes.py
```

It will recursively process all markdown files under `NOTES_FOLDER`.

## What it does

The script will:
- ✓ Add tags (1-5) using your taxonomy + 1-2 new suggestions
- ✓ Add SEO title in the format `{title}: {short descriptor}`, built from the note's `title:` frontmatter field
- ✓ Add SEO description (strictly 150-160 chars, factual — re-asks the LLM once if the first response is out of range)
- ✓ Add SEO keywords (generous, 10-15 keywords)
- ✓ Add slug derived from the filename (lowercased, punctuation stripped, spaces/hyphens collapsed)
- ✓ **Only updates empty fields** - preserves existing values
- ✓ Updates files directly (no confirmation needed)
- ✓ **Preserves existing frontmatter formatting** via round-trip YAML

At the end of a run, if the LLM proposed any genuinely new tags, the script lists them and prompts you to append them to `tag-taxonomy.yaml` automatically.

## Managing the taxonomy

At the end of each run, the script will prompt you to add any newly suggested tags to `tag-taxonomy.yaml` automatically. You can also edit the file by hand at any time.

The LLM will:
- Prefer existing taxonomy tags
- Suggest 1-2 new tags if the content warrants it
- Be conservative with new tag suggestions

## Example output

```
Processing: /path/to/note.md
  + Added tags: self-hosting, linux, docker
    (New suggestions: containers)
  + Added SEO title: Setting Up a Self-Hosted Development Environment
  + Added SEO description
  + Added 12 SEO keywords
  ✓ Updated successfully
```

## Troubleshooting

**LLM connection errors:**
- Check that LM Studio is running: `curl http://localhost:1234/v1/models`
- Verify the model is loaded in LM Studio

**No frontmatter found:**
- The note needs YAML frontmatter between `---` delimiters

**Fields already populated:**
- Script skips notes where all four fields are already filled
- To re-process a note, clear the specific fields you want regenerated