Metadata-Version: 2.4
Name: botgauge
Version: 0.1.1
Summary: Trace AI agents in production, safely and privately, without slowing your app down. Built on OpenTelemetry.
Author-email: "BotGauge AI Inc." <support@botgauge.com>
License-Expression: FSL-1.1-ALv2
Project-URL: Homepage, https://www.botgauge.com/
Keywords: opentelemetry,otel,tracing,observability,llm,llm-observability,ai-agents,agents,langchain,openai,crewai,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: OpenTelemetry
Classifier: Framework :: OpenTelemetry :: Distros
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: botgauge-cli==0.1.1
Requires-Dist: botgauge-tracing==0.1.1
Provides-Extra: openai
Requires-Dist: botgauge-tracing[openai]; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: botgauge-tracing[anthropic]; extra == "anthropic"
Provides-Extra: langchain
Requires-Dist: botgauge-tracing[langchain]; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: botgauge-tracing[langgraph]; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: botgauge-tracing[crewai]; extra == "crewai"
Provides-Extra: llamaindex
Requires-Dist: botgauge-tracing[llamaindex]; extra == "llamaindex"
Provides-Extra: google-adk
Requires-Dist: botgauge-tracing[google-adk]; extra == "google-adk"
Provides-Extra: openai-agents
Requires-Dist: botgauge-tracing[openai-agents]; extra == "openai-agents"
Provides-Extra: autogen-agentchat
Requires-Dist: botgauge-tracing[autogen-agentchat]; extra == "autogen-agentchat"
Provides-Extra: pydantic-ai
Requires-Dist: botgauge-tracing[pydantic-ai]; extra == "pydantic-ai"
Provides-Extra: mcp
Requires-Dist: botgauge-tracing[mcp]; extra == "mcp"
Provides-Extra: distributed
Requires-Dist: botgauge-tracing[distributed]; extra == "distributed"
Provides-Extra: frameworks
Requires-Dist: botgauge-tracing[frameworks]; extra == "frameworks"
Provides-Extra: all
Dynamic: license-file

<p align="center">
  <a href="https://www.botgauge.com/"><img src="https://www.botgauge.com/og_images/web-app-manifest-512x512.png" alt="BotGauge" width="96"></a>
</p>

<h1 align="center">BotGauge Python SDK</h1>

<p align="center">
  Trace AI agents in production, safely and privately, without slowing your application down.<br>
  Built on OpenTelemetry.
</p>

<p align="center">
  <a href="https://pypi.org/project/botgauge/"><img src="https://img.shields.io/pypi/v/botgauge?style=flat-square&label=pypi%20botgauge" alt="PyPI version"></a>
  <a href="https://pypi.org/project/botgauge/"><img src="https://img.shields.io/pypi/pyversions/botgauge?style=flat-square" alt="Python versions"></a>
  <img src="https://img.shields.io/badge/OpenTelemetry-native-425CC7?style=flat-square" alt="OpenTelemetry native">
  <img src="https://img.shields.io/badge/license-FSL--1.1--ALv2-blue?style=flat-square" alt="License: FSL-1.1-ALv2">
</p>

BotGauge records what your agents do: every turn of a conversation, the agents involved, their LLM
calls with model and token counts, and their tool calls. You see it in the BotGauge console as
sessions you can search and inspect.

- **Two ways in.** Add three lines to your code, or trace an existing app without changing it:
  `botgauge instrument python app.py`.
- **Private by default.** Detected PII and credentials (emails, card numbers, API keys, passwords)
  are masked before anything leaves your process. Images, audio and embeddings stay out unless you
  ask for them.
- **Never in your way.** Export runs on a background thread with bounded queues and timeouts. A slow
  or unreachable endpoint never blocks or crashes your app.
- **Standard OpenTelemetry.** It works alongside your existing OpenTelemetry setup and carries
  W3C trace context across services.

## Install

```bash
pip install botgauge          # the tracing SDK (Python library) and the `botgauge` command
botgauge setup --install      # adds tracing for the frameworks your app uses
```

**What `pip install botgauge` gives you:** the tracing SDK (`from botgauge import tracing`) and the
`botgauge` command. On its own it records the turns, agents and spans your code creates. It does not
install tracing for every framework BotGauge supports; you add only what your app uses:

- **`botgauge setup --install`** finds the frameworks installed in your environment (without importing
  them) and installs the matching BotGauge extra for each, such as `botgauge[langchain]`, at your
  installed BotGauge version. `botgauge setup --detect` lists them without installing anything.
- **Or name the extra yourself**, for example in `requirements.txt`: `botgauge[langchain]`. The
  extras are listed under [Frameworks](#frameworks).

An extra adds the instrumentation that records your framework's LLM calls (model, prompts, token
counts) and tool calls.

No `botgauge` command installs anything except `setup --install`: `botgauge instrument` uses what is
installed and, when your app imports a framework without its tracing, logs which extra to add.

## Get an API key

