Metadata-Version: 2.4
Name: promptwall-sdk
Version: 0.5.0
Summary: Official Python SDK for PromptWall — runtime governance for LLM apps (verify, chat, events, tools) + multi-step trace observability.
Author-email: PromptWall <support@prompt-wall.com>
License: MIT
Project-URL: Homepage, https://www.prompt-wall.com
Project-URL: Documentation, https://docs.prompt-wall.com
Project-URL: Repository, https://github.com/Extreme421n/PromptWall-full-backup
Project-URL: Issues, https://github.com/Extreme421n/PromptWall-full-backup/issues
Keywords: promptwall,llm,observability,tracing,spans,ai-security,governance,datadog
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# promptwall

Official Python SDK for [PromptWall](https://www.prompt-wall.com) — multi-step LLM observability (events / traces / spans).

```bash
pip install promptwall-sdk
```

Zero runtime dependencies — uses stdlib `urllib` for HTTP.

## Quick start

```python
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`:

```python
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:

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

## Errors

```python
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.
