aisquare 1.0.4

Explainability SDK for tracing, graphing, and policy auditing of AI agents

AISquare Explainability SDK

Lightweight Python SDK for tracing, graphing, and policy auditing of AI agents. Captures execution traces from any Python agent (Agno, LangChain, plain Python) and delivers them to the AISquare Explainability Gateway.

Installation

pip install aisquare[explainability]

For Agno auto-instrumentation:

pip install aisquare[explainability,agno]

Quick start

import aisquare.explainability as sdk

# Reads EXPLAINABILITY_GATEWAY_URL and EXPLAINABILITY_API_KEY from environment
sdk.init_from_env(service_name="my-agent")

# Run your agent — Agno is auto-instrumented, all spans captured automatically
agent.print_response("...")

# IMPORTANT for short-lived scripts: flush ensures traces reach the gateway
# before the process exits. Long-running services don't need this.
sdk.flush()

What the SDK captures

The SDK collects two layers of signal:

Auto-instrumentation (zero-code): The AgnoAdapter installs openinference-instrumentation-agno, which automatically wraps every Agno agent run, LLM call, and tool invocation as an OTel span.

Manual tracers (governance-grade): Nine context-manager tracers you can add to any Python code — framework-agnostic:

Tracer	Purpose
AgentRunTracer	Wraps a full agent run as the root span
LLMCallTracer	Records an LLM inference call with I/O and token counts
ToolCallTracer	Records a tool invocation with parameters, result, and errors
RetrievalTracer	Records a RAG retrieval with documents and scores
HumanInterventionTracer	Records a human-in-the-loop review or correction
RoutingTracer	Records a routing/delegation decision with selected and rejected paths
DecisionTracer	Records a general decision point with options, selected, and rejected paths
PolicyGateTracer	Records a policy-gate evaluation with the policies checked and the allow/deny outcome
MemoryTracer	Records memory read/write operations

Decorators are also available: @trace_tool and @trace_retrieval.

Manual instrumentation (any framework)

import aisquare.explainability as sdk

sdk.init_from_env()

with sdk.AgentRunTracer(agent_name="MyAgent", run_id="abc-123") as run:
    run.set_input("User query")

    with sdk.LLMCallTracer(model="gpt-4o-mini", provider="openai") as llm:
        response = call_openai(...)
        llm.set_input_messages([{"role": "user", "content": "..."}])
        llm.set_output_messages([{"role": "assistant", "content": response}])
        llm.set_token_counts(prompt=100, completion=50)

    with sdk.RoutingTracer(decision_type="tool_selection") as rt:
        rt.set_selected("web_search", reason="Query requires fresh data")
        rt.set_rejected([{"name": "cached_search", "reason": "Cache is stale"}])

    run.set_output("Agent final answer")

sdk.flush()

Environment variables

Variable	Description
EXPLAINABILITY_GATEWAY_URL	Gateway base URL for trace ingest
EXPLAINABILITY_API_KEY	API key for trace ingest

Diagnostics

The SDK ships a built-in health checker:

explainability-doctor

License

MIT