lmnr 0.2.14__tar.gz → 0.3.0__tar.gz

lmnr-0.3.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.1
+Name: lmnr
+Version: 0.3.0
+Summary: Python SDK for Laminar AI
+License: Apache-2.0
+Author: lmnr.ai
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: 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)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Laminar AI
+
+This repo provides core for code generation, Laminar CLI, and Laminar SDK.
+
+## Quickstart
+```sh
+python3 -m venv .myenv
+source .myenv/bin/activate  # or use your favorite env management tool
+
+pip install lmnr
+```
+
+
+## Decorator instrumentation example
+
+For easy automatic instrumentation, we provide you two simple primitives:
+
+- `observe` - a multi-purpose automatic decorator that starts traces and spans when functions are entered, and finishes them when functions return
+- `wrap_llm_call` - a function that takes in your LLM call and return a "decorated" version of it. This does all the same things as `observe`, plus
+a few utilities around LLM-specific things, such as counting tokens and recording model params.
+
+You can also import `lmnr_context` in order to interact and have more control over the context of the current span.
+
+```python
+import os
+from openai import OpenAI
+
+from lmnr import observe, wrap_llm_call, lmnr_context
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
+
+@observe()  # annotate all functions you want to trace
+def poem_writer(topic="turbulence"):
+    prompt = f"write a poem about {topic}"
+
+    # wrap the actual final call to LLM with `wrap_llm_call`
+    response = wrap_llm_call(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
+
+    if topic in poem:
+        lmnr_context.event("topic_alignment")  # send an event with a pre-defined name
+    
+    # to trigger an automatic check for a possible event do:
+    lmnr_context.check_span_event("excessive_wordiness")
+
+    return poem
+
+if __name__ == "__main__":
+    print(poem_writer(topic="laminar flow"))
+```
+
+This gives an advantage of quick instrumentation, but is somewhat limited in flexibility + doesn't really work as expected with threading.
+This is due to the fact that we use `contextvars.ContextVar` for this, and how Python manages them between threads.
+
+If you want to instrument your code manually, follow on to the next section
+
+## Manual instrumentation example
+
+For manual instrumetation you will need to import the following:
+- `trace` - this is a function to start a trace. It returns a `TraceContext`
+- `TraceContext` - a pointer to the current trace that you can pass around functions as you want.
+- `SpanContext` - a pointer to the current span that you can pass around functions as you want
+
+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
+- `evaluate_event(name: str, data: str)` - register a possible event for automatic checking by Laminar.
+
+Example:
+
+```python
+import os
+from openai import OpenAI
+
+from lmnr import trace, TraceContext, SpanContext
+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)
+
+    prompt = f"write a poem about {topic}"
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": prompt},
+    ]
+    # create a child span within the current `poem_writer` span.
+    llm_span = span.span(name="OpenAI completion", input=messages, span_type="LLM")
+    
+    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?"},
+        ],
+    )
+    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"])
+    span.end(output=poem)
+    return poem
+
+
+t: TraceContext = trace(user_id="user", session_id="session", release="release")
+main(t, topic="laminar flow")
+t.end(success=True)
+```
+
+## Features
+
+- 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
+
+## Making Laminar pipeline calls
+
+After you are ready to use your pipeline in your code, deploy it in Laminar by selecting the target version for the pipeline.
+
+Once your pipeline target is set, you can call it from Python in just a few lines.
+
+Example use:
+
+```python
+from lmnr import Laminar 
+
+# for decorator instrumentation, do: `from lmnr inport lmnr_context`
+
+l = Laminar('<YOUR_PROJECT_API_KEY>')
+result = l.run(  # lmnr_context.run( for decorator instrumentation
+    pipeline = 'my_pipeline_name',
+    inputs = {'input_node_name': 'some_value'},
+    # all environment variables
+    env = {'OPENAI_API_KEY': 'sk-some-key'},
+    # any metadata to attach to this run's trace
+    metadata = {'session_id': 'your_custom_session_id'}
+)
+```
+
+Resulting in:
+
+```python
+>>> result
+PipelineRunResponse(
+    outputs={'output': {'value': [ChatMessage(role='user', content='hello')]}},
+    # useful to locate your trace
+    run_id='53b012d5-5759-48a6-a9c5-0011610e3669'
+)
+```
+
+## PROJECT_API_KEY
+
+Read more [here](https://docs.lmnr.ai/api-reference/introduction#authentication) on how to get `PROJECT_API_KEY`.
+

lmnr-0.3.0/README.md

@@ -0,0 +1,164 @@
+# Laminar AI
+
+This repo provides core for code generation, Laminar CLI, and Laminar SDK.
+
+## Quickstart
+```sh
+python3 -m venv .myenv
+source .myenv/bin/activate  # or use your favorite env management tool
+
+pip install lmnr
+```
+
+
+## Decorator instrumentation example
+
+For easy automatic instrumentation, we provide you two simple primitives:
+
+- `observe` - a multi-purpose automatic decorator that starts traces and spans when functions are entered, and finishes them when functions return
+- `wrap_llm_call` - a function that takes in your LLM call and return a "decorated" version of it. This does all the same things as `observe`, plus
+a few utilities around LLM-specific things, such as counting tokens and recording model params.
+
+You can also import `lmnr_context` in order to interact and have more control over the context of the current span.
+
+```python
+import os
+from openai import OpenAI
+
+from lmnr import observe, wrap_llm_call, lmnr_context
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
+
+@observe()  # annotate all functions you want to trace
+def poem_writer(topic="turbulence"):
+    prompt = f"write a poem about {topic}"
+
+    # wrap the actual final call to LLM with `wrap_llm_call`
+    response = wrap_llm_call(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
+
+    if topic in poem:
+        lmnr_context.event("topic_alignment")  # send an event with a pre-defined name
+    
+    # to trigger an automatic check for a possible event do:
+    lmnr_context.check_span_event("excessive_wordiness")
+
+    return poem
+
+if __name__ == "__main__":
+    print(poem_writer(topic="laminar flow"))
+```
+
+This gives an advantage of quick instrumentation, but is somewhat limited in flexibility + doesn't really work as expected with threading.
+This is due to the fact that we use `contextvars.ContextVar` for this, and how Python manages them between threads.
+
+If you want to instrument your code manually, follow on to the next section
+
+## Manual instrumentation example
+
+For manual instrumetation you will need to import the following:
+- `trace` - this is a function to start a trace. It returns a `TraceContext`
+- `TraceContext` - a pointer to the current trace that you can pass around functions as you want.
+- `SpanContext` - a pointer to the current span that you can pass around functions as you want
+
+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
+- `evaluate_event(name: str, data: str)` - register a possible event for automatic checking by Laminar.
+
+Example:
+
+```python
+import os
+from openai import OpenAI
+
+from lmnr import trace, TraceContext, SpanContext
+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)
+
+    prompt = f"write a poem about {topic}"
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": prompt},
+    ]
+    # create a child span within the current `poem_writer` span.
+    llm_span = span.span(name="OpenAI completion", input=messages, span_type="LLM")
+    
+    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?"},
+        ],
+    )
+    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"])
+    span.end(output=poem)
+    return poem
+
+
+t: TraceContext = trace(user_id="user", session_id="session", release="release")
+main(t, topic="laminar flow")
+t.end(success=True)
+```
+
+## Features
+
+- 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
+
+## Making Laminar pipeline calls
+
+After you are ready to use your pipeline in your code, deploy it in Laminar by selecting the target version for the pipeline.
+
+Once your pipeline target is set, you can call it from Python in just a few lines.
+
+Example use:
+
+```python
+from lmnr import Laminar 
+
+# for decorator instrumentation, do: `from lmnr inport lmnr_context`
+
+l = Laminar('<YOUR_PROJECT_API_KEY>')
+result = l.run(  # lmnr_context.run( for decorator instrumentation
+    pipeline = 'my_pipeline_name',
+    inputs = {'input_node_name': 'some_value'},
+    # all environment variables
+    env = {'OPENAI_API_KEY': 'sk-some-key'},
+    # any metadata to attach to this run's trace
+    metadata = {'session_id': 'your_custom_session_id'}
+)
+```
+
+Resulting in:
+
+```python
+>>> result
+PipelineRunResponse(
+    outputs={'output': {'value': [ChatMessage(role='user', content='hello')]}},
+    # useful to locate your trace
+    run_id='53b012d5-5759-48a6-a9c5-0011610e3669'
+)
+```
+
+## PROJECT_API_KEY
+
+Read more [here](https://docs.lmnr.ai/api-reference/introduction#authentication) on how to get `PROJECT_API_KEY`.

{lmnr-0.2.14 → lmnr-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lmnr"
-version = "0.2.14"
+version = "0.3.0"
 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.2.14"
+version = "0.3.0"
 description = "Python SDK for Laminar AI"
 authors = ["lmnr.ai"]
 readme = "README.md"
@@ -19,16 +19,15 @@ license = "Apache-2.0"
 
 [tool.poetry.dependencies]
 python = "^3.9"
-black = "^24.4.2"
 pydantic = "^2.7.4"
-click = "^8.1.7"
 requests = "^2.32.3"
-websockets = "^12.0"
-cookiecutter = "^2.6.0"
 python-dotenv = "^1.0.1"
-pystache = "^0.6.5"
-lmnr-baml = "^0.40.1"
-watchdog = "^4.0.2"
+
+openai = "^1.41.1"
+backoff = "^2.2.1"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.8.0"
 
 [build-system]
 requires = ["poetry-core"]

lmnr-0.3.0/src/lmnr/__init__.py

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

lmnr-0.3.0/src/lmnr/sdk/client.py

@@ -0,0 +1,161 @@
+from .tracing_types import Span, Trace
+
+from pydantic.alias_generators import to_snake
+from typing import Any, Optional, Union
+import dotenv
+import json
+import logging
+import os
+import requests
+import uuid
+
+from .types import (
+    PipelineRunError,
+    PipelineRunResponse,
+    NodeInput,
+    PipelineRunRequest,
+)
+
+
+class APIError(Exception):
+    def __init__(self, status: Union[int, str], message: str, details: Any = None):
+        self.message = message
+        self.status = status
+        self.details = details
+
+    def __str__(self):
+        msg = "{0} ({1}): {2}"
+        return msg.format(self.message, self.status, self.details)
+
+
+class Laminar:
+    _base_url = "https://api.lmnr.ai"
+
+    def __init__(self, project_api_key: Optional[str] = None):
+        self.project_api_key = project_api_key or os.environ.get("LMNR_PROJECT_API_KEY")
+        if not self.project_api_key:
+            dotenv_path = dotenv.find_dotenv(usecwd=True)
+            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,
+        pipeline: str,
+        inputs: dict[str, NodeInput],
+        env: dict[str, str] = {},
+        metadata: dict[str, str] = {},
+        parent_span_id: Optional[uuid.UUID] = None,
+        trace_id: Optional[uuid.UUID] = None,
+    ) -> PipelineRunResponse:
+        """Runs the pipeline with the given inputs
+
+        Args:
+            pipeline (str): name of the Laminar pipeline
+            inputs (dict[str, NodeInput]):
+                inputs to the endpoint's target pipeline.
+                Keys in the dictionary must match input node names
+            env (dict[str, str], optional):
+                Environment variables for the pipeline execution.
+                Defaults to {}.
+            metadata (dict[str, str], optional):
+                any custom metadata to be stored
+                with execution trace. Defaults to {}.
+            parent_span_id (Optional[uuid.UUID], optional):
+                parent span id for the resulting span.
+                Must usually be SpanContext.id()
+                Defaults to None.
+            trace_id (Optional[uuid.UUID], optional):
+                trace id for the resulting trace.
+                Must usually be TraceContext.id()
+                Defaults to None.
+
+        Returns:
+            PipelineRunResponse: response object containing the outputs
+
+        Raises:
+            ValueError: if project API key is not set
+            PipelineRunError: if the endpoint run fails
+        """
+        if self.project_api_key is None:
+            raise ValueError(
+                "Please initialize the Laminar object with your project API key or set "
+                "the LMNR_PROJECT_API_KEY environment variable"
+            )
+        try:
+            request = PipelineRunRequest(
+                inputs=inputs,
+                pipeline=pipeline,
+                env=env,
+                metadata=metadata,
+                parent_span_id=parent_span_id,
+                trace_id=trace_id,
+            )
+        except Exception as e:
+            raise ValueError(f"Invalid request: {e}")
+
+        response = requests.post(
+            self._base_url + "/v1/pipeline/run",
+            data=json.dumps(request.to_dict()),
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise PipelineRunError(response)
+        try:
+            resp_json = response.json()
+            keys = list(resp_json.keys())
+            for key in keys:
+                value = resp_json[key]
+                del resp_json[key]
+                resp_json[to_snake(key)] = value
+            return PipelineRunResponse(**resp_json)
+        except Exception:
+            raise PipelineRunError(response)
+
+    def batch_post_traces(self, batch: list[Union[Span, Trace]]):
+        log = logging.getLogger("laminar.client")
+        url = self._base_url + "/v1/traces"
+        data = json.dumps({"traces": [item.to_dict() for item in batch]})
+        log.debug(f"making request to {url}")
+        headers = self._headers()
+        res = requests.post(url, data=data, headers=headers)
+
+        if res.status_code == 200:
+            log.debug("data uploaded successfully")
+
+        return self._process_response(
+            res, success_message="data uploaded successfully", return_json=False
+        )
+
+    def _process_response(
+        self, res: requests.Response, success_message: str, return_json: bool = True
+    ) -> Union[requests.Response, Any]:
+        log = logging.getLogger("laminar.client")
+        log.debug("received response: %s", res.text)
+        if res.status_code in (200, 201):
+            log.debug(success_message)
+            if return_json:
+                try:
+                    return res.json()
+                except json.JSONDecodeError:
+                    log.error("Response is not valid JSON.")
+                    raise APIError(res.status_code, "Invalid JSON response received")
+            else:
+                return res
+        try:
+            payload = res.json()
+            log.error("received error response: %s", payload)
+            raise APIError(res.status_code, payload)
+        except (KeyError, ValueError):
+            raise APIError(res.status_code, res.text)
+
+    def _headers(self):
+        return {
+            "Authorization": "Bearer " + self.project_api_key,
+            "Content-Type": "application/json",
+        }