forge-me-notes 0.1.0__tar.gz

forge_me_notes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenMash contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forge_me_notes-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: forge-me-notes
+Version: 0.1.0
+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](CONTRIBUTING.md). See [DECISIONS.md](DECISIONS.md) for the reasoning behind key design choices.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT © 2026 OpenMash contributors

forge_me_notes-0.1.0/README.md

@@ -0,0 +1,187 @@
+# 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](CONTRIBUTING.md). See [DECISIONS.md](DECISIONS.md) for the reasoning behind key design choices.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT © 2026 OpenMash contributors

forge_me_notes-0.1.0/fmn/__init__.py

@@ -0,0 +1,2 @@
+"""forge-me-notes — fmn package"""
+__version__ = "0.1.0"