lmnr 0.4.9__tar.gz → 0.4.11__tar.gz

{lmnr-0.4.9 → lmnr-0.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lmnr
-Version: 0.4.9
+Version: 0.4.11
 Summary: Python SDK for Laminar AI
 License: Apache-2.0
 Author: lmnr.ai
@@ -67,6 +67,9 @@ OpenTelemetry log sender for [Laminar](https://github.com/lmnr-ai/lmnr) for Pyth
 
 
 ## Quickstart
+
+First, install the package:
+
 ```sh
 python3 -m venv .myenv
 source .myenv/bin/activate  # or use your favorite env management tool
@@ -74,21 +77,39 @@ source .myenv/bin/activate  # or use your favorite env management tool
 pip install lmnr
 ```
 
-And the in your main Python file
+Then, you can initialize Laminar in your main file and instrument your code.
 
 ```python
+import os
+from openai import OpenAI
 from lmnr import Laminar as L
 
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
-```
+L.initialize(
+    project_api_key=os.environ["LMNR_PROJECT_API_KEY"],
+)
 
-If you want to automatically instrument particular LLM, Vector DB, and related
-calls with OpenTelemetry-compatible instrumentation, then pass the appropriate instruments to `.initialize()`.
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
-Also if you want to automatically instrument all supported libraries, then pass `instruments=None` or don't pass `instruments` at all.
+def poem_writer(topic: str):
+    prompt = f"write a poem about {topic}"
 
-We rely on the amazing [OpenLLMetry](https://github.com/traceloop/openllmetry), open-source package
-by TraceLoop, to achieve that.
+    # OpenAI calls are automatically instrumented
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "system", "content": "You are a helpful assistant."},
+            {"role": "user", "content": prompt},
+        ],
+    )
+    poem = response.choices[0].message.content
+    return poem
+
+if __name__ == "__main__":
+    print(poem_writer("laminar flow"))
+
+```
+
+Note that you need to only initialize Laminar once in your application.
 
 ### Project API key
 
@@ -97,75 +118,84 @@ You can either pass it to `.initialize()` or set it to `.env` at the root of you
 
 ## Instrumentation
 
-In addition to automatic instrumentation, we provide a simple `@observe()` decorator, if you want more fine-grained tracing
-or to trace other functions.
+### Manual instrumentation
 
-### Example
+To instrument any function in your code, we provide a simple `@observe()` decorator.
+This can be useful if you want to trace a request handler or a function which combines multiple LLM calls.
 
 ```python
 import os
 from openai import OpenAI
+from lmnr import Laminar as L, Instruments
 
-
-from lmnr import observe, Laminar as L
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
+L.initialize(project_api_key=os.environ["LMNR_PROJECT_API_KEY"])
 
 client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
-@observe()  # annotate all functions you want to trace
-def poem_writer(topic="turbulence"):
+def poem_writer(topic: str):
     prompt = f"write a poem about {topic}"
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": prompt},
+    ]
+
+    # OpenAI calls are still automatically instrumented
     response = client.chat.completions.create(
         model="gpt-4o",
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": prompt},
-        ],
+        messages=messages,
     )
     poem = response.choices[0].message.content
+
     return poem
 
-print(poem_writer(topic="laminar flow"))
+@observe()
+def generate_poems():
+    poem1 = poem_writer(topic="laminar flow")
+    L.event("is_poem_generated", True)
+    poem2 = poem_writer(topic="turbulence")
+    L.event("is_poem_generated", True)
+    poems = f"{poem1}\n\n---\n\n{poem2}"
+    return poems
 ```
 
-### Manual instrumentation
-
-Our manual instrumentation is a very thin wrapper around OpenTelemetry's
-`trace.start_span`. Our wrapper sets the span into the active context.
-You don't have to explicitly pass the spans around, it is enough to
-just call `L.start_span`, and OpenTelemetry will handle the context management
+Also, you can use `Laminar.start_as_current_span` if you want to record a chunk of your code using `with` statement.
 
 ```python
