safeai-sdk 0.8.2

Framework-agnostic runtime boundary enforcement for AI systems

SECURE. INTELLIGENT. TRUSTED.

The runtime security layer for AI agents.
Block secrets. Redact PII. Enforce policies. Control tool calls. Require approvals.
Works with any model stack, framework, and deployment style.

---

Table of Contents

• What SafeAI Is
• Capability Overview
• Install
• Quick Start (SDK)
• Scaffold a Full Config Project
• Run as a Proxy API
• CLI Commands
• Framework and Agent Integrations
• Plugins and Policy Templates
• Dashboard and Enterprise Operations
• Documentation Map
• Contributing, Security, and Governance
• Local Development
• License

What SafeAI Is

SafeAI enforces policy at three runtime boundaries:

• input: before user or agent data reaches a model.
• action: before and after tool execution, and during agent-to-agent messaging.
• output: before model output is returned or forwarded.

That model keeps policy decisions close to execution, where incidents actually happen.

                    +----------------------------------+
 User / Agent  ---> |  INPUT BOUNDARY   (scan_input)  | ---> AI Provider
                    |  ACTION BOUNDARY  (intercept)   |      (OpenAI, Gemini,
 AI Provider   <--- |  OUTPUT BOUNDARY  (guard_output)| <---  Claude, etc.)
                    +----------------------------------+
                              SafeAI Runtime

Current status: Phases 1–7 complete, with the current release at v0.8.2.

What SafeAI Is Not

SafeAI focuses on runtime policy enforcement. It does not:

• Replace model safety training — SafeAI enforces policy at runtime boundaries, not during model training or fine-tuning.
• Provide content moderation — It detects secrets and PII, not toxicity, hate speech, or content quality.
• Act as a firewall or WAF — It operates inside your application, not at the network perimeter.
• Make compliance decisions for you — It provides tools and templates, but you are responsible for your own compliance posture.
• Guarantee zero false positives — Detection is pattern-based. Tune policies for your use case.

If your need falls outside these boundaries, consider opening a discussion to see if the community has suggestions.

Capability Overview

SafeAI is intentionally broad. This is the complete capability set currently implemented:

Area	Capabilities
Detection and classification	Built-in detectors for secrets and personal data (email, phone, ssn, credit_card, api_key) with hierarchical tags
Policy engine	Priority-based first-match rules, YAML policies, schema validation, hot reload, fallback output templates
Input and output controls	Prompt scanning (scan_input), response guarding (guard_output), redaction/block/allow enforcement
Structured and file scanning	Nested payload scanning (scan_structured_input) and file scanning (scan_file_input) for JSON and text
Tool boundary enforcement	Request contract checks, response filtering, undeclared tool denial, per-field stripping
Agent identity	Agent registry, tool binding, clearance-tag enforcement
Agent messaging	Source/destination-aware, policy-gated agent-to-agent message interception
Approvals	require_approval runtime gate with persistent queue and explicit approve/deny flow
Secrets access	Capability-token TTL/scope/session binding, secret manager abstraction, Env/Vault/AWS backends
Memory security	Schema-enforced memory controller, encrypted handle storage, retention and purge workflow
Auditability	Append-only JSON logs, rich query filters (boundary/action/agent/tool/tag/session/time/metadata), context hashes and event IDs
Proxy runtime	Sidecar and gateway modes, upstream forwarding, health endpoint, policy reload endpoint
Integrations	LangChain, CrewAI, AutoGen, Claude ADK, Google ADK, coding-agent hooks, MCP server
Extensibility	Plugin loader for detectors/adapters/templates, built-in policy template catalog (finance, healthcare, support)
Skills system	Installable skill packages for policies, plugins, and deployment scripts. Pre-built skills for GDPR, HIPAA, PCI-DSS, prompt injection, secret detection, and deployment automation
Operations UI	Web dashboard (/dashboard) for incidents, approvals, compliance summaries, tenant/RBAC controls, alerts
Alerting and observability	Alert channels (file, webhook, Slack), agent timeline, session trace, Prometheus-style metrics (/v1/metrics)
Intelligence layer	5 AI advisory agents: auto-config, policy recommender, incident explainer, compliance mapper, integration generator. BYOM (Bring Your Own Model), metadata-only, human-approved staging

