StickerStream

StickerStream is a privacy-conscious vehicle inventory intelligence pipeline. It normalizes heterogeneous listing records, runs independent collectors in parallel, enriches location and vehicle attributes, and ranks comparable inventory with an explainable scoring model.

The public repository contains the reusable, offline-safe core. Live source adapters, buyer profiles, raw inventory, purchase targets, credentials, device configuration, and operational history remain private.

Why it exists

Vehicle listings are inconsistent across sources: prices use different labels, feature descriptions drift, identifiers can be incomplete, and distance alone does not express acquisition cost. StickerStream turns those inputs into one schema and keeps the evidence used for each ranking decision.

flowchart LR
    A[Source adapters] --> B[Concurrent runner]
    B --> C[Normalized JSON and CSV]
    C --> D[Vehicle and location enrichment]
    D --> E[Comparable-market medians]
    E --> F[Explainable deal scores]
    F --> G[Reports and dashboards]

Loading

Engineering highlights

• Adapter contract isolates source-specific collection behavior.
• Bounded thread pool executes independent jobs and records partial failures.
• Canonical 48-field schema keeps JSON and CSV outputs interoperable.
• Parsing utilities normalize currency, mileage, HTML, and missing values.
• Haversine and planning-grade drive-time estimates support geographic ranking.
• Median-relative scoring combines price, MSRP discount, mileage, travel, and source-quality signals while preserving every score component.
• Deterministic static adapter makes the end-to-end pipeline testable without browsers, network access, or third-party services.

Verified scope

The private operational system recorded a March 2026 snapshot of 504,978 vehicle rows across nine collection runs. That production-scale evidence is a historical project result, not a promise that the public offline example will contact or reproduce any third-party source.

The public repository verifies:

• normalized JSON and CSV generation;
• concurrent job execution and isolated failure reporting;
• price, mileage, text, and geographic normalization;
• median-relative, component-level scoring; and
• Linux and Windows compatibility through GitHub Actions.

Not included or claimed here:

• live dealer or marketplace connectivity;
• circumvention of access controls or anti-automation systems;
• current prices, incentives, availability, or financing advice; or
• buyer-specific recommendations.

Quick start

Requires Python 3.10 or newer.

python -m venv .venv
python -m pip install -e ".[dev]"
stickerstream collect --config examples/jobs.json --output-dir output/collected
stickerstream score --input output/collected/demo.csv --output output/scored.csv
pytest

The included example uses synthetic records and performs no network requests.

Repository layout

src/stickerstream/
  collectors/static.py   deterministic offline adapter
  collector.py           adapter protocol
  pipeline.py            concurrent orchestration and manifests
  parsers.py             normalization helpers
  schema.py              canonical output schema
  geo.py                 geographic calculations
  scoring.py             explainable market-relative scoring
examples/                 synthetic inputs and runnable job configuration
tests/                    offline unit and integration tests
docs/                     architecture and publication boundary

Responsible use

Use only data you are authorized to access. Follow applicable terms, robots directives, rate limits, privacy obligations, and laws. The public project does not ship site-specific scraping or access-control bypass implementations.

StickerStream is an independent project and is not affiliated with or endorsed by any vehicle manufacturer, dealer, marketplace, or data provider.

License

MIT. Third-party services and datasets remain subject to their own terms and licenses.