Metadata-Version: 2.4
Name: aisquare
Version: 1.0.3
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: 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: 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"
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"
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

```python
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): Seven 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 |
| `MemoryTracer` | Records memory read/write operations |

Decorators are also available: `@trace_tool` and `@trace_retrieval`.

## Manual instrumentation (any framework)

```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_API_KEY` | API key for trace ingest |

## Diagnostics

The SDK ships a built-in health checker:

```bash
explainability-doctor
```

## License

MIT
