Skill: uday390/deepread-pii (version 2.0.0)

--- name: deepread-pii title: DeepRead PII Redaction description: Redact PII from documents before sharing or sending to LLMs. 14 PII types (names, SSN, credit cards, medical records, etc.) detected with context-aware AI — not regex. Knows patient vs. doctor, personal vs. institutional. Black bar redaction on PDFs, scanned images, and text files. Free tier: 2,000 pages/month. metadata: {"openclaw":{"requires":{"env":["DEEPREAD_API_KEY"]},"primaryEnv":"DEEPREAD_API_KEY","homepage":"https://www.deepread.tech"}} --- # DeepRead PII — Document Redaction API Your agent processes documents. Some of those documents contain names, SSNs, medical records, credit card numbers. Before that data flows to another API, a database, a teammate, or an LLM — **it needs to be clean.** ``` Input: "Invoice to: John Smith, 123 Oak St, SSN: 456-78-9012, Card: 4532-1234-5678-9012" Output: "Invoice to: ██████████, ██████████, SSN: ███████████, Card: ███████████████████" ``` **One API call. Document in, redacted copy + detection report back.** DeepRead PII detects 14 types of personally identifiable information using context-aware AI — not regex. It knows "Dr. Sarah Chen" on a hospital letterhead is the physician (skip), but "Sarah Chen" on a patient intake form is the patient (redact). No regex rules to write. No word lists to maintain. No false positive floods. > This skill instructs the agent to POST your file to `https://api.deepread.tech`, poll for results, and download the redacted copy. No system files are modified and no elevated permissions are requested. ## What This Skill Does - **14 PII types detected**: Names, SSNs, credit cards, emails, phones, addresses, dates of birth, passport numbers, driver's licenses, bank accounts, IBANs, IPs, URLs, medical record numbers - **Black bar redaction**: PII replaced with solid black bars — text physically removed from the PDF content stream, irreversible, not just a visual overlay - **Any document format**: PDF (digital + scanned), PNG, JPEG, plain text - **Context-aware**: AI distinguishes personal vs. institutional, patient vs. provider, form labels vs. actual values - **Audit trail**: Every redaction logged with detection counts per type. See DeepRead's [privacy policy](https://www.deepread.tech/privacy) for data handling details. - **Copy-paste proof**: Redacted text cannot be recovered via copy-paste, text selection, or PDF parsing - **Free tier**: 2,000 pages/month (no credit card required) - **Works with other DeepRead skills**: Extract data with `deepread-ocr`, fill forms with `deepread-form-fill`, then redact the originals ## Setup ### 1. Get Your API Key Sign up and create an API key: ```bash # Visit the dashboard https://www.deepread.tech/dashboard # Or use this direct link https://www.deepread.tech/dashboard/?utm_source=clawhub ``` Save your API key: ```bash export DEEPREAD_API_KEY="sk_live_your_key_here" ``` ### 2. Configuration (Optional) Add to your `clawdbot.config.json5`: ```json5 { skills: { entries: { "deepread-pii": { enabled: true // API key is read from DEEPREAD_API_KEY environment variable // Do NOT hardcode your API key here } } } } ``` ### 3. Redact Your First Document **Option A: With Webhook (Recommended)** ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@document.pdf" \ -F "webhook_url=https://your-app.com/webhooks/pii" # Returns immediately: { "id": [REDACTED_SECRET], "status": "queued" } # Your webhook receives results when processing completes ``` **Option B: Poll for Results** ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@patient_record.pdf" # Returns immediately: { "id": [REDACTED_SECRET], "status": "queued" } # Poll until completed: curl https://api.deepread.tech/v1/pii/550e8400-e29b-41d4-a716-446655440000 \ -H "X-[REDACTED_SECRET]" ``` ## Usage Examples ### Redact a PDF Replaces all detected PII with solid black bars. Text is physically removed from the PDF content stream. Copy-paste cannot recover it. ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@contract.pdf" ``` **Response when completed:** ```json { "id": "550e8400-...", "status": "completed", "progress_percent": 100, "redacted_file_url": "https://...(signed URL)...", "report": { "id": "550e8400-...", "page_count": 5, "processing_time_ms": 3421, "pii_detected": { "NAME": { "count": 3, "pages": [1, 2], "confidence_avg": 0.92 }, "PHONE": { "count": 2, "pages": [1], "confidence_avg": 0.89 }, "EMAIL": { "count": 1, "pages": [2], "confidence_avg": 0.97 } }, "total_redactions": 6, "redaction_policy": "black_bar", "confidence_threshold_used": 0.85, "below_threshold_count": 0 } } ``` ### Redact an Image Works on scanned documents, photos of IDs, screenshots — any PNG or JPEG. ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@drivers_license.png" ``` Vision AI detects PII in the image, locates exact positions, and draws black bars over the text. ### Redact Plain Text ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@notes.txt" ``` **Before:** `Patient John Smith, SSN 456-78-9012, called from (555) 867-5309` **After:** `Patient ██████████, SSN ███████████, called from ██████████████` ### Multi-Language Support Supports documents in English, Chinese, Spanish, Hindi, and Arabic. ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@documento.pdf" \ -F "language=es" ``` **Supported languages:** `en` (default), `zh`, `es`, `hi`, `ar` ## When to Use This Skill ### Use DeepRead PII For: - **Before sharing documents externally** — redact before sending to vendors, partners, opposing counsel - **Before feeding documents to LLMs** — strip PII before sending content to any AI model - **Compliance workflows** — GDPR right to erasure, HIPAA de-identification, CCPA requests - **Training data preparation** — create clean datasets from real documents - **Insurance claims** — redact claimant PII before adjuster handoff - **Legal discovery** — privilege review with PII protection - **Medical records** — de-identify patient data for research or sharing - **Financial documents** — mask account numbers, SSNs on statements - **HR documents** — clean employee files before audits ### Don't Use For: - **Real-time processing** — async workflow, not instant (use webhooks) - **Structured data extraction** — use `deepread-ocr` skill for that, then redact - **Documents with no text** — blank images or decorative PDFs ## How It Works ### 3-Layer Detection Pipeline ``` Document → AI Detection → Threshold Filter → Context Validation → Redact ``` **Layer 1: AI Detection** - Text documents: LLM scans for all 14 PII types with confidence scoring - Images/scans: Vision model detects PII with precise bounding box coordinates - Returns type, exact value, and confidence score (0.0–1.0) for each detection **Layer 2: Confidence Threshold** - Default threshold: 0.85 - Detections below threshold are recorded but NOT redacted - Reported separately as `below_threshold_count` for manual review **Layer 3: Context-Aware Validation** - Second AI pass with full document context - Filters false positives that regex-based tools can't handle: - `[REDACTED_SECRET]` → institutional email, SKIP - `[REDACTED_SECRET]` → personal email, REDACT - "Dr. Sarah Chen" on letterhead → physician, SKIP - "Sarah Chen" on intake form → patient, REDACT - "Name:" (form label) → not PII, SKIP - "John Smith" (form value) → PII, REDACT - Invoice dates → not DOB, SKIP - "Date of Birth: 03/15/1990" → DOB, REDACT ### What Gets Detected | PII Type | Examples | |----------|----------| | `SSN` | Social Security numbers, national IDs | | `CREDIT_CARD` | Card numbers, transaction IDs tied to a person | | `EMAIL` | Personal email addresses (not institutional) | | `PHONE` | Phone numbers (all country formats) | | `NAME` | Person names (all cultures/languages) | | `ADDRESS` | Physical addresses, postal codes | | `IP_ADDRESS` | IPv4 and IPv6 addresses | | `DATE_OF_BIRTH` | Birth dates (only when labeled as DOB — not random dates) | | `PASSPORT_NUMBER` | Passport numbers | | `DRIVER_LICENSE` | Driver's licenses, registration numbers | | `BANK_ACCOUNT` | Account numbers, routing numbers | | `IBAN` | International Bank Account Numbers | | `URL` | Personal URLs and web addresses | | `MEDICAL_RECORD` | Medical record numbers, patient IDs, hospital IDs | ### PDF Redaction is Irreversible - Digital PDFs: Text is physically removed from the PDF content stream using redaction annotations — not just covered - Scanned PDFs: Pages are re-rendered as images with black bars, replacing the original - All PDFs: Metadata stripped, content streams cleaned and deflated - Copy-paste, text selection, and PDF parsing cannot recover redacted content ## API Reference ### POST /v1/pii/redact — Submit Document for Redaction **Auth:** `X-[REDACTED_SECRET]` **Content-Type:** `multipart/form-data` **Rate Limit:** 10 requests per 60 seconds | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `file` | File | Yes | — | PDF, PNG, JPEG, or TXT (max 50MB) | | `language` | string | No | `"en"` | `"en"`, `"zh"`, `"es"`, `"hi"`, `"ar"` | | `webhook_url` | string | No | — | HTTPS URL for completion notification | **Response (200 OK):** ```json { "id": [REDACTED_SECRET], "status": "queued" } ``` **Errors:** | Status | Code | Meaning | |--------|------|---------| | 400 | `INVALID_REQUEST` | Bad request parameters | | 400 | `UNSUPPORTED_FORMAT` | File type not supported | | 400 | `EMPTY_DOCUMENT` | File is empty | | 400 | `DOCUMENT_CORRUPTED` | File is corrupt or unreadable | | 400 | `PASSWORD_PROTECTED` | Document is password-protected | | 401 | `UNAUTHORIZED` | Invalid or missing API key | | 413 | `FILE_TOO_LARGE` | Exceeds 50MB size limit | | 429 | `RATE_LIMITED` | Rate limit exceeded | | 500 | `INTERNAL_ERROR` | Server error (retry or contact support) | ### GET /v1/pii/{job_id} — Get Redaction Results **Auth:** `X-[REDACTED_SECRET]` **Rate Limit:** 60 requests per 60 seconds Poll until `status` is `completed` or `failed`. **Response (completed):** ```json { "id": "550e8400-...", "status": "completed", "progress_percent": 100, "redacted_file_url": "https://...(signed URL)...", "report": { "id": "550e8400-...", "page_count": 3, "processing_time_ms": 4200, "pii_detected": { "NAME": { "count": 4, "pages": [1, 2, 3], "confidence_avg": 0.93, "confidence_min": 0.87, "below_threshold": 0, "allowed": 0 }, "SSN": { "count": 1, "pages": [1], "confidence_avg": 0.98, "confidence_min": 0.98, "below_threshold": 0, "allowed": 0 } }, "total_redactions": 5, "redaction_policy": "black_bar", "confidence_threshold_used": 0.85, "below_threshold_count": 0 }, "error": null } ``` **Response (failed):** ```json { "id": "550e8400-...", "status": "failed", "progress_percent": 0, "redacted_file_url": null, "report": null, "error": { "code": "DOCUMENT_CORRUPTED", "message": "Unable to process the document" } } ``` **Statuses:** `queued` → `processing` → `completed` or `failed` ## Code Examples ### Python ```python import requests import time [REDACTED_SECRET]" BASE = "https://api.deepread.tech" # Submit document for redaction with open("patient_record.pdf", "rb") as f: resp = requests.post( f"{BASE}/v1/pii/redact", headers={"X-API-Key": API_KEY}, files={"file": f}, ) job_id = resp.json()["id"] # Poll with backoff delay = 3 while True: time.sleep(delay) result = requests.get( f"{BASE}/v1/pii/{job_id}", headers={"X-API-Key": API_KEY} ).json() if result["status"] == "completed": # Download redacted file redacted_url = result["redacted_file_url"] redacted_pdf = requests.get(redacted_url).content with open("patient_record_redacted.pdf", "wb") as f: f.write(redacted_pdf) # Review detection report report = result["report"] print(f"Redacted {report['total_redactions']} PII instances") for pii_type, summary in report["pii_detected"].items(): print(f" {pii_type}: {summary['count']} found on pages {summary['pages']}") break elif result["status"] == "failed": print(f"Failed: {result['error']['message']}") break delay = min(delay * 1.5, 15) ``` ### JavaScript / Node.js ```javascript import fs from "fs"; const [REDACTED_SECRET]"; const BASE = "https://api.deepread.tech"; // Submit document const form = new FormData(); form.append("file", fs.createReadStream("contract.pdf")); const { id: jobId } = await fetch(`${BASE}/v1/pii/redact`, { method: "POST", headers: { "X-API-Key": API_KEY }, body: form, }).then((r) => r.json()); // Poll with backoff let delay = 3000; let result; do { await new Promise((r) => setTimeout(r, delay)); result = await fetch(`${BASE}/v1/pii/${jobId}`, { headers: { "X-API-Key": API_KEY }, }).then((r) => r.json()); delay = Math.min(delay * 1.5, 15000); } while (!["completed", "failed"].includes(result.status)); if (result.status === "completed") { console.log(`Redacted file: ${result.redacted_file_url}`); console.log(`Total redactions: ${result.report.total_redactions}`); } ``` ### cURL ```bash # Redact a PDF curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@document.pdf" # Redact a scanned image curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@id_card.png" # Redact with language hint curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@documento.pdf" \ -F "language=es" # Check status curl https://api.deepread.tech/v1/pii/JOB_ID \ -H "X-[REDACTED_SECRET]" ``` ## Workflows: Combine with Other DeepRead Skills ### Extract Then Redact Use `deepread-ocr` to extract data, then redact the original before archiving: ```bash # Step 1: Extract structured data (keeps the data you need) curl -X POST https://api.deepread.tech/v1/process \ -H "X-[REDACTED_SECRET]" \ -F "file=@claim.pdf" \ -F 'schema={"type":"object","properties":{"claim_number":{"type":"string"},"amount":{"type":"number"}}}' # Step 2: Redact PII from original (clean copy for filing) curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@claim.pdf" ``` ### Redact Before LLM Processing Strip PII before sending document content to any AI model: ```python # 1. Redact the document resp = requests.post(f"{BASE}/v1/pii/redact", headers={"X-API-Key": API_KEY}, files={"file": open("report.pdf", "rb")}) job_id = resp.json()["id"] # 2. Wait for completion, download redacted version # 3. Now safe to send to any LLM for analysis ``` ### Fill Form Then Redact Copy Use `deepread-form-fill` to complete a form, then redact a copy for records: ```bash # Step 1: Fill the form curl -X POST https://api.deepread.tech/v1/form-fill \ -H "X-[REDACTED_SECRET]" \ -F "file=@w4_form.pdf" \ -F 'form_fields={"full_name":"Jane Smith","ssn":"456-78-9012"}' # Step 2: Redact the filled form for internal records curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@w4_filled.pdf" ``` ## Best Practices ### 1. Use Webhooks for Production ```bash curl -X POST https://api.deepread.tech/v1/pii/redact \ -H "X-[REDACTED_SECRET]" \ -F "file=@document.pdf" \ -F "webhook_url=https://your-app.com/webhooks/pii" ``` Only use polling if you cannot expose a webhook endpoint. ### 2. Review the Detection Report The report tells you exactly what was found and where: ```python report = result["report"] # Check if anything was below confidence threshold if report["below_threshold_count"] > 0: print(f"Warning: {report['below_threshold_count']} detections below threshold") print("Consider manual review of the original document") # See breakdown by type for pii_type, summary in report["pii_detected"].items(): print(f"{pii_type}: {summary['count']} on pages {summary['pages']}") ``` ### 3. Set Language for Non-English Documents Always specify the language for better detection accuracy: ```bash -F "language=zh" # Chinese -F "language=es" # Spanish -F "language=hi" # Hindi -F "language=ar" # Arabic ``` ### 4. Polling Strategy Poll every 3-5 seconds with backoff: ```python delay = 3 while True: time.sleep(delay) result = check_status(job_id) if result["status"] in ("completed", "failed"): break delay = min(delay * 1.5, 15) # cap at 15s ``` ## Rate Limits & Pricing ### Free Tier (No Credit Card) - **2,000 pages/month** - **10 requests/minute** (redact endpoint) - **60 requests/minute** (status endpoint) - Full feature access ### Paid Plans - **PRO**: 50,000 pages/month, 100 req/min @ $99/mo - **SCALE**: Custom volume pricing **Upgrade:** https://www.deepread.tech/dashboard/billing?utm_source=clawhub ## Troubleshooting ### Error: `UNSUPPORTED_FORMAT` **Solution:** Only PDF, PNG, JPEG, and TXT are supported. Convert other formats first. ### Error: `EMPTY_DOCUMENT` **Solution:** File has no content. Check the file is not corrupted or zero-bytes. ### Error: `FILE_TOO_LARGE` **Solution:** Compress the file or split into smaller documents. Max 50MB. ### No PII detected in report **Possible causes:** - Document genuinely contains no PII - PII is in a language not specified (set `language` parameter) - Image quality too low for detection (try higher resolution scan) ### Redaction missed some PII **Possible causes:** - Value was below the 0.85 confidence threshold (check `below_threshold_count`) - Unusual formatting or handwritten text - Report the issue: https://github.com/deepread-tech/deep-read-service/issues ## Security Notes - This skill only calls `https://api.deepread.tech` — no other endpoints are contacted - Documents are uploaded to DeepRead servers for processing and redacted copies are returned via signed URLs - This skill does not modify any system files, install packages, or request elevated permissions - Keep `DEEPREAD_API_KEY` secret — rotate if compromised - If using webhooks, ensure your receiving endpoint uses HTTPS and is authenticated - Test with non-sensitive documents first to verify behavior - Review DeepRead's [privacy policy](https://www.deepread.tech/privacy) for data retention and handling details ## Related DeepRead Skills DeepRead is three tools with one API key: | Skill | What it does | Install | |-------|-------------|---------| | **`deepread-ocr`** | Extract text + structured JSON from any document. 97%+ accuracy. | `clawhub install uday390/deepread-ocr` | | **`deepread-form-fill`** | Fill any PDF form with AI vision — scanned forms, government PDFs | `clawhub install uday390/deepread-form-fill` | | **`deepread-pii`** | Redact sensitive data. This skill. | You're here | **Common pipeline:** Extract data (OCR) → Fill target form (Form Fill) → Redact originals for filing (PII) ## Support & Resources - **Dashboard**: https://www.deepread.tech/dashboard - **Issues**: https://github.com/deepread-tech/deep-read-service/issues - **Email**: [REDACTED_SECRET] --- **Ready to start?** Get your free API key at https://www.deepread.tech/dashboard/?utm_source=clawhub


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)