promptwall-sdk 0.5.0

Official Python SDK for PromptWall — runtime governance for LLM apps (verify, chat, events, tools) + multi-step trace observability.

promptwall

Official Python SDK for PromptWall — multi-step LLM observability (events / traces / spans).

pip install promptwall-sdk

Zero runtime dependencies — uses stdlib urllib for HTTP.

Quick start

import promptwall

pw = promptwall.PromptWall(api_key="pk_live_…")

# Datadog-style multi-step trace
with pw.trace("req-abc-123", mode="chat") as tr:

    with tr.span("retrieval") as s:
        s.metadata(chunks=5)
        # … your retrieval code …

    with tr.span("tool_call") as s:
        s.metadata(tool="calendar")
        # … your tool invocation …

    with tr.span("llm_call") as s:
        # … your LLM call …
        s.tokens(prompt=1200, completion=500)
        s.cost_usd(0.018)

# On exit of the trace context, the SDK batches all spans and
# POSTs them to /v1/events as one event.

Configuration

The SDK reads credentials in this order:

1. Constructor arg: PromptWall(api_key="...")
2. Env var: PROMPTWALL_API_KEY

Optional env vars:

Name	Default
PROMPTWALL_BASE_URL	https://api.prompt-wall.com
PROMPTWALL_TIMEOUT	5.0 (seconds)

Span DSL

Inside a with tr.span(...) as s: block, chain any of these:

Method	What it does
s.metadata(**kv)	Merge structured fields into metadata_json
s.summarize(text)	Short human-readable line (summary column)
s.tokens(prompt=N, completion=N, total=N)	Per-stage token counts
s.cost_usd(amount)	Per-stage USD cost
s.retries(n)	Per-stage retry count
s.error(code, summary?)	Mark stage as failed (status='error')
s.skip(reason?)	Mark stage as skipped

status='error' is also auto-set if the with block raises.

Direct event posting

When the context manager doesn't fit (e.g. async pipelines that collect events into a queue), use the lower-level events.send:

pw.events.send({
    "request_id": "req-1",
    "started_at": "2026-04-27T10:00:00Z",
    "finished_at": "2026-04-27T10:00:02Z",
    "spans": [
        {"stage_name": "retrieval", "latency_ms": 120,
         "metadata": {"chunks": 5}},
        {"stage_name": "llm_call",  "latency_ms": 800,
         "prompt_tokens": 1200, "completion_tokens": 500,
         "cost_usd": 0.018},
    ],
})

Send up to 500 events in one POST via the batch shape:

pw.events.send({"events": [event1, event2, ...]})

Errors

try:
    pw.events.send(...)
except promptwall.AuthError:
    # 401/403 — bad / revoked / wrong-scoped API key
except promptwall.NetworkError:
    # transport error — retry-eligible
except promptwall.PromptWallError:
    # base for everything SDK-raised

Observability is best-effort — most apps should swallow errors at the call site so a temporary outage at PromptWall doesn't break the customer-facing request path.

Versioning

Semver. The 0.x line accepts breaking API changes between minor versions; 1.0 will pin the public surface.

License

MIT.