raipii 0.1.0

Python SDK for the raipii PII detection and sanitization API

raipii Python SDK

Detect and sanitize PII before it reaches your LLM. Replace real data with tokens or realistic fakes. Restore original values after the model responds.

---

Install

pip install raipii

Requires Python 3.8+. The only dependency is requests.

---

Quick start

import raipii

ps = raipii.Raipii(api_key="ps_live_...")

# 1. Sanitize — strip PII before sending to your LLM
result = ps.sanitize(
    "Hi, I'm John Smith — [e-mail], SSN 392-45-7810",
    mode="fake_substitute",
)
print(result.sanitized_text)
# "Hi, I'm Michael Torres — [e-mail], SSN 847-23-1956"

# 2. Call your LLM with the sanitized prompt
llm_response = your_llm(result.sanitized_text)

# 3. Restore — put original values back in the response
original = ps.restore(llm_response, result.session_id)
print(original.restored_text)
# "Hi, I'm John Smith — [e-mail], SSN 392-45-7810"

Set RAIPII_API_KEY in your environment to avoid passing the key in code:

export RAIPII_API_KEY=ps_live_...

ps = raipii.Raipii()  # reads RAIPII_API_KEY automatically

Get a free API key (2M chars/month) at raipii.com.

---

Sanitize modes

token (default)

Replaces PII with labelled placeholder tokens. Safe, lossless, fully reversible.

result = ps.sanitize(
    "Schedule a call with Jane Doe at [e-mail] on 555-867-5309",
    mode="token",
)
print(result.sanitized_text)
# "Schedule a call with [PERSON_1] at [EMAIL_1] on [PHONE_1]"

# Each token maps back to its original value on restore
restored = ps.restore(llm_response, result.session_id)

fake_substitute

Replaces PII with realistic Faker-generated values. The LLM sees natural data and produces better output. All substitutions are reversed on restore.

result = ps.sanitize(
    "Write a summary for John Smith, DOB 1985-03-12, SSN 392-45-7810",
    mode="fake_substitute",
)
print(result.sanitized_text)
# "Write a summary for Michael Torres, DOB 1991-07-24, SSN 847-23-1956"

restored = ps.restore(llm_response, result.session_id)
# LLM response has fake values swapped back to real ones

redact

Replaces PII with [REDACTED]. One-way — there is nothing to restore. Use when the LLM response must never reference PII at all.

result = ps.sanitize(
    "Patient John Smith, MRN 00123456, DOB 1985-03-12",
    mode="redact",
)
print(result.sanitized_text)
# "Patient [REDACTED], MRN [REDACTED], DOB [REDACTED]"

---

Detect only

Scan text for PII without modifying it. Useful for logging, compliance auditing, or deciding whether to sanitize.

result = ps.detect("My SSN is 392-45-7810 and email is [e-mail]")

print(result.pii_detected)   # True
print(result.risk_level)     # "HIGH"

for entity in result.entities_found:
    print(f"  {entity.type}: {entity.value!r} at {entity.position} ({entity.confidence:.0%} confidence)")
# US_SSN: '392-45-7810' at (10, 21) (100% confidence)
# EMAIL:  '[e-mail]' at (35, 48) (100% confidence)

Risk levels: NONE → LOW → MEDIUM → HIGH

Risk	Triggered by
HIGH	SSN, credit card, MRN, bank account, tax ID
MEDIUM	Person name, email, date of birth, address
LOW	Any other detected entity
NONE	No PII found

---

Detected entity types

Type	Example	Tier
PERSON	John Smith	All tiers
EMAIL	[e-mail]	All tiers
PHONE	555-867-5309	All tiers
US_SSN	392-45-7810	All tiers
CREDIT_CARD	4111 1111 1111 1111	All tiers
DATE_OF_BIRTH	1985-03-12	All tiers
ADDRESS	123 Main St, Austin TX	Growth+
IP_ADDRESS	192.168.1.1	All tiers
MEDICAL_RECORD_NUMBER	MRN 00123456	All tiers
BANK_ACCOUNT	12345678	All tiers
TAX_ID	12-3456789	All tiers
IBAN	GB29 NWBK 6016 1331 9268 19	All tiers
JWT	eyJhbGci...	All tiers
AWS_KEY	AKIA...	All tiers

