> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Client-Side Redaction
> Detect and remove PII from transcripts and recordings with your own AI providers, before anything reaches Cekura
export const CopyPageButton = () => {
if (typeof window !== 'undefined') {
setTimeout(function () {
if (document.getElementById('ck-tools')) return;
var anchor = document.getElementById('content-area') || document.querySelector('.mdx-content');
if (!anchor) return;
if (!document.getElementById('ck-style')) {
var s = document.createElement('style');
s.id = 'ck-style';
s.textContent = '#ck-tools{position:absolute;top:6px;right:0;z-index:100;font-family:inherit;}' + '.ck-row{display:inline-flex;align-items:stretch;border:1px solid rgba(0,0,0,0.15);border-radius:8px;overflow:hidden;background:#fff;}' + ':root.dark .ck-row{background:rgba(255,255,255,0.06);border-color:rgba(255,255,255,0.12);}' + '.ck-btn{padding:5px 12px;border:none;background:none;cursor:pointer;font-size:13px;font-weight:500;font-family:inherit;color:#374151;}' + ':root.dark .ck-btn{color:#d1d5db;}' + '.ck-btn:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-btn:hover{background:rgba(255,255,255,0.06);}' + '.ck-chevron{padding:5px 8px;border:none;background:none;cursor:pointer;font-size:14px;font-family:inherit;color:#374151;}' + ':root.dark .ck-chevron{color:#d1d5db;}' + '.ck-chevron:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-chevron:hover{background:rgba(255,255,255,0.06);}' + '.ck-divider{width:1px;background:rgba(0,0,0,0.12);flex-shrink:0;}' + ':root.dark .ck-divider{background:rgba(255,255,255,0.12);}' + '.ck-dd{position:absolute;top:calc(100% + 4px);right:0;min-width:180px;background:#fff;border:1px solid rgba(0,0,0,0.12);border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.1);padding:4px;display:none;z-index:200;}' + ':root.dark .ck-dd{background:#1f2937;border-color:rgba(255,255,255,0.1);box-shadow:0 4px 16px rgba(0,0,0,0.35);}' + '.ck-item{display:block;width:100%;padding:7px 12px;border:none;background:none;border-radius:6px;cursor:pointer;font-size:13px;font-family:inherit;text-align:left;color:#374151;}' + ':root.dark .ck-item{color:#d1d5db;}' + '.ck-item:hover{background:rgba(0,0,0,0.05);}' + ':root.dark .ck-item:hover{background:rgba(255,255,255,0.07);}';
document.head.appendChild(s);
}
var wrap = document.createElement('div');
wrap.id = 'ck-tools';
var row = document.createElement('div');
row.className = 'ck-row';
var mainBtn = document.createElement('button');
mainBtn.className = 'ck-btn';
mainBtn.textContent = 'Copy page';
var divider = document.createElement('span');
divider.className = 'ck-divider';
var chevron = document.createElement('button');
chevron.className = 'ck-chevron';
chevron.textContent = '▾';
var dd = document.createElement('div');
dd.className = 'ck-dd';
function closeDD() {
dd.style.display = 'none';
}
function openDD() {
dd.style.display = 'block';
}
chevron.onclick = function (e) {
e.stopPropagation();
if (dd.style.display === 'block') {
closeDD();
} else {
openDD();
}
};
document.addEventListener('click', function (e) {
if (!e.target.closest('#ck-tools')) {
closeDD();
}
});
document.addEventListener('keydown', function (e) {
if (e.key === 'Escape') {
closeDD();
}
});
function makeItem(label, fn) {
var b = document.createElement('button');
b.className = 'ck-item';
b.textContent = label;
b.onclick = function () {
fn();
closeDD();
};
return b;
}
function getMarkdown() {
var walk = function (node) {
if (!node) return '';
if (node.nodeType === 3) return node.textContent || '';
if (node.nodeType !== 1) return '';
var tag = node.tagName.toLowerCase();
var skip = ['script', 'style', 'svg', 'noscript', 'button', 'iframe'];
if (skip.indexOf(tag) !== -1) return '';
if (node.id === 'ck-tools') return '';
var ch = Array.from(node.childNodes).map(walk).join('');
if (tag === 'h1') return '\n# ' + ch.trim() + '\n\n';
if (tag === 'h2') return '\n## ' + ch.trim() + '\n\n';
if (tag === 'h3') return '\n### ' + ch.trim() + '\n\n';
if (tag === 'p') return '\n' + ch.trim() + '\n\n';
if (tag === 'pre') return '\n```\n' + node.textContent.trim() + '\n```\n\n';
if (tag === 'li') return '- ' + ch.trim() + '\n';
if (tag === 'code') return '`' + ch.trim() + '`';
return ch;
};
var content = document.querySelector('.mdx-content') || document.getElementById('content-area') || document.body;
return walk(content).replace(/\n\n\n+/g, '\n\n').trim();
}
function copyMd() {
var md = getMarkdown();
navigator.clipboard.writeText(md).then(function () {
mainBtn.textContent = 'Copied!';
setTimeout(function () {
mainBtn.textContent = 'Copy page';
}, 2000);
});
}
function viewMd() {
var md = getMarkdown();
var safe = md.split('&').join('&').split('<').join('<').split('>').join('>');
var html = '' + safe + '';
window.open(URL.createObjectURL(new Blob([html], {
type: 'text/html'
})), '_blank');
}
function openClaude() {
var prompt = 'Can you read this Cekura docs page ' + window.location.href + ' so I can ask you questions?';
window.open('https://claude.ai/new?q=' + encodeURIComponent(prompt), '_blank');
}
mainBtn.onclick = copyMd;
dd.appendChild(makeItem('Copy page', copyMd));
dd.appendChild(makeItem('View as Markdown', viewMd));
dd.appendChild(makeItem('Open in Claude', openClaude));
row.appendChild(mainBtn);
row.appendChild(divider);
row.appendChild(chevron);
wrap.appendChild(row);
wrap.appendChild(dd);
anchor.style.position = 'relative';
anchor.insertBefore(wrap, anchor.firstChild);
}, 50);
}
return null;
};
## When to use this
[PII Redaction](/documentation/guides/observability/pii-redaction) runs **after** ingestion: you send the call with `redact_fields`, and Cekura detects and removes the entities from the stored transcript and recording.
Client-side redaction runs **before** ingestion: detection and removal happen in your own process, on your own LLM and speech-to-text providers, with your own API keys. The sensitive values never reach Cekura at all. Use it when:
* Your compliance posture requires that raw PII never leaves your network.
* Your organization is required to use specific model providers or regions for any system that processes customer data.
* You need to scrub fields that server-side redaction does not cover. `redact_fields` applies to the transcript and the audio recording; `metadata`, `dynamic_variables` and `customer_number` are stored as you send them.
The two are complementary. Client-side redaction costs you nothing in Cekura credits but requires you to run the detection; server-side redaction is one parameter and costs 0.4 credits per minute. See [Combining both](#combining-both).
## How it works
The script covers the transcript **and** the recording, and detects entities automatically — you do not have to know the sensitive values in advance.
The transcript is sent to **your** LLM with a detection prompt, which returns every PII span it found as `{original_text, replacement_token}`. Detection is context-driven rather than pattern-driven, so it catches what a regex cannot: dictated digits (`"four one five, five five five"`), spelled-out names (`"is that spelled b e n?"`), and spoken emails (`"a at gmail dot com"`).
Each span is replaced with the same placeholder token Cekura's server-side redaction emits (``, ``, ``, …), applied per JSON string leaf so roles, timings and tool-call IDs survive intact.
The audio is transcribed with word-level timestamps by **your** STT provider, PII is detected on that transcription, each span is mapped back to its time range in the waveform, and those ranges are replaced with a tone.
**Redaction fails closed.** If detection fails, or a detected span cannot be aligned to the audio, the script raises `RedactionError` instead of returning content. Never catch that error and upload the original — that is the one mistake in this whole flow that silently ships raw PII.
## What you need
| | Requirement | Notes |
| ---------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **LLM** | An endpoint that supports tool calling | Any OpenAI-compatible `/chat/completions` API works out of the box — OpenAI, Azure OpenAI, or a self-hosted or gateway deployment. Other providers plug in with a small adapter. |
| **STT** | Word-level timestamps | Required only for audio. Without word timings there is nothing to align a detected span to. |
| **Python** | `pydub` + `ffmpeg` | Required only for audio. The transcript path is standard library only. |
## The script
```python cekura_redact.py theme={null}
"""
Client-side PII redaction for Cekura observability payloads.
Detects and removes PII from the transcript *and* the audio recording before
either leaves your infrastructure, using your own LLM and speech-to-text
providers and your own API keys. Nothing is sent to Cekura until it is scrubbed.
from cekura_redact import openai_compatible_detector, openai_compatible_transcriber
from cekura_redact import redact_payload, redact_audio
detect = openai_compatible_detector(
base_url="https://api.openai.com/v1", api_key=OPENAI_KEY, model="gpt-4.1-mini")
transcribe = openai_compatible_transcriber(
base_url="https://api.openai.com/v1", api_key=OPENAI_KEY, model="whisper-1")
FIELDS = ["person_name", "phone_number", "email_address", "location", "ssn"]
payload = redact_payload(payload, FIELDS, detector=detect)
clean_audio = redact_audio(raw_audio_bytes, FIELDS, detector=detect, transcriber=transcribe)
Dependencies: none for the transcript path (standard library only).
The audio path needs `pydub` and `ffmpeg` for any format other than WAV.
"""
from __future__ import annotations
import io
import json
import re
import urllib.request
import uuid
from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
# Placeholder tokens match the ones Cekura's server-side redaction emits, so a
# call scrubbed here reads the same as one scrubbed with `redact_fields`.
ENTITY_TO_TOKEN: Dict[str, str] = {
"person_name": "",
"age": "",
"phone_number": "",
"email_address": "",
"date": "",
"time": "
## Using it
Scrub the payload and the recording, then send both. The spans found on the transcript are passed into the audio pass as `supplemental_spans`: each pass detects on its own text, so the union beeps entities either one alone would have missed.
```python theme={null}
import json
import os
import requests
from cekura_redact import (
RedactionError,
openai_compatible_detector,
openai_compatible_transcriber,
redact_audio,
redact_payload,
)
FIELDS = [
"person_name", "phone_number", "email_address",
"location", "dob", "ssn", "credit_card", "money",
]
detect = openai_compatible_detector(
base_url=os.environ["LLM_BASE_URL"], # your provider, your key
api_key=os.environ["LLM_API_KEY"],
model="gpt-4.1-mini",
)
transcribe = openai_compatible_transcriber(
base_url=os.environ["STT_BASE_URL"],
api_key=os.environ["STT_API_KEY"],
model="whisper-1",
)
payload = {
"call_id": call.id,
"agent": AGENT_ID,
"transcript_type": "vapi",
"transcript_json": call.transcript,
"customer_number": call.from_number,
"metadata": {"customer_id": customer.id, "name": customer.full_name},
}
try:
clean_payload, spans = redact_payload(payload, FIELDS, detect, return_spans=True)
clean_audio = redact_audio(
raw_audio_bytes, FIELDS, detect, transcribe,
supplemental_spans=spans, # spans found on the transcript
audio_format="mp3",
)
except RedactionError:
# Fail closed. Do not fall back to sending the original.
raise
# Multipart upload: JSON fields are serialized, the recording is a file part.
form = dict(clean_payload)
form["transcript_json"] = json.dumps(form["transcript_json"])
form["metadata"] = json.dumps(form["metadata"])
requests.post(
"https://api.cekura.ai/observability/v1/observe/",
data=form,
files={"voice_recording": ("call.mp3", clean_audio, "audio/mpeg")},
headers={"X-CEKURA-API-KEY": os.environ["CEKURA_API_KEY"]},
timeout=60,
)
```
If you host the redacted recording yourself, send `voice_recording_url` in a JSON body instead of uploading `voice_recording` as multipart — the payload is otherwise identical.
**Transcript before:**
```json theme={null}
{ "role": "user", "message": "It's Jane Doe, my number's four one five, five five five, oh one two three.", "time": 4.2 }
```
**Transcript after:**
```json theme={null}
{ "role": "user", "message": "It's , my number's .", "time": 4.2 }
```
The recording gets a tone over `0:04.2–0:09.6` — the span where those words were spoken — and is otherwise byte-for-byte the same length, so transcript timings still line up with the audio in the Cekura player.
## Bringing your own providers
`detector` and `transcriber` are plain callables. The two adapters in the script cover OpenAI-compatible endpoints; anything else is a short function with the same contract.
Takes the prompt string, returns a list of `{"original_text": ..., "replacement_token": ...}` — or `None` if the call failed. Returning `None` is what makes the script fail closed, so never return `[]` on an error: an empty list means "this transcript contains no PII".
```python theme={null}
def detect(prompt: str) -> list[dict] | None:
try:
response = my_provider.generate(prompt, tools=[SUBMIT_TOOL], temperature=0)
except Exception:
return None
return response.tool_call.arguments["redactions"]
```
Use a tool call or structured-output mode rather than free-form text — the spans must come back parseable, and `original_text` must be verbatim or the replacement silently misses.
Takes the audio bytes, returns `(full_text, words)` where each word is `{"text": ..., "start": , "end": }`. Most STT APIs return this shape under a different key:
```python theme={null}
def transcribe(audio_bytes: bytes) -> tuple[str, list[dict]]:
result = my_stt.transcribe(audio_bytes, word_timestamps=True)
words = [
{"text": w["word"], "start": w["start_time"], "end": w["end_time"]}
for w in result["words"]
]
if not words:
raise RedactionError("no word timestamps; cannot align audio")
return result["text"], words
```
Whatever provider you use, confirm word timings are in **seconds** — some APIs return milliseconds or nanoseconds, and a unit mismatch beeps the wrong part of the call without any error.
Detection is a long-context extraction task with a strict verbatim-copy requirement, not a reasoning task. A mid-tier instruction-following model with reliable tool calling is the right trade-off; run it at `temperature=0`.
Do not cap output tokens tightly. The prompt asks for one entry per occurrence, so a long call with repeated PII produces a long span list, and a truncated tool call fails to parse — which correctly fails closed, but wastes the run.
## Optional: pinning values you already know
Detection is automatic, so `known_values` is optional. Pass it when a specific value must never survive — the caller's name and address from your CRM, say — and those literals are scrubbed deterministically on top of whatever the model found:
```python theme={null}
clean = redact_payload(
payload, FIELDS, detect,
known_values={
"person_name": [customer.full_name, customer.first_name],
"location": [customer.street_address],
"account_number": [customer.account_number],
},
)
```
The script also runs a small deterministic sweep of its own for the unambiguous cases — currency amounts, month-and-day dates, well-formed emails, IPs, SSNs and phone numbers — so a value the model misreads as something else is still caught.
## Combining both
Scrub the payload and beep the recording yourself, and send neither `redact_fields` nor raw audio. Nothing unredacted ever leaves your network, and no redaction credits are charged.
Scrub the JSON yourself — including the `metadata` and `dynamic_variables` that `redact_fields` does not reach — and let Cekura redact the recording on ingest by sending `redact_fields`.
```json Client-side transcript scrub + server-side audio redaction theme={null}
{
"call_id": "call_12345678",
"agent": 1,
"transcript_json": "[ ...already scrubbed on your side... ]",
"voice_recording_url": "https://recordings.example.com/call_12345678.mp3",
"redact_fields": ["person_name", "phone_number", "email_address"]
}
```
Sending `redact_fields` costs **0.4 credits per minute** regardless of how many fields are listed. If your client-side pass already covers you and you are not sending raw audio, omit `redact_fields` entirely.
## Limits
* **Detection quality is your model's.** The prompt in the script is the same approach Cekura's own redaction uses, but the result depends on the model behind it. Evaluate on your own calls before trusting it in production.
* **Audio alignment needs an accurate transcription.** A span the STT transcribed differently cannot be aligned, and the script fails closed rather than shipping partially redacted audio. If that happens often, the fix is a better STT model, not looser alignment.
* **Two providers, two failure modes.** Detection and transcription are network calls in your ingestion path. Give them generous timeouts and decide up front what you do with a call whose redaction failed — the safe default is to skip sending it.
* **Redaction is irreversible.** Cekura only ever sees the tokens and the beeps, so a redacted value cannot be recovered later for debugging. Keep your own mapping if you need one.
* **Broad fields cost context.** Enabling `numerical_pii` tokenizes order and confirmation numbers too, which can make metrics about those flows harder to evaluate. Enable the narrowest set that satisfies your policy.
## Verifying before you roll out
Run the script over a batch of real calls and inspect what changed before putting it in the ingestion path:
```python theme={null}
import json
from cekura_redact import redact_payload
with open("sample_payloads.jsonl") as fh:
for line in fh:
raw = json.loads(line)
clean, spans = redact_payload(raw, FIELDS, detect, return_spans=True)
print(raw["call_id"], len(spans), "spans")
for span in spans:
print(" ", span["replacement_token"], "<-", span["original_text"][:60])
```
Read the span list, not just the output: a short list on a call you know contains PII means detection under-fired, and that is the failure worth catching before it reaches production. Then send a handful of scrubbed calls to a throwaway agent and confirm the transcripts read the way you expect, the recording plays with tones in the right places, and your metrics still evaluate against them.