docs/readme-research.md

README and demo research notes

This note records the presentation research behind the 0.1.0a3 README and staged Hugging Face Space. It is not a benchmark claim and it does not change the taxonomy or runtime contract.

Sources reviewed

The review covered the GitHub monthly trending page and representative high-quality project READMEs with adjacent presentation problems:

• GitHub Trending, monthly: current repository presentation patterns.
• Polars: performance-oriented data tooling with a concise value proposition and evidence-linked benchmarks.
• DuckDB: immediate installation and runnable examples before deeper architecture.
• OpenBB: finance-specific positioning, clear audience, product surfaces, and documentation paths.
• FinanceToolkit: finance-oriented examples, scope, and discoverable feature groups.
• Hugging Face Docker Spaces and the coding-agent setup document: deployment metadata, Docker runtime expectations, and agent API discovery.

The review was conducted on 2026-09-02. Trending content changes over time; the goal was to extract durable communication patterns rather than copy rankings or wording.

Patterns applied

observed pattern	application in Relevance
one-sentence value proposition	“Fast financial-news screening that shows its work.”
show a useful result early	the README opens with real quickstart stdout
put runnable code before exhaustive reference	a complete one-article example appears near the top
explain performance mechanistically	Rust, automata, Rayon, sparse output, and Arrow are mapped to their practical effects
separate product surfaces by user goal	the README distinguishes rich, compact, Arrow, and ranking paths
link performance claims to evidence	claims are bounded to recorded research stages and environments
state boundaries plainly	relevance is separated from sentiment, materiality, prediction, and advice
make the demo self-explanatory	the Space has curated examples, evidence highlights, lineage, downloads, and named APIs
keep deployment reproducible	the Space exporter creates a deterministic source bundle and SHA-256 manifest
avoid decorative clutter	one Space-card emoji; no emoji-heavy package documentation

Marketing standard

The README is intentionally specific rather than superlative. It explains why the system can be fast and traceable, but it does not claim to be the fastest system in all settings. It shows the output contract before implementation details and keeps limitations close to the value proposition.

The intended audience is:

• financial-data and news-ingestion engineers;
• quantitative researchers building candidate-selection pipelines;
• analysts who need literal evidence and provenance;
• researchers comparing exact retrieval with model-based classifiers; and
• teams that need a deterministic first-stage filter before more expensive NLP.

Items intentionally omitted

• unqualified “blazing fast” or “state of the art” language;
• benchmark numbers without the host, stage, dataset, and repetition design;
• claims that rule-based relevance is semantically complete;
• claims that a relevant article predicts price direction;
• a published package badge or live Space badge before either artifact exists.