PsiGuard SDK — Add AI Monitoring to Your Pipeline

🚀

Quick Start

PsiGuard wraps around your existing AI calls. You keep your current model setup — PsiGuard adds a monitoring layer on top. No infrastructure changes required.

💡

One integration point. PsiGuard monitors the exchange between your app and your LLM. You pass in the prompt and the response — PsiGuard scores the response in real time and tells you whether to deliver it or block it.

Step 1 — Install

terminal

pip install psiguard

Step 2 — Initialize

init.py

from psiguard import PsiGuard

guard = PsiGuard(
    openai_api_key="sk-...",     # or set OPENAI_API_KEY env var
    risk_threshold=70,           # block if risk score >= 70 (0–100)
)

Step 3 — Monitor

pipeline.py

# Your existing LLM call — unchanged
ai_response = your_llm.chat(user_message)

# Add PsiGuard check
result = guard.check(
    prompt=user_message,
    response=ai_response,
    thread_id=session_id       # tracks drift across the conversation
)

if result.should_block:
    return {
        "blocked": True,
        "reason": result.explanation,
        "state":  result.state.label
    }

return ai_response   # cleared — deliver to user

⚠️

That's the whole integration. Three lines added to your existing pipeline. Everything else happens inside PsiGuard automatically.

📁

Package Structure

PsiGuard is a single-import package. The public API surface is intentionally small — one class, three methods. Internal implementation details are abstracted away by design.

psiguard/ — package structure

psiguard/ __init__.py — exports PsiGuard, PsiGuardDecision psiguard_core.py — PsiGuard class (your integration point) psi_guard_wrapper.py — internal engine orchestration psi_llm_clients.py — LLM provider adapters (OpenAI, Anthropic, Gemini) psiguard_clean_logger.py — structured session logging metrics/ — cognitive scoring engine (internal) ... — proprietary implementation
your_app/ app.py └── from psiguard import PsiGuard ← your only import

🔒

The metrics engine is internal. The cognitive scoring framework that powers PsiGuard is proprietary and not part of the public API. You interact with it exclusively through the PsiGuard class — which is intentional. Implementation details never leak into your pipeline.

🛡️

The Guard Class

The PsiGuard class is your complete integration surface. Initialize once per application, then call .check() on every AI response you want monitored.

__init__ PsiGuard(openai_api_key, anthropic_api_key, risk_threshold, ...) ▼

Initialize PsiGuard with your LLM provider credentials. Call this once at app startup — the instance is thread-safe and reusable across all conversations.

Parameter	Type	Default	Description
openai_api_key	str \| None	`None`	OpenAI API key. Falls back to `OPENAI_API_KEY` env var if not provided.
anthropic_api_key	str \| None	`None`	Anthropic API key. Falls back to `ANTHROPIC_API_KEY` env var if not provided.
risk_threshold	int	`70`	Risk score (0–100) at which PsiGuard will block a response. Lower = stricter. 70 is the recommended production default.
embedding_provider	str	`"openai"`	Embedding backend. `"openai"` or `"anthropic"`. Should match your primary LLM provider.

FREE .check(prompt, response, thread_id) → PsiGuardDecision ▼

The core monitoring method. Pass in any prompt/response pair and PsiGuard scores the response across all four cognitive metrics, classifies the state, and returns a blocking decision. Call this on every AI response in your pipeline.

Parameter	Type	Default	Description
prompt	str	—	The user prompt sent to the AI. Used to score relevance and detect prompt injection attempts.
response	str	—	The AI-generated response to monitor. PsiGuard scores this against all four cognitive dimensions.
thread_id	str	`"default"`	Conversation identifier. PsiGuard tracks behavioral drift across turns within the same thread. Use a unique ID per user session.

Returns — PsiGuardDecision

Field	Type	Description
should_block	bool	Whether PsiGuard recommends blocking this response. Check this first.
explanation	str	Human-readable reason for the decision. Useful for logging and debugging.
state.label	str	Classified cognitive state: `STABLE`, `WATCH`, or `WARNING`.

method .reset_thread(thread_id) → None ▼

Clears the monitoring state for a specific conversation thread. Call this when a user starts a new session, logs out, or when you want to reset the drift baseline without reinitializing the full guard instance.

Parameter	Type	Description
thread_id	str	The conversation thread ID to clear. Must match the ID used in `.check()`.

