lmnr 0.3.0b1__py3-none-any.whl → 0.3.2__py3-none-any.whl

lmnr/__init__.py

@@ -1,4 +1,7 @@
 from .sdk.client import Laminar
 from .sdk.decorators import observe, lmnr_context, wrap_llm_call
 from .sdk.interface import trace, TraceContext, SpanContext
+from .sdk.tracing_types import EvaluateEvent
 from .sdk.types import ChatMessage, PipelineRunError, PipelineRunResponse, NodeInput
+
+from .semantic_conventions import *

lmnr/sdk/client.py

@@ -38,6 +38,11 @@ class Laminar:
             self.project_api_key = dotenv.get_key(
                 dotenv_path=dotenv_path, key_to_get="LMNR_PROJECT_API_KEY"
             )
+        if not self.project_api_key:
+            raise ValueError(
+                "Please initialize the Laminar object with your project API key or set "
+                "the LMNR_PROJECT_API_KEY environment variable in your environment or .env file"
+            )
 
     def run(
         self,

lmnr/sdk/context.py

@@ -75,7 +75,6 @@ class LaminarContextManager:
                 user_id=user_id,
                 session_id=session_id,
                 release=release,
-                start_time=datetime.datetime.now(datetime.timezone.utc),
             )
             _root_trace_id_context.set(trace.id)
             _lmnr_stack_context.set([trace])
