README.md

metadata

title: RANGE
emoji: 🔎
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.27.0
app_file: app.py
python_version: 3.10.13
pinned: false
license: mit
suggested_hardware: zero-a10g
short_description: Your taxonomy. Your curated dataset. At speed.
tags:
  - dataset-curation
  - text-analysis
  - information-extraction
  - explainable-ai
  - rust

RANGE

Rapid Annotation, Normalization, and Gating Engine

Python package coming soon. CPU today, optional CUDA for bulk screening.

Your taxonomy. Your curated dataset. At speed.

Each successful run displays CPU processing time; batches also display records per second for that run. Timing includes matching, decision evidence and engine setup when needed, excluding input validation, queue/network wait and display rendering. These small interactive runs are separate from the published bulk benchmarks. The curate and batch demo endpoints append a readable timing output and include numeric timing fields in their summaries; the single-record summary includes processing_timing. The package API and matching algorithms are unchanged.

The custom-taxonomy tab automatically compares RANGE's actual Aho–Corasick matcher with native Rust str::find searching each phrase. Both receive the same frozen normalized text and phrases, apply identical token-boundary checks, and collect all overlapping (document, phrase, start, end) matches. Their sorted outputs must agree before times are shown. Setup, normalization, sorting, labels, and Python/UI conversion are outside the timers; match-position collection is inside both. The display uses the median of five warm runs, alternating execution order, on one CPU thread. It makes no universal speedup or indexed-search claim. Comparison input is bounded to 100 documents, 800 KB and 256 phrases, with a 100,000-match cap. If capped or mismatched, no timing comparison is shown. The curate endpoint takes only taxonomy YAML and document JSON; comparison is always enabled. The additional native method is a private hosted-demo diagnostic; the published Windows CPU/CUDA preview downloads are unchanged.

RANGE applies your selection rules to text collections, assigns labels, and shows matched evidence. Start with Curate your text, edit the example YAML, and pass in documents from your own domain. Build your taxonomy includes an AI-agent prompt and a review workflow. No timestamp or finance category is required.

The Example taxonomy: General Economy tab filters economic and financial news. Its companion batch demo and taxonomy guide showcase temporal identities and market relationships. Its benchmark is one workload, not a performance claim for arbitrary taxonomies, biomedical corpora, billions of records, or NER models. The generic engine uses normalized literal phrases and label-specific exclusions; semantic enrichment such as GLiNER is future work.

Generic API: /curate takes taxonomy YAML and a JSON array of text strings. It returns keep/drop decisions, user-defined labels, a fingerprint and capped matched evidence. Local Python users can import CurationEngine and CurationTaxonomy from range_curate. The distribution is range-curate; the specialized economy API is in range_curate.examples.general_economy.

The engine runs inside this Space with no LLM, model download, API key, or outbound inference service. In a hosted Space, submitted text is still processed on Hugging Face infrastructure; do not submit material you are not permitted to share.

The repository can produce a local Docker bundle or a free Gradio/ZeroGPU-compatible bundle. Both execute the same compiled CPU/Rust predictor; ZeroGPU is a hosting route, not a RANGE GPU backend or a GPU benchmark.

Hosting note: This free Gradio deployment uses the ZeroGPU runtime, but RANGE's real prediction endpoints stay on CPU and never request a GPU allocation.

What the General Economy example returns

For one article, the app shows two related outputs:

• Article relevance: relevant or not_relevant in this deterministic demo, with a plain-language result in the interface. The package contract reserves needs_review for optional unresolved semantic evidence.
• Supported exposure: Broad market, S&P 500, Nasdaq-100, or Russell 2000 when an accepted evidence path supports one; otherwise none.

It also returns:

• a concise reason suitable for an application;
• highlighted accepted, review, and rejected matches in the original text;
• offsets, matching method, rules, identities, and exposure lineage;
• a downloadable evidence record that identifies the submitted text by its length and SHA-256 hash instead of repeating the full article; and
• Mermaid source for developer-owned evidence-flow rendering.

A second tab screens a small editable batch and exports JSONL. Requests are capped at 100 rows, 20,000 characters and 80,000 UTF-8 bytes per article, and 200,000 characters and 800,000 UTF-8 bytes per batch. The Python and Arrow APIs are intended for large collections. The web interface and its named API endpoints enforce the same limits before running the screening engine. Batch rows must have exactly the four displayed columns, metadata fields have separate size limits, and nested values are rejected. Combined article and metadata cell content cannot exceed 264,000 characters or 1,056,000 UTF-8 bytes. These figures do not include JSON framing or Gradio's transport envelope. A separate 4 MiB server limit covers the complete HTTP request body before JSON parsing.

