# Changelog

## 2.5.0

### Breaking Changes

- **Renamed LangGraph Integration Classes** — `BeaconCallbackHandler` is now `BeaconLangGraphHandler` and `LangGraphBeaconConfig` is now `BeaconLangGraphConfig` for consistent naming across all integrations. The old names still work but emit deprecation warnings.

### New Features

- **Agentic Governance** — New governance subsystem for real-time policy enforcement on LLM calls, tool invocations, and agent handoffs. Supports `@governance` decorator for framework-agnostic use, `BeaconLangGraphGovernanceHandler` for LangChain/LangGraph workflows, configurable violation thresholds, and OPA/Rego policy evaluation with per-policy verdict details.
- **AWS Secrets Manager Support** — API keys can now be resolved from AWS Secrets Manager via `BEACON_AWS_SECRET_NAME`, `BEACON_AWS_SECRET_KEY`, and `BEACON_AWS_REGION` environment variables, enabling zero-code configuration in deployment environments.
- **Extra OTLP Endpoints** — New `BEACON_EXTRA_OTLP_ENDPOINTS` environment variable allows sending traces to additional gRPC OTLP endpoints alongside the primary Beacon endpoint.
- **Parallel Handoff Tracing** — LangGraph integration now supports parallel agent handoffs via a new `StateAccessor`, correctly tracing concurrent sub-agent invocations within the same graph.
- **Interrupt & Resume in Handoffs** — When a handoff exits via `GraphInterrupt`, child trace IDs are automatically preserved and reused on resume, maintaining trace continuity across human-in-the-loop interrupt cycles.
- **Stack Trace Capture** — New optional `record_stacktrace` parameter on spans captures full exception tracebacks for easier debugging.
- **Experiment Run Progress** — Experiment runs now support progress tracking with real-time status updates.
- **Environment Parameter** — `BeaconClient` accepts a new `environment` parameter, propagated as a resource attribute on all exported spans.
- **Custom User Identity** — Callback handlers now accept `user_email` and `user_name` for associating traces with specific users.

### Bug Fixes

- Fixed resumed handoff nodes incorrectly appearing as agent type instead of their original node type
- Fixed handoff span becoming a root span when no active tool was found in the parent context
- Fixed handoff event parent spans not being set correctly
- Fixed cancel events inside handoff contexts not being traced properly
- Fixed multiple independent invocations with the same handler incorrectly sharing a single trace
- Fixed `tool_calls` format in LiteLLM integration
- Fixed autodetection of parallel handoffs in LangGraph workflows

### Improvements

- Governance configuration is integrated directly into `BeaconLangGraphConfig`, so tracing and policy enforcement can be set up in one place
- Handoff detection is now automatic — no need to manually specify which nodes are handoffs
- LangGraph integration stores Beacon metadata under a `_beacon` key in graph state for cleaner state management
- Refactored CrewAI, LiteLLM, and Strands integrations for consistency and improved test coverage

## 2.4.0

### New Features

- **Strands Agents Integration** — Native tracing support for AWS Strands Agents, capturing agent interactions and tool calls automatically
- **CrewAI Integration** — Native tracing support for CrewAI multi-agent workflows, replacing the previous LiteLLM-based approach
- **Eager Span Export** — Spans can now be exported in real time as they are created, enabling live trace visibility instead of waiting for the full trace to complete
- **LangGraph Interrupt & Resume Support** — Traces now capture human-in-the-loop interruptions and checkpoint data in LangGraph workflows, preserving conversational context across pauses and resumptions
- **Agent Handoff Tracing** — Added support for tracing agent-to-agent handoffs, tracking when one agent delegates work to another
- **Guardrails Module** — New SDK module for interacting with guardrail configurations
- **Isolated Trace Provider** — Beacon can now use its own isolated OpenTelemetry TracerProvider, avoiding conflicts with existing infrastructure tracing pipelines
- **Experiments API Overhaul** — Fully redesigned experiments module with support for running experiments, managing variants, and updated type definitions
- **Datasets & Evaluations SDK** — Expanded SDK support for managing datasets and evaluations, including new CRUD operations and richer type support

### Bug Fixes

