Skip to main content

WonderwallAi

CI Python 3.10+ License: MIT

AI firewall SDK for LLM applications. Protect against prompt injection, data leaks, and off-topic abuse.

Why WonderwallAi?

WonderwallAi Hosted APIs (Lakera, etc.) Heavy Frameworks
Latency <2ms in-process for 90% of threats · <300ms with full LLM scan 50-200ms round trip Varies
Privacy Messages never leave your server Sent to third-party Varies
Integration 3 lines of code API key + HTTP calls Wrap your entire pipeline
Cost Free SDK, hosted API from $0/mo $0.001+ per request Free but complex
Offline Works without internet (semantic router) Requires internet Varies

What It Does

WonderwallAi sits between your users and your LLM, scanning messages in both directions:

Inbound (user to LLM):

  • Semantic Router — Blocks off-topic queries using vector similarity against your allowed topics
  • Sentinel Scan — Detects prompt injection attacks using a fast LLM classifier (Groq)

Outbound (LLM to user):

  • Egress Filter — Catches leaked API keys, PII, and canary tokens before they reach the user
  • File Sanitizer — Validates uploads by magic bytes and strips EXIF metadata

All layers are fail-open by default — errors allow messages through rather than blocking legitimate users.

Installation

# Lightweight (egress filter only — no ML dependencies)
pip install wonderwallai

# Full install (all layers including semantic routing + sentinel)
pip install wonderwallai[all]

# Individual layers
pip install wonderwallai[semantic]   # + sentence-transformers + torch
pip install wonderwallai[sentinel]   # + groq
pip install wonderwallai[files]      # + Pillow + filetype

Quick Start

from wonderwallai import Wonderwall
from wonderwallai.patterns.topics import ECOMMERCE_TOPICS

wall = Wonderwall(
    topics=ECOMMERCE_TOPICS,
    sentinel_api_key="gsk_...",
    bot_description="a customer service chatbot for an online store",
)

# Scan user input before it reaches your LLM
verdict = await wall.scan_inbound(user_message)
if not verdict.allowed:
    return verdict.message  # User-friendly rejection

# Generate a canary token and inject it into your LLM system prompt
canary = wall.generate_canary(session_id)
system_prompt += wall.get_canary_prompt(canary)

# Scan LLM output before it reaches the user
verdict = await wall.scan_outbound(llm_response, canary)
response_text = verdict.message  # Cleaned text (API keys/PII redacted)

Configuration

All parameters have sensible defaults. Pass them as keyword arguments or use a WonderwallConfig object:

from wonderwallai import Wonderwall, WonderwallConfig

# Keyword arguments
wall = Wonderwall(
    topics=["Order tracking", "Returns", "Product questions"],
    similarity_threshold=0.35,
    sentinel_api_key="gsk_...",
    sentinel_model="llama-3.1-8b-instant",
    bot_description="a customer service chatbot",
    canary_prefix="MYAPP-",
    fail_open=True,
    block_message="I can only help with topics I'm designed for.",
)

# Or use a config object
config = WonderwallConfig(topics=["..."], ...)
wall = Wonderwall(config=config)

Key Parameters

Parameter Default Description
topics [] Allowed conversation topics. Empty disables semantic routing.
similarity_threshold 0.35 Cosine similarity threshold (0.0-1.0).
embedding_model None Pre-loaded SentenceTransformer instance (saves memory).
sentinel_api_key "" Groq API key. Falls back to GROQ_API_KEY env var.
sentinel_model "llama-3.1-8b-instant" Model for the sentinel classifier.
bot_description "an AI assistant" Used in the sentinel system prompt.
canary_prefix "WONDERWALL-" Prefix for generated canary tokens.
fail_open True Allow messages through on errors (vs block).
block_message Generic Message shown when semantic router blocks.
block_message_injection Generic Message shown when sentinel blocks.

Pre-Built Topic Sets

from wonderwallai.patterns.topics import (
    ECOMMERCE_TOPICS,   # 18 shopping/order topics
    SUPPORT_TOPICS,     # 13 technical support topics
    SAAS_TOPICS,        # 14 SaaS product topics
)

# Combine topic sets
wall = Wonderwall(topics=ECOMMERCE_TOPICS + SUPPORT_TOPICS)

Custom Patterns

Extend the built-in API key and PII detection patterns:

import re
from wonderwallai.patterns.api_keys import DEFAULT_API_KEY_PATTERNS

wall = Wonderwall(
    api_key_patterns=[re.compile(r'myapp_[a-zA-Z0-9]{32}')],
    pii_patterns={"employee_id": re.compile(r'EMP-\d{6}')},
    include_default_patterns=True,  # Merge with built-in patterns
)

How the Verdict Works

Every scan returns a Verdict object:

verdict = await wall.scan_inbound(message)

verdict.allowed      # bool — True if message passes
verdict.action       # "allow" | "block" | "redact"
verdict.blocked_by   # "semantic_router" | "sentinel_scan" | "egress_filter" | None
verdict.message      # The (possibly cleaned) text or block message
verdict.violations   # List of violation codes
verdict.scores       # Layer scores, e.g. {"semantic": 0.72}

Architecture

User Message
    |
    v
[Semantic Router] ---> cosine similarity vs allowed topics (sub-ms)
    |
    v
[Sentinel Scan] -----> LLM binary classifier via Groq (~100ms)
    |
    v
Your LLM (GPT, Claude, Llama, etc.)
    |
    v
[Egress Filter] -----> canary tokens, API keys, PII detection
    |
    v
User Response (cleaned)

Hosted API

Don't want to self-host? Use the WonderwallAi hosted API:

curl -X POST https://api.wonderwallai.com/v1/scan/inbound \
  -H "Authorization: Bearer ww_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I track my order?"}'

Plans start at $0/month (1,000 scans). See pricing.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Metadata

Release files for wonderwallai 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wonderwallai 0.1.1
File Size Uploaded Provenance Actions
wonderwallai-0.1.1.tar.gz 92.7 kB Without provenance Details for wonderwallai-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wonderwallai 0.1.1
File Interpreter ABI Platform Actions
wonderwallai-0.1.1-py3-none-any.whl Python 3 none any Details for wonderwallai-0.1.1-py3-none-any.whl

Total release size: 112.2 kB

Release files / wonderwallai-0.1.1.tar.gz

Download URL wonderwallai-0.1.1.tar.gz
Size 92.7 kB
Tags Source
SHA-256 checksum
How to use checksums
782c8b43ae3557b3d9489047b26ede74d230d5a4a00765e417a5053741a754cc
BLAKE2b-256 checksum
How to use checksums
9f00c06e7ab74aa4a3d1ca94f51136ff39825f1d1b6587d9cd3926ed804475ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.5

Release files / wonderwallai-0.1.1-py3-none-any.whl

Download URL wonderwallai-0.1.1-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
740b526c22088954ce5913d4391dadfd2021c3b444209cde2303e790a05ac1b0
BLAKE2b-256 checksum
How to use checksums
57e2b3ead09cb076e412ef96c3b2e572a88ad6df4b99eae5a315ee4d08491368
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.5

Security for wonderwallai 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page