@@ -116,8 +115,6 @@ class LaminarContextManager:
             trace = stack[0]
             self.update_trace(
                 id=trace.id,
-                start_time=trace.startTime,
-                end_time=datetime.datetime.now(datetime.timezone.utc),
                 user_id=trace.userId,
                 session_id=trace.sessionId,
                 release=trace.release,
@@ -127,9 +124,7 @@ class LaminarContextManager:
             _lmnr_stack_context.set([])
 
         if error is not None:
-            self.update_current_trace(
-                success=False, end_time=datetime.datetime.now(datetime.timezone.utc)
-            )
+            self.update_current_trace(success=False)
 
         if inspect.isgenerator(result) or is_iterator(result):
             return self._collect_generator_result(
@@ -162,7 +157,8 @@ class LaminarContextManager:
     def update_current_span(
         self,
         metadata: Optional[dict[str, Any]] = None,
-        check_event_names: list[str] = None,
+        attributes: Optional[dict[str, Any]] = None,
+        evaluate_events: list[EvaluateEvent] = None,
         override: bool = False,
     ):
         stack = _lmnr_stack_context.get()
@@ -172,15 +168,21 @@ class LaminarContextManager:
         new_metadata = (
             metadata if override else {**(span.metadata or {}), **(metadata or {})}
         )
-        new_check_event_names = (
-            check_event_names
+        new_evaluate_events = (
+            evaluate_events
+            if override
+            else span.evaluateEvents + (evaluate_events or [])
+        )
+        new_attributes = (
+            attributes
             if override
-            else span.evaluateEvents + (check_event_names or [])
+            else {**(span.attributes or {}), **(attributes or {})}
         )
         self.update_span(
             span=span,
             metadata=new_metadata,
-            evaluate_events=new_check_event_names,
+            evaluate_events=new_evaluate_events,
+            attributes=new_attributes,
         )
 
     def update_current_trace(
@@ -190,7 +192,6 @@ class LaminarContextManager:
         release: Optional[str] = None,
         metadata: Optional[dict[str, Any]] = None,
         success: bool = True,
-        end_time: Optional[datetime.datetime] = None,
     ):
         existing_trace = (
             _lmnr_stack_context.get()[0] if _lmnr_stack_context.get() else None
@@ -199,8 +200,6 @@ class LaminarContextManager:
             return
         self.update_trace(
             id=existing_trace.id,
-            start_time=existing_trace.startTime,
-            end_time=end_time,
             user_id=user_id or existing_trace.userId,
             session_id=session_id or existing_trace.sessionId,
             release=release or existing_trace.release,
@@ -211,8 +210,6 @@ class LaminarContextManager:
     def update_trace(
         self,
         id: uuid.UUID,
-        start_time: Optional[datetime.datetime] = None,
-        end_time: Optional[datetime.datetime] = None,
         user_id: Optional[str] = None,
         session_id: Optional[str] = None,
         release: Optional[str] = None,
@@ -220,8 +217,6 @@ class LaminarContextManager:
         success: bool = True,
     ) -> Trace:
         trace = Trace(
-            start_time=start_time,
-            end_time=end_time,
             id=id,
             user_id=user_id,
             session_id=session_id,
@@ -245,6 +240,7 @@ class LaminarContextManager:
         attributes: Optional[dict[str, Any]] = None,
         check_event_names: list[str] = None,
     ) -> Span:
+        """Internal method to create a span object. Use `ObservationContext.span` instead."""
         span = Span(
             name=name,
             trace_id=trace_id,
@@ -263,18 +259,23 @@ class LaminarContextManager:
         self,
         span: Span,
         finalize: bool = False,
+        input: Optional[Any] = None,
         end_time: Optional[datetime.datetime] = None,
         output: Optional[Any] = None,
         metadata: Optional[dict[str, Any]] = None,
         attributes: Optional[dict[str, Any]] = None,
         evaluate_events: Optional[list[EvaluateEvent]] = None,
+        override: bool = False,
     ) -> Span:
+        """Internal method to update a span object. Use `SpanContext.update()` instead."""
         span.update(
+            input=input,
             end_time=end_time,
             output=output,
             metadata=metadata,
             attributes=attributes,
             evaluate_events=evaluate_events,
+            override=override,
         )
         if finalize:
             self._add_observation(span)
@@ -305,7 +306,13 @@ class LaminarContextManager:
                 f"No active span to add check event. Ignoring event. {name}"
             )
             return
-        stack[-1].evaluateEvents.append(EvaluateEvent(name=name, data=data))
+        stack[-1].evaluateEvents.append(
+            EvaluateEvent(
+                name=name,
+                data=data,
+                timestamp=datetime.datetime.now(datetime.timezone.utc),
+            )
+        )
 
     def run_pipeline(
         self,
@@ -328,7 +335,8 @@ class LaminarContextManager:
         )
 
     def _force_finalize_trace(self):
-        self.update_current_trace(end_time=datetime.datetime.now(datetime.timezone.utc))
+        # TODO: flush in progress spans as error?
+        pass
 
     def _add_observation(self, observation: Union[Span, Trace]) -> bool:
         return self.thread_manager.add_task(observation)

lmnr/sdk/decorators.py

@@ -5,6 +5,7 @@ from typing import Any, Callable, Literal, Optional, Union
 
 from .context import LaminarSingleton
 from .providers.fallback import FallbackProvider
+from ..semantic_conventions.gen_ai_spans import PROVIDER
 from .types import NodeInput, PipelineRunResponse
 from .utils import (
     PROVIDER_NAME_TO_OBJECT,
@@ -103,6 +104,7 @@ class LaminarDecorator:
     def update_current_span(
         self,
         metadata: Optional[dict[str, Any]] = None,
+        attributes: Optional[dict[str, Any]] = None,
         override: bool = False,
     ):
         """Update the current span with any optional metadata.
@@ -112,7 +114,9 @@ class LaminarDecorator:
             override (bool, optional): Whether to override the existing metadata. If False, metadata is merged with the existing metadata. Defaults to False.
         """
         laminar = LaminarSingleton().get()
-        laminar.update_current_span(metadata=metadata, override=override)
+        laminar.update_current_span(
+            metadata=metadata, attributes=attributes, override=override
+        )
 
     def update_current_trace(
         self,
@@ -232,7 +236,7 @@ def wrap_llm_call(func: Callable, name: str = None, provider: str = None) -> Cal
             if provider_module
             else {}
         )
-        attributes["provider"] = provider_name
+        attributes[PROVIDER] = provider_name
         span = laminar.observe_start(
             name=name, span_type="LLM", input=inp, attributes=attributes
         )
@@ -255,7 +259,7 @@ def wrap_llm_call(func: Callable, name: str = None, provider: str = None) -> Cal
             if provider_module
             else {}
         )
-        attributes["provider"] = provider_name
+        attributes[PROVIDER] = provider_name
         span = laminar.observe_start(
             name=name, span_type="LLM", input=inp, attributes=attributes
         )

lmnr/sdk/interface.py

@@ -24,9 +24,6 @@ class ObservationContext:
     def _get_parent(self) -> "ObservationContext":
         raise NotImplementedError
 
-    def end(self, *args, **kwargs):
-        raise NotImplementedError
-
     def update(self, *args, **kwargs):
         raise NotImplementedError
 
@@ -50,7 +47,7 @@ class ObservationContext:
         Returns:
             SpanContext: The new span context
         """
-        parent = self._get_parent()
+        parent = self
         parent_span_id = (
             parent.observation.id if isinstance(parent.observation, Span) else None
         )
@@ -87,16 +84,20 @@ class SpanContext(ObservationContext):
 
     def end(
         self,
+        input: Optional[Any] = None,
         output: Optional[Any] = None,
         metadata: Optional[dict[str, Any]] = None,
+        attributes: Optional[dict[str, Any]] = None,
         evaluate_events: Optional[list[EvaluateEvent]] = None,
         override: bool = False,
     ) -> "SpanContext":
         """End the span with the given output and optional metadata and evaluate events.
 
         Args:
+            input (Optional[Any], optional): Inputs to the span. Defaults to None.
             output (Optional[Any], optional): output of the span. Defaults to None.
             metadata (Optional[dict[str, Any]], optional): any additional metadata to the span. Defaults to None.
+            attributes (Optional[dict[str, Any]], optional): pre-defined attributes (see semantic-convention). Defaults to None.
             check_event_names (Optional[list[EvaluateEvent]], optional): List of events to evaluate for and tag. Defaults to None.
             override (bool, optional): override existing metadata fully. If False, metadata is merged. Defaults to False.
 
@@ -111,25 +112,31 @@ class SpanContext(ObservationContext):
             )
         self._get_parent()._children.pop(self.observation.id)
         return self._update(
+            input=input,
             output=output,
             metadata=metadata,
             evaluate_events=evaluate_events,
+            attributes=attributes,
             override=override,
             finalize=True,
         )
 
     def update(
         self,
+        input: Optional[Any] = None,
         output: Optional[Any] = None,
         metadata: Optional[dict[str, Any]] = None,
+        attributes: Optional[dict[str, Any]] = None,
         evaluate_events: Optional[list[EvaluateEvent]] = None,
         override: bool = False,
     ) -> "SpanContext":
         """Update the current span with (optionally) the given output and optional metadata and evaluate events, but don't end it.
 
         Args:
+            input (Optional[Any], optional): Inputs to the span. Defaults to None.
             output (Optional[Any], optional): output of the span. Defaults to None.
             metadata (Optional[dict[str, Any]], optional): any additional metadata to the span. Defaults to None.
+            attributes (Optional[dict[str, Any]], optional): pre-defined attributes (see semantic-convention). Defaults to None.
             check_event_names (Optional[list[EvaluateEvent]], optional): List of events to evaluate for and tag. Defaults to None.
             override (bool, optional): override existing metadata fully. If False, metadata is merged. Defaults to False.
 
@@ -137,9 +144,11 @@ class SpanContext(ObservationContext):
             SpanContext: the finished span context
         """
         return self._update(
+            input=input or self.observation.input,
             output=output or self.observation.output,
-            metadata=metadata or self.observation.metadata,
-            evaluate_events=evaluate_events or self.observation.evaluateEvents,
+            metadata=metadata,
+            evaluate_events=evaluate_events,
+            attributes=attributes,
             override=override,
             finalize=False,
         )
@@ -182,40 +191,39 @@ class SpanContext(ObservationContext):
         Returns:
             SpanContext: the updated span context
         """
-        existing_evaluate_events = self.observation.evaluateEvents
-        output = self.observation.output
         self._update(
-            output=output,
-            evaluate_events=existing_evaluate_events
-            + [EvaluateEvent(name=name, data=data)],
+            input=self.observation.input,
+            output=self.observation.output,
+            evaluate_events=[
+                EvaluateEvent(
+                    name=name,
+                    data=data,
+                    timestamp=datetime.datetime.now(datetime.timezone.utc),
+                )
+            ],
             override=False,
         )
 
     def _update(
         self,
+        input: Optional[Any] = None,
         output: Optional[Any] = None,
         metadata: Optional[dict[str, Any]] = None,
+        attributes: Optional[dict[str, Any]] = None,
         evaluate_events: Optional[list[EvaluateEvent]] = None,
         override: bool = False,
         finalize: bool = False,
     ) -> "SpanContext":
-        new_metadata = (
-            metadata
-            if override
-            else {**(self.observation.metadata or {}), **(metadata or {})}
-        )
-        new_evaluate_events = (
-            evaluate_events
-            if override
-            else self.observation.evaluateEvents + (evaluate_events or [])
-        )
         self.observation = laminar.update_span(
+            input=input,
+            output=output,
             span=self.observation,
             end_time=datetime.datetime.now(datetime.timezone.utc),
-            output=output,
-            metadata=new_metadata,
-            evaluate_events=new_evaluate_events,
+            metadata=metadata,
+            attributes=attributes,
+            evaluate_events=evaluate_events,
             finalize=finalize,
+            override=override,
         )
         return self
 
@@ -253,42 +261,6 @@ class TraceContext(ObservationContext):
             success=success if success is not None else self.observation.success,
         )
 
-    def end(
-        self,
-        user_id: Optional[str] = None,
-        session_id: Optional[str] = None,
-        release: Optional[str] = None,
-        metadata: Optional[dict[str, Any]] = None,
-        success: bool = True,
-    ) -> "TraceContext":
-        """End the current trace with the given metadata and success status.
-
-        Args:
-            user_id (Optional[str], optional): Custom user_id of your user. Useful for grouping and further analytics. Defaults to None.
-            session_id (Optional[str], optional): Custom session_id for your session. Random UUID is generated on Laminar side, if not specified.
-                                                  Defaults to None.
-            release (Optional[str], optional): _description_. Release of your application. Useful for grouping and further analytics. Defaults to None.
-            metadata (Optional[dict[str, Any]], optional):  any additional metadata to the trace. Defaults to None.
-            success (bool, optional): whether this trace ran successfully. Defaults to True.
-
-        Returns:
-            TraceContext: context of the ended trace
-        """
-        if self._children:
-            self._log.warning(
-                "Ending trace id: %s, but it has children that have not been finalized. Children: %s",
-                self.observation.id,
-                [child.observation.name for child in self._children.values()],
-            )
-        return self._update(
-            user_id=user_id or self.observation.userId,
-            session_id=session_id or self.observation.sessionId,
-            release=release or self.observation.release,
-            metadata=metadata or self.observation.metadata,
-            success=success if success is not None else self.observation.success,
-            end_time=datetime.datetime.now(datetime.timezone.utc),
-        )
-
     def _update(
         self,
         user_id: Optional[str] = None,
@@ -301,12 +273,10 @@ class TraceContext(ObservationContext):
         self.observation = laminar.update_trace(
             id=self.observation.id,
             user_id=user_id,
-            start_time=self.observation.startTime,
             session_id=session_id,
             release=release,
             metadata=metadata,
             success=success,
-            end_time=end_time,
         )
         return self
 
@@ -320,9 +290,9 @@ def trace(
 
     Args:
         user_id (Optional[str], optional): Custom user_id of your user. Useful for grouping and further analytics. Defaults to None.
-            session_id (Optional[str], optional): Custom session_id for your session. Random UUID is generated on Laminar side, if not specified.
-                                                  Defaults to None.
-            release (Optional[str], optional): _description_. Release of your application. Useful for grouping and further analytics. Defaults to None.
+        session_id (Optional[str], optional): Custom session_id for your session. Random UUID is generated on Laminar side, if not specified.
+                                                Defaults to None.
+        release (Optional[str], optional): _description_. Release of your application. Useful for grouping and further analytics. Defaults to None.
 
     Returns:
         TraceContext: the pointer to the trace context. Use `.span()` to create a new span within this context.
@@ -334,6 +304,5 @@ def trace(
         user_id=user_id,
         session_id=session_id,
         release=release,
-        start_time=datetime.datetime.now(datetime.timezone.utc),
     )
     return TraceContext(trace, None)

lmnr/sdk/providers/fallback.py

@@ -1,3 +1,19 @@
+from ...semantic_conventions.gen_ai_spans import (
+    FINISH_REASONS,
+    FREQUENCY_PENALTY,
+    INPUT_TOKEN_COUNT,
+    MAX_TOKENS,
+    OUTPUT_TOKEN_COUNT,
+    PRESENCE_PENALTY,
+    REQUEST_MODEL,
+    RESPONSE_MODEL,
+    STOP_SEQUENCES,
+    STREAM,
+    TEMPERATURE,
+    TOP_K,
+    TOP_P,
+    TOTAL_TOKEN_COUNT,
+)
 from .base import Provider
 from .utils import parse_or_dump_to_dict
 
@@ -85,11 +101,12 @@ class FallbackProvider(Provider):
                 decisions.append(None)
 
         return {
-            "response_model": obj.get("model"),
-            "input_token_count": obj.get("usage", {}).get("prompt_tokens"),
-            "output_token_count": obj.get("usage", {}).get("completion_tokens"),
-            "total_token_count": obj.get("usage", {}).get("total_tokens"),
-            "decision": self._from_singleton_list(decisions),
+            RESPONSE_MODEL: obj.get("model"),
+            INPUT_TOKEN_COUNT: obj.get("usage", {}).get("prompt_tokens"),
+            OUTPUT_TOKEN_COUNT: obj.get("usage", {}).get("completion_tokens"),
+            TOTAL_TOKEN_COUNT: obj.get("usage", {}).get("total_tokens"),
+            FINISH_REASONS: obj.get("finish_reason"),
+            # "decision": self._from_singleton_list(decisions),
         }
 
     def extract_llm_output(
@@ -107,9 +124,15 @@ class FallbackProvider(Provider):
         self, func_args: list[Any], func_kwargs: dict[str, Any]
     ) -> dict[str, Any]:
         return {
-            "request_model": func_kwargs.get("model"),
-            "temperature": func_kwargs.get("temperature"),
-            "stream": func_kwargs.get("stream", False),
+            REQUEST_MODEL: func_kwargs.get("model"),
+            TEMPERATURE: func_kwargs.get("temperature"),
+            TOP_P: func_kwargs.get("top_p"),
+            TOP_K: func_kwargs.get("top_k"),
+            FREQUENCY_PENALTY: func_kwargs.get("frequency_penalty"),
+            PRESENCE_PENALTY: func_kwargs.get("presence_penalty"),
+            STOP_SEQUENCES: func_kwargs.get("stop"),
+            MAX_TOKENS: func_kwargs.get("max_tokens"),
+            STREAM: func_kwargs.get("stream", False),
         }
 
     def _message_to_key_and_output(

lmnr/sdk/providers/openai.py

@@ -1,4 +1,19 @@
 from .base import Provider
+from ...semantic_conventions.gen_ai_spans import (
+    FINISH_REASONS,
+    FREQUENCY_PENALTY,
+    INPUT_TOKEN_COUNT,
+    MAX_TOKENS,
+    OUTPUT_TOKEN_COUNT,
+    PRESENCE_PENALTY,
+    REQUEST_MODEL,
+    RESPONSE_MODEL,
+    STOP_SEQUENCES,
+    STREAM,
+    TEMPERATURE,
+    TOP_P,
+    TOTAL_TOKEN_COUNT,
+)
 from .utils import parse_or_dump_to_dict
 
 from collections import defaultdict
@@ -92,12 +107,12 @@ class OpenAI(Provider):
                 decisions.append(None)
 
         return {
-            "response_model": obj.get("model"),
-            "input_token_count": obj.get("usage", {}).get("prompt_tokens"),
-            "output_token_count": obj.get("usage", {}).get("completion_tokens"),
-            "total_token_count": obj.get("usage", {}).get("total_tokens"),
-            "finish_reason": obj.get("finish_reason"),
-            "decision": self._from_singleton_list(decisions),
+            RESPONSE_MODEL: obj.get("model"),
+            INPUT_TOKEN_COUNT: obj.get("usage", {}).get("prompt_tokens"),
+            OUTPUT_TOKEN_COUNT: obj.get("usage", {}).get("completion_tokens"),
+            TOTAL_TOKEN_COUNT: obj.get("usage", {}).get("total_tokens"),
+            FINISH_REASONS: obj.get("finish_reason"),
+            # "decision": self._from_singleton_list(decisions),
         }
 
     def extract_llm_output(
@@ -115,10 +130,14 @@ class OpenAI(Provider):
         self, func_args: list[Any], func_kwargs: dict[str, Any]
     ) -> dict[str, Any]:
         return {
-            "request_model": func_kwargs.get("model"),
-            "temperature": func_kwargs.get("temperature"),
-            "top_p": func_kwargs.get("top_p"),
-            "stream": func_kwargs.get("stream", False),
+            REQUEST_MODEL: func_kwargs.get("model"),
+            TEMPERATURE: func_kwargs.get("temperature"),
+            TOP_P: func_kwargs.get("top_p"),
+            FREQUENCY_PENALTY: func_kwargs.get("frequency_penalty"),
+            PRESENCE_PENALTY: func_kwargs.get("presence_penalty"),
+            STOP_SEQUENCES: func_kwargs.get("stop"),
+            MAX_TOKENS: func_kwargs.get("max_tokens"),
+            STREAM: func_kwargs.get("stream", False),
         }
 
     def _message_to_key_and_output(

lmnr/sdk/tracing_types.py

@@ -10,6 +10,7 @@ from .utils import to_dict
 class EvaluateEvent(pydantic.BaseModel):
     name: str
     data: str
+    timestamp: Optional[datetime.datetime] = None
 
 
 class Span(pydantic.BaseModel):
@@ -62,6 +63,7 @@ class Span(pydantic.BaseModel):
     def update(
         self,
         end_time: Optional[datetime.datetime],
+        input: Optional[Any] = None,
         output: Optional[Any] = None,
         metadata: Optional[dict[str, Any]] = None,
         attributes: Optional[dict[str, Any]] = None,
@@ -69,6 +71,7 @@ class Span(pydantic.BaseModel):
         override: bool = False,
     ):
         self.endTime = end_time or datetime.datetime.now(datetime.timezone.utc)
+        self.input = input
         self.output = output
         new_metadata = (
             metadata if override else {**(self.metadata or {}), **(metadata or {})}
@@ -111,8 +114,6 @@ class Trace(pydantic.BaseModel):
     id: uuid.UUID
     version: str = CURRENT_TRACING_VERSION
     success: bool = True
-    startTime: Optional[datetime.datetime] = None
-    endTime: Optional[datetime.datetime] = None
     userId: Optional[str] = None  # provided by user or null
     sessionId: Optional[str] = None  # provided by user or uuid()
     release: Optional[str] = None
@@ -121,8 +122,6 @@ class Trace(pydantic.BaseModel):
     def __init__(
         self,
         success: bool = True,
-        start_time: Optional[datetime.datetime] = None,
-        end_time: Optional[datetime.datetime] = None,
         id: Optional[uuid.UUID] = None,
         user_id: Optional[str] = None,
         session_id: Optional[str] = None,
@@ -132,9 +131,7 @@ class Trace(pydantic.BaseModel):
         id_ = id or uuid.uuid4()
         super().__init__(
             id=id_,
-            startTime=start_time,
             success=success,
-            endTime=end_time,
             userId=user_id,
             sessionId=session_id,
             release=release,

lmnr/semantic_conventions/gen_ai_spans.py

@@ -0,0 +1,48 @@
+# source: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md
+# last updated: 2024-08-26
+
+REQUEST_MODEL: str = "gen_ai.request.model"
+RESPONSE_MODEL: str = "gen_ai.response.model"
+PROVIDER: str = "gen_ai.system"
+INPUT_TOKEN_COUNT: str = "gen_ai.usage.input_tokens"
+OUTPUT_TOKEN_COUNT: str = "gen_ai.usage.output_tokens"
+TOTAL_TOKEN_COUNT: str = "gen_ai.usage.total_tokens"  # custom, not in the spec
+# https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/semcov/__init__.py
+COST: str = "gen_ai.usage.cost"
+
+OPERATION: str = "gen_ai.operation.name"
+
+FREQUENCY_PENALTY: str = "gen_ai.request.frequency_penalty"
+TEMPERATURE: str = "gen_ai.request.temperature"
+MAX_TOKENS: str = "gen_ai.request.max_tokens"
+PRESENCE_PENALTY: str = "gen_ai.request.presence_penalty"
+STOP_SEQUENCES: str = "gen_ai.request.stop_sequences"
+TEMPERATURE: str = "gen_ai.request.temperature"
+TOP_P: str = "gen_ai.request.top_p"
+TOP_K: str = "gen_ai.request.top_k"
+
+# https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/semcov/__init__.py
+STREAM: str = "gen_ai.request.is_stream"
+
+FINISH_REASONS = "gen_ai.response.finish_reasons"
+
+__all__ = [
+    "REQUEST_MODEL",
+    "RESPONSE_MODEL",
+    "PROVIDER",
+    "INPUT_TOKEN_COUNT",
+    "OUTPUT_TOKEN_COUNT",
+    "TOTAL_TOKEN_COUNT",
+    "COST",
+    "OPERATION",
+    "FREQUENCY_PENALTY",
+    "TEMPERATURE",
+    "MAX_TOKENS",
+    "PRESENCE_PENALTY",
+    "STOP_SEQUENCES",
+    "TEMPERATURE",
+    "TOP_P",
+    "TOP_K",
+    "STREAM",
+    "FINISH_REASONS",
+]

{lmnr-0.3.0b1.dist-info → lmnr-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lmnr
-Version: 0.3.0b1
+Version: 0.3.2
 Summary: Python SDK for Laminar AI
 License: Apache-2.0
 Author: lmnr.ai
@@ -12,7 +12,6 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: backoff (>=2.2.1,<3.0.0)
-Requires-Dist: black (>=24.4.2,<25.0.0)
 Requires-Dist: openai (>=1.41.1,<2.0.0)
 Requires-Dist: pydantic (>=2.7.4,<3.0.0)
 Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
@@ -31,6 +30,32 @@ source .myenv/bin/activate  # or use your favorite env management tool
 pip install lmnr
 ```
 
+Create .env file at the root and add `LMNR_PROJECT_API_KEY` value to it.
+
+Read more [here](https://docs.lmnr.ai/api-reference/introduction#authentication) on how to get `LMNR_PROJECT_API_KEY`.
+
+## Sending events
+
+You can send events in two ways:
+- `.event(name, value)` – for a pre-defined event with one of possible values.
+- `.evaluate_event(name, data)` – for an event that our agent checks for and assigns a value from possible values.
+
+There are 3 types of events:
+- SCORE - this is an integer score where you specify inclusive minimum and maximum.
+- CLASS - this is a classifier with one of the possible values.
+- TAG - this event has no value and can be assigned to a span.
+
+Important notes:
+- If event name does not match anything pre-defined in the UI, the event won't be saved.
+- If event value (when sent with `.event()`) is not in the domain, the event won't be saved.
+
+## Instrumentation
+
+We provide two ways to instrument your python code:
+- With `@observe()` decorators and `wrap_llm_call` helpers
+- Manually
+
+It is important to not mix the two styles of instrumentation, this can lead to unpredictable results.
 
 ## Decorator instrumentation example
 
@@ -65,10 +90,11 @@ def poem_writer(topic="turbulence"):
     poem = response.choices[0].message.content
 
     if topic in poem:
-        lmnr_context.event("topic_alignment")  # send an event with a pre-defined name
+        # send an event with a pre-defined name
+        lmnr_context.event("topic_alignment", "good")
     
     # to trigger an automatic check for a possible event do:
-    lmnr_context.check_span_event("excessive_wordiness")
+    lmnr_context.evaluate_event("excessive_wordiness", poem)
 
     return poem
 
@@ -91,11 +117,11 @@ For manual instrumetation you will need to import the following:
 Both `TraceContext` and `SpanContext` expose the following interfaces:
 - `span(name: str, **kwargs)` - create a child span within the current context. Returns `SpanContext`
 - `update(**kwargs)` - update the current trace or span and return it. Returns `TraceContext` or `SpanContext`. Useful when some metadata becomes known later during the program execution
-- `end(**kwargs)` – update the current span, and terminate it
 
 In addition, `SpanContext` allows you to:
-- `event(name: str, value: str | int = None)` - emit a custom event at any point
+- `event(name: str, value: str | int)` - emit a custom event at any point
 - `evaluate_event(name: str, data: str)` - register a possible event for automatic checking by Laminar.
+- `end(**kwargs)` – update the current span, and terminate it
 
 Example:
 
@@ -103,11 +129,12 @@ Example:
 import os
 from openai import OpenAI
 
-from lmnr import trace, TraceContext, SpanContext
+from lmnr import trace, TraceContext, SpanContext, EvaluateEvent
+from lmnr.semantic_conventions.gen_ai_spans import INPUT_TOKEN_COUNT, OUTPUT_TOKEN_COUNT, RESPONSE_MODEL, PROVIDER, STREAM
 client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
 def poem_writer(t: TraceContext, topic = "turbulence"):
-    span: SpanContext = t.span(name="poem_writer", input=None)
+    span: SpanContext = t.span(name="poem_writer", input=topic)
 
     prompt = f"write a poem about {topic}"
     messages = [
@@ -126,24 +153,73 @@ def poem_writer(t: TraceContext, topic = "turbulence"):
     )
     poem = response.choices[0].message.content
     if topic in poem:
-        llm_span.event("topic_alignment")  # send an event with a pre-defined name
-
-    # note that you can register possible events here as well, not only `llm_span.check_span_event()`
-    llm_span.end(output=poem, check_event_names=["excessive_wordiness"])
+        llm_span.event("topic_alignment", "good")  # send an event with a pre-defined name
+
+    # note that you can register possible events here as well,
+    # not only `llm_span.evaluate_event()`
+    llm_span.end(
+        output=poem,
+        evaluate_events=[EvaluateEvent(name="excessive_wordines", data=poem)],
+        attributes={
+            INPUT_TOKEN_COUNT: response.usage.prompt_tokens,
+            OUTPUT_TOKEN_COUNT: response.usage.completion_tokens,
+            RESPONSE_MODEL: response.model,
+            PROVIDER: 'openai',
+            STREAM: False
+        }
+    )
     span.end(output=poem)
     return poem
 
 
-t: TraceContext = trace(user_id="user", session_id="session", release="release")
+t: TraceContext = trace(user_id="user123", session_id="session123", release="release")
 main(t, topic="laminar flow")
-t.end(success=True)
 ```
 
-## Features
+## Manual attributes
+
+You can specify span attributes when creating/updating/ending spans.
+
+If you use [decorator instrumentation](#decorator-instrumentation-example), `wrap_llm_call` handles all of this for you.
+
+Example usage:
+
+```python
+from lmnr.semantic_conventions.gen_ai_spans import REQUEST_MODEL
+
+# span_type = LLM is important for correct attribute semantics
+llm_span = span.span(name="OpenAI completion", input=messages, span_type="LLM")
+llm_span.update(
+    attributes={REQUEST_MODEL: "gpt-4o-mini"}
+)
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hello. What is the capital of France?"},
+    ],
+)
+```
+
+Semantics:
+
+Check for available semantic conventions in `lmnr.semantic_conventions.gen_ai_spans`.
+
+You can specify the cost with `COST`. Otherwise, the cost will be calculated 
+on the Laminar servers, given the following are specified:
 
-- Make Laminar endpoint calls from your Python code
-- Make Laminar endpoint calls that can run your own functions as tools
-- CLI to generate code from pipelines you build on Laminar or execute your own functions while you test your flows in workshop
+- span_type is `"LLM"`
+- Model provider: `PROVIDER`, e.g. 'openai', 'anthropic'
+- Output tokens: `OUTPUT_TOKEN_COUNT`
+- Input tokens: `INPUT_TOKEN_COUNT`*
+- Model. We look at `RESPONSE_MODEL` first, and then, if it is not present, we take the value of `REQUEST_MODEL`
+
+\* Also, for the case when `PROVIDER` is `"openai"`, the `STREAM` is set to `True`, and `INPUT_TOKEN_COUNT` is not set, we will calculate
+the number of input tokens, and the cost on the server using [tiktoken](https://github.com/zurawiki/tiktoken-rs) and 
+use it in cost calculation.
+This is done because OpenAI does not stream the usage back
+when streaming is enabled. Output token count is (approximately) equal to the number of streaming
+events sent by OpenAI, but there is no way to calculate the input token count, other than re-tokenizing.
 
 ## Making Laminar pipeline calls
 
@@ -180,7 +256,3 @@ PipelineRunResponse(
 )
 ```
 
-## PROJECT_API_KEY
-
-Read more [here](https://docs.lmnr.ai/api-reference/introduction#authentication) on how to get `PROJECT_API_KEY`.
-

lmnr-0.3.2.dist-info/RECORD

@@ -0,0 +1,23 @@
+lmnr/__init__.py,sha256=vUiBEqNVi-dWlFKqnyxt0387t1kzVXrwFp7ShhDJyXY,324
+lmnr/sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lmnr/sdk/client.py,sha256=e6cIvJq38a6XAU8FGWYtNXVAPlEoZEyKS7hC3M_6EkU,5749
+lmnr/sdk/collector.py,sha256=6LRmPhOcmGplUDWm_sJh0dVrLTHknd_kmq7POGuAvoQ,5338
+lmnr/sdk/constants.py,sha256=USCfwuUqRx6_0xC8WUxqGj766dInqQkWJcf8U5vPK7s,34
+lmnr/sdk/context.py,sha256=0fLckE56hQxBrPWCsqVCwpTlj6V1nfYJFiiI3FChG_c,15356
+lmnr/sdk/decorators.py,sha256=njl1w76SuKJBpCMD-g_LGLSuDCrRS8WCQ4FIgrelhmY,12011
+lmnr/sdk/interface.py,sha256=ShVtyH2HpKDJU0FLMB-87Zd9tPH0kCP5meKtfz8a3X4,12229
+lmnr/sdk/providers/__init__.py,sha256=wNCgQnt9-bnTNXLQWdPgyKhqA1ajiaEd1Rr2KPOpazM,54
+lmnr/sdk/providers/base.py,sha256=xc6iA8yY_VK6tbzswt-3naZ53aAXtOLur9j8eimC_ZA,1054
+lmnr/sdk/providers/fallback.py,sha256=9-srLJgDK5CWD8DIdnxo6jbSsnwDvdHC-vA06BfEkqQ,5431
+lmnr/sdk/providers/openai.py,sha256=9X2VWz4_EqQBEA1UEww2EKdqods6IzOEmaO6dnhY-Lw,5725
+lmnr/sdk/providers/utils.py,sha256=ROt82VrvezExYOxionAynD3dp6oX5JoPW6F1ayTm7q8,946
+lmnr/sdk/tracing_types.py,sha256=N2aA0gtfayawmiLaotEs_8k5sYIN7uvi9oka54ubHGc,6241
+lmnr/sdk/types.py,sha256=hVxOsa3oCQQ-8aS_WkOtErg4nHJRkBVySfYlTgDlDyk,2084
+lmnr/sdk/utils.py,sha256=1yhXtdGmVXfnc8SOQiTH_zAZGbZrzO8oaFd7q5nE7eY,3349
+lmnr/semantic_conventions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lmnr/semantic_conventions/gen_ai_spans.py,sha256=3s-2J5v3t5LcMKwK2DefPn56XpxN5oMEYtb9Mf9D_gA,1541
+lmnr-0.3.2.dist-info/LICENSE,sha256=67b_wJHVV1CBaWkrKFWU1wyqTPSdzH77Ls-59631COg,10411
+lmnr-0.3.2.dist-info/METADATA,sha256=3NxSt1RIDS1Y06y5uPJauKB7Zlrz8KpgigRs33_ip4o,9663
+lmnr-0.3.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+lmnr-0.3.2.dist-info/entry_points.txt,sha256=Qg7ZRax4k-rcQsZ26XRYQ8YFSBiyY2PNxYfq4a6PYXI,41
+lmnr-0.3.2.dist-info/RECORD,,

lmnr-0.3.0b1.dist-info/RECORD

@@ -1,21 +0,0 @@
-lmnr/__init__.py,sha256=U3sQyxCHM9ojzfo05XYxM0T_Bh1StZFSp5K82NjATxc,242
-lmnr/sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lmnr/sdk/client.py,sha256=6mp4sQF1IEESPYe6ABFgchMBQBKr2AT7eqP-mIC5cEA,5482
-lmnr/sdk/collector.py,sha256=6LRmPhOcmGplUDWm_sJh0dVrLTHknd_kmq7POGuAvoQ,5338
-lmnr/sdk/constants.py,sha256=USCfwuUqRx6_0xC8WUxqGj766dInqQkWJcf8U5vPK7s,34
-lmnr/sdk/context.py,sha256=jfu2HGyZEJYSDf-LQAmmK8MKFnNhYfR66k_baQWx99s,15271
-lmnr/sdk/decorators.py,sha256=B2wdhs45-ZM0niotZBOx5FSSCu_vGQ32pntG9o3fKKU,11860
-lmnr/sdk/interface.py,sha256=BucPNopp_Xvb1Tvn6We4ETvqqQiWtwjbCksAtt4qmvU,13717
-lmnr/sdk/providers/__init__.py,sha256=wNCgQnt9-bnTNXLQWdPgyKhqA1ajiaEd1Rr2KPOpazM,54
-lmnr/sdk/providers/base.py,sha256=xc6iA8yY_VK6tbzswt-3naZ53aAXtOLur9j8eimC_ZA,1054
-lmnr/sdk/providers/fallback.py,sha256=DXnxBX1vxusGSUC76d0AjouR4NSoajQMdMeG37TRf4k,4741
-lmnr/sdk/providers/openai.py,sha256=EygnBniKlcic6eIOfS5zORpytLqUYZxnDRB5Z4MnXZY,5193
-lmnr/sdk/providers/utils.py,sha256=ROt82VrvezExYOxionAynD3dp6oX5JoPW6F1ayTm7q8,946
-lmnr/sdk/tracing_types.py,sha256=RvVb8yCLjCu9DT59OX_tvUxaOTCtE6fcsDH4nMddzHA,6399
-lmnr/sdk/types.py,sha256=hVxOsa3oCQQ-8aS_WkOtErg4nHJRkBVySfYlTgDlDyk,2084
-lmnr/sdk/utils.py,sha256=1yhXtdGmVXfnc8SOQiTH_zAZGbZrzO8oaFd7q5nE7eY,3349
-lmnr-0.3.0b1.dist-info/LICENSE,sha256=67b_wJHVV1CBaWkrKFWU1wyqTPSdzH77Ls-59631COg,10411
-lmnr-0.3.0b1.dist-info/METADATA,sha256=U5UBpCkOSbDzsoQw4b4GkJxGKgMlxv8qoVRLzAVupiw,6700
-lmnr-0.3.0b1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-lmnr-0.3.0b1.dist-info/entry_points.txt,sha256=Qg7ZRax4k-rcQsZ26XRYQ8YFSBiyY2PNxYfq4a6PYXI,41
-lmnr-0.3.0b1.dist-info/RECORD,,