- Fixed spans not being properly finished when a context manager handler fails
- Fixed resource attributes missing from eagerly exported spans
- Restored sensitive data masking in the span export pipeline, which was accidentally removed during a prior refactor
- Various stability fixes in the client, configuration handling, and LangChain integration

### Improvements

- Added database callback support to the client for custom span persistence
- LangChain integration now supports async configuration retrieval for better performance in async workflows

## 2.3.0

### New Features

- **LangGraph Interrupt & Cancel Support** — Traces now capture human-in-the-loop interrupt and cancellation events in LangGraph workflows, enabling visibility into paused and cancelled agent runs
- **OTEL gen_ai Semantic Conventions** — Span attributes for LangChain and LiteLLM integrations now follow the OpenTelemetry gen_ai semantic conventions for better interoperability with standard observability tools

### Improvements

- Removed content size limits on traced data, so full inputs and outputs are now captured without truncation

## 2.2.0

### Improvements

- Improved automatic model name capture in the LangChain integration, providing more accurate model attribution across traced LLM calls

## 2.1.0

### New Features

- **Singleton Client** — The SDK now supports a singleton client pattern, so multiple parts of an application can share the same Beacon client without manual wiring
- **Async Context Manager** — `BeaconClient` can now be used as an async context manager (`async with`) for cleaner resource management
- **Multiple Trace Providers** — Added support for registering multiple OpenTelemetry trace providers, enabling side-by-side tracing pipelines

### Improvements

- Enhanced error handling with more descriptive warnings and error messages for common misconfiguration scenarios
- Various stability fixes in the client and LangChain integration

## 2.0.0

### Breaking Changes

- **OTLP Pipeline Rewrite** — The span export pipeline has been completely rewritten to use OpenTelemetry's native OTLP protocol, replacing the previous custom transport. This is a breaking change for custom transport configurations.

### New Features

- **Time to First Token (TTFT) Tracking** — LangChain and LiteLLM integrations now automatically capture time-to-first-token metrics for streaming LLM responses
- **Agent & Environment Tracing** — LangChain integration now captures agent type and execution environment metadata on traced spans

### Bug Fixes

- Fixed SSL verification errors when sending traces with `BEACON_VERIFY=false`

## 1.3.0

### Breaking Changes

- **Renamed Callback Handlers** — `BeaconOtelCallbackHandler` is now `BeaconCallbackHandler`, and `BeaconOtelLiteLLMLogger` is now `BeaconLiteLLMLogger`. The old names are removed.

### Bug Fixes

- Fixed LangChain function calls not nesting correctly under their parent tool call spans
- Fixed API key not being sent correctly in certain request configurations

## 1.2.0

### Improvements

- **Python 3.10 Support** — Lowered the minimum Python version requirement from 3.12 to 3.10, broadening compatibility
- **Lazy Imports** — LangChain callback handler is now lazily imported, so installing the SDK no longer requires `langchain-core` unless you actually use the integration
- Removed `project_id` from the SDK interface — project association is now handled server-side

## 1.1.0

### New Features

- **OTLP Ingestion Endpoint** — The SDK now sends traces to any standard OTLP ingestion endpoint, enabling broader compatibility with OpenTelemetry-based backends

### Improvements

- Removed `project_id` from the SDK configuration, client, and data models — project association is now handled server-side

## 1.0.0

### Features

- **Core Tracing** — Manual span creation, `@trace` decorator, and context manager APIs for instrumenting Python applications
- **LangChain Integration** — Automatic tracing for LangChain chains, agents, tools, and LLM calls via `BeaconCallbackHandler`
- **LiteLLM Integration** — Callback logger for tracing LiteLLM completions across multiple LLM providers
- **Datasets** — SDK support for creating, listing, and managing datasets and dataset items
- **Experiments** — SDK support for creating and managing A/B testing experiments
- **Evaluations** — SDK support for running and tracking model evaluations
- **Prompts** — SDK support for fetching, rendering, and versioning prompt templates
- **Sensitive Data Masking** — Built-in masking engine for redacting PII and sensitive content from traced spans, with Presidio-based guardrails integration
- **File & HTTP Transport** — Traces can be exported via HTTP (OTLP) or saved to local JSON files for offline analysis
