SDK Functions

Distributional is now Talaria Scientific. The DBNL product described in these docs has been sunset; this documentation is preserved for reference. Read the announcement.

`convert_otlp_traces_data`

dbnl.convert_otlp_traces_data(data: pd.Series[Any],
	format: Literal['otlp_json',
	'otlp_proto'] | None = None
) → pd.Series[Any]

Converts a Series of OTLP TracesData to a Series of DBNL spans matching the DBNL semantic convention.

The resulting Series can be used as is to fill the spans column of a DataFrame to be logged with the dbnl.log function.

For a complete specification of the TracesData format, see the OTLP specification

Parameters:
- data: Series of OTLP TracesData
- format: OTLP TracesData format (otlp_json or otlp_proto) or None to infer from data
Returns: Series of spans data

`create_filter`

dbnl.create_filter(project_id: str,
	name: str,
	table: Literal['spans',
	'traces',
	'sessions'],
	description: str | None = None,
	conditions: list[FilterCondition] | None = None,
	expression: str | None = None
) → Filter

Create a new Filter

Parameters:
- project_id: The Project ID to create the Filter for
- name: Name for the Filter
- table: Table to create the Filter for
- description: Optional description of the Filter
- conditions: Conditions for the Filter
- expression: Expression string e.g. length(traces.input) > 10
Returns: Created Filter

`create_llm_model`

dbnl.create_llm_model(*,
	name: str,
	description: str | None = None,
	type: Literal['completion',
	'embedding'] | None = 'completion',
	provider: str,
	model: str,
	params: dict[str,
	Any] | None = None
) → LLMModel

Create an LLM Model.

Parameters:
- name: Model name
- description: Model description, defaults to None
- type: Model type (e.g. completion or embedding), defaults to “completion”
- provider: Model provider (e.g. openai, bedrock, etc.)
- model: Model (e.g. gpt-4, gpt-3.5-turbo, etc.)
- params: Model provider parameters (e.g. api key), defaults to None
Returns: LLM Model

`create_metric`

dbnl.create_metric(*,
	project: Project | None = None,
	project_id: str | None = None,
	name: str,
	table: Literal['spans',
	'traces',
	'sessions'] = 'traces',
	expression: str,
	description: str | None = None,
	greater_is_better: bool | None = None
) → Metric

Create a new Metric

Parameters:
- project: The Project to create the Metric for
- name: Name for the Metric
- table: Table to create the Metric for
- expression: Expression string e.g. length(traces.input)
- description: Optional description of what computation the metric is performing
- greater_is_better: Flag indicating whether greater values are semantically ‘better’ than lesser values
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLInputValidationError: Input does not conform to expected format
Returns: Created Metric

`create_project`

dbnl.create_project(*,
	name: str,
	description: str | None = None,
	default_llm_model_id: str | None = None,
	default_llm_model_name: str | None = None,
	template: Literal['default'] | None = 'default'
) → Project

Create a new Project