Install

uv pip install safeai-sdk

Or with pip:

pip install safeai-sdk

Optional extras:

uv pip install "safeai-sdk[vault]"   # HashiCorp Vault backend
uv pip install "safeai-sdk[aws]"     # AWS Secrets Manager backend
uv pip install "safeai-sdk[mcp]"     # MCP server support
uv pip install "safeai-sdk[all]"     # Vault + AWS + MCP
uv pip install "safeai-sdk[dev]"     # local development tooling

Quick Start (SDK)

For fast adoption with no config files:

from safeai import SafeAI

ai = SafeAI.quickstart()

Then enforce both ends of the model call:

# Input boundary
scan = ai.scan_input("Summarize this: token=sk-ABCDEF1234567890ABCDEF")
print(scan.decision.action, scan.decision.reason)

# Output boundary
guard = ai.guard_output("Contact [e-mail]")
print(guard.safe_output)

Structured payload example:

payload = {"user": {"email": "[e-mail]"}, "note": "hello world"}
result = ai.scan_structured_input(payload, agent_id="default-agent")
print(result.decision.action)
print(result.filtered)

Scaffold a Full Config Project

When you need full policy and runtime control:

safeai init --path .

This scaffolds:

• safeai.yaml
• policies/default.yaml
• contracts/example.yaml
• schemas/memory.yaml
• agents/default.yaml
• plugins/example.py
• tenants/policy-sets.yaml
• alerts/default.yaml

Use config mode via:

from safeai import SafeAI

ai = SafeAI.from_config("safeai.yaml")

Run as a Proxy API

Start the proxy:

safeai serve --mode sidecar --host 127.0.0.1 --port 8910 --config safeai.yaml

Health check:

curl http://127.0.0.1:8910/v1/health

Hello world scan:

curl -s -X POST http://127.0.0.1:8910/v1/scan/input \
  -H "content-type: application/json" \
  -d '{"text":"hello world","agent_id":"default-agent"}'

Core HTTP endpoints:

• GET /v1/health
• GET /v1/metrics
• POST /v1/scan/input
• POST /v1/scan/structured
• POST /v1/scan/file
• POST /v1/guard/output
• POST /v1/intercept/tool
• POST /v1/intercept/agent-message
• POST /v1/memory/write
• POST /v1/memory/read
• POST /v1/memory/resolve-handle
• POST /v1/memory/purge-expired
• POST /v1/audit/query
• POST /v1/policies/reload
• GET /v1/plugins
• GET /v1/policies/templates
• GET /v1/policies/templates/{template_name}
• POST /v1/proxy/forward
• GET /v1/intelligence/status
• POST /v1/intelligence/explain
• POST /v1/intelligence/recommend
• POST /v1/intelligence/compliance
• GET /dashboard

CLI Commands

Daily commands you will actually use:

safeai init --path .
safeai validate --config safeai.yaml
safeai scan --boundary input --input "hello world"
safeai logs --tail 20 --json-output
safeai serve --mode sidecar --port 8910

safeai approvals list --status pending
safeai approvals approve <request_id> --approver security-lead
safeai approvals deny <request_id> --approver security-lead --note "policy mismatch"

safeai templates list
safeai templates show --name healthcare --format yaml

safeai setup claude-code --config safeai.yaml --path .
safeai setup cursor --config safeai.yaml --path .
safeai setup generic --config safeai.yaml

safeai hook --config safeai.yaml
safeai mcp --config safeai.yaml

safeai intelligence auto-config --path . --output-dir .safeai-generated
safeai intelligence recommend --since 7d
safeai intelligence explain <event_id>
safeai intelligence compliance --framework hipaa
safeai intelligence integrate --target langchain --path .

safeai alerts add --channel slack --url https://hooks.slack.com/...
safeai alerts list
safeai alerts test --channel slack

safeai observe agents
safeai observe sessions