Sign in at [cloud.botgauge.com](https://cloud.botgauge.com) and create an API key. It starts with
`bg_`. Then make it available to your app:

```bash
export BOTGAUGE_API_KEY="bg_..."
```

## Quickstart

**Zero-code:** trace an existing app as it is. `botgauge instrument` turns on the tracing your
extras installed.

```bash
botgauge instrument python app.py
```

**In code:** start tracing, attach your framework's instrumentor, and wrap each turn of a conversation.

```python
from botgauge import tracing
from openinference.instrumentation.langchain import LangChainInstrumentor

provider = tracing.init()                            # reads BOTGAUGE_API_KEY
LangChainInstrumentor().instrument(tracer_provider=provider)

with tracing.turn(session_id="ses_123"), tracing.agent("support-agent"):
    ...                                              # your agent's LLM and tool calls

tracing.shutdown()                                   # flushes on exit
```

`botgauge doctor` checks your setup: installed instrumentation, trace propagation and configuration.

## Frameworks

| Framework | Extra | Instrumentor, in code |
|---|---|---|
| LangChain, LangGraph | `botgauge[langchain]`, `botgauge[langgraph]` | `LangChainInstrumentor` |
| OpenAI SDK | `botgauge[openai]` | `OpenAIInstrumentor` |
| Anthropic SDK | `botgauge[anthropic]` | `AnthropicInstrumentor` |
| LlamaIndex | `botgauge[llamaindex]` | `LlamaIndexInstrumentor` |
| CrewAI | `botgauge[crewai]` | `CrewAIInstrumentor` and `OpenAIInstrumentor` |
| OpenAI Agents | `botgauge[openai-agents]` | `OpenAIAgentsInstrumentor` |
| Google ADK | `botgauge[google-adk]` | `GoogleADKInstrumentor` |
| AutoGen AgentChat | `botgauge[autogen-agentchat]` | `AutogenAgentChatInstrumentor` |
| PydanticAI | `botgauge[pydantic-ai]` | See below |
| MCP | `botgauge[mcp]` | `MCPInstrumentor` |
| HTTP and gRPC trace context across services | `botgauge[distributed]` | Zero-code only |

In code, import the instrumentor from `openinference.instrumentation.<framework>` (for example
`from openinference.instrumentation.openai import OpenAIInstrumentor`) and call
`.instrument(tracer_provider=provider)` on it after `provider = tracing.init()`, as in the
quickstart. PydanticAI instruments itself instead:

```python
from botgauge import tracing
from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

provider = tracing.init()
# version=5 for PydanticAI 2; use version=3 on PydanticAI 1.x
Agent.instrument_all(InstrumentationSettings(tracer_provider=provider, version=5))
provider.add_span_processor(OpenInferenceSpanProcessor())
```

Zero-code needs none of this: `botgauge instrument` does it for every installed extra.

BotGauge verifies exact framework and instrumentor versions in CI. Other versions are traced too, and
startup says when a version isn't one BotGauge has verified, and why.

### Already instrumented, or a framework not listed?

- **You already have the instrumentor installed:** `pip install botgauge` is enough. `botgauge
  instrument` finds installed instrumentors whichever way they were installed, and traces a version
  BotGauge hasn't verified too, saying so at startup. If your app already calls `.instrument()` itself,
  BotGauge leaves it alone instead of instrumenting twice; set `BOTGAUGE_PRODUCER_OWNER=<framework>=customer`
  to make that explicit.
- **You already use OpenTelemetry:** `tracing.init()` attaches to your existing tracer provider
  instead of replacing it, so spans from your instrumentation are exported to BotGauge too, with the
  same privacy masking.
- **Your framework is not in the table:** zero-code doesn't trace it, but in code you can. Install
  its [OpenInference](https://github.com/Arize-ai/openinference) instrumentor, or any instrumentor that
  follows the OpenTelemetry GenAI conventions, and call `.instrument(tracer_provider=provider)` after
  `provider = tracing.init()`. BotGauge exports those LLM and tool spans with the same privacy masking;
  they just aren't versions BotGauge has verified.
- **Your framework calls the OpenAI or Anthropic SDK underneath:** `botgauge[openai]` or
  `botgauge[anthropic]` traces those LLM calls, zero-code included, without the framework's own steps.
- **Anything else** you can trace yourself with `tracing.turn()`, `tracing.agent()` and
  `tracing.get_tracer()`.

## Privacy controls

| Setting | Default | Options |
|---|---|---|
| `BOTGAUGE_CAPTURE` / `capture=` | `text`: prompts, responses and tool data, without media | `metadata` (model, tokens, timing only), `text`, `full` (adds images, audio and embeddings) |
| `BOTGAUGE_REDACTED` / `redacted=` | `true`: detected PII and credentials are masked | `false` exports original content without masking, in every capture mode: it overrides the capture setting |

`OTEL_SDK_DISABLED=true` turns tracing off without code changes.

## Packages

| Package | What it is |
|---|---|
| `botgauge` | This meta-package. It installs the two below; its extras add framework instrumentation |
| [`botgauge-tracing`](https://pypi.org/project/botgauge-tracing/) | The tracing SDK, imported as `from botgauge import tracing`. Its page has the full guide and every setting |
| [`botgauge-cli`](https://pypi.org/project/botgauge-cli/) | The `botgauge` command (alias `botg`): `instrument`, `doctor`, `probe`, `setup`, `help`, `version` |

All three release together with the same version. Python 3.10 or later.

## Links

- Website: [botgauge.com](https://www.botgauge.com/)
- Console and API keys: [cloud.botgauge.com](https://cloud.botgauge.com)
- Support: [support@botgauge.com](mailto:support@botgauge.com)

## License

Functional Source License, Version 1.1, ALv2 Future License (`FSL-1.1-ALv2`). You may use, modify and
redistribute the software for any purpose other than a competing commercial product or service. Each
release becomes available under the Apache License 2.0 two years after it is published.