Parameters:
- name: Name for the Project
- description: Description for the Project, defaults to None. Description is limited to 255 characters.
- default_llm_model_id: Default model connection used for LLM metrics that don’t specify a model. If None, the global default model connection will be used, if configured.
- default_llm_model_name: Default model connection (by name) used for LLM metrics that don’t specify a model. If None, the global default model connection will be used, if configured. Only one of default_llm_model_id and default_llm_model_name can be provided.
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLAPIValidationError: dbnl API failed to validate the request
- DBNLConflicting[Project](classes.md#Project)Error: Project with the same name already exists
Returns: Project

Examples:

import dbnl

dbnl.login()

proj_1 = dbnl.create_project(name="test_p1")

# With a default model specified by name
proj_2 = dbnl.create_project(
    name="test_p2",
    default_llm_model_name="my-gpt4-model",
)

# Or by model ID
proj_3 = dbnl.create_project(
    name="test_p3",
    default_llm_model_id="llm_lKQReG8Bq7CkiFmVzw1r2",
)

# DBNLConflictingProjectError: A Project with name test_p1 already exists.
dbnl.create_project(name="test_p1")

`delete_filter`

dbnl.delete_filter(*,
	filter_id: str
) → None

Delete a Filter by id

Parameters:
- filter_id: Filter id
Returns: None

`delete_llm_model`

dbnl.delete_llm_model(*,
	llm_model_id: str
) → None

Delete an LLM Model by id.

Parameters:
- llm_model_id: LLM Model id
Returns: LLM Model if found

`delete_metric`

dbnl.delete_metric(*,
	metric_id: str
) → None

Delete a Metric by ID

Parameters:
- metric_id: ID of the metric to delete
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLAPIValidationError: dbnl API failed to validate the request
Returns: None

`flatten_otlp_traces_data`

dbnl.flatten_otlp_traces_data(data: pd.Series[Any],
	format: Literal['otlp_json',
	'otlp_proto'] | None = None
) → DataFrame

Flattens a Series of OTLP TracesData to a DataFrame matching the DBNL semantic convention.

The resulting DataFrame can be used as is to be logged with the dbnl.log function and will included all minimally required columns (timestamp, input, output) as well as the spans column for further flattening server-side.

For a complete specification of the TracesData format, see the OTLP specification

Parameters:
- data: Series of OTLP TracesData
- format: OTLP TracesData format (otlp_json or otlp_proto) or None to infer from data
Returns: DataFrame with columns timestamp, input, output, spans

`get_dbnl_exporter`

dbnl.get_dbnl_exporter(*,
	project_id: str,
	namespace_id: str | None = None
) → OTLPSpanExporter

Return an OTLP span exporter configured for the dbnl ingestion endpoint.

Useful when you manage your own TracerProvider and want to wire dbnl into an existing pipeline without init_tracing().

Requires dbnl.login() to have been called first.

Parameters:
- project_id: dbnl project ID used to route ingested traces.
- namespace_id: dbnl namespace ID used to route ingested traces. When omitted, the header is not sent and the server uses the organization’s default namespace.
Returns: A configured OTLPSpanExporter.

`get_dbnl_span_processor`

dbnl.get_dbnl_span_processor(*,
	project_id: str,
	namespace_id: str | None = None
) → BatchSpanProcessor

Return a BatchSpanProcessor wrapping the dbnl OTLP exporter.

A single call to provider.add_span_processor(get_dbnl_span_processor(...)) is all that’s needed to send traces to dbnl from any TracerProvider.

Requires dbnl.login() to have been called first.

Parameters:
- project_id: dbnl project ID used to route ingested traces.
- namespace_id: dbnl namespace ID used to route ingested traces. When omitted, the header is not sent and the server uses the organization’s default namespace.
Returns: A BatchSpanProcessor ready to be added to a provider.

`get_filter`

dbnl.get_filter(*,
	filter_id: str | None = None,
	name: str | None = None
) → Filter

Get a Filter by id or name.

Parameters:
- filter_id: Filter id
- name: Filter name
Returns: Filter

Examples:

import dbnl

dbnl.login()

# By id
f = dbnl.get_filter(filter_id="filter_123")

# By name
f = dbnl.get_filter(name="long_inputs")

`get_llm_model`

dbnl.get_llm_model(*,
	llm_model_id: str | None = None,
	name: str | None = None
) → LLMModel

Get an LLM Model by id or name.

Parameters:
- llm_model_id: Model id
- name: LLM Model name
Returns: LLM Model if found

Examples:

import dbnl

dbnl.login()

# By id
model = dbnl.get_llm_model(llm_model_id="model_123")

# By name
model = dbnl.get_llm_model(name="gpt-4")

`get_metric`

dbnl.get_metric(*,
	metric_id: str | None = None,
	name: str | None = None
) → Metric

Get a Metric by ID or name.

Parameters:
- metric_id: ID of the metric to get
- name: Name of the metric to get
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLAPIValidationError: dbnl API failed to validate the request
Returns: The requested metric

Examples:

import dbnl

dbnl.login()

# By ID
metric = dbnl.get_metric(metric_id="metric_123")

# By name
metric = dbnl.get_metric(name="input_length")

`get_or_create_filter`

dbnl.get_or_create_filter(*,
	project_id: str,
	name: str,
	table: Literal['spans',
	'traces',
	'sessions'],
	description: str | None = None,
	conditions: list[FilterCondition] | None = None,
	expression: str | None = None
) → Filter

Get a Filter by name, or create it if it does not exist.

Parameters:
- project_id: The Project ID to get the Filter for
- name: Name of the Filter to get
- table: Table to get the Filter for
- description: Optional description of the Filter
- conditions: Conditions for the Filter
- expression: Expression string e.g. length(traces.input) > 10
Returns: Filter

`get_or_create_llm_model`

dbnl.get_or_create_llm_model(*,
	name: str,
	description: str | None = None,
	type: Literal['completion',
	'embedding'] | None = 'completion',
	provider: str,
	model: str,
	params: dict[str,
	Any] | None = None
) → LLMModel

Get an LLM Model by name, or create it if it does not exist.

Parameters:
- name: Model name
- description: Model description, defaults to None
- type: Model type (e.g. completion or embedding), defaults to “completion”
- provider: Model provider (e.g. openai, bedrock, etc.)
- model: Model (e.g. gpt-4, gpt-3.5-turbo, etc.)
- params: Model provider parameters (e.g. api key), defaults to None
Returns: Model

`get_or_create_metric`

dbnl.get_or_create_metric(*,
	project: Project | None = None,
	project_id: str | None = None,
	name: str,
	table: Literal['spans',
	'traces',
	'sessions'] = 'traces',
	expression: str,
	description: str | None = None,
	greater_is_better: bool | None = None
) → Metric

Get a Metric by name, or create it if it does not exist.

Parameters:
- project_id: The Project ID to get the Metric for
- name: Name of the Metric to get
- table: Table to get the Metric for
- expression: Expression string e.g. length(traces.input)
- description: Optional description of what computation the metric is performing
- greater_is_better: Flag indicating whether greater values are semantically ‘better’ than lesser values

Examples:

import dbnl

dbnl.login()

# By project_id
metric = dbnl.get_or_create_metric(
    project_id="proj_123",
    name="input_length",
    expression="length(traces.input)",
)

`get_or_create_project`

dbnl.get_or_create_project(*,
	name: str,
	description: str | None = None,
	default_llm_model_id: str | None = None,
	default_llm_model_name: str | None = None,
	template: Literal['default'] | None = 'default'
) → Project

Get the Project with the specified name or create a new one if it does not exist

Parameters:
- name: Name for the Project
- description: Description for the Project, defaults to None
- default_llm_model_id: Default model connection used for LLM metrics that don’t specify a model. If None, the global default model connection will be used, if configured.
- default_llm_model_name: Default model connection (by name) used for LLM metrics that don’t specify a model. If None, the global default model connection will be used, if configured. Only one of default_llm_model_id and default_llm_model_name can be provided.
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLAPIValidationError: dbnl API failed to validate the request
Returns: Newly created or matching existing Project

Examples:

import dbnl

dbnl.login()

proj_1 = dbnl.create_project(name="test_p1")
proj_2 = dbnl.get_or_create_project(name="test_p1")

assert proj_1.id == proj_2.id

# With a default model specified by name
proj_3 = dbnl.get_or_create_project(
    name="test_p2",
    default_llm_model_name="my-gpt4-model",
)

# Or by model ID
proj_4 = dbnl.get_or_create_project(
    name="test_p3",
    default_llm_model_id="llm_lKQReG8Bq7CkiFmVzw1r2",
)

`get_project`

dbnl.get_project(*,
	project_id: str | None = None,
	name: str | None = None
) → Project

Retrieve a Project by id or name.

Parameters:
- project_id: The id for the existing Project.
- name: The name for the existing Project.
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNL[Project](classes.md#Project)NotFoundError: Project with the given id does not exist.
- DBNL[Project](classes.md#Project)NameNotFoundError: Project with the given name does not exist.
Returns: Project

Examples:

import dbnl

dbnl.login()

proj_1 = dbnl.create_project(name="test_p1")

# Retrieve by id
proj_2 = dbnl.get_project(project_id=proj_1.id)
assert proj_1.id == proj_2.id

# Retrieve by name
proj_3 = dbnl.get_project(name="test_p1")
assert proj_1.id == proj_3.id

`init_tracing`

dbnl.init_tracing(*,
	project_id: str,
	namespace_id: str | None = None,
	service_name: str | None = None,
	resource: Resource | None = None,
	tracer_provider: TracerProvider | None = None,
	auto_instrument: bool = True
) → TracerProvider

Initialize OpenTelemetry tracing for the dbnl platform.

Configures a TracerProvider with an OTLP HTTP exporter that sends traces to the dbnl ingestion endpoint. The provider is registered as the global tracer provider so any opentelemetry instrumentation picks it up automatically.

When tracer_provider is supplied, the dbnl span processor is added to it directly. The provider is not registered as the global tracer provider and is not tracked internally; the caller owns the lifecycle.

Requires dbnl.login() to have been called first.

Parameters:
- project_id: dbnl project ID used to route ingested traces.
- namespace_id: dbnl namespace ID used to route ingested traces. When omitted, the header is not sent and the server uses the organization’s default namespace.
- service_name: Convenience shorthand that creates a Resource with service.name set to this value. Ignored when resource or *tracer_provider* is provided.
- resource: An OpenTelemetry Resource attached to the provider. Takes precedence over *service_name*. Ignored when *tracer_provider* is provided.
- tracer_provider: An existing TracerProvider to attach the dbnl span processor to. When provided, *service_name* and resource are ignored, the provider is not set as the global tracer provider, and no duplicate-call warning is issued.
- auto_instrument: When True (default), automatically discovers and instruments all installed OpenInference instrumentor packages.
Returns: The configured TracerProvider.

`log`

dbnl.log(*,
	project_id: str,
	otlp_data: Series,
	data_start_time: datetime,
	data_end_time: datetime,
	otlp_format: Literal['otlp_json',
	'otlp_proto'] | None = None,
	wait_timeout: float | None = 600,
	spans_extra: DataFrame | None = None,
	traces_extra: DataFrame | None = None,
	sessions_extra: DataFrame | None = None
) → None

Log OTLP trace data for a date range to a project.

Parameters:
- project_id: The Project id to send the logs to.
- otlp_data: Pandas Series of OTLP TracesData (proto bytes or JSON).
- data_start_time: Data start date.
- data_end_time: Data end time.
- otlp_format: OTLP format (“otlp_json” or “otlp_proto”), or None to auto-detect.
- wait_timeout: If set, the function will block for up to wait_timeout seconds until the data is done processing, defaults to 10 minutes.
Raises:
- DBNLNotLoggedInError: dbnl SDK is not logged in. See login.
- DBNLInputValidationError: Input does not conform to expected format

dbnl.login(*,
	api_token: str | None = None,
	api_url: str | None = None,
	app_url: str | None = None,
	verify: bool = True
) → None

Setup dbnl SDK to make authenticated requests. After login is run successfully, the dbnl client will be able to issue secure and authenticated requests against hosted endpoints of the dbnl service.

Parameters:
- api_token: dbnl API token for authentication; token can be found at /tokens page of the dbnl app. If None is provided, the environment variable DBNL_API_TOKEN will be used by default.
- namespace_id: The namespace ID to use for the session.
- api_url: The base url of the Distributional API. By default, this is set to localhost:8080/api, for sandbox users. For other users, please contact your sys admin. If None is provided, the environment variable DBNL_API_URL will be used by default.
- app_url: An optional base url of the Distributional app. If this variable is not set, the app url is inferred from the DBNL_API_URL variable. For on-prem users, please contact your sys admin if you cannot reach the Distributional UI.

`update_filter`

dbnl.update_filter(*,
	filter_id: str,
	name: str | None = None,
	description: str | None = None,
	conditions: list[FilterCondition] | None = None,
	expression: str | None = None
) → Filter

Update a Filter by id

Parameters:
- filter_id: Filter id
- name: Filter name
- description: Filter description
- conditions: Filter conditions
- expression: Filter expression
Returns: Updated Filter

`update_llm_model`

dbnl.update_llm_model(*,
	llm_model_id: str,
	name: str | None = None,
	description: str | None = None,
	model: str | None = None,
	params: dict[str,
	Any] | None = None
) → LLMModel

Update an LLM Model by id.

Parameters:
- llm_model_id: Model id
- name: Model name
- description: Model description, defaults to None
- model: Model (e.g. gpt-4, gpt-3.5-turbo, etc.)
- params: Model provider parameters (e.g. api key), defaults to {}
Returns: Updated LLM Model

`update_metric`

dbnl.update_metric(*,
	metric_id: str,
	name: str | None = None,
	expression: str | None = None,
	description: str | None = None,
	greater_is_better: bool | None = None
) → Metric

PreviousPython SDK NextClasses