# 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](https://github.com/trending?since=monthly): current
  repository presentation patterns.
- [Polars](https://github.com/pola-rs/polars): performance-oriented data tooling with
  a concise value proposition and evidence-linked benchmarks.
- [DuckDB](https://github.com/duckdb/duckdb): immediate installation and runnable
  examples before deeper architecture.
- [OpenBB](https://github.com/OpenBB-finance/OpenBB): finance-specific positioning,
  clear audience, product surfaces, and documentation paths.
- [FinanceToolkit](https://github.com/JerBouma/FinanceToolkit): finance-oriented
  examples, scope, and discoverable feature groups.
- [Hugging Face Docker Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
  and the [coding-agent setup document](https://huggingface.co/new-space/agents.md):
  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.