-from lmnr import observe, Laminar as L
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
+def handle_user_request(topic: str):
+    with L.start_as_current_span(name="poem_writer", input=topic):
+        ...
+
+        poem = poem_writer(topic=topic)
+        
+        ...
+        
+        # while within the span, you can attach laminar events to it
+        L.event("is_poem_generated", True)
+
+        # Use set_span_output to record the output of the span
+        L.set_span_output(poem)
+```
 
-def poem_writer(topic="turbulence"):
-    
-    span = L.start_span("poem_writer", topic) # start a span
+### Automatic instrumentation
 
-    prompt = f"write a poem about {topic}"
+Laminar allows you to automatically instrument majority of the most popular LLM, Vector DB, database, requests, and other libraries.
 
-    # OpenAI calls are still automatically instrumented with OpenLLMetry
-    response = client.chat.completions.create(
-        model="gpt-4o",
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": prompt},
-        ],
-    )
-    poem = response.choices[0].message.content
-    # while within the span, you can attach laminar events to it
-    L.event("event_name", "event_value")
+If you want to automatically instrument a default set of libraries, then simply do NOT pass `instruments` argument to `.initialize()`.
+See the full list of available instrumentations in the [enum](/src/lmnr/traceloop_sdk/instruments.py).
 
-    L.set_span_output(poem) # set an output
-    
-    # IMPORTANT: don't forget to end all the spans (usually in `finally` blocks)
-    # Otherwise, the trace may not be sent/displayed correctly
-    span.end()
+If you want to automatically instrument only specific LLM, Vector DB, or other
+calls with OpenTelemetry-compatible instrumentation, then pass the appropriate instruments to `.initialize()`.
+For example, if you want to only instrument OpenAI and Anthropic, then do the following:
 
-    return poem
+```python
+from lmnr import Laminar as L, Instruments
+
+L.initialize(project_api_key=os.environ["LMNR_PROJECT_API_KEY"], instruments={Instruments.OPENAI, Instruments.ANTHROPIC})
 ```
 
+If you want to fully disable any kind of autoinstrumentation, pass an empty set as `instruments=set()` to `.initialize()`. 
+
+Majority of the autoinstrumentations are provided by Traceloop's [OpenLLMetry](https://github.com/traceloop/openllmetry).
 
 ## Sending events
 

{lmnr-0.4.9 → lmnr-0.4.11}/README.md

@@ -9,6 +9,9 @@ OpenTelemetry log sender for [Laminar](https://github.com/lmnr-ai/lmnr) for Pyth
 
 
 ## Quickstart
+
+First, install the package:
+
 ```sh
 python3 -m venv .myenv
 source .myenv/bin/activate  # or use your favorite env management tool
@@ -16,21 +19,39 @@ source .myenv/bin/activate  # or use your favorite env management tool
 pip install lmnr
 ```
 
-And the in your main Python file
+Then, you can initialize Laminar in your main file and instrument your code.
 
 ```python
+import os
+from openai import OpenAI
 from lmnr import Laminar as L
 
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
-```
+L.initialize(
+    project_api_key=os.environ["LMNR_PROJECT_API_KEY"],
+)
 
-If you want to automatically instrument particular LLM, Vector DB, and related
-calls with OpenTelemetry-compatible instrumentation, then pass the appropriate instruments to `.initialize()`.
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
-Also if you want to automatically instrument all supported libraries, then pass `instruments=None` or don't pass `instruments` at all.
+def poem_writer(topic: str):
+    prompt = f"write a poem about {topic}"
 
-We rely on the amazing [OpenLLMetry](https://github.com/traceloop/openllmetry), open-source package
-by TraceLoop, to achieve that.
+    # OpenAI calls are automatically instrumented
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "system", "content": "You are a helpful assistant."},
+            {"role": "user", "content": prompt},
+        ],
+    )
+    poem = response.choices[0].message.content
+    return poem
+
+if __name__ == "__main__":
+    print(poem_writer("laminar flow"))
+
+```
+
+Note that you need to only initialize Laminar once in your application.
 
 ### Project API key
 
@@ -39,75 +60,84 @@ You can either pass it to `.initialize()` or set it to `.env` at the root of you
 
 ## Instrumentation
 
