GuardTrellis

A small Python SDK for local checks around model inputs, complete outputs, retrieved text, and proposed tool calls. Policies are explicit, composable, and independent of model providers.

APIs may change before a stable release. Supported Python: 3.11–3.14. Apache-2.0 licensed.

Version: 0.1.0a4. See PyPI for availability and release notes. A source checkout may describe a candidate that has not been published yet.

Install this version in an activated virtual environment:

python -m pip install 'guardtrellis==0.1.0a4'

An explicit version opts into a prerelease when applicable. Optional integrations: 'guardtrellis[fastapi]==0.1.0a4', 'guardtrellis[langgraph]==0.1.0a4', 'guardtrellis[openai]==0.1.0a4', 'guardtrellis[gemini]==0.1.0a4'.

Included in this alpha

• A retrieval and tool-call recipe that carries checked text and validated arguments through both boundaries using core dependencies.
• A separate 40-case Unicode and PII development set with synthetic provenance, multilingual context, benign cases, and retained misses and false positives. The original 72-case smoke corpus and its historical results remain available.
• OpenAI SDK 3 compatibility for the optional OpenAI and Azure examples, using HTTPX2. See the migration notes for custom clients and certificate trust changes.

These additions do not change core scanner rules or establish broader detection accuracy.

Quickstart

from guardtrellis import Guard, PIIScanner, SecretScanner

guard = Guard(
    input_scanners=[SecretScanner(), PIIScanner()],
    output_scanners=[SecretScanner(), PIIScanner()],
)

# Deterministic local demonstration, not a real model integration.
result = guard.run("Contact casey@example.org", lambda text: f"Received: {text}")
print(result.require_text())  # Received: Contact [PII]
print(result.diagnostics())  # Metadata only; no matched strings or prompt text.

run calls your callback only after accepted input checks, then checks the complete returned string before exposing it. Use await guard.arun(text, callback) for async work; both sync and async callbacks work there. Provider SDKs are not required by the core.

No scanners are installed implicitly: Guard() permits bounded text. Choose policies for each boundary. Heuristic matches are signals, not probabilities or comprehensive protection.

from guardtrellis import Action, Guard, JSONScanner, LiteralScanner, Stage, ToolGuard

guard = Guard(
    retrieval_scanners=[LiteralScanner(["confidential"], action=Action.BLOCK)],
    output_scanners=[JSONScanner({"type": "object", "required": ["answer"]})],
)
retrieval = guard.scan("A public reference", stage=Stage.RETRIEVAL)
# In async code: await guard.ascan("A public reference", stage=Stage.RETRIEVAL)

tools = ToolGuard(
    {
        "search": {
            "type": "object",
            "properties": {"query": {"type": "string", "maxLength": 200}},
            "required": ["query"],
            "additionalProperties": False,
        },
    }
)
call = tools.validate("search", '{"query":"public documentation"}')
name, arguments = call.require_call()
# Your application must still enforce identity, permissions, and execution limits.

ALLOW, WARN, and REDACT expose result.text; BLOCK and ERROR expose None. require_text() / require_call() raise a payload-free Rejected exception on rejection. WARN deliberately permits delivery. Scanner/callback exceptions are errors, never successful checks. The first block/error stops its stage. Input rejection prevents the callback entirely.

Stages have separate scanner lists: input_scanners, output_scanners, retrieval_scanners, and tool_scanners. Use scan(text, stage=Stage.INPUT/OUTPUT/RETRIEVAL/TOOL) or ascan; the default stage is Stage.INPUT. Retrieval/tool checks must be invoked explicitly; run does not discover or intercept these operations. ToolGuard adds name/schema validation.

Scanners run in configuration order. Each sees the text produced by preceding redactions. Findings record half-open character offsets, scanner index, and the input revision they refer to; every redacting scanner increments the revision. Offsets from different revisions must not be applied to the original string. No originals or rehydration maps are retained.

Defaults: 100,000 characters per stage, 256 findings per scanner, JSON nesting at most 32, and a 5-second per-operation async wait. Synchronous calls have no execution deadline. Async cancellation cannot terminate a running thread or preempt a coroutine that blocks the event loop. Timed-out work may continue and have side effects. Use process isolation and application concurrency limits when execution must be forcibly bounded.

Examples and development

Clone the source to run the examples or contribute:

git clone https://github.com/sahilmathur254/guardtrellis.git
cd guardtrellis
uv sync --all-extras --group dev
uv run python examples/plain_callable.py
uv run python examples/retrieval_tools.py   # Checked retrieval through a proposed tool call
uv run python examples/fastapi_app.py       # Local TestClient demo, no server needed
uv run python examples/langgraph_app.py     # Local graph, no provider credentials
uv run python examples/openai_app.py        # Real SDK, in-memory HTTP mock by default
uv run python examples/azure_openai_app.py  # Azure SDK, in-memory HTTP mock by default
uv run python examples/gemini_app.py        # Gemini SDK, in-memory HTTP mock by default
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run python evaluation/run.py --report-dir /tmp/guardtrellis-eval
uv build
uv run python scripts/smoke_dist.py

The retrieval/tool-call recipe uses only core dependencies and shows checked data crossing both boundaries, rejected callbacks, and host authorization.

FastAPI and LangGraph are optional extras (.[fastapi], .[langgraph]). LangGraph input checks run before text enters graph state. The example also checks model output before returning it to graph state. Instrumentation around callbacks may still capture raw data.

The optional provider examples (.[openai]) use direct OpenAI Responses or Azure OpenAI Chat Completions through guarded callbacks. Their default modes and ordinary tests make no provider calls. See the OpenAI guide and Azure guide for setup, privacy/failure boundaries, and separately approved one-request live smokes. The openai extra now requires openai>=3,<4 and httpx2>=2.12,<3; custom clients must follow the SDK 3 migration notes above. Live verification of both paths is pending.

The separate Gemini example uses the optional .[gemini] extra and also defaults to mocked HTTP. Its one-request live smoke can use an approved Gemini Free Tier project with the documented model and limits. A maintainer-approved live smoke passed on 2026-09-26; the guide records the exact source, versions, token counts, and evidence limits.

See API details, limitations and trust boundaries, evaluation methodology, measured smoke results, Unicode and PII challenges, resource measurements and host controls, and contribution guidance. These checks do not provide comprehensive prompt-injection prevention, factual verification, regulatory compliance, or a tool sandbox.

Roadmap and contributions

Use the public GitHub Project to find ready work and track progress. The roadmap explains the release milestones, dependencies, and longer-term proposals. Start with a good first issue or a help wanted issue, then follow the contributor workflow.

See the changelog for version-specific behavior and the release guide for packaging checks, TestPyPI rehearsal, and maintainer-approved publication.