Opik Observability Integration

This package integrates Opik tracing with the Bridgic framework, providing worker granularity tracing implementation.

Installation

# Automatically install the Opik package
pip install bridgic-traces-opik

Prerequisites

Before using OpikTraceCallback, you need to configure Opik. You can choose between two options:

• To use the hosted version, you need to create a Comet account and grab your API Key.
• To run the Opik platform locally, see the installation guide for more information.

The recommended way to configure the Python SDK is to run the opik configure command. It prompts you to enter your API key and, if applicable, the Opik instance URL so requests are routed and authenticated correctly. All details are saved to a configuration file.

If you are using the Cloud version of the platform, you can configure the SDK by running:

import opik

opik.configure(use_local=False)

You can also configure the SDK by calling configure from the command line:

opik configure

If you are self-hosting the platform, you can configure the SDK by running:

import opik

opik.configure(use_local=True)

or from the command line:

opik configure --use_local

Both variants of configure prompt you for the required information and save it to ~/.opik.config. When using the command-line version, you can pass the -y or --yes flag to automatically approve any confirmation prompts:

opik configure --yes

Once configured, you can start using OpikTraceCallback in your Bridgic applications.

Usage

The OpikTraceCallback can be configured in two ways:

Method 1: Per-Automa Scope with RunningOptions

Apply the callback only to a single automa by configuring it through RunningOptions. In this mode, every worker instantiated by that automa receives its own callback instance, while other automa remain unaffected.

from bridgic.core.automa import GraphAutoma, RunningOptions, worker
from bridgic.core.automa.worker import WorkerCallbackBuilder
from bridgic.traces.opik import OpikTraceCallback
import asyncio

class MyAutoma(GraphAutoma):
    @worker(is_start=True)
    async def step1(self):
        await asyncio.sleep(1)
        return "hello"
    
    @worker(dependencies=["step1"], is_output=True)
    async def step2(self, step1: str):
        await asyncio.sleep(1)
        return f"{step1} world"

async def main():
    builder = WorkerCallbackBuilder(
        OpikTraceCallback, 
        init_kwargs={"project_name": "my-project"}
    )
    running_options = RunningOptions(callback_builders=[builder])
    automa = MyAutoma(running_options=running_options)
    result = await automa.arun()
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

Method 2: Global Scope with GlobalSetting

You can register the callback at the global level through GlobalSetting to make it effective for every automa in the runtime. Each worker, regardless of which automa creates it, is instrumented with the same callback configuration.

from bridgic.core.automa import GraphAutoma, worker
from bridgic.core.automa.worker import WorkerCallbackBuilder
from bridgic.core.config import GlobalSetting
from bridgic.traces.opik import OpikTraceCallback
import asyncio

# Configure global callback
GlobalSetting.set(callback_builders=[WorkerCallbackBuilder(
    OpikTraceCallback, 
    init_kwargs={"project_name": "my-project"}
)])

class MyAutoma(GraphAutoma):
    @worker(is_start=True)
    async def step1(self):
        await asyncio.sleep(1)
        return "hello"
    
    @worker(dependencies=["step1"], is_output=True)
    async def step2(self, step1: str):
        await asyncio.sleep(1)
        return f"{step1} world"


async def main():
    automa = MyAutoma()  # Automatically uses global callback
    result = await automa.arun()
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

From the perspective of tracking worker execution, the following approach is equivalent to the above one:

from bridgic.traces.opik import start_opik_trace

start_opik_trace(project_name="my-project")

However, start_opik_trace is a higher-level function that encapsulates the functionality of the first approach. As the framework may add tracking for more important phases in the future, start_opik_trace will provide a unified interface for all tracking capabilities, making it the recommended approach for most use cases.