bsky-firehose/README.md

# Grand Aim
A semantically colored feed of bluesky skeets, for your perspective, someone else's or another group's.

## Intermediate goals so far
- [x] Visualize bluesky data.
- [x] Read from jetstream
- [x] Extract interesting fields
- [x] Filter by commit/post type. Learning bsky data model just enough, filter also by keywords. Count limit.
- [x] Get color selection ergonomic for further development, 24-bit? 32-bit? color, the alpha paramter of colorama is quite useful
  - [x] colorspace, hsla / hsl
  - [x] Vary colors, find balance so nothing draws excessive attention, but noticeable, though gradual, color evolution occurs
        And, for ergonomic use to communicate meaning. Color for cluster / direction. Brightness, inverse to length, for ease of reading, uniformity of gestalt. Saturation for content searching versus scaffolding metadata. Errors in grey too.
- [x] Port to Rust for better performance and native compilation
- [ ] Get semantic clustering working -- static color. Faiss? enough?  Word2Vec? Queries?
- [ ] Get sematic selection & filtering working, based on keywords, chosen posts
- [ ] Get db/profiles/queries/modes set up -- so every taste selection input can inform any future use
- [ ] Get a streaming web view working -- possibly even fully in-browser
  - fallen? [twitterfall](https://twitterfall.com) inspiration. [hatnote's L2W](https://l2w.hatnote.com)

# Run it

## Rust version (recommended)
```bash
# Build and run
cargo run

# With options
cargo run -- --count 10 --filters "+love,-hate" --cfilters "+create"

# Install and run
cargo install --path .
bsky-firehose-term --help
```

## Python version
```bash
uv run --with websockets,colorama,munch,fire python3 bluesky-simple-print.py
```

## Command-line options
Both versions support the same filtering options:

- `--skips`: Skip certain types (comma-separated)
- `--only`: Only show certain types (comma-separated)  
- `--cfilters`: Commit type filters (+include,-skip format)
- `--filters`: Text filters (+include,-skip format)
- `--count`: Stop after N posts

Examples:
```bash
# Show only posts containing "rust" or "programming"
cargo run -- --filters "+rust,+programming"

# Skip posts containing "spam"
cargo run -- --filters "-spam"

# Show only commit types containing "create"
cargo run -- --cfilters "+create"

# Show only 5 posts
cargo run -- --count 5
```

# What it looks like
![firehose screenshot](/res/Screenshot_20250222_162327.png)
![firehose asciinema](/res/ascii-1.gif)