-In addition to automatic instrumentation, we provide a simple `@observe()` decorator, if you want more fine-grained tracing
-or to trace other functions.
+### Manual instrumentation
 
-### Example
+To instrument any function in your code, we provide a simple `@observe()` decorator.
+This can be useful if you want to trace a request handler or a function which combines multiple LLM calls.
 
 ```python
 import os
 from openai import OpenAI
+from lmnr import Laminar as L, Instruments
 
-
-from lmnr import observe, Laminar as L
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
+L.initialize(project_api_key=os.environ["LMNR_PROJECT_API_KEY"])
 
 client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
-@observe()  # annotate all functions you want to trace
-def poem_writer(topic="turbulence"):
+def poem_writer(topic: str):
     prompt = f"write a poem about {topic}"
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": prompt},
+    ]
+
+    # OpenAI calls are still automatically instrumented
     response = client.chat.completions.create(
         model="gpt-4o",
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": prompt},
-        ],
+        messages=messages,
     )
     poem = response.choices[0].message.content
+
     return poem
 
-print(poem_writer(topic="laminar flow"))
+@observe()
+def generate_poems():
+    poem1 = poem_writer(topic="laminar flow")
+    L.event("is_poem_generated", True)
+    poem2 = poem_writer(topic="turbulence")
+    L.event("is_poem_generated", True)
+    poems = f"{poem1}\n\n---\n\n{poem2}"
+    return poems
 ```
 
-### Manual instrumentation
-
-Our manual instrumentation is a very thin wrapper around OpenTelemetry's
-`trace.start_span`. Our wrapper sets the span into the active context.
-You don't have to explicitly pass the spans around, it is enough to
-just call `L.start_span`, and OpenTelemetry will handle the context management
+Also, you can use `Laminar.start_as_current_span` if you want to record a chunk of your code using `with` statement.
 
 ```python
-from lmnr import observe, Laminar as L
-L.initialize(project_api_key="<LMNR_PROJECT_API_KEY>", instruments=set())
+def handle_user_request(topic: str):
+    with L.start_as_current_span(name="poem_writer", input=topic):
+        ...
+
+        poem = poem_writer(topic=topic)
+        
+        ...
+        
+        # while within the span, you can attach laminar events to it
+        L.event("is_poem_generated", True)
+
+        # Use set_span_output to record the output of the span
+        L.set_span_output(poem)
+```
 
-def poem_writer(topic="turbulence"):
-    
-    span = L.start_span("poem_writer", topic) # start a span
+### Automatic instrumentation
 
-    prompt = f"write a poem about {topic}"
+Laminar allows you to automatically instrument majority of the most popular LLM, Vector DB, database, requests, and other libraries.
 
-    # OpenAI calls are still automatically instrumented with OpenLLMetry
-    response = client.chat.completions.create(
-        model="gpt-4o",
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": prompt},
-        ],
-    )
-    poem = response.choices[0].message.content
-    # while within the span, you can attach laminar events to it
-    L.event("event_name", "event_value")
+If you want to automatically instrument a default set of libraries, then simply do NOT pass `instruments` argument to `.initialize()`.
+See the full list of available instrumentations in the [enum](/src/lmnr/traceloop_sdk/instruments.py).
 
-    L.set_span_output(poem) # set an output
-    
-    # IMPORTANT: don't forget to end all the spans (usually in `finally` blocks)
-    # Otherwise, the trace may not be sent/displayed correctly
-    span.end()
+If you want to automatically instrument only specific LLM, Vector DB, or other
+calls with OpenTelemetry-compatible instrumentation, then pass the appropriate instruments to `.initialize()`.
+For example, if you want to only instrument OpenAI and Anthropic, then do the following:
 
-    return poem
+```python
+from lmnr import Laminar as L, Instruments
+
+L.initialize(project_api_key=os.environ["LMNR_PROJECT_API_KEY"], instruments={Instruments.OPENAI, Instruments.ANTHROPIC})
 ```
 
+If you want to fully disable any kind of autoinstrumentation, pass an empty set as `instruments=set()` to `.initialize()`. 
+
+Majority of the autoinstrumentations are provided by Traceloop's [OpenLLMetry](https://github.com/traceloop/openllmetry).
 
 ## Sending events
 

