Lumenova Beacon SDK

A Python observability SDK for AI/LLM applications — trace agentic frameworks (LangChain, LangGraph, CrewAI, Strands, MCP, Temporal), LLM calls, and custom code with OpenTelemetry-compatible spans.

Features

LangChain/LangGraph Integration - Automatic tracing for chains, agents, tools, retrievers, with interrupt/resume and agent handoff support
Strands Agents Integration - Hook provider (recommended) or legacy callback handler for AWS Strands agent tracing
CrewAI Integration - Event listener for CrewAI crew tracing
MCP Server and Client Integration - FastMCP middleware that traces an MCP server (tools, resources, prompts) independently of any agent, plus a client that carries the caller's trace into it
LiteLLM Integration - Callback logger for LiteLLM proxy tracing
Temporal Integration - Replay-safe plugin that traces workflows, activities, signals, queries and updates
FastAPI Integration - Instrumentation that verifies it took effect, drops ASGI noise, and flushes on shutdown
Agentic Governance - Real-time policy enforcement for AI agent tool calls and LLM invocations
Guardrails - Apply Beacon content guardrails, pinned to a configuration version
System Probes - Run autonomous AI agents that probe your HTTP system locally (private APIs, custom auth) and produce scored markdown reports
OpenTelemetry Integration - Automatic instrumentation for Anthropic, OpenAI, FastAPI, Redis, HTTPX, and more
Manual & Decorator Tracing - Create spans manually or use @trace decorator
Context Propagation - One trace across Beacon and OpenTelemetry spans, load balancers, and queues
Trace Querying & Export - Query, search, and filter the traces you sent to Beacon — and download complete traces back out for archiving or offline analysis
Agent Registry & Insights - Register the agents traces are attributed to, read Beacon's AI-generated insights and recommendations, and trigger/monitor analysis runs
Dataset Management - ActiveRecord-style API for managing test datasets
Prompt Management - Version-controlled prompt templates with labels (staging, production)
Experiment & Evaluation Management - Run experiments over datasets and evaluate results
Human Annotations - Enqueue traces/spans/sessions for human review, push external feedback, read annotation summaries back
Data Masking - Deterministic PII floor plus Beacon Guardrails detection, applied to every exported span
Span Noise Control - Drop the spans you don't want (name globs, ASGI plumbing, orphan background work) before they leave the process
Flexible Transport - HTTP or file-based span export
Full Async Support - Async/await throughout

Requirements

Python 3.10+

Installation

pip install lumenova-beacon

The core install depends only on httpx and tenacity. Integrations are optional extras:

Extra	Adds
`opentelemetry`	OpenTelemetry SDK + OTLP exporters (for OTel instrumentors)
`langchain`	LangChain / LangGraph tracing and governance
`litellm`	LiteLLM callback logger
`strands`	AWS Strands Agents tracing
`crewai`	CrewAI tracing
`mcp`	FastMCP server middleware and client
`temporal`	Temporal plugin
`fastapi`	FastAPI instrumentation
`aws`	AWS Secrets Manager API-key resolution

pip install 'lumenova-beacon[langchain,opentelemetry]'

Quick Start

LangChain / LangGraph

from lumenova_beacon import BeaconClient, BeaconLangGraphHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Initialize client
client = BeaconClient(
    endpoint="https://your-beacon-endpoint.lumenova.ai",
    api_key="your-api-key",
)

# Create a tracing handler
handler = BeaconLangGraphHandler(session_id="session-123")

# All LangChain operations are now traced automatically
llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_template("Tell me about {topic}")
chain = prompt | llm

response = chain.invoke(
    {"topic": "AI agents"},
    config={"callbacks": [handler]}
)

Basic Tracing

from lumenova_beacon import BeaconClient, trace

client = BeaconClient(
    endpoint="https://your-beacon-endpoint.lumenova.ai",
    api_key="your-api-key",
    session_id="my-session"
)

@trace
def my_function(x, y):
    return x + y

result = my_function(10, 20)  # Automatically traced

No endpoint? Pass file_directory='./traces' instead of endpoint to write spans as JSON locally — useful for development and tests.

Configuration

Set BEACON_ENDPOINT and BEACON_API_KEY and BeaconClient() needs no arguments; constructor parameters override environment variables. BEACON_ENABLED=false (or enabled=False) turns tracing off completely. The full list of settings is in the configuration page of the guide.

Documentation

The full usage guide ships inside the package, at lumenova_beacon/docs/, so every install carries the copy that matches its version. Start at lumenova_beacon/docs/README.md. To find it in your environment:

