dirtydishes/islandflow
1
0
Fork 0
Code Issues 2 Pull requests 4 Projects Releases Packages Wiki Activity Actions 1

refresh readme description with current classification flow
Some checks are pending
Discord notifications / Push -> Discord (main) (push) Waiting to run
Details
Discord notifications / CI result -> Discord (red on failure) (push) Waiting to run
Details
Discord notifications / Release -> Discord (lavender) (push) Waiting to run
Details
Publish Docs / build (push) Waiting to run
Details
Publish Docs / deploy (push) Blocked by required conditions
Details

Browse source
This commit is contained in:
dirtydishes 2026-05-20 21:56:07 -04:00
parent df9c9f3a1b
commit 1e2ed3e432
3 changed files with 279 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

32
README.md
View file

@ -8,12 +8,14 @@
Islandflow is a Bun + TypeScript monorepo for a personal-use, event-sourced market microstructure research platform focused on:
- options prints + NBBO,
- off-exchange equity prints,
- market news context,
- explainable smart-money flow classification,
- deterministic replay,
- evidence-linked UI inspection.
- multi-source options/equities/news ingest (synthetic + live adapters),
- deterministic parent-event reconstruction over prints, quotes, and NBBO,
- explainable participant-style flow classification (not a single binary "smart money" flag),
- evidence-linked alerts, packet drilldowns, and context hydration,
- real-time + historical + replay delivery over REST and WebSocket,
- terminal-style inspection UI for tape, signals, charts, and news.
In its current state, Islandflow acts as an event-sourced intelligence layer on top of raw market microstructure events. Services publish and consume through NATS/JetStream, persist both raw and derived events in ClickHouse, and expose low-latency live feeds plus cursor-based history/replay APIs for research and operator workflows.
## Current Implementation Status
@ -51,6 +53,24 @@ Planned / not yet complete:
- **Taxonomy over folklore**: "smart money" is modeled as participant-style hypotheses, not a single binary label.
- **Bun-first tooling**: runtime, package management, scripts, and tests use Bun.
## How Print Classification Works (Current Approach)
Islandflow follows the same high-level philosophy captured in [`smartmoney.md`](smartmoney.md): the tape is informative but noisy, and a useful classifier should model multiple participant-style hypotheses instead of forcing every print into one "smart money" bucket.
Current flow in the compute pipeline:
1. **Ingest + normalize** options prints, NBBO, equity prints/quotes, and news into shared schemas.
2. **Reconstruct parent events** from child prints using bounded clustering windows, quote alignment, and structure-aware packet planning.
3. **Compute evidence features** such as aggressor side vs NBBO, premium/notional concentration, burst timing, quote freshness/coverage, DTE/moneyness context, and cross-signal linkage.
4. **Score profile hypotheses** including `institutional_directional`, `retail_whale`, `event_driven`, `vol_seller`, `arbitrage`, and `hedge_reactive`, with reason codes and confidence bands.
5. **Emit explainable artifacts** (`FlowPacket`, `SmartMoneyEvent`, `ClassifierHitEvent`, `AlertEvent`, inferred-dark events) for both live fanout and historical replay.
Important behavior:
- The classifier can **abstain** when evidence is weak.
- Suppression guards reduce known false positives (stale/missing quote context, special/complex print ambiguity, hedge-reactive or parity-like structure confusion).
- Compatibility endpoints remain available while newer smart-money semantics are first-class.
## Smart-Money Classification Taxonomy
Islandflow now emits first-class `SmartMoneyEvent` records instead of treating old classifier hits as the final semantic object. `FlowPacket` remains the clustering bridge, while smart-money events carry typed features, profile scores, confidence bands, directions, reason codes, abstention state, and suppression reasons.