prefactor_langchain.spans module
prefactor_langchain.spans module
Section titled “prefactor_langchain.spans module”LangChain-specific span definitions for Prefactor observability.
This module defines span dataclasses that capture LangChain-specific semantics using the ‘langchain:
*’ type namespace. These spans are self-contained and can be serialized to JSON for transport to the backend.
Note: span_id, parent_span_id, and trace_id are managed by the backend automatically, so they are not included in these span definitions.
class prefactor_langchain.spans.AgentSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, agent_name: str | None = None, agent_config: dict[str, ~typing.Any]=, initial_messages: list[dict[str, ~typing.Any]]=, final_messages: list[dict[str, ~typing.Any]]=, iteration_count: int = 0)
Section titled “class prefactor_langchain.spans.AgentSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, agent_name: str | None = None, agent_config: dict[str, ~typing.Any]=, initial_messages: list[dict[str, ~typing.Any]]=, final_messages: list[dict[str, ~typing.Any]]=, iteration_count: int = 0)”Bases: LangChainSpan
Span representing an agent execution.
Captures the lifecycle of an agent run, including the agent’s name, configuration, and the messages/state that drove the execution.
agent_config : dict[str, Any]
Section titled “agent_config : dict[str, Any]”agent_name : str | None = None
Section titled “agent_name : str | None = None”final_messages : list[dict[str, Any]]
Section titled “final_messages : list[dict[str, Any]]”initial_messages : list[dict[str, Any]]
Section titled “initial_messages : list[dict[str, Any]]”iteration_count : int = 0
Section titled “iteration_count : int = 0”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert to dictionary including agent-specific fields.
type : str = ‘langchain:agent’
Section titled “type : str = ‘langchain:agent’”class prefactor_langchain.spans.ErrorInfo(error_type: str, message: str, stacktrace: str | None = None)
Section titled “class prefactor_langchain.spans.ErrorInfo(error_type: str, message: str, stacktrace: str | None = None)”Bases: object
Error information for failed spans.
error_type : str
Section titled “error_type : str”message : str
Section titled “message : str”stacktrace : str | None = None
Section titled “stacktrace : str | None = None”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert to dictionary for serialization.
class prefactor_langchain.spans.LLMSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, model_name: str | None = None, provider: str | None = None, token_usage: TokenUsage | None = None, temperature: float | None = None, max_tokens: int | None = None, top_p: float | None = None, stop_sequences: list[str] = , messages: list[dict[str, ~typing.Any]]=, response_content: str | None = None)
Section titled “class prefactor_langchain.spans.LLMSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, model_name: str | None = None, provider: str | None = None, token_usage: TokenUsage | None = None, temperature: float | None = None, max_tokens: int | None = None, top_p: float | None = None, stop_sequences: list[str] = , messages: list[dict[str, ~typing.Any]]=, response_content: str | None = None)”Bases: LangChainSpan
Span representing an LLM call.
Captures model-specific metadata including the model name, provider, token usage, and generation parameters.
max_tokens : int | None = None
Section titled “max_tokens : int | None = None”messages : list[dict[str, Any]]
Section titled “messages : list[dict[str, Any]]”model_name : str | None = None
Section titled “model_name : str | None = None”provider : str | None = None
Section titled “provider : str | None = None”response_content : str | None = None
Section titled “response_content : str | None = None”stop_sequences : list[str]
Section titled “stop_sequences : list[str]”temperature : float | None = None
Section titled “temperature : float | None = None”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert to dictionary including LLM-specific fields.
token_usage : TokenUsage | None = None
Section titled “token_usage : TokenUsage | None = None”top_p : float | None = None
Section titled “top_p : float | None = None”type : str = ‘langchain:llm’
Section titled “type : str = ‘langchain:llm’”class prefactor_langchain.spans.LangChainSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’)
Section titled “class prefactor_langchain.spans.LangChainSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’)”Bases: object
Base class for all LangChain spans.
All LangChain spans share common fields for timing, status, inputs/outputs, and error information. Trace correlation (span_id, parent_span_id, trace_id) is handled by the backend.
Note: The ‘type’ field is defined in subclasses to avoid dataclass field shadowing issues.
complete(outputs: dict[str, Any] | None = None) → None
Section titled “complete(outputs: dict[str, Any] | None = None) → None”Mark the span as completed with outputs.
end_time : float | None = None
Section titled “end_time : float | None = None”error : ErrorInfo | None = None
Section titled “error : ErrorInfo | None = None”fail(error: Exception) → None
Section titled “fail(error: Exception) → None”Mark the span as failed with error information.
inputs : dict[str, Any]
Section titled “inputs : dict[str, Any]”metadata : dict[str, Any]
Section titled “metadata : dict[str, Any]”name : str = ‘unnamed’
Section titled “name : str = ‘unnamed’”outputs : dict[str, Any] | None = None
Section titled “outputs : dict[str, Any] | None = None”start_time : float
Section titled “start_time : float”status : Literal[‘pending’, ‘running’, ‘completed’, ‘failed’] = ‘pending’
Section titled “status : Literal[‘pending’, ‘running’, ‘completed’, ‘failed’] = ‘pending’”tags : list[str]
Section titled “tags : list[str]”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert span to dictionary for serialization.
Returns a JSON-serializable dictionary representation of the span.
type : str = ‘langchain:agent’
Section titled “type : str = ‘langchain:agent’”class prefactor_langchain.spans.TokenUsage(prompt_tokens: int, completion_tokens: int, total_tokens: int)
Section titled “class prefactor_langchain.spans.TokenUsage(prompt_tokens: int, completion_tokens: int, total_tokens: int)”Bases: object
Token usage information for LLM calls.
completion_tokens : int
Section titled “completion_tokens : int”prompt_tokens : int
Section titled “prompt_tokens : int”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert to dictionary for serialization.
total_tokens : int
Section titled “total_tokens : int”class prefactor_langchain.spans.ToolSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, tool_name: str | None = None, tool_schema: dict[str, ~typing.Any] | None=None, arguments: dict[str, ~typing.Any]=, execution_time_ms: int | None = None, tool_type: str | None = None, retriever_metadata: dict[str, ~typing.Any] | None=None)
Section titled “class prefactor_langchain.spans.ToolSpan(name: str = ‘unnamed’, start_time: float = , end_time: float | None = None, status: Literal[‘pending’, ‘running’, ‘completed’, ‘failed’]=‘pending’, inputs: dict[str, ~typing.Any]=, outputs: dict[str, ~typing.Any] | None=None, metadata: dict[str, ~typing.Any]=, tags: list[str] = , error: ErrorInfo | None = None, type: str = ‘langchain:agent’, tool_name: str | None = None, tool_schema: dict[str, ~typing.Any] | None=None, arguments: dict[str, ~typing.Any]=, execution_time_ms: int | None = None, tool_type: str | None = None, retriever_metadata: dict[str, ~typing.Any] | None=None)”Bases: LangChainSpan
Span representing a tool execution.
Captures tool-specific metadata including the tool name, schema, arguments, and execution time. Can represent any tool call including retrievers (with appropriate metadata).
arguments : dict[str, Any]
Section titled “arguments : dict[str, Any]”execution_time_ms : int | None = None
Section titled “execution_time_ms : int | None = None”retriever_metadata : dict[str, Any] | None = None
Section titled “retriever_metadata : dict[str, Any] | None = None”to_dict() → dict[str, Any]
Section titled “to_dict() → dict[str, Any]”Convert to dictionary including tool-specific fields.