{lmnr-0.4.9 → lmnr-0.4.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lmnr"
-version = "0.4.9"
+version = "0.4.11"
 description = "Python SDK for Laminar AI"
 authors = [
   { name = "lmnr.ai", email = "founders@lmnr.ai" }
@@ -11,7 +11,7 @@ license = "Apache-2.0"
 
 [tool.poetry]
 name = "lmnr"
-version = "0.4.9"
+version = "0.4.11"
 description = "Python SDK for Laminar AI"
 authors = ["lmnr.ai"]
 readme = "README.md"

{lmnr-0.4.9 → lmnr-0.4.11}/src/lmnr/__init__.py

@@ -2,3 +2,4 @@ from .sdk.evaluations import Evaluation
 from .sdk.laminar import Laminar
 from .sdk.types import ChatMessage, PipelineRunError, PipelineRunResponse, NodeInput
 from .sdk.decorators import observe
+from .traceloop_sdk import Instruments

{lmnr-0.4.9 → lmnr-0.4.11}/src/lmnr/sdk/decorators.py

@@ -4,22 +4,19 @@ from lmnr.traceloop_sdk.decorators.base import (
 )
 from opentelemetry.trace import INVALID_SPAN, get_current_span
 
-from typing import Callable, Optional, ParamSpec, TypeVar, cast
+from typing import Callable, Optional, cast
 
 from lmnr.traceloop_sdk.tracing.tracing import update_association_properties
 
 from .utils import is_async
 
-P = ParamSpec("P")
-R = TypeVar("R")
-
 
 def observe(
     *,
     name: Optional[str] = None,
     user_id: Optional[str] = None,
     session_id: Optional[str] = None,
-) -> Callable[[Callable[P, R]], Callable[P, R]]:
+) -> Callable[[Callable], Callable]:
     """The main decorator entrypoint for Laminar. This is used to wrap
     functions and methods to create spans.
 
@@ -41,7 +38,7 @@ def observe(
         R: Returns the result of the wrapped function
     """
 
-    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+    def decorator(func: Callable) -> Callable:
         current_span = get_current_span()
         if current_span != INVALID_SPAN:
             if session_id is not None:
@@ -64,4 +61,4 @@ def observe(
             else entity_method(name=name)(func)
         )
 
-    return cast(Callable[P, R], decorator)
+    return cast(Callable, decorator)

{lmnr-0.4.9 → lmnr-0.4.11}/src/lmnr/sdk/types.py

@@ -2,7 +2,7 @@ import datetime
 import requests
 import pydantic
 import uuid
-from typing import Any, Literal, Optional, TypeAlias, Union
+from typing import Any, Awaitable, Callable, Literal, Optional, Union
 
 from .utils import to_dict
 
@@ -17,9 +17,9 @@ class ConditionedValue(pydantic.BaseModel):
     value: "NodeInput"
 
 
-Numeric: TypeAlias = Union[int, float]
-NodeInput: TypeAlias = Union[str, list[ChatMessage], ConditionedValue, Numeric, bool]
-PipelineOutput: TypeAlias = Union[NodeInput]
+Numeric = Union[int, float]
+NodeInput = Union[str, list[ChatMessage], ConditionedValue, Numeric, bool]
+PipelineOutput = Union[NodeInput]
 
 
 class PipelineRunRequest(pydantic.BaseModel):
@@ -74,8 +74,8 @@ class PipelineRunError(Exception):
             return super().__str__()
 
 
-EvaluationDatapointData: TypeAlias = dict[str, Any]
-EvaluationDatapointTarget: TypeAlias = dict[str, Any]
+EvaluationDatapointData = dict[str, Any]
+EvaluationDatapointTarget = dict[str, Any]
 
 
 # EvaluationDatapoint is a single data point in the evaluation
@@ -87,24 +87,24 @@ class EvaluationDatapoint(pydantic.BaseModel):
     target: EvaluationDatapointTarget
 
 
-ExecutorFunctionReturnType: TypeAlias = Any
-EvaluatorFunctionReturnType: TypeAlias = Union[Numeric, dict[str, Numeric]]
+ExecutorFunctionReturnType = Any
+EvaluatorFunctionReturnType = Union[Numeric, dict[str, Numeric]]
 
-# ExecutorFunction: TypeAlias = Callable[
-#     [EvaluationDatapointData, *tuple[Any, ...], dict[str, Any]],
-#     Union[ExecutorFunctionReturnType, Awaitable[ExecutorFunctionReturnType]],
-# ]
+ExecutorFunction = Callable[
+    [EvaluationDatapointData, Any, dict[str, Any]],
+    Union[ExecutorFunctionReturnType, Awaitable[ExecutorFunctionReturnType]],
+]
 
 # EvaluatorFunction is a function that takes the output of the executor and the
 # target data, and returns a score. The score can be a single number or a
 # record of string keys and number values. The latter is useful for evaluating
 # multiple criteria in one go instead of running multiple evaluators.
-# EvaluatorFunction: TypeAlias = Callable[
-#     [ExecutorFunctionReturnType, *tuple[Any, ...], dict[str, Any]],
-#     Union[EvaluatorFunctionReturnType, Awaitable[EvaluatorFunctionReturnType]],
-# ]
+EvaluatorFunction = Callable[
+    [ExecutorFunctionReturnType, Any, dict[str, Any]],
+    Union[EvaluatorFunctionReturnType, Awaitable[EvaluatorFunctionReturnType]],
+]
 
-EvaluationStatus: TypeAlias = Literal["Started", "Finished", "Error"]
+EvaluationStatus = Literal["Started", "Finished", "Error"]
 
 
 class CreateEvaluationResponse(pydantic.BaseModel):

{lmnr-0.4.9 → lmnr-0.4.11}/src/lmnr/traceloop_sdk/instruments.py

@@ -2,6 +2,8 @@ from enum import Enum
 
 
 class Instruments(Enum):
+    # The list of libraries which will be autoinstrumented
+    # if no specific instruments are provided to initialize()
     OPENAI = "openai"
     ANTHROPIC = "anthropic"
     COHERE = "cohere"
@@ -15,10 +17,6 @@ class Instruments(Enum):
     MILVUS = "milvus"
     TRANSFORMERS = "transformers"
     TOGETHER = "together"
-    REDIS = "redis"
-    REQUESTS = "requests"
-    URLLIB3 = "urllib3"
-    PYMYSQL = "pymysql"
     BEDROCK = "bedrock"
     REPLICATE = "replicate"
     VERTEXAI = "vertexai"
@@ -27,3 +25,10 @@ class Instruments(Enum):
     ALEPHALPHA = "alephalpha"
     MARQO = "marqo"
     LANCEDB = "lancedb"
+
+    # The following libraries will not be autoinstrumented unless
+    # specified explicitly in the initialize() call.
+    REDIS = "redis"
+    REQUESTS = "requests"
+    URLLIB3 = "urllib3"
+    PYMYSQL = "pymysql"

{lmnr-0.4.9 → lmnr-0.4.11}/src/lmnr/traceloop_sdk/tracing/tracing.py

@@ -531,10 +531,6 @@ def init_instrumentations(should_enrich_metrics: bool):
     init_milvus_instrumentor()
     init_transformers_instrumentor()
     init_together_instrumentor()
-    init_redis_instrumentor()
-    init_requests_instrumentor()
-    init_urllib3_instrumentor()
-    init_pymysql_instrumentor()
     init_bedrock_instrumentor(should_enrich_metrics)
     init_replicate_instrumentor()
     init_vertexai_instrumentor()
@@ -545,6 +541,12 @@ def init_instrumentations(should_enrich_metrics: bool):
     init_lancedb_instrumentor()
     init_groq_instrumentor()
 
+    # These libraries are not instrumented by default, but if the user wants, he can manually specify them
+    # init_redis_instrumentor()
+    # init_requests_instrumentor()
+    # init_urllib3_instrumentor()
+    # init_pymysql_instrumentor()
+
 
 def init_openai_instrumentor(should_enrich_metrics: bool):
     try: