13416015178

from typing import List, Optional
from uuid import uuid4

from .typesgen import ImpactResponse, ModeledRow


class Tracer:
    """
    Tracer is responsible for tracking and aggregating environmental impact metrics
    from AI model interactions. It supports nested tracing, async operations, and
    provides detailed impact breakdowns for energy, emissions and water usage.

    Args:
        name (str, optional): Name identifier for the tracer. Defaults to None.
        keep_traces (bool, optional): Whether to keep trace history after completion.
            Defaults to False.
        client_id (str, optional): Client identifier for categorizing traces.
            Overrides global `SCOPE3AI_CLIENT_ID` setting. Defaults to None.
        project_id (str, optional): Project identifier for categorizing traces.
            Overrides global `SCOPE3AI_PROJECT_ID` setting. Defaults to None.
        application_id (str, optional): Application identifier for categorizing traces.
            Overrides global `SCOPE3AI_APPLICATION_ID` setting. Defaults to None.
        session_id (str, optional): Session identifier for tracking user sessions.
            Only available at tracer level. Defaults to None.
        trace_id (str, optional): Unique identifier for the trace.
            Auto-generated if not provided. Defaults to None.
    """

    def __init__(
        self,
        name: str = None,
        keep_traces: bool = False,
        client_id: Optional[str] = None,
        project_id: Optional[str] = None,
        application_id: Optional[str] = None,
        session_id: Optional[str] = None,
        trace_id: Optional[str] = None,
    ) -> None:
        from scope3ai.lib import Scope3AI

        self.trace_id = trace_id or uuid4().hex
        self.scope3ai = Scope3AI.get_instance()
        self.name = name
        self.keep_traces = keep_traces
        self.children: List[Tracer] = []
        self.rows: List[ModeledRow] = []
        self.traces = []  # type: List[Scope3AIContext]

        self.client_id = client_id
        self.project_id = project_id
        self.application_id = application_id
        self.session_id = session_id

    def impact(self, timeout: Optional[int] = None) -> ImpactResponse:
        """
        Return an aggregated impact response for the current tracer and its children.

        As the impact is computed asynchronously, this method will wait for the
        impact response to be available before returning it.
        """
        for trace in self.traces:
            trace.wait_impact(timeout)
        return self._impact()

    async def aimpact(self, timeout: Optional[int] = None) -> ImpactResponse:
        """
        Async version of Tracer::impact.
        """
        for trace in self.traces:
            await trace.await_impact(timeout)
        return self._impact()

    def _impact(self) -> ImpactResponse:
        """
        Return an aggregated impact response for the current tracer and its children.
        """
        all_rows = self.get_all_rows()
        return ImpactResponse(
            rows=all_rows,
            total_energy_wh=sum([row.total_impact.usage_energy_wh for row in all_rows]),
            total_gco2e=sum(
                [row.total_impact.usage_emissions_gco2e for row in all_rows]
            ),
            total_mlh2o=sum([row.total_impact.usage_water_ml for row in all_rows]),
            has_errors=any([row.error is not None for row in all_rows]),
        )

    def add_impact(self, impact: ModeledRow) -> None:
        self.rows.append(impact)

    def get_all_rows(self) -> List[ModeledRow]:
        all_rows = self.rows[:]
        for child in self.children:
            all_rows.extend(child.get_all_rows())
        return all_rows

    def _link_parent(self, parent: Optional["Tracer"]) -> None:
        if parent and (self not in parent.children):
            parent.children.append(self)

    def _unlink_parent(self, parent: Optional["Tracer"]) -> None:
        pass

    def _link_trace(self, trace) -> None:
        if trace not in self.traces:
            self.traces.append(trace)

    def _unlink_trace(self, trace) -> None:
        if self.keep_traces:
            return
        if trace in self.traces:
            self.traces.remove(trace)

1	from typing import List, Optional	4✔
2	from uuid import uuid4	4✔
3
4	from .typesgen import ImpactResponse, ModeledRow	4✔
5
6
7	class Tracer:	4✔
8	"""
9	Tracer is responsible for tracking and aggregating environmental impact metrics
10	from AI model interactions. It supports nested tracing, async operations, and
11	provides detailed impact breakdowns for energy, emissions and water usage.
12
13	Args:
14	name (str, optional): Name identifier for the tracer. Defaults to None.
15	keep_traces (bool, optional): Whether to keep trace history after completion.
16	Defaults to False.
17	client_id (str, optional): Client identifier for categorizing traces.
18	Overrides global `SCOPE3AI_CLIENT_ID` setting. Defaults to None.
19	project_id (str, optional): Project identifier for categorizing traces.
20	Overrides global `SCOPE3AI_PROJECT_ID` setting. Defaults to None.
21	application_id (str, optional): Application identifier for categorizing traces.
22	Overrides global `SCOPE3AI_APPLICATION_ID` setting. Defaults to None.
23	session_id (str, optional): Session identifier for tracking user sessions.
24	Only available at tracer level. Defaults to None.
25	trace_id (str, optional): Unique identifier for the trace.
26	Auto-generated if not provided. Defaults to None.
27	"""
28
29	def __init__(	4✔
30	self,
31	name: str = None,
32	keep_traces: bool = False,
33	client_id: Optional[str] = None,
34	project_id: Optional[str] = None,
35	application_id: Optional[str] = None,
36	session_id: Optional[str] = None,
37	trace_id: Optional[str] = None,
38	) -> None:
39	from scope3ai.lib import Scope3AI	4✔
40
41	self.trace_id = trace_id or uuid4().hex	4✔
42	self.scope3ai = Scope3AI.get_instance()	4✔
43	self.name = name	4✔
44	self.keep_traces = keep_traces	4✔
45	self.children: List[Tracer] = []	4✔
46	self.rows: List[ModeledRow] = []	4✔
47	self.traces = [] # type: List[Scope3AIContext]	4✔
48
49	self.client_id = client_id	4✔
50	self.project_id = project_id	4✔
51	self.application_id = application_id	4✔
52	self.session_id = session_id	4✔
53
54	def impact(self, timeout: Optional[int] = None) -> ImpactResponse:	4✔
55	"""
56	Return an aggregated impact response for the current tracer and its children.
57
58	As the impact is computed asynchronously, this method will wait for the
59	impact response to be available before returning it.
60	"""
61	for trace in self.traces:	4✔
62	trace.wait_impact(timeout)	4✔
63	return self._impact()	4✔
64
65	async def aimpact(self, timeout: Optional[int] = None) -> ImpactResponse:	4✔
66	"""
67	Async version of Tracer::impact.
68	"""
69	for trace in self.traces:	×
70	await trace.await_impact(timeout)	×
71	return self._impact()	×
72
73	def _impact(self) -> ImpactResponse:	4✔
74	"""
75	Return an aggregated impact response for the current tracer and its children.
76	"""
77	all_rows = self.get_all_rows()	4✔
78	return ImpactResponse(	4✔
79	rows=all_rows,
80	total_energy_wh=sum([row.total_impact.usage_energy_wh for row in all_rows]),
81	total_gco2e=sum(
82	[row.total_impact.usage_emissions_gco2e for row in all_rows]
83	),
84	total_mlh2o=sum([row.total_impact.usage_water_ml for row in all_rows]),
85	has_errors=any([row.error is not None for row in all_rows]),
86	)
87
88	def add_impact(self, impact: ModeledRow) -> None:	4✔
89	self.rows.append(impact)	4✔
90
91	def get_all_rows(self) -> List[ModeledRow]:	4✔
92	all_rows = self.rows[:]	4✔
93	for child in self.children:	4✔
94	all_rows.extend(child.get_all_rows())	4✔
95	return all_rows	4✔
96
97	def _link_parent(self, parent: Optional["Tracer"]) -> None:	4✔
98	if parent and (self not in parent.children):	4✔
99	parent.children.append(self)	4✔
100
101	def _unlink_parent(self, parent: Optional["Tracer"]) -> None:	4✔
102	pass	4✔
103
104	def _link_trace(self, trace) -> None:	4✔
105	if trace not in self.traces:	4✔
106	self.traces.append(trace)	4✔
107
108	def _unlink_trace(self, trace) -> None:	4✔
109	if self.keep_traces:	4✔
110	return	4✔
111	if trace in self.traces:	4✔
112	self.traces.remove(trace)	4✔

scope3data / scope3ai-py / 13416015178

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous