README.md

# ReviewQueue 0.6

Offline AI review hints for structured business records. Every source row, text ID and extra field survives unchanged; the output is a review report for a person to inspect.

**[Interactive synthetic demo and source](https://reviewqueue.rahmat19800402.chatgpt.site)**

Original project started 14 October 2026 for the Hacktoberfest Week 2 Side Hustle challenge. This package contains original BSD-3-Clause code, synthetic data and a locally trained synthetic model. No client data, credentials or paid APIs are included. Contest submission status is recorded separately; deployment is not proof of entry.

## Run with your own reference records

Python 3.12; tested with scikit-learn 1.8.0. Use a virtual environment:

```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python reviewqueue.py sample_input.json --output my_review.json
```

After dependencies are installed, analysis is local and needs no network. The CLI refuses to overwrite the input or an existing output. The output retains a SHA-256 hash of the input file's original bytes. JSON serialization does not preserve original whitespace or number spelling; the input file remains untouched.

Input: an object containing `reference` and `records` arrays, each up to 5,000 objects. Fields: text `record_id`, uppercase three-letter `currency`, plain decimal `amount` and positive `quantity`. Extra fields survive. Use quoted decimal strings for exact decimals. Numeric locale guessing, duplicate JSON keys and lossy float decoding are rejected. References need at least 20 valid records and five distinct feature vectors per currency. Currency syntax does not verify an ISO code. Reference context and units must match the batch. The CLI limit is 8 MB.

## AI and review policy

Isolation Forest is fitted locally, separately per currency. Features are signed-log amount, log quantity and signed-log unit amount. A model hint is promoted only when the model's decision score is negative **and** a feature is outside the reference's observed minimum/maximum. The conservative gate reduces review noise; it can miss unusual records inside that support. Raw candidate status, score, support status and policy metadata remain inspectable. Scores are not probabilities.

Deterministic checks flag repeated IDs, ambiguous/invalid numbers, nonpositive quantities, missing text IDs and malformed currency. Insufficient same-currency reference causes explicit abstention; an unscored row should not be assumed safe. No correction, deletion, fraud finding or business decision is performed.

## Interactive browser demo

`web_demo/index.html` includes two separate experiences:

1. **Live inference:** 100 exported trees from the demo's scikit-learn model run through original JavaScript traversal code. Inputs are fictional USD amounts and quantities. The fixed reference has quantity 1 and amounts 80–158. This is not a model trained on visitors' businesses.
2. **Full-report workflow:** inspect the precomputed six-record Python report, confirm that exact snapshot and download its JSON. Reset/review revokes the gate. A digest binds the complete exported report; confirmation is a UI state, not identity verification or certification that rows are correct.

The page makes no API calls. The fixed model and all assets are included. HTTPS/Web Crypto is needed for the digest; local-file browser behavior varies. Use the hosted demo or an ordinary local static server on your own computer. JavaScript floating point is used for synthetic live inference. The Python CLI is the path for exact-decimal source handling.

## Reproduce checks

```sh
python demo.py
python build_browser_model.py
python -m unittest demo test_conversation test_policy -q
node --test web_demo/test_core.cjs web_demo/test_inference.cjs web_demo/test_ui.cjs
python audit_synthetic.py --output audit-new.json
```

The Python suite checks source preservation, numeric/JSON rejection, abstention, deterministic model output, CLI overwrite protection and conversation export gates. Node checks include 204 numerical probes against scikit-learn, unchanged report bytes and event flows in a simulated DOM. These are not native-browser layout, accessibility or file-download checks. This environment did not provide the Sites-required browser QA capability; visual/native-download verification remains a limitation.

## Honest evaluation

The original development fixture flagged 17/25 ordinary-by-construction rows. Version 0.6's conservative policy flags 0/25, 10/10 extreme numeric rows, and 0/5 plausible numeric rows carrying unverifiable notes. This same fixture informed development: these numbers are regression evidence, **not independent accuracy, recall or false-positive rates**. Numeric models cannot verify facts in notes. No production/customer accuracy is known; there are no customers or sales. The business hypothesis is paid configuration and review-workflow support for freelancers handling structured exports.

`browser_parity.json` contains new numerical probes for the exported scorer; this validates implementation parity, not business accuracy. `synthetic_audit_result.json` includes the complete audit and preservation evidence.

## Code and attribution

BSD-3-Clause, see `LICENSE`. `THIRD_PARTY_NOTICES.md` credits scikit-learn and its dependencies. Model trees are newly trained on this project's original synthetic records, not copied third-party weights. AI assistance was used for implementation, testing and documentation. No partner prize category or real-user validation is claimed.

The optional `conversation.py` is a typed local review/export adapter. It is not an Alexa integration or a language agent.