From 48613f20884289c9e5c650b26893746e71d617da Mon Sep 17 00:00:00 2001
From: Yoni <cigan1@gmail.com>
Date: Fri, 29 May 2026 21:16:18 -0400
Subject: [PATCH 1/2] docs: sharpen README first-screen positioning

Add an audience line, an "At a glance" summary, and good-fit/not-a-fit
guidance above the fold so a stranger can decide whether siftfy fits in
seconds. No behavior changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/README.md b/README.md
index 1b0496d..9f212ff 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,25 @@ queues, no models to host.
 [![CI](https://github.com/siftfy/siftfy-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/siftfy/siftfy-python/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+`siftfy` is a small, typed client built for Python developers who need to keep
+spam out of contact forms, signups, comments, reviews, and moderation queues —
+the everyday content-moderation use case — without training, tuning, or hosting
+a model. Add a few lines and call `predict()`; it lets you branch on a single
+score so you can block or flag spam before it lands.
+
+### At a glance
+
+- **In:** a string of text. **Out:** a calibrated `spam_probability` (0–1) plus a
+  coarse `"low" | "medium" | "high"` bucket.
+- Sync (`Siftfy`) and async (`AsyncSiftfy`) clients, fully type-hinted (ships `py.typed`).
+- Automatic retries with backoff on transient failures; typed exceptions for the rest.
+- One dependency (`httpx`), Python 3.9+. Free tier: 10,000 requests/month.
+
+**Good fit:** real-time spam scoring of user-submitted text when you want a hosted,
+calibrated probability and would rather not run ML infrastructure.
+**Not a fit:** fully offline/air-gapped environments, or when you need to own and
+retrain the model yourself — Siftfy is a hosted API.
+
 ## Requirements
 
 Siftfy supports Python 3.9 and newer.

From 24551d71158ed9206e838d0f0aabb1ebc22b8ea2 Mon Sep 17 00:00:00 2001
From: Yoni <cigan1@gmail.com>
Date: Fri, 29 May 2026 21:28:26 -0400
Subject: [PATCH 2/2] docs: add above-the-fold proof snippet and inline FastAPI
 example

Show the input-to-output payoff before any setup, and demonstrate a real
request-handler integration inline rather than only linking out. Docs-only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/README.md b/README.md
index 9f212ff..f065068 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,16 @@ calibrated probability and would rather not run ML infrastructure.
 **Not a fit:** fully offline/air-gapped environments, or when you need to own and
 retrain the model yourself — Siftfy is a hosted API.
 
+```python
+from siftfy import Siftfy
+
+client = Siftfy(api_key="sk_live_...")
+result = client.predict("Win a free iPad — click here!")
+
+result.spam_probability  # 0.97
+result.likelihood        # "high"
+```
+
 ## Requirements
 
 Siftfy supports Python 3.9 and newer.
@@ -53,6 +63,27 @@ print(result.likelihood)        # "high"
 Get an API key at [siftfy.io](https://siftfy.io) — the free tier covers
 10,000 requests/month at no cost.
 
+## In a request handler
+
+What it looks like wired into a real endpoint — reject the submission when the
+score crosses your threshold, accept it otherwise:
+
+```python
+from fastapi import FastAPI, HTTPException
+from siftfy import Siftfy
+
+app = FastAPI()
+siftfy = Siftfy(api_key="sk_live_...")
+
+@app.post("/contact")
+def contact(message: str):
+    result = siftfy.predict(message)
+    if result.spam_probability > 0.8:
+        raise HTTPException(status_code=422, detail="Message flagged as spam")
+    # ... persist / notify / queue the legitimate message
+    return {"ok": True}
+```
+
 ## Runnable examples
 
 Use these when wiring Siftfy into a real form, signup flow, or moderation