Visceral Python SDK

visceral — runtime optimization layer for AI agents. Wrap your LLM client and Visceral observes traffic, finds wasted work, and proves a cheaper call is safe before making it. Fails open: if Visceral is unreachable, your agent runs exactly as before.

Install

pip install "visceral-ai[openai]"   # or [anthropic], [google], [all-providers]

uv add "visceral-ai[openai]"        # same extras, uv-managed projects

On a framework, add its extra so instrument() can capture it:

pip install "visceral-ai[langchain]"   # or [llama-index], [crewai]

Distribution name is visceral-ai; the import package is visceral. Requires Python 3.10+.

Agent-assisted setup

The package ships a /visceral skill for AI coding assistants (Claude Code today). Register it once:

visceral install

(python -m visceral install does the same; and if you only want the registrar without adding the SDK to a project yet, uv tool install visceral-ai or pipx install visceral-ai gives you the visceral command globally.)

Then open your assistant in the repo you want instrumented and run /visceral . — it detects your stack (provider clients vs. frameworks) and wires wrap() / instrument() / @node / @tool in the right spots, observe-only, then reports what it did. --project installs the skill into the current repo instead of your user profile; --stdout prints it for other assistants.

Usage

from openai import OpenAI
from visceral import wrap

client = wrap(OpenAI(), agent_id="my-agent")   # same client back, now instrumented

Annotate the steps of your agent so they show up as named spans:

from visceral import node

@node("retrieve")
def retrieve(query: str) -> list[str]:
    ...

Beyond observation

Observation is the default; three opt-in paths build on it, each fully fail-open. Full detail in the SDK guide.

• wrap(..., apply=True) — apply the optimizations the backend has already proven safe for your traffic: output-neutral cache-layout rewrites (Anthropic cache_control markers, OpenAI prompt_cache_key) and tool-call reuse. Never changes what the model reads or returns.

  client = wrap(Anthropic(), agent_id="support-bot", apply=True)
  

• instrument(framework, agent_id) — the client-less counterpart to wrap(). Capture an agent framework's structure (LangChain / LangGraph, LlamaIndex, CrewAI) without wrapping a client. Framework capture wins over provider capture, so don't also wrap() the same traffic.

  from visceral import instrument
  instrument("langgraph", agent_id="research-agent")
  

• @tool(...) — annotate a tool function so read-only calls can be deduplicated and, once proven and with apply=True, served from a stored result instead of re-executed. Serving needs readonly=True and replay_safe=True; a failure always runs the real tool.

  from visceral import tool
  
  @tool("get_customer", readonly=True, replay_safe=True)
  def get_customer(customer_id: str) -> dict:
      return db.fetch_customer(customer_id)
  

Authentication

You hold exactly one secret: the workspace API key (vsc_...), from your workspace's Settings page in the dashboard (or from Visceral during onboarding). Set it as VISCERAL_API_KEY, or pass api_key= to wrap(); set VISCERAL_BASE_URL only if self-hosting. The key both authenticates the SDK and selects the workspace your traffic lands in — there is no separate user or org credential. One process serves one workspace: wrap every client in a process with the same key.

Prompt and response text never leaves your process unencrypted: content is stripped or AES-256-GCM-encrypted before export with a per-workspace encryption key the SDK fetches automatically — you never handle it — and spans that cannot be redacted are dropped, never sent.

Develop

uv sync --extra all-providers --extra dev   # or: pip install -e ".[dev]"
uv run ruff check src/ tests/
uv run pytest

uv.lock is committed; CI installs with uv sync --locked, so lockfile drift fails the build — run uv lock after changing dependencies.

License

Apache-2.0 — see LICENSE.