Metadata-Version: 2.4
Name: aisquare
Version: 1.0.6
Summary: Explainability SDK for tracing, graphing, and policy auditing of AI agents
Author: AISquare
License: MIT
Project-URL: Homepage, https://github.com/AISquare-Studio
Keywords: ai,agents,observability,tracing,governance,explainability
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: explainability
Requires-Dist: httpx<1.0,>=0.27; extra == "explainability"
Requires-Dist: aiosqlite<1.0,>=0.20; extra == "explainability"
Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "explainability"
Requires-Dist: opentelemetry-api<2.0,>=1.24; extra == "explainability"
Provides-Extra: proxy-scale
Requires-Dist: redis<6.0,>=5.0; extra == "proxy-scale"
Provides-Extra: gateway
Requires-Dist: fastapi<1.0,>=0.111; extra == "gateway"
Requires-Dist: uvicorn<1.0,>=0.30; extra == "gateway"
Requires-Dist: pydantic<3.0,>=2.7; extra == "gateway"
Requires-Dist: redis<6.0,>=5.0; extra == "gateway"
Requires-Dist: neo4j<6.0,>=5.20; extra == "gateway"
Requires-Dist: asyncpg<1.0,>=0.29; extra == "gateway"
Requires-Dist: openai<2.0,>=1.30; extra == "gateway"
Requires-Dist: prometheus-client<1.0,>=0.20; extra == "gateway"
Requires-Dist: sse-starlette<3.0,>=2.0; extra == "gateway"
Requires-Dist: python-dotenv<2.0,>=1.0; extra == "gateway"
Requires-Dist: cryptography<45.0,>=42.0; extra == "gateway"
Requires-Dist: reportlab<5.0,>=4.0; extra == "gateway"
Requires-Dist: python-dotenv<2.0,>=1.0; extra == "gateway"
Requires-Dist: httpx<1.0,>=0.27; extra == "gateway"
Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "gateway"
Requires-Dist: opentelemetry-api<2.0,>=1.24; extra == "gateway"
Requires-Dist: aiosqlite<1.0,>=0.20; extra == "gateway"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: agno
Requires-Dist: agno>=0.1; extra == "agno"
Requires-Dist: openinference-instrumentation-agno>=0.1; extra == "agno"
Provides-Extra: claude
Requires-Dist: fastapi<1.0,>=0.111; extra == "claude"
Requires-Dist: uvicorn<1.0,>=0.30; extra == "claude"
Requires-Dist: httpx<1.0,>=0.27; extra == "claude"
Requires-Dist: aiosqlite<1.0,>=0.20; extra == "claude"
Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "claude"
Requires-Dist: opentelemetry-api<2.0,>=1.24; extra == "claude"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Requires-Dist: openinference-instrumentation-langchain>=0.1; extra == "langchain"
Provides-Extra: all
Requires-Dist: agno>=0.1; extra == "all"
Requires-Dist: openinference-instrumentation-agno>=0.1; extra == "all"
Requires-Dist: langchain-core>=0.2; extra == "all"
Requires-Dist: openinference-instrumentation-langchain>=0.1; extra == "all"
Dynamic: license-file

# 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

```bash
pip install aisquare[explainability]
```

For Agno auto-instrumentation:

```bash
pip install aisquare[explainability,agno]
```

## Quick start

Every trace needs an agent identity on its root span — `agent_name` is the key
the gateway routes traces by. Name your agent explicitly and pre-register it:

```python
# .env: EXPLAINABILITY_GATEWAY_URL, EXPLAINABILITY_API_KEY,
# EXPLAINABILITY_AGENTS=support-bot   <- pre-registers; must equal agent_name below
import aisquare.explainability as sdk

sdk.init_from_env()

with sdk.AgentRunTracer(agent_name="support-bot"):
    with sdk.LLMCallTracer(model="gpt-4o", provider="openai") as llm:
        ...  # your agent logic — nested spans inherit the run's routing identity

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

Using a framework instead of manual tracers? The identity contract is the
same — the agent's explicit name becomes `agent.name` on the root span: Agno
`Agent(name="support-bot")`, LangChain `metadata={"agent_name": "support-bot"}`,
or `GovernedAgent(..., agent_name="support-bot")`.

## What the SDK captures

The SDK collects two layers of signal:

**Auto-instrumentation** (zero tracing code): The `AgnoAdapter` installs `openinference-instrumentation-agno`, which automatically wraps every Agno agent run, LLM call, and tool invocation as an OTel span. The Agno `Agent(name=...)` becomes the trace's routing identity — always name your agents.

**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)

Leaf tracers (LLM, tool, routing, ...) always run nested inside an
`AgentRunTracer` — its `agent_name` is stamped as `agent.name` on the root
span, the attribute the gateway routes the trace by. A trace with no agent
identity is rejected at ingest (409 `no_agent_identity`).

```python
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 |
| `EXPLAINABILITY_AGENTS` | Comma-separated agent names registered at init; must match your `AgentRunTracer` / framework agent names |
| `AISQUARE_AGENT_NAME` | The SDK's default agent identity, in two roles: the identity used for policy checks, and (since 1.0.6) the fallback trace identity stamped on spans that would otherwise be rootless so the trace still routes. Keep it equal to your `agent_name`. |

**Multiple agents:** name each agent in code (`AgentRunTracer(agent_name=...)`
or the framework equivalent) — that per-run name is what routes each trace.
`AISQUARE_AGENT_NAME` holds a single name and is a single-agent convenience
only; it cannot distinguish between agents in the same process.

## Diagnostics

The SDK ships a built-in health checker:

```bash
explainability-doctor
```

Its `agent_identity` check warns when no agent identity is configured (the
classic precondition for 409 `no_agent_identity` ingest rejections), and its
`delivery_backlog` check surfaces traces stuck in the local inbox after
gateway 409s — with the remediation for each rejection code.

## License

MIT
