Spaces:
Running on Zero
Running on Zero
| 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](https://huggingface.co/spaces/Brianferrell787/range/blob/main/BENCHMARKS.md) | |
| ## 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: | |
| ```bash | |
| 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](https://huggingface.co/spaces/Brianferrell787/range/blob/main/cuda/README.md) | |
| 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. | |