> For the complete documentation index, see [llms.txt](https://docs.dbnl.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnl.com/v0.31.x/reference/python-sdk/sdk-functions.md).

# SDK Functions

### `convert_otlp_traces_data`

```python
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](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/\[https:/docs.dbnl.com/configuration/dbnl-semantic-convention]\(https:/docs.dbnl.com/configuration/dbnl-semantic-convention\)/README.md).

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](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/\[https:/github.com/open-telemetry/opentelemetry-proto/blob/e5a5dc1f2c7f9e0eefbe061f1d5c09c67722f4d6/opentelemetry/proto/trace/v1/trace.proto#L38-L45]\(https://github.com/open-telemetry/opentelemetry-proto/blob/e5a5dc1f2c7f9e0eefbe061f1d5c09c67722f4d6/opentelemetry/proto/trace/v1/trace.proto#L38-L45\))

* **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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#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`

```python
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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#Project) to create the [Metric](/v0.31.x/reference/python-sdk/classes.md#Metric) for
  * **`name`** – Name for the Metric
  * **`table`** – Table to create the [Metric](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLInputValidationError`** – Input does not conform to expected format
* **Returns:** Created Metric

### `create_project`

```python
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](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLAPIValidationError`** – dbnl API failed to validate the request
  * **`DBNLConflicting[Project](classes.md#Project)Error`** – [Project](/v0.31.x/reference/python-sdk/classes.md#Project) with the same name already exists
* **Returns:** Project

#### Examples:

```python
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`

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

Delete a Filter by id

* **Parameters:**
  * **`filter_id`** – Filter id
* **Returns:** `None`

### `delete_llm_model`

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

Delete an [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) by id.

* **Parameters:**
  * **`llm_model_id`** – [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) id
* **Returns:** [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) if found

### `delete_metric`

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

Delete a [Metric](/v0.31.x/reference/python-sdk/classes.md#Metric) by ID

* **Parameters:**
  * **`metric_id`** – ID of the metric to delete
* **Raises:**
  * **`DBNLNotLoggedInError`** – dbnl SDK is not logged in. See [`login`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLAPIValidationError`** – dbnl API failed to validate the request
* **Returns:** `None`

### `flatten_otlp_traces_data`

```python
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](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/\[https:/docs.dbnl.com/configuration/dbnl-semantic-convention]\(https:/docs.dbnl.com/configuration/dbnl-semantic-convention\)/README.md).

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](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/\[https:/github.com/open-telemetry/opentelemetry-proto/blob/e5a5dc1f2c7f9e0eefbe061f1d5c09c67722f4d6/opentelemetry/proto/trace/v1/trace.proto#L38-L45]\(https://github.com/open-telemetry/opentelemetry-proto/blob/e5a5dc1f2c7f9e0eefbe061f1d5c09c67722f4d6/opentelemetry/proto/trace/v1/trace.proto#L38-L45\))

* **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_filter`

```python
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:

```python
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`

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

Get an [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) by id or name.

* **Parameters:**
  * **`llm_model_id`** – Model id
  * **`name`** – [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) name
* **Returns:** [LLM Model](/v0.31.x/reference/python-sdk/classes.md#LLMModel) if found

#### Examples:

```python
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`

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

Get a [Metric](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLAPIValidationError`** – dbnl API failed to validate the request
* **Returns:** The requested metric

#### Examples:

```python
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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#LLMModel) 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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#Metric) by name, or create it if it does not exist.

* **Parameters:**
  * **`project_id`** – The [Project](/v0.31.x/reference/python-sdk/classes.md#Project) ID to get the [Metric](/v0.31.x/reference/python-sdk/classes.md#Metric) for
  * **`name`** – Name of the [Metric](/v0.31.x/reference/python-sdk/classes.md#Metric) to get
  * **`table`** – Table to get the [Metric](/v0.31.x/reference/python-sdk/classes.md#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:

```python
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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#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](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLAPIValidationError`** – dbnl API failed to validate the request
* **Returns:** Newly created or matching existing Project

#### Examples:

```python
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`

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

Retrieve a [Project](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNL[Project](classes.md#Project)NotFoundError`** – [Project](/v0.31.x/reference/python-sdk/classes.md#Project) with the given id does not exist.
  * **`DBNL[Project](classes.md#Project)NameNotFoundError`** – [Project](/v0.31.x/reference/python-sdk/classes.md#Project) with the given name does not exist.
* **Returns:** Project

#### Examples:

```python
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`

```python
dbnl.init_tracing(*,
	project_id: str,
	namespace_id: str | None = None,
	service_name: str | None = None,
	resource: Resource | None = None
) → 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.

Requires [`dbnl.login()`](#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 — creates a `Resource` with `service.name` set to this value. Ignored when *resource* is provided explicitly.
  * **`resource`** – An OpenTelemetry `Resource` attached to the provider. Takes precedence over `*service_name*`.
* **Returns:** The configured `TracerProvider`.

### `log`

```python
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](/v0.31.x/reference/python-sdk/classes.md#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`](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk/python-sdk.md#login).
  * **`DBNLInputValidationError`** – Input does not conform to expected format

### `login`

```python
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`

```python
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`

```python
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](/v0.31.x/reference/python-sdk/classes.md#LLMModel) 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`

```python
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
```