Metadata-Version: 2.4
Name: forge-me-notes
Version: 0.1.1
Summary: Build and maintain Obsidian knowledge bases with LLM assistance
Author: OpenMash contributors
License: MIT
Project-URL: Homepage, https://codeberg.org/DenvaDude/forge-me-notes
Project-URL: Repository, https://codeberg.org/DenvaDude/forge-me-notes
Project-URL: Issues, https://codeberg.org/DenvaDude/forge-me-notes/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: anthropic>=0.25.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: ollama
Requires-Dist: requests>=2.31.0; extra == "ollama"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# forge-me-notes

> 🇩🇪 [Deutsche Version](README.de.md)

**fmn** is a command-line tool for building and maintaining structured [Obsidian](https://obsidian.md) vaults with LLM assistance.

Use it for anything you want to develop as structured, connected knowledge: business planning, research, civic data projects, hobby projects, home renovation. You describe what you want in plain English — fmn handles the context, the LLM call, and the note writing.

> *The LLM doesn't write the knowledge. It writes the YAML. The knowledge comes from you.*

Works with any consistently structured Obsidian vault. The [OpenMash vault](https://codeberg.org/DenvaDude/openmash) is one example — a civic open data toolkit built with fmn.

---

## How it works

```
Your vault → fmn pack → context snapshot
context snapshot + your request → fmn generate → input/notes.yaml
review input/notes.yaml → fmn write → new notes in your vault
```

Or all at once:

```bash
fmn run "Add 3 use cases for air quality monitoring" --provider anthropic
```

The LLM never writes directly to your vault. `fmn generate` produces an intermediate `input/notes.yaml` that you review before `fmn write` touches anything.

---

## Who is this for?

- **Anyone** who maintains a structured Obsidian vault and wants LLM help expanding it
- **Civic technologists and researchers** building open data knowledge bases
- **NGOs and community groups** mapping datasets, user groups, or use cases
- **Developers** who want a scriptable vault generation pipeline

You do not need to be a programmer. If you can run a terminal command, you can use fmn.

---

## Installation

```bash
pipx install forge-me-notes
```

> No `pipx`? Run `pip install pipx && pipx ensurepath` first, or see [pipx.pypa.io](https://pipx.pypa.io).
> Alternatively: `pip install forge-me-notes`

Set your vault path:

```bash
export VAULT_PATH=/path/to/your/vault
# or pass it per command:
fmn --vault /path/to/your/vault pack
```

---

## Quick start

```bash
fmn pack                                                          # snapshot your vault
fmn generate "Add 3 notes about Nordic city cycling policy"      # LLM → input/notes.yaml
fmn write                                                         # review passed → write notes

# Or all at once:
fmn run "Add 3 notes about Nordic city cycling policy" --provider anthropic

# Check vault health:
fmn audit
```

---

## Commands

| Command | What it does |
|--------|--------------|
| `fmn pack` | Scans your vault → exports context snapshot to `context/` |
| `fmn write` | Reads `input/notes.yaml` → writes notes into the vault |
| `fmn generate "request"` | Context + request → LLM → produces `input/notes.yaml` |
| `fmn run "request"` | Pack + generate + confirm + write in one step |
| `fmn audit` | Checks vault health: broken links, orphans, missing properties |

---

## LLM providers

No API key? Use `--provider manual` — fmn prints the full prompt and you paste it into any chat interface yourself.

| Provider | Flag | Requires |
|----------|------|----------|
| Anthropic (Claude) | `--provider anthropic` | `ANTHROPIC_API_KEY` |
| OpenAI (GPT-4o) | `--provider openai` | `OPENAI_API_KEY` |
| Ollama (local) | `--provider ollama` | [Ollama](https://ollama.com) running locally — free |
| Manual (any chat UI) | `--provider manual` | Nothing |

---

## Command reference

### `fmn pack`
```bash
fmn pack           # snapshot index + metadata
fmn pack --notes   # also include full note bodies
```

### `fmn generate "request"`
```bash
fmn generate "Add a user group note for Roma communities" --provider ollama --model mistral
fmn generate "Add 3 inspiration notes about Nordic cities" --provider manual
```

### `fmn write`
```bash
fmn write           # write notes from input/notes.yaml
fmn write --force   # overwrite existing notes
```

### `fmn run "request"`
```bash
fmn run "Update all use cases to reference my new Vienna datasets" --force
```

### `fmn audit`
```bash
fmn audit             # summary (capped at 5 per category)
fmn audit --verbose   # show all issues
fmn audit --fix       # auto-repair broken links with near-matches
fmn audit --report    # save report as a timestamped vault note
fmn audit --trend     # show audit history from .fmn/history.yaml
```

---

## Project structure

```
forge-me-notes/
├── fmn/
│   ├── cli.py        # entry point
│   ├── pack.py       # vault scanner
│   ├── generate.py   # LLM interface
│   ├── write.py      # note writer
│   ├── audit.py      # vault health checker
│   └── run.py        # orchestrator
├── input/notes.yaml  # generated note specs — review before fmn write
├── context/all.md    # vault context snapshot
├── prompts/system_prompt.md
└── tests/
```

---

## Example vault: OpenMash

[OpenMash](https://codeberg.org/DenvaDude/openmash) is a civic open data toolkit built with fmn — a structured Obsidian vault for mapping datasets, user groups, barriers, and use cases for any city. It ships with a Karlsruhe example and a full workshop facilitation kit.

```bash
git clone https://codeberg.org/DenvaDude/openmash
cd openmash/openmash-vault
export VAULT_PATH=$(pwd)
fmn audit
fmn run "Add 3 use cases for cycling infrastructure" --provider anthropic
```

---

## Contributing

See [CONTRIBUTING.md](https://codeberg.org/DenvaDude/forge-me-notes/src/branch/main/CONTRIBUTING.md). See [DECISIONS.md](https://codeberg.org/DenvaDude/forge-me-notes/src/branch/main/DECISIONS.md) for the reasoning behind key design choices.

---

## Changelog

See [CHANGELOG.md](https://codeberg.org/DenvaDude/forge-me-notes/src/branch/main/CHANGELOG.md).

---

## License

MIT © 2026 OpenMash contributors
