Sam Rolfe
63ed336dfa
Add docs/outline/00-index.md plus system overview, config/env, code map, and agent runbook in Simplified Technical English. Link the set from the README. Completes the project-docs Outline layer.
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# obsidian-sorter — Code Structure Map
|
|
|
|
> **Target**: AI Agents — ASD-STE100 Simplified Technical English.
|
|
|
|
## Dependencies
|
|
|
|
The sorter uses the Python standard library only. It requires Python 3.10 or
|
|
later. It uses no PyYAML, no HTTP library, and no JEV SDK. Deploy with `rsync`.
|
|
Hosts need no pip.
|
|
|
|
## Layout
|
|
|
|
| Path | Purpose |
|
|
| :--- | :--- |
|
|
| `sorter/__main__.py` | Module entry point. Calls `cli.main`. |
|
|
| `sorter/cli.py` | Argument parser and all commands. |
|
|
| `sorter/models.py` | Data types. Folder-to-type map. `Note`, `Proposal`. |
|
|
| `sorter/vault.py` | Vault scanning and index introspection. |
|
|
| `sorter/frontmatter.py` | Minimal YAML frontmatter reader and writer. |
|
|
| `sorter/classify.py` | Tier 1 deterministic classifier. |
|
|
| `sorter/jev.py` | TypeSafe JEV client. Cost tracking. |
|
|
| `sorter/tier2.py` | Tier 2 semantic classifier. Hybrid logic. |
|
|
| `sorter/writer.py` | Plans, frontmatter merge, TOC insert, apply. |
|
|
| `sorter/watch.py` | Inbox watcher. Maintains proposals. |
|
|
| `tests/run_tests.py` | Test suite. Runs against an isolated vault copy. |
|
|
| `tools/normalize_tags.py` | One-off tag cleanup tool. |
|
|
| `docs/` | Diagrams, handoff notes, and this Outline set. |
|
|
|
|
## Entry Points
|
|
|
|
1. **Command wrapper**: `~/bin/obsidian-sort`. It changes to `~/obsidian-sorter`,
|
|
then runs `python3 -m sorter` with the vault and inbox set.
|
|
2. **Module**: `python3 -m sorter --vault <path> --inbox <name> <command>`.
|
|
3. **Systemd unit**: `ExecStart=~/bin/obsidian-sort watch --interval 10`.
|
|
|
|
## Commands
|
|
|
|
Read-only commands:
|
|
|
|
| Command | Purpose |
|
|
| :--- | :--- |
|
|
| `scan` | Report vault shape. |
|
|
| `propose <file>` | Classify one note. |
|
|
| `inbox` | Classify every inbox note. |
|
|
| `validate` | Replay the classifier against known-good notes. |
|
|
| `benchmark` | Measure accuracy and cost of the hybrid classifier. |
|
|
|
|
Write commands:
|
|
|
|
| Command | Purpose |
|
|
| :--- | :--- |
|
|
| `sort <file>` | Plan, then optionally apply, sorting for one note. |
|
|
| `sort-inbox` | Plan, then optionally apply, sorting for the whole inbox. |
|
|
| `watch` | Watch the inbox and maintain proposals. |
|
|
|
|
## Core Data Flow
|
|
|
|
`vault.py` scans notes into `Note` objects. `classify.py` picks a folder with
|
|
rules. `tier2.py` escalates to `jev.py` when needed. `writer.py` builds a
|
|
`Proposal` and a `Plan`, then applies it. `watch.py` connects the classifier to
|
|
the file system on a 10-second poll.
|
|
|
|
## Where to Fix Things
|
|
|
|
- **Misfiled notes**: edit `FOLDER_NOTES` in `sorter/tier2.py`. This teaches the
|
|
model the meaning of each folder.
|
|
- **Rule behaviour**: edit `sorter/classify.py`.
|
|
- **Type or folder rules**: edit `sorter/models.py`.
|
|
- **Filing safety**: edit `sorter/writer.py`.
|