Starter tier detects structured PII reliably. Growth and Business tiers add enhanced contextual detection with higher accuracy for unstructured entities such as names and addresses.

---

Multi-turn conversations

Keep consistent fake substitutions across all turns of a conversation. The same entity always maps to the same fake value within a session.

conv = ps.conversations.create(ttl=86400)  # 24hr TTL

# Turn 1
turn1 = ps.sanitize(
    "My name is John Smith. What should I know about my account?",
    mode="fake_substitute",
    conversation_id=conv.conversation_id,
)
llm_reply_1 = your_llm(turn1.sanitized_text)
response1 = ps.restore(llm_reply_1, turn1.session_id)

# Turn 2 — "John Smith" maps to the SAME fake name as turn 1
turn2 = ps.sanitize(
    "What were you saying about John Smith earlier?",
    mode="fake_substitute",
    conversation_id=conv.conversation_id,
)
llm_reply_2 = your_llm(turn2.sanitized_text)
response2 = ps.restore(llm_reply_2, turn2.session_id)

---

Error handling

from raipii import (
    AuthenticationError,
    QuotaExceededError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServiceUnavailableError,
)

try:
    result = ps.sanitize(text)
except AuthenticationError:
    # Invalid or missing API key
    print("Check your API key at raipii.com")
except QuotaExceededError:
    # Monthly character limit reached
    print("Upgrade your plan at raipii.com")
except NotFoundError:
    # Session expired or not found
    print("Session expired — re-sanitize the original text")
except RateLimitError:
    # Too many requests — SDK retries automatically, this means retries exhausted
    print("Rate limit hit")
except ServiceUnavailableError:
    # Detection backend temporarily unavailable — SDK retried 3 times
    print("Service unavailable, try again shortly")
except ValidationError as e:
    print(f"Bad request: {e}")

All exceptions inherit from raipii.RaipiiError and expose .status_code and .response.

---

Retry behaviour

The SDK automatically retries on 429 Too Many Requests and 503 Service Unavailable with exponential backoff:

Attempt	Delay
1st retry	1s
2nd retry	2s
3rd retry	4s

Default max_retries=3. Override:

ps = raipii.Raipii(api_key="...", max_retries=5)
ps_no_retry = raipii.Raipii(api_key="...", max_retries=0)

---

Client options

ps = raipii.Raipii(
    api_key="ps_live_...",    # or RAIPII_API_KEY env var
    base_url="https://api.raipii.com",  # override for testing
    timeout=30,               # request timeout in seconds
    max_retries=3,            # retries on 429/503
)

---

Return types

SanitizeResult

Field	Type	Description
session_id	str	Pass to restore()
sanitized_text	str	Text with PII replaced
entities_found	list[EntityFound]	Each detected entity
char_count	int	Characters processed
usage.chars_billed	int	Characters billed
conversation_id	str | None	Echo of the conversation_id passed in

RestoreResult

Field	Type	Description
restored_text	str	Text with original PII restored
substitutions_reversed	int	Number of tokens replaced
usage.chars_billed	int	Characters billed

DetectResult

Field	Type	Description
entities_found	list[DetectedEntity]	Detected PII entities
pii_detected	bool	True if any PII found
risk_level	str	NONE / LOW / MEDIUM / HIGH
usage.chars_billed	int	Characters billed

---

Caveats

• Session TTL — sessions expire after session_ttl seconds (default 1hr). Calling restore() after expiry raises NotFoundError. Store the session_id and call restore promptly after getting the LLM response.
• redact mode has no restore — [REDACTED] tokens contain no reversible information. Calling restore() on a redact session returns the text unchanged.
• Conversation TTL — conversation sessions expire after their TTL (default 24hr). After expiry, new turns start a fresh mapping.
• Characters billed — both sanitize and restore bill by character count of the input text. detect also bills. Free tier: 2M chars/month.
• Starter tier detects structured PII reliably. Upgrade to Growth for enhanced contextual detection of names and addresses in free-form text.

---

Get an API key

Free tier — 2M characters/month, no credit card required: raipii.com