Skip to main content

Python SDK

Availability

Open core · self-host + all Splyntra Cloud plans

pip install splyntra — the Apache-2.0 Python SDK. It captures every agent step, LLM call, and tool invocation as an OpenTelemetry trace, enriched with risk scoring, and adds trace-correlated logs, an inline guard, evaluation, and governance helpers.

Install​

pip install splyntra

With framework auto-instrumentation extras:

pip install "splyntra[langgraph,openai]"

Available extras: langgraph, openai, openai-agents, crewai.

Initialize​

Call Splyntra(...) once at application startup. The instrument parameter enables automatic tracing for supported frameworks with no per-call changes.

import os
from splyntra import Splyntra

Splyntra(
    api_key=os.environ["SPLYNTRA_API_KEY"],
    project="support-agent",
    endpoint=os.environ.get("SPLYNTRA_ENDPOINT", "http://localhost:4318"),
    environment="production",
    instrument=("langgraph", "openai"),
)

# Run your agent as usual — spans are captured automatically.

Constructor parameters​

ParameterDefaultDescription
api_keyrequiredSplyntra API key, sent as a Bearer token
projectrequiredProject slug
endpointhttp://localhost:4318Collector base URL
environmentdevelopmentDeployment environment label
service_namevalue of projectOpenTelemetry service.name resource
frameworkNoneFramework label shown on the Agents page
redact_by_defaultTrueStrip secrets from spans before export
instrumentNoneTuple of frameworks to auto-instrument, e.g. ("openai", "langgraph")
guard"off"Inline guardrail mode: "off", "monitor", or "block"
guard_fail_openTrueOn a guard-service error, allow (fail open) vs. raise

instrument()​

You can enable auto-instrumentation separately from init — useful when clients are configured elsewhere.

from splyntra import instrument

instrument()             # auto-detect all installed frameworks
instrument("langgraph")  # or target a specific one

See the SDK overview for the full list of instrument names.

Structured logs​

Emit trace-correlated logs to the same collector. Each entry auto-attaches the active trace_id/span_id and is redacted with the same rules as spans, so logs line up with the trace timeline on the Logs page.

from splyntra import log

log.info("charged card", {"amount": 42})
log.warn("rate limited", {"server": "stripe"})
log.error("payment failed", {"code": "card_declined"})
# also: log.debug(...), log.fatal(...)

The attributes mapping is optional and redacted before export.

Inline guard​

The guard runs a fast, high-confidence check before a model or tool call completes, so you can block or redact rather than only detect after the fact. Enable it at init with guard="monitor" (log only) or guard="block" (raise on a high-confidence prompt-injection match).

from splyntra import Splyntra, SplyntraBlocked

Splyntra(api_key="...", project="my-app", guard="block", instrument=("openai",))

try:
    run_agent(user_input)
except SplyntraBlocked as e:
    # A high-precision injection signature was detected pre-flight.
    handle_blocked(e)

Secrets are redacted in place; only high-precision injection signatures block, so benign role-play prompts pass through (deep analysis stays on the async detector path). guard_fail_open=True (default) allows the call if the guard service is unreachable — set it to False to fail closed. See Guardrails.

Evaluation​

Score caller-produced results against a dataset's ground truth (joined by input). The service never runs your agent. run(..., gate=True) exits non-zero on a regression versus the dataset baseline, making it a CI gate.

from splyntra import eval as ev

ev.push_dataset("support-qa", [
    {"input": "capital of France?", "expected_output": "Paris",
     "context": "Paris is the capital of France."},  # context powers groundedness
])

result = ev.run(
    dataset_id,
    results=[{"input": "capital of France?", "actual": "Paris"}],
    scorers=["exact_match", "groundedness"],
    gate=True,           # exit non-zero on regression
    set_baseline=False,  # promote this run to the dataset baseline
)

Item shape is {"input", "expected_output", "context"}; results are {"input", "actual"}. See Evaluation and Scorers.

Governance​

Request delegation decisions and record consequential actions to the immutable ledger. These call the commercial /v1 endpoints, available on Splyntra Cloud and Enterprise.

from splyntra import authorize, log_action

decision = authorize(
    "payments.refund",
    agent_id="support_agent",
    context={"amount": 80},
)

if decision["decision"] == "allow":
    ...  # proceed
elif decision["decision"] == "needs_approval":
    ...  # routed to human approval in the dashboard

log_action("refund", actor="support_agent", resource="order_42", metadata={"amount": 80})

authorize(...) returns {"decision": "allow" | "deny" | "needs_approval"}. See Governance overview and Delegation & approvals.

Manual instrumentation​

For custom agent, tool, and LLM functions outside a supported framework, use the decorators — both sync and async functions are supported.

from splyntra import trace_agent, trace_tool, trace_llm

@trace_agent(name="support_agent", workflow="refund")
def run(query: str):
    customer = read_customer("42")
    return call_llm(query)

@trace_tool(name="crm.read")
def read_customer(id: str):
    ...

@trace_llm(model="gpt-4o", provider="openai")
def call_llm(prompt: str) -> dict:
    # Return a dict with a "usage" key for token/cost analytics.
    ...

See Manual instrumentation for the full pattern.

Next steps​