python -c "import lumenova_beacon, pathlib; print(pathlib.Path(lumenova_beacon.__file__).parent / 'docs')"

Paths below are relative to lumenova_beacon/docs/.

Core

Configuration — configuration.md. Environment variables and constructor options, project routing for workspace API keys, TLS/proxy settings, the off switch, file transport, errors and retries.
Tracing — tracing.md. @trace, client.trace() and client.create_span(); sessions; set_session() / set_agent() to name a trace's session and agent from inside a request; multimodal images; the span API and enums.
Context propagation — context-propagation.md. One trace across Beacon and OpenTelemetry spans; the inbound_context policy for Cloud Run / GCLB / ELB; inject_trace_context() / start_consumer_span() across queues and topics.
Data masking — masking.md. A masking function (custom, or backed by Beacon Guardrails) plus a deterministic PII floor on every exported span; fail-closed behavior and the Guardrails call limits.
Span noise control — span-filtering.md. SpanFilter rules, predicates, and when drop_parentless is safe.
Agentic governance — governance.md. @governance, the LangChain governance handler and wrap(), BeaconLangGraphAgent, GovernanceConfig, streaming, the payload ceiling, and violation handling.
Guardrails — guardrails.md. Guardrail.apply(), grounding metadata, version pinning, end-user attribution, version history.
System probes — probes.md. Run a probe configured in the Beacon UI against a private HTTP API, with the built-in dispatcher or your own callable.

Integrations

LangChain / LangGraph — integrations/langchain.md. BeaconLangGraphHandler for chains and one-shot agents; BeaconLangGraphConfig for checkpointed agents that interrupt and resume; per-invocation identity.
Strands Agents — integrations/strands.md. BeaconStrandsHooks (recommended) and the legacy BeaconStrandsHandler; per-request identity via invocation_state.
CrewAI — integrations/crewai.md. BeaconCrewAIListener.
MCP — integrations/mcp.md. BeaconMCPMiddleware for FastMCP servers (span per request method, trace topology, noise defaults) and BeaconMCPClient for callers.
LiteLLM — integrations/litellm.md. BeaconLiteLLMLogger or auto_instrument_litellm=True.
Temporal — integrations/temporal.md. BeaconTemporalPlugin: replay-safe tracing of workflows, activities and messages; sessions from the starter or workflow memo.
FastAPI — integrations/fastapi.md. instrument_fastapi() and verify_fastapi_instrumentation().
OpenTelemetry instrumentors — integrations/opentelemetry.md. Anthropic, OpenAI, HTTPX, Redis and other instrumentors reporting to Beacon; sharing a process with another OTel pipeline.

Data APIs

ActiveRecord-style classes with sync and async (a-prefixed) methods.

Datasets — data/datasets.md. Dataset and DatasetRecord.
Prompts — data/prompts.md. Versioned text and chat prompts, labels, tags and categories, bulk fetch, LangChain conversion.
Experiments — data/experiments.md. Runs, variables and sweeps, macro-graph stages, external agents.
Evaluations — data/evaluations.md. Trace- and dataset-based evaluations, runs, extraction engines, statistics, evaluator versions, result export, environment promotion, clusters.
Traces — data/traces.md. Query, filter and export traces already in Beacon.
Agents & insights — data/agents.md. Agent registry, usage, findings, analysis runs.
Human annotations — data/annotations.md. Annotation queues and summaries.
LLM configs — data/llm-configs.md. LLMConfig.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Release files for lumenova-beacon 2.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lumenova-beacon 2.17.0
File	Size	Uploaded
lumenova_beacon-2.17.0.tar.gz	1.6 MB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for lumenova-beacon 2.17.0
File	Interpreter	ABI	Platform	Reset
lumenova_beacon-2.17.0-py3-none-any.whl 577.2 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 2.2 MB

Release files / lumenova_beacon-2.17.0.tar.gz

Download URL	lumenova_beacon-2.17.0.tar.gz
Size	1.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`db6f7b0066a950b6a1407d7ae897ec1b22e631b1bb1089859a0263f5b8b81f85`
BLAKE2b-256 checksum How to use checksums	`f97509d9cec900487ee9b548fbbe561cc830957492e173e731c559d18eec185f`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / lumenova_beacon-2.17.0-py3-none-any.whl

Download URL	lumenova_beacon-2.17.0-py3-none-any.whl
Size	577.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`358577daef21fc9aaf4c26150d51b7cde18d683045e3abd7aba0734367e807a7`
BLAKE2b-256 checksum How to use checksums	`5ab0da50df5b9ac2bb000625214a742540be58b71d9ff7e68589e512bbe20016`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`