note-tagger/README.md

# Note Tagging & SEO Automation

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

The script requires 4 frontmatter fields named as such:
- tags
- seo-title
- seo-description
- seo-keywords

## Setup

1. **Install dependencies:**
   ```bash
   pip install pyyaml requests
   ```
2. **Make sure LM Studio is running** on `http://192.168.68.84:1234` with the `openai/gpt-oss-20b` 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 automatically process all markdown files in the 'NOTES_FOLDER'.

## What it does

The script will:
- ✓ Add tags (1-5) using your taxonomy + 1-2 new suggestions
- ✓ Add SEO title (clean, non-clickbaity)
- ✓ Add SEO description (150-160 chars, factual)
- ✓ Add SEO keywords (generous, 10-15 keywords)
- ✓ **Only updates empty fields** - preserves existing values
- ✓ Updates files directly (no confirmation needed)
- ✓ **Only touches**: `tags`, `seo-title`, `seo-description`, `seo-keywords`
- ✓ **Preserves everything else** in your frontmatter

## Managing the taxonomy

Edit `tag-taxonomy.yaml` to add new tags that the LLM suggests and you like.

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