safeai skills list
safeai skills search secret
safeai skills add prompt-injection-shield
safeai skills remove prompt-injection-shield

Framework and Agent Integrations

Built-in adapters:

• LangChain
• CrewAI
• AutoGen
• Claude ADK
• Google ADK

Coding-agent integration:

• universal hook adapter (safeai hook)
• installer commands for Claude Code and Cursor (safeai setup ...)
• MCP server (safeai mcp) for MCP-compatible clients

Quick adapter example:

from safeai import SafeAI
from safeai.middleware.langchain import wrap_langchain_tool

ai = SafeAI.from_config("safeai.yaml")
safe_tool = wrap_langchain_tool(ai, my_tool, agent_id="default-agent")

Plugins and Policy Templates

Phase 6 added extensibility as first-class behavior.

Plugin model:

• load plugin modules from plugins/*.py (configurable in safeai.yaml)
• extend detector patterns
• register adapters
• contribute policy templates

Template catalog:

• built-in packs: finance, healthcare, support
• list with safeai templates list
• inspect with safeai templates show --name <template>
• proxy discovery endpoints via /v1/policies/templates*

Minimal plugin shape:

def safeai_detectors():
    return [
        (r"my-custom-pattern", "custom.tag", "custom_detector"),
    ]

def safeai_adapters():
    return {
        "my-adapter": lambda safeai: object(),
    }

def safeai_policy_templates():
    return [
        {
            "name": "my-template",
            "template": {"version": "v1alpha1", "policies": []},
        }
    ]

Dashboard and Enterprise Operations

SafeAI includes a dashboard surface for security operations:

• incidents and policy events
• approval queue workflow
• compliance report summaries
• tenant-scoped policy sets
• RBAC checks
• alert rule evaluation and alert logs

Run the proxy and open /dashboard in your browser.

Documentation Map

Start here:

• Docs home: docs/index.md
• Install: docs/getting-started/installation.md
• Quickstart: docs/getting-started/quickstart.md
• Configuration: docs/getting-started/configuration.md

Guides:

• Policy engine: docs/guides/policy-engine.md
• Tool contracts: docs/guides/tool-contracts.md
• Agent identity: docs/guides/agent-identity.md
• Structured scanning: docs/guides/structured-scanning.md
• Capability tokens: docs/guides/capability-tokens.md
• Audit logging: docs/guides/audit-logging.md

Integrations:

• Integrations overview: docs/integrations/index.md
• LangChain: docs/integrations/langchain.md
• CrewAI: docs/integrations/crewai.md
• AutoGen: docs/integrations/autogen.md
• Claude ADK: docs/integrations/claude-adk.md
• Google ADK: docs/integrations/google-adk.md
• Coding agents: docs/integrations/coding-agents.md
• Proxy/sidecar: docs/integrations/proxy-sidecar.md
• Plugins: docs/integrations/plugins.md

Reference:

• CLI reference: docs/cli/index.md
• API reference: docs/reference/safeai.md
• Changelog: docs/changelog.md

Project and planning:

• Architecture: docs/project/architecture.md
• Roadmap: docs/project/roadmap.md
• Security: docs/project/security.md
• Governance: docs/project/governance.md
• Compatibility: docs/project/compatibility.md
• Intelligence layer: docs/guides/intelligence.md
• Delivery tracker: docs/project/roadmap.md

Notebooks:

• Notebook index: docs/notebooks/index.md
• Raw notebooks: notebook/

Contributing, Security, and Governance

Core project policies:

• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Governance model: GOVERNANCE.md
• Maintainer policy: MAINTAINERS.md
• Code of conduct: CODE_OF_CONDUCT.md
• Compatibility and semver contract: COMPATIBILITY.md
• Roadmap: ROADMAP.md

Local Development

git clone https://github.com/enendufrankc/safeai.git
cd safeai
uv sync --extra dev --extra all

Or with pip:

pip install -e ".[dev,all]"

Quality gates used in CI:

uv run ruff check safeai tests
uv run mypy safeai
uv run python -m pytest tests/ -v

License

SafeAI is licensed under Apache 2.0.