Metadata-Version: 2.4
Name: bowerbird-bookmarks
Version: 0.6.0
Summary: Audit, clean, categorise and explore your browser bookmarks — link validation, LLM thematic analysis, Wayback recovery, and safe write-back
Project-URL: Homepage, https://github.com/michael-borck/bowerbird
Author-email: Michael Borck <michael.borck@curtin.edu.au>
License: MIT License
        
        Copyright (c) 2026 Michael Borck
        
        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.
License-File: LICENSE
Keywords: bookmarks,brave,browser,chrome,claude,curation,firefox,link-rot,obsidian,wayback
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.90
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# Bowerbird

Like its namesake bowerbird, it collects — then, unlike you, it curates.
Bowerbird audits, cleans, categorises and helps you rediscover your browser
bookmarks, entirely on your own machine.

```
pip install bowerbird-bookmarks
bowerbird ingest  # read your browsers' bookmarks (read-only)
bowerbird check   # validate every link
bowerbird serve   # dashboard at http://127.0.0.1:8420
```

## What it does

- **Multi-browser ingest** — Chrome, Brave, Edge, Vivaldi (one Chromium parser),
  Firefox (`places.sqlite`) and Safari (read-only). Sources are facets, not
  silos: the same link saved in two browsers is one URL, tracked once.
- **Link validation** that doesn't lie: only 404/410 (or a confirmed soft-404)
  counts as *dead*; a bot-wall 403 is *blocked, not dead*; reaching a login page
  counts as *alive*; YouTube videos are checked via oEmbed because deleted
  videos still return 200.
- **Canonicalisation and duplicate detection** (tracking params stripped,
  youtu.be unified, per-source dupe groups with a keeper heuristic).
- **LLM thematic analysis** (Claude, two-pass): a taxonomy is derived from your
  collection first, then bookmarks are assigned 1–3 categories with confidence.
  Categories are tags — one bookmark can live in many.
- **Full-text search** (SQLite FTS5) over titles, URLs, topics, and the visible
  text of every reachable page.
- **Ask your bookmarks** — ask a question, get *links from your own collection*
  grouped by theme with a line on why each is relevant. Never answers from the
  open web.
- **Graveyard & Wayback** — dead links get Internet Archive snapshot lookup,
  per-row or bulk replace, and bulk retire for the unrecoverable.
- **Domain triage** — review a whole domain in one decision.
- **Obsidian export** — topic notes plus per-bookmark stubs with frontmatter
  and wikilinks; drop the folder into your vault.
- **Topic map** — a force-directed graph of your collection's themes.
- **Safe write-back** — regenerate the browser's bookmarks file: duplicates
  collapsed, dead links moved to a `_Graveyard` folder (never silently
  deleted), Wayback replacements applied. Dry-run by default, timestamped
  backup always, refuses to run while the browser is open.

## Requirements

- macOS (browser profile discovery is macOS-path based for now)
- Python 3.12+
- An Anthropic API key (`ANTHROPIC_API_KEY`) for the categorisation and Ask
  features — everything else works without one.

## Data location

Everything lives in `$BOWERBIRD_HOME` (default `~/.bowerbird`): the SQLite database,
write-back backups, reports and exports. A `bowerbird.db` in the current directory is respected. Your browsers' own files are only ever
written by the explicit `bowerbird writeback --apply`, and backed up first.

## Commands

| Command | What it does |
|---|---|
| `bowerbird sources` | detect and register installed browsers |
| `bowerbird ingest` | import bookmarks + history (read-only, reconciling) |
| `bowerbird check` | validate links (`--recheck` to re-probe) |
| `bowerbird enrich` | fetch page titles/descriptions/text for search |
| `bowerbird categorize --taxonomy` / `--assign` | two-pass LLM categorisation |
| `bowerbird index` | rebuild the full-text search index |
| `bowerbird wayback` | look up Internet Archive snapshots for dead links |
| `bowerbird report` | write a Markdown audit report |
| `bowerbird obsidian` | export an Obsidian-ready folder |
| `bowerbird writeback --source-id N [--apply]` | write the cleaned tree back |
| `bowerbird serve` | the dashboard (Library, Ask, Graveyard, Duplicates, Domains, Topic map) |

## Notes

The CLI is also installed under the short alias `bower`, and the Python module
is `import bowerbird`.

## Status

Beta. Built and used in anger on a 9,600-bookmark collection; APIs and schema
may still change. Issues and ideas welcome.
