Card: quick start with the idealens package (classify, extract, score)

README.md

@@ -47,16 +47,52 @@ Scoring a document takes two steps:
    worked examples, and runs this step. Score the outline as extracted; the paraphrasing step is only for training data.
 2. **Score the outline** with this model, as below.
 
-### With the idealens package
+### Quick start: everything with the idealens package
 
-[idealens](https://github.com/RishanthRajendhran/IdeaLens) ([PyPI](https://pypi.org/project/idealens/)) runs every step, scores with this model on vLLM and applies the thresholds in this repo:
+[idealens](https://github.com/RishanthRajendhran/IdeaLens) ([PyPI](https://pypi.org/project/idealens/)) classifies each document's format, extracts its outline with the prompt, role
+vocabulary and worked examples IdeaLens was trained with, scores the outline on vLLM and applies the thresholds in this
+repo:
 
 ```bash
 pip install "idealens[vllm]"
+export GEMINI_API_KEY=...   # or --provider vertex | openai | anthropic | openrouter | compatible
+idealens run docs.jsonl -o scores.jsonl --model IdeaLens --dry-run   # price the LLM calls first
 idealens run docs.jsonl -o scores.jsonl --model IdeaLens
 ```
 
-Input is JSONL with a `text` field per document. The rest of this section runs the model directly.
+Input is JSONL with a `text` field per document. The same steps in Python:
+
+```python
+import idealens as il
+
+texts = [open("document.txt").read()]
+formats = il.classify(texts)                  # one of the eight formats per document
+outlines = il.extract(texts, formats)         # role-labelled outlines
+with il.Detector("IdeaLens") as det:          # vLLM, with this repo's thresholds
+    records = det.score_outlines(outlines, format=formats)
+
+r = records[0]
+print(r["p_human"], r["verdict"]["ai"], r["verdict"]["cut"])   # P(human); flagged at the 1% global cut?
+print(outlines[0].render())                   # the outline that was scored
+```
+
+`classify` and `extract` call Gemini 3.7 Flash, the extractor the thresholds were fitted with; pass
+`provider=idealens.providers.make("openai", "gpt-6-sol")` (or Vertex, Anthropic, OpenRouter, a local server) to use
+another. Each record also carries verdicts at every calibrated false-positive rate under the global, per-format and
+per-topic schemes. The [package README](https://github.com/RishanthRajendhran/IdeaLens#ways-to-use-idealens) covers batch jobs, scoring outlines you already have and calibrating
+on your own data.
+
+### Mix and match: extract with the package, score with your own code
+
+```python
+import idealens as il
+
+text = open("document.txt").read()
+outline = il.extract([text], il.classify([text]))[0].render()   # one "[Role] content" line per item
+print(p_human(outline))   # p_human (transformers) or p_human_batch (vLLM), defined below
+```
+
+The rest of this section runs the model directly.
 
 ### Load the merged model (66 GB download)
 
@@ -93,7 +129,7 @@ the adapter and skips it without a warning; the model then scores close to the b
 
 ### Score an outline
 
-Write the outline one item per line, as `[Role] content`. IdeaLens compares the next-token probabilities of `human` and `ai`:
+Write the outline one item per line, as `[Role] content`, or take it from `il.extract` as above. IdeaLens compares the next-token probabilities of `human` and `ai`:
 
 ```python
 SYSTEM = "Given a role-labelled outline of a document, answer with one word: human if the source document was human-written, ai if it was AI-generated."