PRO .get_thread_summary(thread_id) → dict ▼

Returns a full metric summary for a conversation thread — aggregate scores, peak values, state history, and any detection events. Available on Pro and Enterprise plans. Useful for audit logging, compliance exports, and dashboard displays.

Parameter	Type	Description
thread_id	str	The conversation thread ID to summarize.

example response

{
  "thread_id":     "session-abc123",
  "message_count": 14,
  "peak_risk":     82,
  "state_history": ["STABLE", "STABLE", "WATCH", "WARNING"],
  "blocked_count": 1,
  "metrics_avg": {
    "coherence":  0.74,
    "drift":      0.31,
    "entropy":    0.22,
    "stability":  0.68
  }
}

💳

Free vs Pro

The core monitoring loop — .check() — is available on all plans. Pro unlocks the full metric suite and audit-grade features.

Feature	Free	Pro — $99/mo	Enterprise
.check() — blocking decisions	✓ Included	✓ Included	✓ Included
4 cognitive metrics (Coherence, Drift, Entropy, Stability)	✓ Included	✓ Included	✓ Included
Thread management & drift tracking	✓ Included	✓ Included	✓ Included
Monthly API call limit	Limited	Unlimited	Unlimited + SLA
.get_thread_summary() — audit exports	—	✓ Pro	✓ Enterprise
Multi-model support	1 model	✓ All models	✓ + Custom endpoints
Sandbox evaluation environment	—	—	✓ Dedicated
Custom risk thresholds per endpoint	—	—	✓ Enterprise

✂️

Code Snippets

Ready-to-use integration examples for the most common pipeline patterns.

Flask / FastAPI endpoint

api.py

from psiguard import PsiGuard
from flask import request, jsonify

# Initialize once at startup
guard = PsiGuard(openai_api_key="sk-...")

@app.route("/chat", methods=["POST"])
def chat():
    data = request.json
    user_msg   = data["message"]
    session_id = data["session_id"]

    # Your existing LLM call
    ai_response = llm.chat(user_msg)

    # PsiGuard check
    result = guard.check(
        prompt=user_msg,
        response=ai_response,
        thread_id=session_id
    )

    if result.should_block:
        return jsonify({
            "error": "response_blocked",
            "state": result.state.label
        }), 422

    return jsonify({"response": ai_response, "state": result.state.label})

Environment variable configuration (recommended for production)

.env

# .env — never commit this file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

app.py — keys load from env automatically

from psiguard import PsiGuard

# No keys needed — reads OPENAI_API_KEY from environment
guard = PsiGuard()

Session cleanup on user logout

session.py

@app.route("/logout", methods=["POST"])
def logout():
    # Clear PsiGuard thread state on session end
    guard.reset_thread(session["session_id"])
    session.clear()
    return jsonify({"status": "logged_out"})

🔁

Common Patterns

Soft block — warn the user instead of hard-blocking

soft_block.py

result = guard.check(prompt=prompt, response=response, thread_id=tid)

if result.should_block:
    # Deliver with a warning rather than hard blocking
    return {
        "response": response,
        "warning":  "This response was flagged by PsiGuard. Review before acting.",
        "state":    result.state.label,
        "flagged":  True
    }

return {"response": response, "flagged": False}

Tiered response by risk state

tiered.py

result = guard.check(prompt=prompt, response=response, thread_id=tid)
state  = result.state.label

if   state == "STABLE":  return deliver(response)
elif state == "WATCH":   return deliver_with_flag(response)
elif state == "WARNING": return block_and_log(result.explanation)

Anthropic Claude pipeline

claude_pipeline.py

from psiguard import PsiGuard
import anthropic

guard  = PsiGuard(anthropic_api_key="sk-ant-...", embedding_provider="anthropic")
client = anthropic.Anthropic()

def monitored_claude(user_message: str, session_id: str) -> str:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": user_message}]
    )
    response_text = msg.content[0].text

    result = guard.check(
        prompt=user_message,
        response=response_text,
        thread_id=session_id
    )
    if result.should_block:
        raise ValueError(f"Blocked: {result.explanation}")
    return response_text

Add PsiGuard to yourAI pipeline in minutes.

Quick Start

Package Structure

The Guard Class

Free vs Pro

Code Snippets

Common Patterns

Add PsiGuard to your
AI pipeline in minutes.