Download files are temporary conveniences, not storage. A generated file becomes eligible for deletion after five minutes, and the app makes a best-effort cleanup pass once a minute. The host may remove it sooner when the Space restarts. Save a file promptly if you need it, and do not rely on the download link as an archive.

General Economy benchmark scope

Implementation	Articles / second	Measurement
CUDA research record	1,833,059	Qualified warm screening of 10 million articles
CPU block-processing engine	548,532–582,107	Two qualified 10-million-article runs; 24–26% faster than matched CPU controls
Newer retained CUDA installation	958,155	Separate local installed-package qualification

Measured on an Intel i7-10750H Windows laptop with 10 CPU workers; CUDA used an RTX 2070 Max-Q. These are separate experiments, not a same-run CPU/GPU speedup. The CUDA peak belongs to an earlier qualified implementation; later sessions varied substantially. Do not combine its peak with later percentage gains.

Screening timings exclude file loading, imports, initialization and verification. CUDA timings include transfers, exact CPU fallback and result assembly. The live demo uses a different CPU environment and rich explanations, so these figures are not its throughput or a service guarantee.

Read the benchmark record

Python package coming soon

We are preparing RANGE for straightforward Python installation, with CPU support and an optional CUDA backend. Public package release, clean installation across supported platforms and broader GPU compatibility are still ahead. The current Space lets you explore the engine today.

What we want to try next

• Finish the release: clean installs, supported platforms, documentation and validation of the exact wheels people will use.
• Share work across taxonomies: build on successful two-taxonomy experiments, then extend packaging and memory scheduling for more rule sets.
• Choose CPU or CUDA by workload: measure small batches, large batches and routing overhead before introducing automatic selection.
• Target remaining matching ideas: direct StringZilla integration and other CUSMART methods remain candidates, not demonstrated improvements.
• Train optimizations on separate data: investigate corpus-trained automata on larger future taxonomies. A fresh compiler-profile experiment was tested and did not qualify for adoption.

Recent alternatives did not beat the retained matcher. We keep negative results and require exact outputs before considering a speed improvement.

What the result means

A relevant result means the article passed the configured financial and economic relevance policy. Evidence-path state and supported exposure are reported separately. Neither result means the article is bullish, bearish, material, complete, or predictive of returns.

The app does not perform sentiment analysis, investment recommendations, fuzzy semantic search, or LLM inference. Each result remains traceable to literal observations and explicit policy.

API and coding agents

The Gradio functions expose named endpoints:

• /analyze — one timestamped article with detailed evidence;
• /batch — up to 100 timestamped articles with JSONL summaries.

After this bundle is deployed to <namespace>/<space>, inspect the generated agent instructions with:

curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/spaces/<namespace>/<space>/agents.md

That document tells coding agents how to discover and call the Space API. Private Spaces require a Hugging Face bearer token for both agents.md and API requests. The Space does not need a separate model endpoint.

Package

This app is built from RANGE 0.1.0a3, a deterministic CPU/Rust research alpha. The Python distribution is range-curate and the import namespace is range_curate. The standalone bundle includes the default taxonomy used by the demo. Package users can copy and edit its YAML or extend the taxonomy in Python without modifying the engine.

See PACKAGE_README.md in an exported bundle for the full Python API, taxonomy, benchmark context, and limitations.

Safety and scope

This software is for research and information-screening workflows. It does not provide investment advice. A hosted production deployment returns a simple error to the user when something unexpected fails; diagnostic details stay in the host logs.

Do not submit private, licensed, or confidential article text to a public deployment unless you have permission to do so. The article text is still processed on the Space host and can appear in the interactive page even though downloaded evidence records omit it.

Making the Space public also makes its repository public. That includes the app source, bundled RANGE source and native runtime, package documentation, and default taxonomy. Keep credentials, private datasets, licensed articles, local paths, and unpublished rules out of every uploaded file and revision.

The current alpha uses CPython 3.10. Moving the native package and Space runtime to CPython 3.12 is planned as a separate, tested migration; the existing CPython 3.10 wheel cannot be reused for that change.

Generic demo limits

/curate accepts at most32 labels and256 phrases, each at most160 characters; taxonomy YAML is limited to12,000 characters/48,000 bytes and has no anchors or aliases. Documents are limited to100 rows,20,000 characters/80,000 UTF-8 bytes per row and200,000 characters/800,000 UTF-8 bytes in total. JSON framing is also bounded. Evidence is capped at50 spans per document; all matches still contribute to decisions. No uploaded YAML is executed or used to access files.

Retained CUDA implementation

The source and preview installation files include the Phase60/61 CUDA implementation behind the peak benchmark. The hosted interface remains CPU-based. CUDA preview support is Windows CPython3.10/sm75; its kernels and private CPU fallback are byte-identical to Phase61. Public PyPI release and broader GPU support are still pending. No benchmark rerun was made.